Codex AGENTS.md 調査結果 — Claude.md をベースに最強の設定ファイルを作る

2026年3月7日 17:52 更新

一言でいうと

Codex 用の「AIへの指示書」を、今の Claude.md レベルに引き上げるための調査まとめ

なぜこれが必要なのか

今の Codex の設定ファイル（~/.codex/AGENTS.md）には、C.C.（コードギアスのキャラ）の口調設定しか入っていない。Claude Code の CLAUDE.md には「どんなツールを使うか」「コードの書き方のルール」「判断に迷ったらどうするか」といったプロジェクトルールがぎっしり詰まっているのに、Codex にはそれがゼロ。

つまり Codex にタスクを投げるたびに、毎回ゼロから説明し直している状態。研究データによると、ちゃんとした AGENTS.md があるだけで実行時間が約28%短縮、トークン（AIが処理するテキスト量）も約16%削減される。「指示書がないと、AIは遠回りする」ということ。

何をしたのか

3方面から並行して調査を実施した。

1 公式ドキュメント・GitHub・ブログ記事

AGENTS.md の仕様、書き方のベストプラクティス、CLAUDE.md からの移植ガイドを調査

2 X（Twitter）のユーザー投稿

実際のユーザーがどんな AGENTS.md を書いているか、Tipsやコツを収集

3 Codex CLI の使い方・特性

Codex 固有の機能やクセを調査し、AGENTS.md に反映すべき項目を特定

調査結果 1: AGENTS.md の基本ルール

AGENTS.md って何？

AGENTS.md は、Codex（OpenAI の AI コーディングツール）が作業を始める前に必ず読む「指示書」。Claude Code でいう CLAUDE.md と同じ役割。普通のテキストファイル（Markdown形式）で、特別なフォーマットは不要。

置き場所と優先順位

置き場所	効果の範囲	用途
`~/.codex/AGENTS.md`	全プロジェクト共通	口調、基本ルール、共通の好み
プロジェクトのルート	そのプロジェクトだけ	技術スタック、テスト方法、構造説明
サブフォルダ	そのフォルダ以下だけ	チームごと・機能ごとの特別ルール

深いフォルダにあるものほど優先される（フォルダの中にフォルダがあれば、内側が勝つ）。全ファイルの合計サイズ上限は 32KB。

便利機能: `/init` コマンド

Codex CLI で /init と打つと、プロジェクトの中身を自動スキャンして AGENTS.md のテンプレートを作ってくれる。ゼロから書くのが面倒なときに便利。

調査結果 2: 書くべきこと・書かないべきこと

書くと効果が高いもの（2,500リポジトリの分析結果）

GitHub が 2,500以上のリポジトリを分析して出した結論。「三層構造」で書くのが最も効果的。

常にすること（Always）

テスト実行コマンド、lint（コードの書き方チェック）実行、コミット（変更記録）のルールなど。「これは毎回やれ」という指示。

先に確認すること（Check first）

新しいライブラリ（外部ツール）の追加、本番環境の設定変更など。「やる前に聞け」という指示。

絶対にしてはいけないこと（Never）

パスワードをコードに直書き、.env（秘密情報ファイル）のコミットなど。「これだけは絶対ダメ」という指示。

書かないべきもの

曖昧なペルソナ設定 — 「有能なコーディングアシスタントとして振る舞え」のような抽象的な指示は効果なし。口調指定（「〜だ」「〜だろう」等）は具体的なのでOK
長すぎる説明文 — AIが読み切れる指示は150〜200項目が限界。それ以上はノイズになる
すぐ古くなるファイルパスの羅列 — 別ファイルに分けてリンクする方式が推奨

調査結果 3: 今の AGENTS.md の問題点

今の状態

C.C.の口調設定だけ
プロジェクトルールなし
テスト・lint 指示なし
禁止事項なし
TTS: で始める指示あり

目指す状態

口調 + 開発ルール
CLAUDE.md 相当の規約
検証コマンド明記
三層構造の指示
TTS: 削除

調査結果 4: CLAUDE.md → AGENTS.md の移植ポイント

そのまま使えるもの

基本原則 — YAGNI（今必要なものだけ作る）、KISS（シンプルに保つ）等はそのまま移植できる
共通ツール — パッケージマネージャの判定ルール（lock ファイルで判定）はそのまま
検証コマンド — tsc --noEmit → lint → テストの順序はそのまま
口調設定 — C.C.の口調は具体的な指示なので残してOK（ただし「TTS:」は削除）

Codex 向けに調整が必要なもの

CLAUDE.md の機能	AGENTS.md での対応
`@ファイル名` でインポート	使えない。サブフォルダに分けて置く
サブエージェント指定	Codex にはない。削除する
plan-viewer 連携	Claude Code 専用。削除する
外部ツール連携（Discord等）	MCP（外部サービス接続）があれば書ける
`/compact` 提案	Codex にも `/compact` あり。そのまま使える
Second-Brain 書き出し	Codex でも可能。パスは同じ

Codex 固有で追加すべきもの

autonomy レベル（自律度の設定）— suggest（全部確認）/ auto-edit（編集は任せる）/ full-auto（全自動）の使い分け指示
Codex の得意・不得意 — ターミナル操作やコードレビューは得意。複雑なアーキテクチャ設計は苦手
曖昧な指示への弱さ — 「いい感じにして」ではなく「何を達成したいか」を具体的に書く必要がある

調査結果 5: X で見つけた実践Tips

シンボリックリンクで共有する（Fabrizio Rinaldi）

1つのファイルを CLAUDE.md と AGENTS.md の両方から参照させる。どのツールでも同じルールが適用される。ただし Claude Code 専用の記述（サブエージェント等）は分ける必要あり。

AGENTS.md は「従業員への研修マニュアル」（Eric J. Ma）

「プログラムを書いているのではなく、従業員を訓練している」と考える。セッション中に気づいたことは「AGENTS.md に追記して」と指示すれば、AI 自身が学習ファイルを更新してくれる。

コンテキスト切れに注意（Sash Zats）

長時間作業するとAIの「記憶」が薄れ、AGENTS.md の指示を無視し始めることがある。こまめに /compact（記憶の整理コマンド）を使うこと。

AGENTS.md の自動生成もアリ（Dan Mac / Yazin）

「このリポジトリ用の AGENTS.md を書いて」とCodex自身に頼むこともできる。/init コマンドでも自動生成可能。ただしグローバル設定（~/.codex/AGENTS.md）は手動で書いた方がいい。

次のアクション

1 グローバル AGENTS.md を書き直す

今の C.C. 口調設定を残しつつ、CLAUDE.md から移植可能なルールを追加。TTS: プレフィックスは削除。三層構造（Always / Check first / Never）で整理する。

2 Codex 固有のルールを追加

autonomy レベルの使い分け、得意・不得意への対策、曖昧指示の禁止を明記。

3 Claude Code 専用の記述を除外

サブエージェント指定、plan-viewer、@インポート、Discord/X スキル連携など、Codex にないものは削除。

ポイント

CLAUDE.md と完全に統一するのは現実的ではない。Claude Code にはサブエージェント、plan-viewer、スキル、フックなど Codex にない機能が多い。逆に Codex には autonomy レベルやマルチエージェント（複数AIの同時作業）など Claude Code にない機能がある。

「共通部分」と「ツール固有部分」を分けて考えるのがベスト。基本原則・コーディングルール・検証コマンドは共通。ツール連携・ワークフロー指示は各ツール専用にする。

32KB の上限に注意。CLAUDE.md は長くても問題ないが、AGENTS.md は全ファイル合計で 32KB まで。簡潔さが重要。

効果は実証済み。ちゃんとした AGENTS.md を書くだけで、実行時間28%短縮・トークン16%削減。投資対効果が高い。