chukaofili/agent-plugins

PRs Empilhados

O orçamento de tamanho

Busque cerca de 300 linhas alteradas por PR, com 500 como teto. Nesse tamanho um humano consegue reter toda a alteração na cabeça para uma revisão rápida, e agentes de revisão retornam conclusões limpas e específicas, em vez de passarem superficialmente.

O que conta: código escrito à mão e testes.

O que não conta: lockfiles, código gerado (migrations, codegen, saída OpenAPI), snapshots, fixtures e arquivos vendored. Eles são apenas skimados, não lidos. Liste quais arquivos são gerados no corpo do PR para que o revisor saiba o que pular.

Divida antes de escrever, não depois. A divisão é decidida no plano (veja coding-process). Se um estágio planejado ultrapassar 500, replaneje-o. Costuras comuns:

• Testes podem vir como seu próprio estágio. Por exemplo, lógica com testes unitários e de integração, depois UI com testes E2E.
• Schema ou modelo de dados, depois o serviço que o utiliza, depois a superfície da API, depois a UI.
• Um refactor que torna a alteração fácil, depois a alteração em si.
• Uma sincronização de documentação muito grande para acompanhar recebe um estágio apenas de docs no topo.

Alterações genuinamente indivisíveis, como uma migration coesa ou uma renomeação em 80 arquivos, podem ultrapassar. O corpo do PR explica o motivo e aponta o revisor para a parte que realmente precisa ser lida.

Commits atômicos continuam sendo válidos dentro de cada PR. O orçamento é por PR e não substitui a higiene de commits.

Empilhamento

Trabalhos multi-estágio são entregues como uma pilha de PRs, nunca como um único branch carregando todo o plano. Cada PR é um estágio e ele mira o branch do estágio anterior, não main. Assim, cada diff que o revisor vê é apenas a alteração daquele estágio, e um estágio arriscado (uma migration, uma mudança de autenticação) pode ser revisado e revertido individualmente.

• Ramifique cada estágio a partir do head do estágio anterior. Apenas o PR inferior mira main:

  gh pr create --base <branch-estagio-anterior>
  

• Anote a posição no corpo de cada PR (Empilhado em #123) para que um revisor que abra um fora de ordem saiba o que está vendo.
• Faça landing de baixo para cima. Quando um branch base muda (um fix de revisão, ou a base sendo mesclada), faça rebase dos branches acima dele e force-push nesses. Force-push nos seus próprios branches não mesclados da pilha é rotineiro. Force-push em main ou em um branch compartilhado nunca é.
• Depois que qualquer PR na pilha for mesclado, sincronize o restante na nova base antes de iniciar o próximo estágio.
• Correções de uma revisão ou verificação em uma superfície de UI são enviadas como um novo estágio no topo, para que a construção e as correções permaneçam separadamente revisáveis.
• Ferramentas de empilhamento como gh stack, Graphite ou git-town são opcionais. Git puro e gh são suficientes.

Revisão sequencial

Revise uma pilha um estágio por vez. Solicite revisão do revisor do projeto (veja Gates do Projeto em AGENTS.md) apenas no PR inferior, depois:

1. Solicite revisão naquele único estágio.
2. Trate cada observação (veja abaixo).
3. Solicite revisão novamente e repita até que o estágio seja aprovado.
4. Só então solicite revisão no próximo estágio acima.

Não solicite revisão na pilha inteira de uma vez. Uma observação no estágio 1 pode invalidar comentários já escritos nos estágios 2 a 5, e a revisão sequencial mantém o esforço do revisor limitado.

Se um estágio emperrar (sem revisão voltando, ou uma observação que exija uma decisão de produto), sinalize-o e continue construindo os estágios acima localmente onde eles não dependem da resposta.

Lidando com observações de revisão (qualquer PR, empilhado ou não)

• Verifique cada observação tecnicamente antes de agir. Leia o código ao qual ela aponta e reproduza o problema se possível.
• Corrija-o ou conteste com argumentos. Revisores, humanos ou bots, estão confiantemente errados como um evento normal. Fazer uma alteração ruim para parecer agradável é pior do que argumentar. Sem concordância performática.
• Julgue observações pela probabilidade real. Conteste correções para cenários que não podem realisticamente acontecer e sugestões que adicionam complexidade sem ganho real.
• Não adicione testes que não possam falhar. Um teste que passa independentemente de o bug existir é ruído. Execute-o contra o código quebrado primeiro (veja testing).
• Responda a cada observação para que o revisor possa ver o que aconteceu com ela: corrigida em qual commit, ou por que não.