Como escrever verificações eficazes
Uma boa verificação parece uma regra que um novo colega poderia aplicar lendo o código. Para o formato de arquivo e as opções, consulte Verificações do repositório.
Uma regra decidível por verificação
Coloque cada regra não relacionada em um arquivo próprio. Os problemas encontrados são marcados com o nome do arquivo da verificação, e cada arquivo tem os próprios padrões.
Escreva a regra como uma condição sobre o código: o que a quebra e o que a atende.
Defina o escopo com padrões de arquivo
Adicione padrões de files para que a verificação se aplique apenas onde a regra importa; sem eles, ela se aplica a todos os pull requests. Exclua testes ou fixtures com ! e coloque cada padrão entre aspas no YAML.
Dê o motivo e exemplos
Diga por que a regra importa, para que o HeyDeer possa julgar casos que ela não previu. Descreva o código correto e também o que quebra a regra, com um exemplo curto incorreto e outro correto do seu código.
Mantenha as verificações curtas e ordenadas
A maioria das boas verificações cabe em uma tela. Se várias verificações precisam do mesmo contexto, mova-o para uma skill.
Cada revisão aplica no máximo 10 verificações correspondentes, na ordem dos nomes de arquivo, então coloque números antes das mais importantes, como 10-auth.md. Para uma verificação simples, defina skip_extra_reviewers: true; as revisões Profundas passam a revisá-la como a Padrão faz. Consulte Até 10 verificações por revisão.
Teste em um pull request real
- Faça o merge da verificação. O HeyDeer lê as verificações da branch base.
- Abra um pull request que quebre a regra e confirme que um problema encontrado cita sua verificação. Confirme que o código que segue a regra não recebe nenhum.
- Se a verificação apontar código correto, torne a regra ou os padrões mais rigorosos. Se ela deixar passar um caso, adicione esse caso como exemplo incorreto.
Antipadrões
| Antipadrão | Por que falha | Escreva em vez disso |
|---|---|---|
| Vago: “Siga as boas práticas de design de API.” | Não há uma condição que o código deva cumprir, então os problemas encontrados variam. | “Os handlers em src/api/ validam o corpo da requisição com o schema da rota.” |
| Invisível para o HeyDeer: “Reprove, a menos que a CI passe e a segurança tenha aprovado.” | O HeyDeer não vê resultados de CI nem aprovações formais. | Use as regras de branch do GitHub para exigir CI e aprovações. |
| Executar algo: “Rode os testes e informe o resultado.” | O HeyDeer nunca executa código, testes ou builds. | “Alterações em src/billing/ incluem um teste que exercita a função alterada.” |
| Formatação: “Use indentação de dois espaços e ordene os imports.” | Um formatador ou linter aplica isso com exatidão. | Execute essas ferramentas na CI. |
| Especulação: “Aponte qualquer coisa que possa ser lenta.” | Sem um padrão concreto, os problemas encontrados viram opiniões. | “Um loop não deve fazer uma consulta ao banco de dados por item; agrupe a consulta.” |
| Várias regras em um arquivo: “Verifique autenticação, logs, nomenclatura e testes.” | Os problemas encontrados compartilham um único rótulo, e as regras não podem ter escopos separados. | Um arquivo por regra, cada um com os próprios padrões. |
Antes e depois
Antes:
---
files: "src/**"
---
Follow API best practices. Make sure endpoints are secure, fast,
and well tested, and that naming is consistent. Run the test suite
and fail if anything breaks.Depois, como .agents/checks/20-api-workspace-scope.md:
---
files:
- "src/api/**/*.ts"
- "!**/*.test.ts"
---
# API handlers scope queries to the caller’s workspace
Every query in an API handler that reads or writes a table with a
`workspace_id` column must filter on the workspace returned by
`requireWorkspace()`. Without that filter, one customer can read
or change another customer’s data.
Fail when a handler queries such a table without that filter.
Pass when every such query filters on the workspace, or when the
handler only touches tables without a `workspace_id` column.
Incorrect:
```ts
const invoice = await db.query.invoices.findFirst({
where: eq(invoices.id, id),
});
```
Correct:
```ts
const { workspaceId } = await requireWorkspace(req);
const invoice = await db.query.invoices.findFirst({
where: and(eq(invoices.id, id), eq(invoices.workspaceId, workspaceId)),
});
```A reescrita mantém uma única preocupação, a limita aos handlers de API, diz o que falha e o que passa e explica o risco. As outras preocupações viram verificações próprias ou passam para ferramentas e para o AGENTS.md.