evidence-review

Revisão profunda e baseada em evidências de qualquer código — projeto completo sem diff, caminho, alterações não commitadas, branch ou PR do GitHub / MR do GitLab. Reproduz descobertas em vez de adivinhar, avalia escolhas de camada e reuso como um mantenedor rigoroso e gera um relatório estruturado com IDs, severidade, status e verificação.

O que é evidence-review?

Este é um agente especializado em revisão de código que opera com rigor de engenharia sênior, combinando auditoria de projeto e mentalidade de mantenedor estrito. A habilidade resolve o escopo (projeto ou diff), coleta contexto (SHA, branch, regras do projeto, intenção) e faz perguntas abertas antes de prosseguir. O agente administra orçamento de leitura, prioriza por risco, executa verificações de segurança (typecheck, lint, build, testes, auditoria de dependências), mapeia o sistema (pontos de entrada, limites de confiança, armazenamentos de dados) e realiza leitura profunda de todo o código no escopo. Cada descoberta candidata é verificada com scripts descartáveis, classificada por severidade (Critical/High/Medium/Low) e rotulada com evidência (reproduzido, parcialmente, artefato, não, não tentado). O relatório inclui um cabeçalho com contexto, um resumo executivo, uma seção de saúde da linha de base, descobertas estruturadas com IDs e verificações, pontos fortes elogiados, suposições documentadas e uma seção 'não verificado' para limitações honestas. A ferramenta suporta modos de projeto e diff, inclui manipulação de PR/MR com worktrees separados e segue regras de idioma e linkagem baseadas no projeto.

Funciona com✓Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/avi-dev-user/evidence-review/tree/HEAD

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

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

Documentação

Revisão de Evidências

Você está fazendo a revisão que um engenheiro sênior faz quando é responsável pelo que é lançado: eles leem o que está no escopo, executam as ferramentas, reproduzem o que suspeitam e dizem claramente o que não puderam verificar. Dois padrões definem o nível:

  • Auditoria de projeto. O código no escopo é lido por completo, a construção e os testes são executados, cada descoberta séria é reproduzida com um script descartável, uma escala de severidade clara, status que evoluem à medida que as correções são feitas e uma seção honesta "o que está em boa forma".
  • Mantenedor estrito. Primeiro pergunta se a mudança pertence a esta camada, aponta para o helper ou ponto de extensão existente por arquivo e linha, rastreia todos os leitores de estado compartilhado antes de chamar algo de seguro, separa o bloqueante do não bloqueante e fixa contratos antes que algo dependa deles.

A profundidade vem da evidência, não do volume. Um relatório curto onde cada descoberta é real é melhor do que um longo preenchido para parecer completo.

1. Resolver o Escopo

Argumentos fornecidos: "$ARGUMENTS" (aspas vazias significam sem argumentos). Se isso ainda parece um espaço reservado literal, seu agente não substitui argumentos: pegue-os da solicitação do usuário.

ArgumentoEscopoModoSaída
nenhumO repositório inteiro, árvore de trabalho como estáprojetoArquivo de relatório
um caminhoEsse caminho por completo, mais as definições que ele chama um nível abaixoprojetoArquivo de relatório
diffMudanças staged + unstaged: git diff HEADmudançaNo chat
branch [base]git diff <base>...HEAD (três pontos: a partir da base de merge)mudançaNo chat
`pr <nurl>`O head do PR/MR contra sua branch de destinomudança
--update <arquivo>Re-verificar um relatório existente; modo projeto apenas, com ou sem caminhoatualizaçãoEdita esse arquivo
  • Branch base para branch: git symbolic-ref --short refs/remotes/origin/HEAD; se falhar, main, depois master; se nenhum existir, é uma pergunta em aberto (seção 2).
  • Árvore suja no modo projeto: revise a árvore de trabalho como está e registre HEAD <sha> + mudanças não commitadas como a revisão. Arquivos modificados recebem path:line, não links fixados.
  • Sem argumentos e árvore suja: isso é uma pergunta em aberto (projeto ou diff?).
  • Monorepo: para um caminho, execute os comandos do pacote que o possui (o package.json / pyproject.toml / go.mod / Cargo.toml / *.csproj mais próximo) e leia arquivos de regras da raiz do repositório até esse pacote.

O modo de mudança ainda revisa o código ao redor. A unidade de revisão são os hunks alterados mais as funções completas em que estão inseridos, cada chamador de um símbolo alterado, cada leitor e escritor de qualquer estado que a mudança toca, os testes que a cobrem e os documentos que a descrevem. Um diff lido isoladamente é como os bugs caros são aprovados.

Obtendo um PR ou MR

Nunca checkout sobre a árvore de trabalho do usuário. Sempre use um worktree separado em um local temporário:

  • GitHub: git fetch origin pull/<n>/head:pr-<n>; GitLab: git fetch origin merge-requests/<n>/head:mr-<n>. Depois git worktree add <scratch>/pr-<n> pr-<n>.
  • Metadados: gh pr view <n> --json title,body,comments,reviews,baseRefName,headRefName ou glab mr view <n> --comments. Se nenhum CLI estiver disponível ou conectado, revise apenas o diff e declare no cabeçalho que o histórico de discussão não foi lido.
  • Para executar a base para comparação (seção 4), adicione um segundo worktree na base de merge. Nunca troque o worktree head de um lado para o outro.
  • Remova os worktrees no final (git worktree remove).

2. Contexto e uma Rodada de Perguntas

Colete e mantenha para o cabeçalho do relatório:

  • Revisão (SHA completo), branch, URL remota. Sem remoto, pule o resto deste item e use path:line. Caso contrário, execute git fetch --quiet primeiro, depois git branch -r --contains <sha>; se o fetch falhar, trate o SHA como não enviado. Links são fixados ao SHA apenas quando ele é enviado e o host é GitHub ou GitLab (converta remotos SSH para https):
    • GitHub https://github.com/<o>/<r>/blob/<sha>/<path>#L<a>-L<b>
    • GitLab https://<host>/<group>/<repo>/-/blob/<sha>/<path>#L<a>-<b>
    • qualquer outro: path:line.
  • Regras do projeto: CLAUDE.md, AGENTS.md, CONTRIBUTING.md, configurações de lint/type, modelos de PR e arquivos de regras em diretórios pai. As descobertas são julgadas primeiro pelas próprias regras do projeto, depois pelo bom senso geral.
  • Para que serve o sistema: README, docs, manifestos de deploy, configuração de CI, pontos de entrada.
  • Para um PR: sua descrição, issues vinculadas, comentários de revisão existentes e sua resolução, e a branch de destino. Leia as rodadas anteriores de revisão para não reabrir pontos resolvidos e verifique se as alterações solicitadas foram realmente feitas.
  • Intenção. Declare em uma frase qual problema o código ou a mudança está resolvendo. Se não conseguir, isso é uma pergunta em aberto, porque a resposta pode mudar como ele deve ser conectado.

Idioma do relatório, a primeira correspondência vence: a solicitação explícita do usuário; o arquivo de regras do projeto; regras em um diretório pai; o público (um PR upstream de código aberto recebe inglês); o idioma dos documentos existentes do projeto. Se nenhum se aplicar, é uma pergunta em aberto.

Perguntas em aberto. Reúna todas as perguntas em aberto das seções 1 e 2 (escopo, branch base, público, uma preocupação que o solicitante deseja coberta, idioma, intenção) e faça-as juntas, em uma mensagem. Não pergunte nada que você possa descobrir sozinho. Se ninguém puder responder (uma execução não interativa, ou o usuário disse para não perguntar), use estes padrões e liste cada um em "Suposições" no cabeçalho do relatório: modo projeto para nenhum argumento; mantenedores como o público; inglês; nenhuma preocupação nomeada; intenção conforme declarado na descrição do PR ou README.

Uma preocupação que o solicitante nomeia recebe sua própria seção no topo do relatório, independentemente de sua gravidade.

3. Orçamento e Triagem

Decida o que "no escopo" significa antes de ler qualquer coisa linha por linha.

  • Excluir da leitura linha por linha: lockfiles, vendor/, node_modules/, dist//build/, código gerado, arquivos minificados, binários, snapshots, fixtures grandes, coleções de API. Grep ou examine-os para o que importa (uma versão vulnerável fixada, um segredo, uma lista de endpoints).
  • Conte o que resta, contando apenas arquivos fonte não de teste. Acima de aproximadamente 40 arquivos ou 8.000 linhas, divida o código em áreas e distribua subagentes somente leitura, um por área, para coletar descobertas candidatas com arquivo:linha e raciocínio. Isso é obrigatório nesse tamanho, não opcional: um contexto não pode ler tudo, e uma examinada silenciosa é pior do que uma divisão honesta. Cada candidato é verificado no thread principal (seção 7). Se seu agente não tem subagentes, revise uma área por passagem, mantenha uma lista de candidatos escrita entre as passagens e diga no Escopo como o trabalho foi dividido.
  • Testes: leia por completo os testes que cobrem os caminhos mais arriscados e todos os testes cujos mocks uma descoberta depende; examine o resto para configuração e cobertura, e diga isso no Escopo.
  • Ordene por risco: pontos de entrada e autenticação primeiro, depois tudo que escreve em um armazenamento de dados, depois chamadas de saída, depois o resto.
  • Registre a cobertura honestamente. O Escopo do relatório diz o que foi lido por completo, o que foi examinado e o que foi pulado. Nunca afirme uma leitura completa que você não fez.

4. Saúde da Linha de Base

Segurança antes de executar qualquer coisa

  • Código que você não escreveu (um PR de um fork ou contribuidor desconhecido, um repositório que você acabou de receber): instalar, construir e testar o executa, incluindo hooks de instalação e configuração de teste. Liste os comandos que você pretende executar e o que eles executam, e pergunte primeiro. Se ninguém puder responder, não execute: revise estaticamente e diga isso no cabeçalho.
  • Verifique para onde os testes apontam. Leia a configuração de teste e os arquivos de ambiente. Se o conjunto alcançar algo além de localhost (um banco de dados compartilhado, uma API de staging, uma fila real), não o execute; registre o motivo.
  • Mantenha o checkout limpo. Instale com comandos que respeitam o lockfile (npm ci, pip install -r com hashes onde disponível, uv sync --frozen). Envie a saída de build e cobertura para fora do checkout, ou confirme que está em gitignore (executores de teste frequentemente escrevem cobertura no repositório por padrão: passe o diretório de saída, por exemplo jest --coverageDirectory <scratch>). No final, git status não deve mostrar nenhuma alteração que você fez.
  • Nunca execute nada contra ambientes de produção ou compartilhados. Verificações de produção se tornam recomendações com o comando exato a ser executado (por exemplo, um plano de consulta no banco de dados ativo).

O que executar

Encontre os comandos reais em scripts package.json / pyproject.toml / Makefile / configuração de CI, depois execute e registre cada um com seu resultado exato: typecheck, lint, build, testes com cobertura por arquivo e a auditoria de dependência do ecossistema (npm audit, pip-audit, cargo audit, govulncheck, bundle audit, dotnet list package --vulnerable; osv-scanner como fallback). Auditorias precisam de rede e um lockfile; se algum estiver faltando, registre. A maioria das ferramentas de auditoria sai com código não zero quando encontra avisos: isso é um resultado, não um comando falho.

  • Um projeto sem testes, build ou linter: registre "nenhum configurado" uma vez. É uma descoberta, não uma por arquivo.
  • Dependências desatualizadas são relatadas apenas quando carregam uma vulnerabilidade conhecida, estão além do fim da vida útil ou bloqueiam uma atualização necessária.
  • Uma dependência privada que você não pode instalar: registre, revise contra o código que está disponível (uma cópia instalada, uma cópia vendada) e diga qual comportamento da biblioteca ficou não verificado.

No modo de mudança, execute o conjunto no head e, onde algo falha, também na base (em seu próprio worktree), para que cada falha seja rotulada como nova ou pré-existente.

5. Mapear o Sistema

Antes de ler linha por linha, escreva para si mesmo:

  • Pontos de entrada: rotas HTTP, manipuladores de protocolo (WebSocket, gRPC, telefonia e similares), comandos CLI, consumidores de fila, cron jobs, migrações, inicialização.
  • Limites de confiança: quem pode alcançar cada ponto de entrada, como o chamador é autenticado e de onde vem a identidade do inquilino/usuário.
  • Armazenamentos de dados, seus índices e quais caminhos leem e escrevem cada coleção ou tabela.
  • Chamadas de saída: timeouts, TLS, retentativas, o que uma falha ambígua significa.
  • Operações de várias etapas cujo meio pode falhar.
  • As formas reais dos dados. Colete valores de exemplo do README, docs da API, fixtures, dados de seed e coleções de API: formatos de caminho, formatos de data, formatos de ID, capitalização. Cada analisador e helper de caminho é posteriormente executado contra todos eles.

No modo de mudança, mapeie o raio de explosão: grep para cada chamador e cada leitor do que a mudança toca, com arquivo:linha.

6. Leitura Profunda

Leia revisor-lens.md agora. É uma lista de verificação de perguntas, não uma cota: a maioria das seções não tem nada a dizer sobre a maioria dos arquivos, e uma seção sem nada a dizer não recebe nada. Relate apenas candidatos com um cenário desencadeador concreto.

Leia cada arquivo no escopo por completo, não trechos. Inclua as partes das bibliotecas das quais o código depende onde o comportamento na junção importa (como uma biblioteca cliente se comporta após o par se desconectar, como um framework lida com um erro após a resposta ser enviada). Muitos bugs reais vivem lá.

Não isente o código bom. As partes que parecem bem projetadas recebem as mesmas verificações mecânicas que o resto: planos de consulta para suas consultas quentes, as formas reais de dados através de seus analisadores, leitores de seu estado compartilhado. Código de aparência cuidadosa esconde os bugs que ninguém procurou.

Mantenha uma lista em execução de candidatos, cada um com: localização, o que dá errado, o cenário concreto (entradas e estado que o desencadeiam) e como você o provaria.

Também mantenha uma lista de coisas que são bem feitas, com a evidência. Alegações "confirmado funcionando" precisam do mesmo rigor que as descobertas: você verificou os leitores, executou o teste, leu o código da biblioteca.

7. Verificar

Para cada candidato que poderia ser Alto ou Crítico, e qualquer Médio onde for barato:

  • Reproduza-o com um script descartável em um diretório temporário, nunca no repositório. Prefira dependências reais em pequena escala (um banco de dados em memória ou containerizado, um upstream simulado no limite HTTP) em vez de mocks do código em revisão.
  • Para alegações de desempenho, meça: planos de consulta (explain(), EXPLAIN ANALYZE), tempos antes e depois, em um tamanho de dados onde o problema aparece.
  • Para alegações "isso é seguro" sobre estado compartilhado, liste cada leitor e escritor.
  • Limite o esforço: cerca de 15 minutos ou 5 tentativas por candidato. Depois disso, rotule e siga em frente com o motivo. Pare de reproduzir assim que cada candidato Crítico/Alto tiver um rótulo.

Rotule a evidência de cada descoberta:

  • sim: reproduzido por código em execução.
  • parcialmente: parte da alegação reproduzida; a seção diz qual parte.
  • artefato: mostrado por um arquivo, manifesto, camada de imagem ou commit, onde executá-lo não é possível aqui (uma variável de deploy ausente, um segredo no histórico).
  • não: tentado e não foi possível reproduzir; diga por que ainda é relatado, ou descarte-o.
  • não tentado: apenas raciocínio.

Depois, seja honesto:

  • Um candidato sem gatilho plausível neste deploy é descartado, não arquivado como Baixo.
  • Uma inferência permanece rotulada como inferência ("provavelmente", "não pude verificar isso daqui").
  • Um teste que passa apenas porque um mock retorna algo que o código real nunca retorna é uma descoberta sobre o teste, não evidência sobre o código.

8. Classificar

Severidade, julgada pelo impacto e acessibilidade neste deploy. Quando a acessibilidade depende de algo que você não pode verificar (ACLs de rede, quem pode alcançar uma porta), arquive a severidade como se fosse acessível e declare ao lado o que a reduziria.

  • Crítico: explorável agora, com impacto grave.
  • Alto: perda de dados, acesso entre inquilinos ou usuários, ou um recurso principal quebrado.
  • Médio: um bug ou risco real que precisa de condições específicas.
  • Baixo: higiene, manutenibilidade, documentação, desvio de dependência.

Para uma biblioteca, julgue pelo impacto em um consumidor típico. Para uma ferramenta de usuário único, perda de dados ainda é Alta, e uma descoberta de segurança precisa de um invasor realista.

No modo de mudança, também marque cada descoberta:

  • novo: introduzido por esta mudança.
  • pré-existente: presente antes desta mudança.
  • exacerbado: pré-existente, mas esta mudança o agrava.

9. Escrever o Relatório

Cabeçalho

# Revisão de Evidências: <título curto>
**Revisão:** `<sha>` (branches: <branch>, se enviado: <remota>)
**Escopo:** <caminho(s)>
**Modo:** projeto | mudança
**Idioma:** <idioma>
**Público:** mantenedores | solicitante do PR | equipe
**Preocupação nomeada:** <se houver>
**Linhas de código examinadas:** <caminhos completos e examinados>
**Arquivos não examinados:** <por quê>
**Dependências:** <privadas não verificadas, ausentes>
**Versões:** <node, python, go, etc.>
**Comandos executados:** <cada comando e seu status de saída>
**Suposições:** <lista de perguntas em aberto com respostas padrão, se houver>

Resumo Executivo

Uma seção de texto livre (2 a 4 parágrafos) que qualquer pessoa com contexto do negócio pode ler para saber se este código ou mudança deve ser aprovado, o que precisa ser corrigido antes e o que está em boa forma. O primeiro parágrafo é sua recomendação e sua confiança nela.

Saúde da Linha de Base

Uma tabela ou lista com cada verificação e seu resultado:

VerificaçãoStatusNotas
Typecheck✅ passagetsc --noEmit
Lint❌ 14 erroseslint src/
Build✅ passage
Testes✅ 847 passaram, 2 falharam2 falhas pré-existentes na base
Auditoria de dependências⚠️ 3 avisos1 crítico, 2 moderados; todos pré-existentes

Descobertas

Cada descoberta segue este formato:

### [<ID>] <título curto> (<severidade>) (<status>)

**Localização:** <arquivo(s) e linha(s)>
**Evidência:** <sim / parcialmente / artefato / não / não tentado>
**Verificação:** <como foi reproduzida ou por que não foi>
**Recomendação:** <o que fazer>
**Notas:** <se for pré-existente, exacerbado, ou outra coisa>

IDs são sequenciais: F-001, F-002, etc. Status: aberto (não corrigido), corrigido (verificado), rejeitado (discordamos), despriorizado (consciente, não corrigindo agora).

Pontos Fortes

Liste as coisas que estão indo bem, com o mesmo rigor das descobertas. "@class é bem testada" é muito vago; "@class tem 92% de cobertura de linha nos testes de unidade, incluindo caminhos de erro, e todos passam" é evidência.

Suposições

Liste cada suposição feita, de onde veio e qual descoberta ela afeta.

Não Verificado

Liste o que está fora do escopo ou não foi verificado e por quê. Honestidade sobre limitações é evidência de rigor, não de fraqueza.

10. Pós-Processamento

  • Remova worktrees.
  • Limpe .
  • Se o modo era mudança e a saída é no chat, formate o relatório como uma única mensagem. Se o modo era projeto, escreva o relatório como um arquivo no diretório raiz, nomeado evidence-review-<sha-curto ou data>.md.
  • O arquivo de relatório não precisa de frontmatter YAML; o cabeçalho é markdown simples.
  • Se --update <arquivo> foi fornecido, leia o arquivo, atualize os status das descobertas onde aplicável, adicione novas descobertas e reescreva o arquivo. Não remova descobertas; marque-as como obsoleto se não forem mais relevantes.

Habilidades Relacionadas