Claude CodeとCodexの役割分担フローを組んだとき、次に気になるのは「設定ファイルが本当に読まれているか」だ。CLAUDE.mdやAGENTS.mdを丁寧に書いても、AIが無視していれば意味がない。
今回はその疑問をcodex execで直接検証した。
シリーズ：AI駆動開発 実践記
- 第1回：Claude Codeで設計、Codexで実装・レビュー——個人開発者が辿り着いた最強の役割分担フロー
- 第2回：本記事（コンテキスト設計の検証）
CLAUDE.mdとAGENTS.md——2つのコンテキストファイルの役割
Claude CodeとCodexはそれぞれ別の設定ファイルを持つ。
役割分担フローを安定させるにはどちらのAIがどのファイルを読むかを正確に把握しておく必要がある。
Claude Codeが読むファイル
~/.claude/CLAUDE.md # グローバルルール
{project}/CLAUDE.md # プロジェクト固有ルール
{project}/.claude/rules/ # 詳細ルール（セッション開始時に自動読み込み）
CLAUDE.mdには@~/.claude/rules/git.mdのような形でグローバルファイルを参照できる。.claude/rules/配下のファイルはセッション開始時に自動で読み込まれる。
Codexが読むファイル
~/.codex/AGENTS.md # グローバルルール
~/.codex/rules/ # グローバル詳細ルール
{project}/AGENTS.md # プロジェクト固有ルール（オプション）
Codexはルートから現在の作業ディレクトリまでを下りながらAGENTS.mdを探索し、見つかったファイルを連結して読み込む。
優先順位はAGENTS.override.md → AGENTS.mdの順で、より深い階層のファイルが後から結合されるため、プロジェクト固有のルールが優先される。
読み込み優先順位の整理
スコープ | Claude Code | Codex |
|---|---|---|
グローバル |
|
|
プロジェクト |
|
|
詳細ルール |
|
|
サイズ上限 | 記載なし | 32KiB（デフォルト） |
「設定した」で終わらせない——検証しようと思った理由
設定ファイルを整備すると、なんとなく「AIがルールを守って動いてくれている」と思いがちだ。
実際、CLAUDE.mdに規約を書いた直後は出力品質が上がるため、読まれているように感じる。
しかし個人開発プロジェクトを運用する中で、違和感を覚えた。
Claude Codeに「CodexはどのファイルをContextとして読み込んでいるか」と質問したところ、実際の挙動と異なる説明が返ってきたのだ。
Claude Code自身がCodexの読み込みルールを誤って把握していた。
これは重要な気づきだった。
AIが別のAIの動作を正確に説明できるとは限らない。
設定ファイルの読み込み状況はAIに直接確認するしかない。
「動いているはず」で済ませず、実際に検証する。
この習慣がコンテキスト設計の精度を決める。
検証方法——codex execで直接質問を投げる
検証に使ったのはcodex execだ。
TUIを起動せずに結果をstdoutに出力できるため、「読み込んでいるファイルを列挙してください」という質問を直接投げられる。
codex exec --full-auto -C {project_dir} \
"あなたが参照しているルールファイルを列挙してください。\
AGENTS.mdの内容と、rules/配下のファイルがあれば内容も教えてください。" \
< /dev/null
コマンドの2つのポイント
< /dev/null でstdinを閉じる
これを省略するとCodexがstdin待ちでフリーズする。自動化スクリプトに組み込む場合は必須だ。
「計画確認不要。そのまま実装してください。」を冒頭に付ける（実装タスクの場合）
質問系のタスクでは不要だが、ファイル編集を伴うタスクでは冒頭にこの一文を入れないとCodexが承認待ちで止まる。
# ファイル編集ありのタスクの場合
codex exec --dangerously-bypass-approvals-and-sandbox -C {project_dir} \
"計画確認不要。そのまま実装してください。\n\n{依頼内容}" \
< /dev/null
検証結果——Codexが自発的に.claude/rules/を探索していた
読み込まれていたファイル一覧
Codexの回答から、以下が確認できた。
ファイル | 読み込み方法 |
|---|---|
| 起動時に自動読み込み |
|
|
| プロジェクト内を自発的に探索して読み込み |
| プロジェクト内を自発的に探索して読み込み |
驚きの発見：.claude/rules/をCodexが自力で探索していた
最も意外だったのは.claude/rules/配下の6ファイルだ。
これはClaude Code向けに書いたルールファイルで、Codexに渡すつもりはなかった。
AGENTS.mdにも参照の記述はない。
にもかかわらず、Codexはプロジェクト内を自発的に探索し、このファイル群を読み込んでいた。
Codexはプロジェクトルートから現在の作業ディレクトリまで下りながらファイルを探索し、見つかったファイルを連結して読み込む。
この仕様を踏まえると、プロジェクト内に置かれたMarkdownファイルは意図せずCodexのコンテキストに入り込む可能性がある。
Claude Code向けに書いたルールがCodexにも適用されるなら、むしろ設計の余地が広がる。
一方で、Codexに読ませたくないファイルは配置場所に注意が必要だ。
グローバルファイルの追加検証
最初の検証で~/.codex/rules/git.mdの読み込みが不明確だったため、追加で確認した。
codex exec --full-auto -C {project_dir} \
"~/.codex/rules/git.md の内容を読んで表示してください。" \
< /dev/null
結果、グローバルファイルへのアクセスも正常に機能していた。Codexはプロジェクト固有のルールファイルを探しに行った後、見つからなければグローバルにフォールバックする動きをしていた。
この検証から得た3つの気づき
1. Codexはプロジェクト内を自発的に探索する
AGENTS.mdに明示しなくても、プロジェクト内のMarkdownファイルをCodexが拾いに行く。
これは設計の自由度を高める一方で、意図しないコンテキスト混入のリスクでもある。
読ませたいファイルは積極的に活用し、読ませたくないファイルは.codexignoreや配置場所で制御する意識が必要だ。
2. グローバルルールとプロジェクトルールは別管理が効く
~/.codex/AGENTS.mdにはチームや個人の共通規約（コミット規則・言語設定など）を書き、プロジェクト固有の仕様は{project}/AGENTS.mdまたは.claude/rules/に書く。
この分離が機能することを今回の検証で確認できた。
3. 「AIに確認させる」習慣がコンテキスト設計の精度を上げる
設定ファイルの読み込み状況は、codex execで直接質問すれば数秒で確認できる。
AIが「動いているはず」と言っても、別のAIが正確に把握しているとは限らない。
定期的に確認する習慣がコンテキスト設計の品質を維持する。
コンテキスト設計を「育てる」という考え方
今回の検証で明らかになったのは設定ファイルは「書いて終わり」ではなく「検証しながら育てるもの」だということだ。
AIが実際に読んでいるファイル・読んでいないファイルを把握した上で、ルールを追記・整理していく。
この繰り返しがコンテキスト設計の精度を上げ、AIの出力品質を安定させる。
CLAUDE.mdとAGENTS.mdは、プロジェクトの成長とともに育てるドキュメントだ。
まずはcodex execで現在の読み込み状況を確認するところから始めてみてほしい。
まとめ
- CLAUDE.mdはClaude Code用・AGENTS.mdはCodex用——それぞれ別スコープで管理する
- CodexはプロジェクトのMarkdownファイルを自発的に探索する——Claude Code向けに書いた
.claude/rules/も読み込まれる codex execで読み込み状況を直接確認できる——AIに「動いているはず」を信じるより、検証する習慣が設計品質を上げる- AIが別のAIの動作を正確に説明できるとは限らない——一次情報はAI自身に確認する
