AGENTS.md

書く内容

新しいチームメンバーが知っておくべき規約を書きます。コードの構成、命名、使用するヘルパーやライブラリ、エラーとテストの扱い方などです。

• 「読みやすいコードを書く」のように、経験のあるエンジニアなら誰でも知っていることは省きます。HeyDeer もコーディングエージェントも、一般的なプラクティスにはすでに従っています。
• いくつかの見出しの下に、箇条書き 1 項目につき 1 つの規約を書きます。
• 各規約が対象とするパス、関数、ライブラリを明記します。
• 理由が明らかでない場合は理由を添えます。そうすれば、規約に明記されていないケースも HeyDeer が判断できます。
• HeyDeer が触れなくてよい点など、レビューだけに関するガイダンスは REVIEW.md かレビューへの指示に書きます。該当するすべてのプルリクエストで HeyDeer に必ず検証させたい要件は、リポジトリのチェックに書きます。

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 はこれらのファイルをプルリクエストから読み込むため、これらを編集するプルリクエストは、編集後のバージョンでレビューされます。プルリクエストで変更できるものを参照してください。

CLAUDE.md を使う場合

AGENTS.md がないディレクトリでは、HeyDeer は代わりに CLAUDE.md を読み込みます。両方があるディレクトリでは、HeyDeer は AGENTS.md だけを読み込みます。

制限

• HeyDeer は、ルートから適用される最も深いファイルまで、これらのファイルを合計 32 KiB まで読み込みます。上限をまたぐファイルは途中で切り捨てられ、それより深いファイルは読み込まれません。
• HeyDeer は、CLAUDE.md の @docs/testing.md のようなインポートをたどりません。規約はファイル自体に直接書いてください。