🔬 Avançado — Revisor de PRs com Claude Code

Um plugin Claude Code que recebe um número de PR como input, faz checkout isolado via git worktree e entrega um relatório Markdown estruturado com findings por severidade.

Revisões de código automáticas economizam horas de revisão humana. Compreender o escopo evita feature creep durante o build incremental.

Plugin scope, input/output contract, PR number como parâmetro, relatório como artefato.

git worktree permite criar um segundo checkout do repositório em um diretório temporário sem interferir no working tree principal — ideal para revisar uma branch de PR enquanto você trabalha em outra.

Fazer checkout do PR na branch atual contamina seu trabalho em progresso. O worktree resolve isso sem stash ou commit temporário.

git worktree add, diretório /tmp/pr-review-NNN, EXIT trap para cleanup garantido, isolamento de branches.

Camada 1 — Isolamento: worktree setup e cleanup. Camada 2 — Análise: loop de revisão com 3 personas e estado YAML. Camada 3 — Relatório: consolidação de findings e integração GitHub.

Separar responsabilidades em camadas permite testar e iterar cada uma independentemente. Se o worktree falha, a lógica de análise não é afetada.

Separation of concerns, camadas independentes, contratos entre camadas, testabilidade por camada.

O SPEC.md define: ciclo de vida do revisor (SETUP→REVIEWING→SUMMARIZING→DONE), schema do estado YAML, estrutura de arquivos esperada, invariantes de segurança e contrato dos hooks.

O SPEC serve como fonte de verdade para todos os 5 prompts de build. Sem ele, cada prompt reimagina a arquitetura.

Fonte de verdade, ciclo de vida, schema YAML, invariantes, contrato de hook.

O file tree completo do plugin: claude.json, hooks/stop-hook.sh, scripts/setup-worktree.sh, scripts/cleanup-worktree.sh, state/review.yaml, .claudex/reviews/.

Saber o destino antes de começar evita decisões de naming inconsistentes entre prompts. Cada arquivo tem uma responsabilidade única.

File tree, responsabilidade por arquivo, convenções de naming, separação de scripts e estado.

Checklist para validar o SPEC antes do primeiro prompt: ciclo de vida coberto? Schema com todos os campos? Invariantes explícitas? File tree definido? Contrato dos hooks documentado?

Um SPEC incompleto gera ambiguidades que o Claude resolve de formas diferentes a cada prompt, criando inconsistências.

SPEC completeness, checklist de validação, ambiguidade vs decisão explícita, revisão do SPEC.

O Prompt 01 entrega o scaffold completo: claude.json com hooks registrados, stub do stop-hook com fail-open, scripts de setup e cleanup do worktree.

O scaffold define o contrato externo. Acertar aqui evita reescritas de estrutura nos prompts 2 a 5.

Plugin scaffold, claude.json manifest, fail-open stub, setup/cleanup scripts.

O texto exato do primeiro prompt de build, com todas as instruções de entrega, restrições e verificações que o Claude deve seguir.

Ver o prompt real mostra como estruturar instruções para Claude: o que entregar, restrições claras e como verificar antes de avançar.

Estrutura de prompt de build, seções Entregue/Restrições/Verificação, prompts atômicos.

claude.json define os hooks registrados. hooks/stop-hook.sh é o stub fail-open. scripts/setup-worktree.sh cria o worktree. scripts/cleanup-worktree.sh remove via EXIT trap.

Cada arquivo tem responsabilidade única. Claude.json é o manifest; os scripts são lógica de infraestrutura separada do hook.

claude.json, hook registration, script separation, manifest-driven plugins.

`git worktree add /tmp/pr-review-$PR_NUMBER origin/pr-branch` cria um segundo working tree. O EXIT trap chama cleanup-worktree.sh para `git worktree remove --force` mesmo se o script falhar.

Sem o EXIT trap, worktrees órfãos acumulam em /tmp e o repositório fica em estado inconsistente.

git worktree add/remove, EXIT trap, cleanup garantido, --force para remoção.

O setup-worktree.sh verifica com `git worktree list` antes de criar. Se já existe, reutiliza. Se criação falha por qualquer motivo, retorna exit 0 (fail-open) e loga o erro.

Idempotência evita falhas em reruns. Fail-open evita que um erro de infraestrutura bloqueie o desenvolvedor.

Idempotência, fail-open, verificação antes de criar, reuse vs recreate.

Checklist: `claude --version` carrega o plugin, `bash -n hooks/stop-hook.sh` passa, `bash scripts/setup-worktree.sh 123` cria worktree em /tmp/pr-review-123, script de cleanup remove corretamente.

Verificar o Prompt 01 antes de avançar garante que a base está sólida. Bugs de scaffold são baratos aqui e caros depois.

Verificação por camada, smoke test de scaffold, lint de bash, test de worktree manual.

O Prompt 02 cria o sistema de estado persistente: state/review.yaml com schema completo, helpers de leitura/escrita atômica, CAS e lockfile para exclusão mútua.

O estado precisa existir e estar correto antes que o hook possa tomar decisões. Construir estado primeiro é o padrão correto.

Estado persistente, YAML schema, helpers de I/O, CAS, lockfile.

O texto exato do segundo prompt de build, com instruções para criar o schema YAML, os helpers de escrita atômica e o mecanismo de CAS.

A forma como você pede CAS e escrita atômica determina se Claude implementa correto. Prompts explícitos produzem implementações explícitas.

Prompt explícito, instruções de CAS, atomic write spec, schema-first.

Campos: pr_number (int), worktree_path (string), status (SETUP|REVIEWING|SUMMARIZING|DONE), round (int), max_rounds (int), findings (list), started_at (epoch).

Um schema bem definido evita que cada prompt interprete o estado de forma diferente. Cada campo tem tipo e propósito explícito.

YAML schema, campos tipados, status enum, round tracking, findings list.

Escrita atômica: escrever em .review.yaml.tmp e renomear. CAS: ler versão atual, verificar que não mudou, depois escrever. Se versão mudou, abort com erro.

Claude Code pode ser interrompido a qualquer momento. CAS garante que duas instâncias paralelas não corrompem o estado simultaneamente.

Atomic rename, compare-and-swap, version field, concurrent write protection.

`flock -n state/review.lock` tenta adquirir lock exclusivo. Se já existe, retorna imediatamente com erro — não espera. O lock é liberado via EXIT trap.

Sem lockfile, abrir duas abas do Claude Code no mesmo repo dispara dois revisores em paralelo que corrompem o estado um do outro.

flock, exclusão mútua, lock não-bloqueante, stale lock detection.

Testes: escrever estado, ler de volta, confirmar que campos batem. Simular conflito de CAS (modificar versão entre ler e escrever), confirmar abort. Testar lockfile com duas chamadas simultâneas.

CAS e atomicidade são difíceis de debugar depois. Testar agora, com o sistema simples, é muito mais eficiente.

Teste de CAS, conflict simulation, concurrent lock test, verificação de estado.

O Prompt 03 substitui o stub pelo engine real: o Stop Hook lê o estado YAML e decide BLOCK (continuar loop) ou APPROVE (encerrar sessão) com base na fase atual.

Este hook é o coração do revisor. Sem ele, o sistema executa uma única revisão — não um loop controlado por estado.

Stop Hook, BLOCK vs APPROVE, reason como instrução, ciclo de vida controlado.

O texto exato do terceiro prompt de build com as instruções para implementar o case statement por fase, a lógica de BLOCK com reason estruturado e o ERR trap obrigatório.

Ver como especificar um case statement de hook mostra o padrão para controle de fluxo baseado em estado persistente.

Case statement por fase, ERR trap, JSON reason, prompt spec para hooks.

SETUP: cria worktree e inicializa estado. REVIEWING: loop de N rodadas com personas. SUMMARIZING: consolida findings em relatório. DONE: cleanup e APPROVE.

Estados explícitos evitam transições implícitas que criam loops infinitos ou pulos de fase. Cada transição tem uma condição clara.

State machine, transições explícitas, condições de transição, estado terminal DONE.

O hook escreve um runner script em .claudex/runners/PR-NNN-round-N.sh que monta o diff do PR, o contexto da persona e invoca `claude --print` com o prompt de revisão.

Separar o runner do hook permite testar cada rodada de revisão independentemente, sem precisar disparar o hook completo.

Runner script, claude --print, diff injection, contexto de persona, separação hook/runner.

`gh pr view $PR_NUMBER --json title,body,files` captura metadados. `git diff origin/main...HEAD` no worktree captura o diff. Ambos são injetados no prompt do runner.

O contexto completo (título, descrição, diff, arquivos modificados) é o que permite ao Claude fazer revisão significativa em vez de genérica.

gh cli, pr metadata, git diff no worktree, context injection, prompt enrichment.

Criar repo de teste com branch de PR sintético. Disparar o hook manualmente. Verificar: SETUP→REVIEWING, runner escrito, BLOCK com reason. Disparar novamente: round incrementa. Estado final DONE = APPROVE.

O loop é a parte mais complexa do sistema. Testar com PR sintético (sem custo de API) valida a lógica de transição antes de usar créditos reais.

PR sintético, smoke test manual, verificação de transições, teste sem API call.

O Prompt 04 adiciona rotação de personas ao runner (round 1 = Author, round 2 = Reviewer, round 3 = Security) e o código que consolida os findings em PR-NNN.md.

Personas transformam uma revisão genérica em três perspectivas especializadas. O relatório estruturado torna os findings acionáveis.

Persona rotation, round-based context, findings consolidation, relatório estruturado.

O texto exato do quarto prompt com as instruções para implementar os system prompts das 3 personas, a extração de findings estruturados e o template do relatório final.

A especificação das personas determina a qualidade da revisão. Prompts de persona bem escritos ativam heurísticas diferentes no modelo.

System prompt por persona, findings schema, structured extraction, template de relatório.

Author (round 1): avalia intenção e completude da implementação. Reviewer (round 2): procura bugs, edge cases e violações de contrato. Security (round 3): foca em vulnerabilidades, injection, autenticação.

Cada persona ativa um conjunto diferente de heurísticas. Author encontra coisas que Reviewer nunca procuraria, e vice-versa.

Author perspective, bug hunting, security review, multi-perspective coverage, perspectiva complementar.

Relatório com: sumário executivo, findings agrupados por arquivo, cada finding com severidade (CRITICAL/HIGH/MEDIUM/LOW), linha, descrição e sugestão de fix. Métricas no final.

Um relatório sem estrutura é um dump de texto. Severidade + agrupamento por arquivo + sugestão de fix tornam a revisão acionável imediatamente.

Severity levels, file grouping, actionable findings, sumário executivo, métricas de revisão.

O relatório é salvo em .claudex/reviews/PR-NNN.md com timestamp no nome para histórico. Pode ser versionado no repo ou listado pelo comando /pr-reviewer:list.

Salvar como artefato permite comparar revisões ao longo do tempo e compartilhar com o time sem precisar manter a sessão do Claude Code aberta.

Artefato persistente, timestamp naming, histórico de revisões, relatório compartilhável.

Rodar o revisor em um PR de teste com bugs conhecidos intencionais. Verificar: as 3 personas rodaram? Os bugs conhecidos aparecem no relatório? Severidades corretas? Relatório salvo em .claudex/reviews/?

Validar com bugs conhecidos é o teste mais confiável: se o revisor não encontra o que você plantou, há problema nas personas ou no diff injection.

PR de teste com bugs plantados, verificação de cobertura de personas, validação de formato do relatório.

O Prompt 05 é o safety pass final: audita o código contra as 6 primitivas de segurança, adiciona o comando `gh pr comment` para postar o relatório e cria o arquivo de configuração por repo.

Todo sistema que vai para produção precisa de um safety pass explícito. Sem ele, basta uma edge case não coberta para o plugin corromper dados ou bloquear trabalho.

Safety pass, auditoria de primitivas, production readiness, gh pr comment.

O texto exato do quinto prompt com as instruções para auditar cada script contra as 6 primitivas, adicionar gh pr comment e criar review-config.yaml.

A estrutura do safety pass — auditar por primitiva, corrigir, adicionar integrações — é um padrão reutilizável para qualquer plugin.

Audit por primitiva, safety checklist, integration layer, config file.

6 primitivas: (1) ERR trap em todos os scripts, (2) CAS em todas as escritas de estado, (3) lockfile não-bloqueante, (4) varredor de stale locks, (5) validação de path absoluto, (6) timeout em subprocessos.

Cada primitiva cobre uma classe de falha diferente. Sem o varredor de stale locks, um crash deixa o sistema permanentemente travado.

ERR trap, CAS universal, stale lock sweeper, path traversal prevention, subprocess timeout.

`gh pr comment $PR_NUMBER --body-file .claudex/reviews/PR-NNN.md` posta o relatório diretamente no PR do GitHub. O comentário inclui badge de severidade no topo.

Postar automaticamente elimina o passo manual de copiar o relatório. A revisão aparece no contexto onde o time já está trabalhando.

gh pr comment, --body-file, badge de severidade, integração automatizada, PR comment thread.

.claude/review-config.yaml permite configurar: max_rounds, personas ativas, paths a ignorar, severidade mínima para comment no PR, timeout por rodada.

Hardcoded defaults não funcionam para todos os repos. Configuração por repo permite que times ajustem o revisor ao seu contexto sem modificar o plugin.

Config por repo, YAML config, override de defaults, gitignore vs versionado, config discovery.

Teste E2E completo: criar PR de teste no GitHub, rodar o plugin com `/pr-reviewer 123`, verificar que as 3 rodadas completam, relatório salvo e postado como comentário no PR real.

O teste E2E é o único que valida a integração ponta a ponta: Claude Code → hooks → worktree → runner → relatório → GitHub. Cada ponto de integração pode falhar.

E2E test, integração ponta a ponta, PR de teste no GitHub, validação do ciclo completo.