Boas Práticas

​

Um agente por assunto

​

Escreva instruções focadas

1. O que procurar, de forma concreta: “imports de src/domain dentro de src/http”, e não “problemas de arquitetura”.
2. O que ignorar: estilo, nomes, o que outro agente ou a Kody já cobre.
3. Que prova um apontamento precisa: “cite o arquivo que mostra o padrão existente”, “mostre o caminho da origem até o uso”, “cite a regra de docs/ledger.md”.

Review the code for quality and best practices.

Flag code in src/http/** that imports from src/infra/** directly.
Handlers reach infrastructure only through the ports in src/domain/ports.
Ignore tests, generated code and naming.
For each finding, name the port the handler should use, or say that
none exists yet.

​

Diga que prova um apontamento precisa

• Uma regra num guia: vincule o doc ou a skill e peça para o agente citar a regra. A citação é conferida no guia na branch de destino.
• Um resultado de CLI: as linhas da saída que citam o arquivo entram no comentário como evidência.
• Uma regra do ast-grep: um match vale como prova sozinho, sem checagem pelo modelo.

​

Deixe os globs explícitos

• Preencha Files com o código que importa para o agente: src/payments/**, e não vazio. Um agente sem globs roda em todo pull request.
• Use Except para testes, fixtures e código gerado.
• Nomeie os arquivos explicitamente quando eles estão nos caminhos ignorados e o agente ainda precisa lê-los: package.json, infra/**/*.tf. Um glob amplo como **/*.ts, ou uma pasta como src/**, não chega em arquivos ignorados.
• Num diretório, os globs continuam começando na raiz do repositório.

​

Skill ou doc?

​

Teste num pull request real antes de ligar

1. Escolha um pull request recente que toque os arquivos do agente, de preferência um em que você sabe o que um bom revisor diria.
2. Rode o Try it. Leia as chamadas de ferramenta, as skills que ele abriu e cada apontamento.
3. Ajuste as instruções, os globs ou a severidade mínima e rode de novo.
4. Ligue o agente quando os comentários que seriam postados forem os que você quer ver num pull request.

​

Leia os motivos de descarte

​

Controle o volume

• Defina Max comments per pull request em agentes que podem gerar muitos apontamentos, como um agente de código duplicado. Ficam os mais graves.
• Use One PR comment para agentes cujos apontamentos ficam melhores juntos, como um relatório de cobertura.
• Use Suggested fix: Never quando a correção seria um palpite, como mover algo de camada.