AGENTS.md

写些什么

写下新同事需要了解的约定：代码如何组织、如何命名、该用哪些辅助函数和库，以及错误处理和测试怎么做。

• 不要写有经验的工程师都知道的东西，例如“代码要易读”。HeyDeer 和编程智能体本来就遵循通行做法。
• 每个要点写一条约定，并归入几个标题下。
• 写明每条约定涉及的路径、函数和库。
• 理由不明显时，请写明理由，这样 HeyDeer 才能判断约定没有明确写到的情况。
• 只与审查相关的指导（例如 HeyDeer 不必理会哪些内容）请放在 REVIEW.md 或审查指令中。HeyDeer 必须在每个匹配的 PR 中核实的要求，请写成仓库检查。

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.

根目录文件与嵌套文件

在仓库根目录添加 AGENTS.md。需要单独约定的目录可以有自己的文件，例如 src/payments/AGENTS.md。

对于 HeyDeer 读取的每个文件，从仓库根目录到该文件所在目录的所有 AGENTS.md 都会生效。层级更深的文件是对上层文件的补充，两者冲突时以更深的文件为准。

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 从 PR 中读取这些文件，所以修改了这些文件的 PR 会按 PR 里的版本审查。参见 PR 可以更改哪些内容。

使用 CLAUDE.md

如果目录中没有 AGENTS.md，HeyDeer 会改为读取 CLAUDE.md。如果目录中两者都有，HeyDeer 只读取 AGENTS.md。

限制

• HeyDeer 从根目录开始，逐层读取到生效的最深一层文件，总共最多读取 32 KiB。超出上限的文件会被截断，更深层的文件不会被读取。
• HeyDeer 不会加载导入的内容，例如 CLAUDE.md 中的 @docs/testing.md。请把约定直接写在文件里。