結論（先に要点）
-
AGENTS.mdは「エージェント向けREADME」。人間向けREADMEに載せにくい「ビルド・テスト手順、コード規約、PRルール、守ってほしいガードレール」など、エージェントが作業するのに必要な具体指示を置く場所です。CodexはAGENTS.mdを読んで作業を進められます。 (agents.md)
-
要件定義は別ファイルで管理がベスト。AGENTS.mdに全文は入れず、「参照リンク＋遵守方法（受入条件の確認・テスト実行など）」だけを書くと運用が安定します。
-
分割は“レベル”で分けると吉：
- 上位：製品/全体要件（非機能・品質・セキュリティ）
- 中位：機能ごとの要件（エピック/機能単位）
- 下位：タスク/ストーリーの受入条件
⇒ タスクに合わせて**細かく“断片化しすぎない”**のがコツ。リンクで結ぶ。
-
リンク方式：AGENTS.mdから相対リンクで要件ドキュメント群に飛ばす。CodexはAGENTS.mdの指示を優先的に読む（同時に、AGENTS.mdに書いた「テスト/チェックを走らせる指示」も尊重されます）。 (OpenAI)
-
階層運用OK：モノレポ等ではサブディレクトリにもAGENTS.mdを置け、**“より近い階層が優先”**されます（Codex/他ツールの実装）。 (OpenAI)
AGENTS.md の役割と書き方（Codex前提）
役割
- エージェントが安全かつ一貫したやり方であなたのリポジトリを編集・ビルド・テストできるようにする“行動ガイド”。Codexはここに書いた手順やチェック（テスト・リンタ等）を実行し、合格を目指します。 (OpenAI)
最小構成テンプレ
# AGENTS.md
## プロジェクト概要（1〜3行）
このリポジトリは～。主要ディレクトリ: `api/`, `web/`, `infra/`。
## セットアップ/ビルド/テスト
- 依存解決: `pnpm i`
- Lint/Typecheck: `pnpm lint && pnpm typecheck`
- 単体テスト: `pnpm test`
- E2E: `pnpm e2e`
- 変更をコミットする前に上のチェックが**全て緑**であること
## コーディング規約（要点）
- TypeScript: strict。import順序はeslint-plugin-importに従う。PRごとに型エラーゼロ。
- PRタイトル: `[api] 説明…` の形式。
## ガードレール / 禁止事項
- 秘密情報を追加しない。生成コードにAPIキーを埋め込まない。
- 破壊的変更は`docs/adr/`にADR追加後に実施。
## 要件・受入基準の参照
- **実装前に**以下を必ず読む：`docs/requirements/README.md`
- 今回の作業対象がある場合、該当機能の文書を開き**受入基準(Acceptance Criteria)**を満たすテストを追加/更新すること。
## PRルール
- 変更理由/影響範囲/テスト結果をPR本文に記載。
CodexはAGENTS.mdの“プログラム的チェック（テスト、リンタ等）”を走らせるべき、また近い階層のAGENTS.mdが優先という仕様/挙動が公開情報として示されています。 (OpenAI)
階層運用（モノレポなど）
- ルートに総則、
packages/foo/AGENTS.mdにfoo専用ルール、のように近い方が優先。実地検証記事でも“近い階層が勝つ”動作が報告されています。 (Qiita)
“要件定義”はどう分ける？どこに置く？
1) 別ファイルに分けるのが基本
- AGENTS.mdは**“実行可能な作業手順と規約・ガードレールの要点”**に絞り、要件本文は別MDに。
- 理由：AGENTS.mdはエージェントにとっての“作業マニュアル”。要件全文まで詰め込むと可読性/保守性が落ちます。AGENTS.mdはリンク集&遵守のしかたを書き、本文は
docs/requirements/*.mdに置く運用がスケールします。 - なお、ツールによってはAGENTS.mdから外部MDをインクルード運用できるものもあります（例：Android Studio Geminiは
@./file.mdで分割可能）。Codexは“参照指示＋相対リンク”で十分実用的です。 (Android Developers)
2) 分割の粒度（おすすめの3層）
-
上位（全体要件/非機能）：
docs/requirements/000-overview.md -
中位（機能/エピック別）：
docs/requirements/feature-foo.md -
下位（ストーリー/タスク受入条件）：
docs/requirements/feature-foo-story-123.md
→ タスク駆動で細かく分けるのは有効ですが、“受入条件は最も近い要件ページに集約”、タスク側はその見出しへリンクする形にすると、迷子になりません。
3) リンクの張り方（実例）
repo/
├─ AGENTS.md
└─ docs/
├─ requirements/
│ ├─ README.md # 入口/索引
│ ├─ 000-overview.md # 全体要件・非機能
│ ├─ feature-foo.md # 機能要件（Foo）
│ └─ feature-foo-story-123.md # 受入条件（タスク/ストーリー）
└─ adr/
└─ 2025-09-17-xxx.md # 重要設計判断
AGENTS.md側の書き方（リンク例）
## 要件ドキュメント
- 索引: ./docs/requirements/README.md
- 機能Foo: ./docs/requirements/feature-foo.md
- 作業着手前に対象ストーリーの**受入条件**を確認し、足りなければ追記を提案してから実装開始。
- 変更後は関連テストを更新し、`pnpm test` が**緑**になるまで修正。
Codexでの挙動・仕様のポイント（運用のヒント）
- CodexはAGENTS.mdを読んで、そこに列挙された“プログラム的チェック（テスト等）”を実行し、合格を目指すよう設計されています。チェックを明記しておくと品質が安定します。 (OpenAI)
- スコープ/優先順位：“より近い（深い）AGENTS.mdが優先”。モノレポでは各パッケージごとにAGENTS.mdを置くと、意図どおりの規約で動かせます（実地検証もあり）。 (OpenAI)