AGENTS.md 階層設計 - グローバル・プロジェクト・サブディレクトリ

AGENTS.md は、Codex が作業を始める前に読むリポジトリ契約です。コーディング規約だけでなく、読むべき仕様、変更禁止領域、検証コマンド、承認が必要な操作を示します。

読み込み順序

Codex は起動時に指示の連鎖を作ります。

1. ~/.codex/AGENTS.override.md または ~/.codex/AGENTS.md
2. Git ルートから現在の作業フォルダまでにある AGENTS.override.md または AGENTS.md
3. ルート側から現在地側へ連結し、後から読んだ近い階層の指示を優先

この仕組みにより、全リポジトリ共通の個人設定、プロジェクト全体の規約、特定モジュールだけの注意事項を分離できます。

~/.codex/AGENTS.md
project/AGENTS.md
project/apps/web/AGENTS.md

apps/web で Codex を起動した場合、上から順に三つの指示が連結されます。ただし、同じ階層に AGENTS.override.md があれば、通常の AGENTS.md より優先されます。

ルート AGENTS.md に書くこと

ルートには、リポジトリ全体へ適用する契約だけを書きます。

# AGENTS.md

## Read Order
1. Read this file.
2. Read the applicable rules in `shared/rules/`.
3. Read the task-specific skill.

## Non-Negotiable Rules
- Do not deploy without explicit approval.
- Keep Japanese content as the source of truth.

## Verification
- Run `npm run harness:check` after harness changes.

長い手順をすべて埋め込むと、毎回のコンテキストを圧迫します。詳細は shared/rules/、shared/skills/、仕様書へ分け、AGENTS.md は読み込み順と重要な境界を示す目次として保ちます。

サブディレクトリ指示の使いどころ

サブディレクトリの AGENTS.md は、その領域だけに異なるテストや規約がある場合に使います。単に同じ内容を複製するためには使いません。

例	追加する指示
apps/web/	UI テスト、アクセシビリティ、ブラウザ確認
packages/database/	マイグレーション規約、破壊的変更の承認
src/content/docs/	i18n、frontmatter、リンク検証

確認方法

Codex に「現在有効な指示ファイルと優先順位を説明して」と依頼し、想定した階層が読み込まれているか確認します。必須ルールが長い個人メモリだけに存在しないことも確認してください。

次は config.toml 設計 で、指示ではなく実行環境の設定を扱います。

このページの外部仕様・背景情報は、参考文献を参照してください。[1][2]

参考文献

1. OpenAI, Codex documentation
2. OpenAI, OpenAI API documentation