Boas práticas
Como escrever orientações de revisão
As instruções de revisão e o AGENTS.md funcionam melhor como regras curtas e específicas que um novo colega conseguiria seguir. Para escolher entre eles, consulte Onde cada regra deve ficar.
Comece por revisões reais
Deixe o HeyDeer revisar alguns pull requests antes de escrever qualquer coisa. Adicione uma regra quando algo que ele deixa passar ou um comentário indesejado se repetir, poucas regras por vez, e leia as próximas revisões para ver o efeito.
Escreva regras curtas e específicas
- Agrupe as regras sob alguns títulos, como Prioridades, Deixar de lado e Convenções.
- Escreva uma regra por item e cite os caminhos, as funções e as bibliotecas de que ela trata.
- Adicione o motivo quando ele não for óbvio.
- Mantenha as exclusões restritas: “Não comente sobre arquivos em scripts/one-off/”, e não “Não comente sobre scripts”, o que também esconde problemas reais.
- Mostre algumas linhas de código incorreto e correto do seu código.
- Fique bem abaixo do limite de 12.000 caracteres. Quando as instruções crescerem, mova as convenções para o AGENTS.md e os requisitos obrigatórios para as verificações do repositório.
O que não incluir
| Não inclua | Por quê | Em vez disso |
|---|---|---|
| Regras de formatação, como indentação ou ordem dos imports | Um formatador ou linter as aplica com exatidão. | Execute essas ferramentas na CI. |
| “Seja mais minucioso”, “Não deixe passar nada” | Elas não dão ao HeyDeer nada específico sobre o que agir. | Cite os riscos que importam, ou use a profundidade Profunda ou um Escopo do feedback mais amplo. |
| Definição de persona, como “Você é um engenheiro de segurança sênior” | Um papel não diz o que procurar. | Escreva as regras que essa pessoa aplicaria. |
| “Bloqueie o merge se…”, “Aprove PRs pequenos” | As instruções moldam a revisão, não o que o HeyDeer faz no GitHub. | Use Reprovar a verificação quando forem encontrados problemas com uma regra de branch, e a Aprovação automática. |
| “Rode os testes”, “Faça o build do projeto primeiro” | O HeyDeer lê código. Ele nunca executa código, testes ou builds. | Peça o que o HeyDeer consegue verificar lendo. |
| Links, como “Siga os padrões da nossa wiki” | O HeyDeer não consegue abrir links da web. | Copie as regras que importam, mantenha o documento no repositório ou conecte um servidor MCP. |
| “Escreva os problemas encontrados em japonês” | O idioma é uma configuração que também abrange resumos e títulos. | Defina o Idioma da revisão. |
Antes e depois
Antes:
You are a world-class senior engineer. Be extremely thorough and
never miss a bug. Follow our standards at
https://wiki.example.com/engineering/standards. Use 2-space
indentation. Write all comments in Japanese. Run the tests before
you review, and block the PR if anything is wrong.Depois:
## Priorities
- Code under src/payments/ is high risk. Every call to chargeCard()
passes an idempotency key derived from the order ID, so a retried
request cannot charge twice.
- Retries use retry() from src/lib/retry.ts, which adds backoff.
Replace hand-written retry loops with it.
## Leave alone
- Files under scripts/one-off/. They run once by hand and are deleted.
- Formatting. The formatter enforces it in CI.
## Conventions
- Return client errors through AppError with a stable code.
Incorrect:
```ts
return Response.json({ error: err.message }, { status: 500 });
```
Correct:
```ts
throw new AppError('INVOICE_NOT_FOUND', 404);
```A reescrita transforma a persona e o link da wiki em regras específicas. Todo o resto vai para os lugares indicados na tabela acima.