Verificações do repositório

Gere verificações automaticamente

No painel, escolha Configurar verificações do repositório em Primeiros passos. O HeyDeer lê o repositório e os pull requests anteriores e depois abre um pull request que adiciona verificações. Não usa créditos.

Para que seu próprio agente de código as escreva, passe este prompt para ele:

Add HeyDeer repository checks to this repository following the guide below, and open a pull request with them. If it needs no new check, explain why instead.

# Write repository checks

A check is a Markdown file in `.agents/checks/` that states a requirement. Each check adds a reviewer of its own to every pull request that changes the files it covers, on top of a general review that already looks for common bugs and security issues. Add one only for a requirement that is specific to this codebase, costly to miss and easy to overlook.

1. Learn what the team cares about: the code, AGENTS.md or CLAUDE.md, REVIEW.md, the checks already in `.agents/checks/`, and as much of the merged pull requests and their review discussions as you need to see what reviewers keep asking for and where bugs were fixed.
2. Choose the requirements, usually one or two, leaving out what existing checks cover. Give each check one requirement or a few closely related ones, and keep one requirement in one check.
3. Write each check as `.agents/checks/<name>.md`, its name starting with a letter or digit and using only letters, digits, `.`, `_` and `-`, excluding every case variant of `README.md`:
   - Start with YAML frontmatter whose `files` lists glob patterns, relative to the repository root, for the files where the requirement can break. A pattern without a slash matches in any folder, a `!` prefix excludes, and the last matching pattern decides; exclusions need an including pattern. Compare the patterns with `git ls-files` so they match those files and little else. Add `skills` only to name repository skills the check needs.
     ```
     ---
     files:
       - "src/api/**/*.ts"
       - "!**/*.test.ts"
     ---
     ```
   - Below it, state the requirement as a condition on the code: what breaks it, what satisfies it and why it matters, with a short incorrect and correct example from this codebase. Most checks fit on a screen; a file can be up to 16000 bytes.
   - Write it in the language of the repository's own Markdown, such as its README and AGENTS.md, even when you write the pull request in another language.
4. In the pull request, say what each check covers and why it is worth a reviewer. Link the discussions that led to a check when there are any.

Adicionar uma verificação

1. Crie um arquivo Markdown em .agents/checks/, como api-workspace-scope.md.
2. Comece o arquivo com um frontmatter que liste em files os arquivos cobertos pela verificação.
3. Abaixo do frontmatter, escreva o requisito: o que o viola, o que o atende e por que ele importa.
4. Faça commit do arquivo em um pull request. O HeyDeer lê as verificações do pull request, então a nova verificação já vale para a revisão desse mesmo pull request. Consulte O que um pull request pode alterar.

.agents/checks/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)),
});
```

• Cada arquivo .md diretamente na pasta cujo frontmatter tenha files é uma verificação. O HeyDeer ignora os demais arquivos da pasta, como README.md e verificações escritas para outras ferramentas de revisão.
• Os nomes de arquivo começam com uma letra ou um dígito e usam apenas letras, dígitos, ., _ e -.

Escrever uma verificação eficaz

Cada verificação correspondente tem um revisor próprio, então ela é minuciosa, mas usa mais créditos. Reserve as verificações para requisitos caros de deixar passar e fáceis de ignorar, e coloque o resto no REVIEW.md ou no AGENTS.md.

• Escreva o que é específico do seu código. Toda revisão já procura bugs e problemas de segurança comuns, então uma verificação como “As consultas devem ser seguras” aumenta o custo sem encontrar mais.
• Dê a cada verificação um requisito, ou alguns intimamente relacionados. Uma verificação que junta requisitos sem relação analisa cada um com menos profundidade.
• Não divida um requisito entre várias verificações, e limite files aos lugares onde o requisito pode ser quebrado, para que a verificação rode só onde importa.
• Escreva o requisito como uma condição sobre o código: o que o quebra, o que o atende e por que ele importa, para que o HeyDeer consiga julgar casos que você não previu. Adicione um exemplo curto incorreto e um correto do seu código.
• A maioria das boas verificações cabe em uma tela. Se várias verificações precisam do mesmo contexto, mova-o para uma skill.
• Teste uma nova verificação em um pull request que viole o requisito e confirme que um problema encontrado cita sua verificação.

Como os resultados aparecem

Quando o código viola uma verificação, o HeyDeer relata um problema encontrado que indica o arquivo da verificação após Verificação do repositório:, no GitHub e no HeyDeer. Uma verificação sem problemas encontrados não acrescenta nada à revisão.

Esses problemas encontrados contam como quaisquer outros para a verificação HeyDeer Review e para a aprovação automática. O resumo da verificação HeyDeer Review também conta as verificações do repositório com falha.

Se o HeyDeer não conseguir concluir uma verificação, a verificação HeyDeer Review mostra Revisão incompleta e falha; solicite outra revisão.

Referência do frontmatter

O frontmatter é um bloco YAML entre duas linhas ---, com as chaves abaixo.

O HeyDeer ignora as demais chaves, como as que outras ferramentas de revisão leem.

Se uma verificação for inválida, por exemplo uma lista de padrões só com exclusões, o HeyDeer a ignora e a indica em Observações da revisão. A revisão é feita mesmo assim, mas o HeyDeer não a aprova automaticamente.

Quais arquivos uma verificação cobre

Uma verificação se aplica quando pelo menos um arquivo alterado corresponde a ela, e o HeyDeer a concentra nesses arquivos.

• Use files: ["**"] para abranger todos os arquivos alterados.
• Os padrões são relativos à raiz do repositório e aceitam *, ** e {a,b}. Um padrão sem barra, como *.sql, corresponde em qualquer pasta.
• Os padrões são aplicados em ordem, e o último que corresponde a um arquivo decide; assim, um padrão posterior pode incluir arquivos que uma exclusão anterior removeu.
• Arquivos gerados nunca correspondem.

Se uma verificação parecer ignorada, consulte Solução de problemas.

Limites

Um espaço de trabalho pode iniciar até 30 tarefas de geração de verificações em qualquer período de 30 dias, somando todos os seus repositórios, incluindo tarefas que falham ou são canceladas.

Um arquivo de verificação pode ter até 16.000 bytes.

Uma revisão executa no máximo 10 verificações correspondentes, na ordem dos nomes de arquivo. O HeyDeer lista as demais em Observações da revisão, a verificação HeyDeer Review mostra Revisão incompleta, e o HeyDeer não aprova essa revisão automaticamente.

Restrinja ou combine verificações para que menos delas correspondam. Para escolher quais são executadas primeiro, adicione números no início dos nomes de arquivo, como 10-auth.md.

Quando uma verificação é inválida

Arquivos sem frontmatter ou sem a chave files são ignorados. YAML inválido, frontmatter acima do limite de tamanho, padrões files vazios e padrões apenas com exclusões são ignorados e relatados.

Para verificações que correspondem a arquivos alterados, o HeyDeer também valida o nome e o tamanho do arquivo e os nomes das habilidades. Verificações inválidas são ignoradas e listadas em Observações da revisão. A revisão continua, mas o HeyDeer não a aprova automaticamente.

Corrija a verificação no pull request e depois comente @heydeer review.