CommunityEscrita e Ediçãogithub.com

maxgfr/ultraeval

Avalie uma habilidade ou base de código com um fluxo de trabalho multiagente, fundamente cada descoberta em um arquivo:linha real e gere um backlog de correções TDD explorável por IA. Uma habilidade de agente do skills.sh.

O que é ultraeval?

O ultraeval é uma habilidade de agente AI projetada para avaliar sistematicamente uma habilidade ou base de código, produzindo um backlog de correções fundamentado e priorizado que pode ser executado automaticamente por um modelo de linguagem. Diferente de revisões de código superficiais, o ultraeval usa um fluxo de trabalho multiagente que primeiro pesquisa, planeja, executa e julga as descobertas — garantindo que cada problema ou oportunidade de melhoria seja ancorado a um arquivo:linha real no código-alvo. Essa abordagem de 'gate de fundamentação' de duas camadas (estrutural + semântica) elimina alucinações e fornece cartões TDD (Test-Driven Development) que um agente pode implementar no ciclo red→green→refactor. A habilidade é ideal para auditar a prontidão de produção de uma skill, revisar a qualidade de uma base de código, ou gerar um plano de correção após regressões. Suporta modos de auditoria (somente defeitos), melhoria (oportunidades fundamentadas) ou profundo (ambos). O ultraeval é invocado através de comandos de linha de comando (node scripts/ultraeval.mjs) e gera uma série de artefatos: um workflow multiagente, contratos de subagentes, esquemas de descobertas, um backlog priorizado e cartões de correção individuais. O fluxo de trabalho pode ser executado com um haras de Workflow ou manualmente, lendo os contratos e despachando subagentes. O resultado final é um score ponderado (0-100), um veredito se atende às expectativas e um conjunto de artefatos de correção prontos para serem consumidos por outros agentes.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add maxgfr/ultraeval

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

ultraeval: avaliar uma habilidade ou base de código → documentação de correção fundamentada e explorável por IA

O markdown é o programa. Um pequeno mecanismo determinístico estrutura a execução, gera o fluxo de trabalho multiagente e impõe uma barreira de fundamentação; você (com subagentes distribuídos) faz a pesquisa, o julgamento e a escrita. Cada descoberta deve resolver para um arquivo:linha real no alvo — a barreira rejeita as alucinadas — e a saída é um backlog priorizado mais cartões TDD por correção que um modelo pode implementar no ciclo red→green→refactor.

Quando usar

  • "Avaliar / auditar / classificar / pontuar esta habilidade (ou repositório)"; "está pronta para produção / atende às expectativas?"
  • "Revisar esta base de código e me dar um plano de correção / um backlog TDD."
  • Proteção contra regressões em suas próprias habilidades após mudanças, ou avaliar uma de terceiros antes de confiar nela.

Não para: uma revisão rápida de código de um arquivo (apenas leia); executar o próprio conjunto de testes do alvo (faça isso diretamente).

O ciclo

init → plan → run(pesquisa → plano-de-teste → executar+barreiras → julgar → resultados) → verificar → backlog(TDD) → pontuar → renderizar

Tudo é uma chamada simples node <diretório-da-habilidade>/scripts/ultraeval.mjs <comando>. Distribuir subagentes é uma otimização que o fluxo de trabalho gerado codifica — nunca um requisito.

Entradas a confirmar

  • Alvo — um caminho para a habilidade/repositório a ser avaliado (ou uma URL git que o usuário já clonou localmente).
  • Tipo — skill (habilidade) ou codebase (base de código) (auto-detectado: um SKILL.md ⇒ habilidade). Sobrescreva com --kind.
  • Categoria — ex. "habilidade de agente", "CLI", "biblioteca", "aplicação web", "ferramenta de segurança". Direciona a rubrica inicial.
  • Modo — audit (auditoria - defeitos, padrão) · improve (melhoria - oportunidades fundamentadas) · deep (profundo - ambos). Defina com --mode.

Modos e descoberta de melhorias

O ultraeval encontra duas coisas, ambas fundamentadas e com barreira:

  • Defeitos (audit, deep) — algo está errado; cada um cita um arquivo:linha real.
  • Oportunidades (improve, deep) — uma oportunidade de melhoria fundamentada (saúde interna e produto/capacidade), avaliada como impacto × esforço. Descobertas por analyze (hotspots determinísticos/dependências/rotatividade/lacunas de teste) → brainstorm (lentes divergentes) → brainstorm --rank (classifica as oportunidades em findings.json como kind:"opportunity"). A mesma barreira se aplica — uma oportunidade deve ancorar em código/métricas reais, para nunca se tornar um vago "reescrever tudo". Consulte references/analysis-playbook.md.

Para improve/deep, o plan adiciona as etapas Analyze e Brainstorm ao fluxo de trabalho gerado.

Procedimento

1. Estruturar a execução.

node <diretório-da-habilidade>/scripts/ultraeval.mjs init --target <CAMINHO> --out <EXECUÇÃO> [--kind skill|codebase] [--category "<c>"]

Escreve eval.config.json com as dimensões iniciais (consulte references/rubric-library.md).

2. Gerar o fluxo de trabalho + contratos de subagentes.

node <diretório-da-habilidade>/scripts/ultraeval.mjs plan --run <EXECUÇÃO>

Emite <EXECUÇÃO>/eval.workflow.mjs (um Workflow multiagente pronto para lançar, com os caminhos absolutos do mecanismo e do alvo embutidos), <EXECUÇÃO>/agents/*.md (os contratos de despacho), TEST-PLAN.template.md, dimensions.json, findings.schema.json.

3. Executar a avaliação. Lance o workflow gerado com a ferramenta Workflow do seu harness: Workflow({ scriptPath: "<EXECUÇÃO>/eval.workflow.mjs" }). Ele sequencia Pesquisa → PlanoDeTeste → Execução → Descobertas → Barreira → Julgamento → Resultados e auto-invoca as barreiras do mecanismo. Se você não tem um harness de workflow, execute as etapas manualmente: leia cada agents/<etapa>.md e despache um subagente conforme o contrato. Consulte references/orchestration.md. Cada subagente recebe o caminho ABSOLUTO para <diretório-da-habilidade>/scripts/ultraeval.mjs — ele tem seu próprio diretório de trabalho atual e não pode resolver um caminho relativo (o plan já embute o caminho absoluto no workflow).

4. Fundamentar cada descoberta. Consolide os resultados em <EXECUÇÃO>/findings.json (esquema: references/gate-contract.md). Cada descoberta cita evidence[].ref como caminho:linha no alvo ou execuçã0:caminhoRelativo#Lnn em um log produzido. Então:

node <diretório-da-habilidade>/scripts/ultraeval.mjs check --run <EXECUÇÃO>

Corrija findings.json até que ele saia com 0 — repare ou exclua descobertas não fundamentadas; nunca enfraqueça a barreira.

5. Verificar (barreira de saída adversarial).

node <diretório-da-habilidade>/scripts/ultraeval.mjs verify --run <EXECUÇÃO>          # escreve VERIFY.todo.json
# preencha cada veredito: supported | partial | refuted | unsupported (use subagentes céticos; --shards N --shard i para paralelizar)
node <diretório-da-habilidade>/scripts/ultraeval.mjs verify --run <EXECUÇÃO> --apply <verdicts.json>
node <diretório-da-habilidade>/scripts/ultraeval.mjs check --run <EXECUÇÃO> --semantic --require-verify   # barreira de saída — nunca apresente antes que isso passe

Uma descoberta refuted deve ser marcada como dismissed. Uma supported/partial sobrevive.

6. Remediar — a entrega.

node <diretório-da-habilidade>/scripts/ultraeval.mjs backlog --run <EXECUÇÃO> --tdd

Emite BACKLOG.json (uma lista de tarefas legível por máquina, ordenada por prioridade, que um agente downstream pode executar), REMEDIATION.md, e um fixes/FIX-*.md cartão TDD por descoberta confirmada — cada um com uma especificação VERMELHA de teste-falha-primeiro, a mudança VERDE e um comando VERIFY. Consulte references/tdd-remediation.md.

7. Pontuar + renderizar + apresentar.

node <diretório-da-habilidade>/scripts/ultraeval.mjs score --run <EXECUÇÃO>           # judges.jsonl + dimensões -> scorecard.json (0-100 + atende-expectativas)
node <diretório-da-habilidade>/scripts/ultraeval.mjs render --run <EXECUÇÃO>          # index.html + index.md dashboard (mostra o veredito)

score reduz o painel de juízes judges.jsonl e as dimensões de configuração a um veredito ponderado; uma descoberta P0 ativa (ou qualquer juiz votando não, ou uma pontuação abaixo do limite) define atende-expectativas como falso. Apresente o veredito, o título do backlog P0/P1 e os caminhos (RESULTS.md, BACKLOG.json, fixes/) que um agente de correção deve consumir.

Códigos de saída do CLI: 0 ok / barreira passou · 1 barreira falhou (check/verify) · 2 erro de uso ou execução.

8. (opcional) Conduzir as correções. Passe cada fixes/FIX-*.md para um agente de build implementar TDD — o cartão é escrito para que ele possa ir red→green→refactor sem re-derivar o problema.

O contrato de fundamentação

Uma descoberta só é confiável se sua evidência for resolvível. check abre cada caminho:linha no alvo e confirma que a linha existe e está dentro do intervalo; uma linha obsoleta/inventada é uma falha grave. verify então pergunta a um cético se o conteúdo citado realmente suporta a afirmação. Esta barreira de duas camadas (estrutural + semântica) é o ponto central — gramática completa e regras de aprovação/reprovação em references/gate-contract.md.

Método e rubricas

  • references/eval-playbook.md — o método pesquisa→plano-de-teste→execução→julgamento→resultados, e como construir uma rubrica pontuada por dimensão.
  • references/orchestration.md — o workflow gerado, os contratos de despacho de subagentes e o invariante do <diretório-da-habilidade> absoluto para a distribuição.
  • references/gate-contract.md — esquema do findings.json, gramática de referência de evidência, e exatamente o que faz o check/verify passar ou falhar.
  • references/tdd-remediation.md — a forma do BACKLOG.json e o formato do cartão TDD fixes/FIX-*.md.
  • references/rubric-library.md — dimensões iniciais por categoria de alvo.
  • references/analysis-playbook.md — os sinais do analyze, as lentes do brainstorm e como as oportunidades permanecem fundamentadas.

Segurança

  • ultraeval apenas lê o alvo e escreve sob <EXECUÇÃO>. Ele nunca executa o código do alvo; o subagente executor pode executar os comandos próprios do alvo (testes, barreiras) — isole repositórios não confiáveis em um sandbox.
  • clean --run <EXECUÇÃO> remove apenas artefatos derivados de barreira/renderização e mantém as entregas; --all remove toda a execução.

Habilidades Relacionadas