AGENTS.md

What to write

Write the conventions a new teammate would need: how the code is organized, naming, which helpers and libraries to use, and how errors and tests work.

• Leave out what any experienced engineer already knows, such as “Write readable code”. HeyDeer and coding agents follow common practice already.
• Write one convention per bullet, under a few headings.
• Name the paths, functions and libraries each convention is about.
• Add the reason when it isn’t obvious, so HeyDeer can judge cases the convention doesn’t spell out.
• Keep review-only guidance, such as what HeyDeer should leave alone, in REVIEW.md or review instructions. Put a requirement HeyDeer must verify in every matching pull request in a repository check.

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.

Root and nested files

Add AGENTS.md to the repository root. A directory that needs its own conventions can have its own file, such as src/payments/AGENTS.md.

For each file HeyDeer reads, the AGENTS.md files from the repository root down to that file’s directory apply. A deeper file adds to the ones above it, and wins where they conflict.

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.

HeyDeer reads these files from the pull request, so a pull request that edits them is reviewed with its own version. See What a pull request can change.

Using CLAUDE.md

In a directory without AGENTS.md, HeyDeer reads CLAUDE.md instead. Where a directory has both, HeyDeer reads only AGENTS.md.

Limits

• HeyDeer reads up to 32 KiB of these files, from the root down to the deepest one that applies. A file that crosses the limit is cut off, and deeper files are left out.
• HeyDeer doesn’t follow imports, such as @docs/testing.md in CLAUDE.md. Write the conventions in the file itself.