AGENTS.md

O que escrever

Escreva as convenções de que um novo colega de equipe precisaria: como o código é organizado, a nomenclatura, quais helpers e bibliotecas usar e como funcionam os erros e os testes.

• Deixe de fora o que qualquer engenheiro experiente já sabe, como “Escreva código legível”. O HeyDeer e os agentes de código já seguem as práticas comuns.
• Escreva uma convenção por item e agrupe-as sob alguns títulos.
• Cite os caminhos, as funções e as bibliotecas de que cada convenção trata.
• Inclua o motivo quando ele não for óbvio, para que o HeyDeer consiga avaliar casos que a convenção não detalha.
• Deixe no REVIEW.md ou nas instruções de revisão as orientações que valem só para a revisão, como o que o HeyDeer deve deixar de lado. Coloque em uma verificação do repositório um requisito que o HeyDeer precisa verificar em todo pull request correspondente.

AGENTS.md

# Conventions

## Structure

- API handlers live in src/api/, one file per resource.
- Background jobs live in src/jobs/ and are idempotent, because
  the queue can run a job twice.

## Helpers

- Retries use retry() from src/lib/retry.ts, which adds backoff.
- Read the current time through now() from src/lib/clock.ts, so
  tests can set it.

## Errors and tests

- Return client errors through AppError with a stable code, such
  as new AppError('INVOICE_NOT_FOUND', 404).
- Each new API handler has a test in tests/api/ that runs against
  a real database.

Arquivos na raiz e em subdiretórios

Adicione o AGENTS.md à raiz do repositório. Um diretório que precise de convenções próprias pode ter o próprio arquivo, como src/payments/AGENTS.md.

Para cada arquivo que o HeyDeer lê, valem os arquivos AGENTS.md da raiz do repositório até o diretório desse arquivo. Um arquivo mais profundo complementa os que estão acima dele e prevalece quando há conflito.

src/payments/AGENTS.md

# Payments

- Every call to chargeCard() passes an idempotency key derived
  from the order ID, so a retried request can't charge twice.
- Amounts are integers in cents. Never use floating point for money.

O HeyDeer lê esses arquivos do pull request, então um pull request que os edita é revisado com a versão que ele mesmo contém. Consulte O que um pull request pode alterar.

Como usar o CLAUDE.md

Em um diretório sem AGENTS.md, o HeyDeer lê o CLAUDE.md. Quando um diretório tem os dois, o HeyDeer lê apenas o AGENTS.md.

Limites

• O HeyDeer lê até 32 KiB desses arquivos, da raiz até o arquivo mais profundo que se aplica. Um arquivo que ultrapassa o limite é cortado, e os arquivos mais profundos ficam de fora.
• O HeyDeer não segue importações, como @docs/testing.md no CLAUDE.md. Escreva as convenções no próprio arquivo.