AGENTS.md の書き方 — Codex に指示を渡す設定ファイル
2026年6月3日、OpenAIは「新しい Codex」を発表し、長時間タスクを自律実行する Goal Mode が正式版となった。エージェントが長く動くほど、最初に渡す指示の質が成果を左右する。その指示を毎回プロンプトに書かず、リポジトリ側に固定しておくのが AGENTS.md だ。本記事では AGENTS.md の役割、Codex が読み込む場所と優先順位、書くべき項目、そして肥大化を避ける運用のコツまでを順に解説する。
Codex はグローバルの ~/.codex から始め、Git ルートから現在のディレクトリへと各階層を辿って AGENTS.md を探す。複数見つかった場合はルートから連結され、現在地に近いファイルが後勝ちで優先される。~/.codex/config.toml の project_doc_max_bytes（既定 32 KiB）を超えると読み込みは打ち切られる。
実務では最小構成から始め、サブパッケージごとにネストした AGENTS.md で精度を上げるのが定石だ。Goal Mode の正式版化で自律実行が長くなった今こそ、最初の指示を磨くことが手戻りを減らす最短ルートになる。
目次 (13)
- AGENTS.md とは — Codex が作業前に読む「リポジトリの取扱説明書」
- なぜ今 AGENTS.md なのか — Goal Mode 正式版で「最初の指示」が効く
- Codex が AGENTS.md を探す場所 — グローバル・プロジェクト・ネストの三層
- AGENTS.override.md の使いどころ — base を消さずに差し替える
- config.toml で読み込みを調整する — フォールバック名と上限バイト数
- AGENTS.md に何を書くか — 定番の 6 セクション
- 最小構成から始める — 例で育てる AGENTS.md
- ネストと検証 — 精度を上げる二つの工夫
- サブパッケージごとにネストする
- 反映と内容を確認する
- よくある落とし穴 — 肥大化・矛盾・更新漏れ
- まとめ — 最初の指示を磨くことが自律実行の精度を決める
- 出典
AGENTS.md とは — Codex が作業前に読む「リポジトリの取扱説明書」
AGENTS.md は、Codex がコードに触れる前に読み込む永続的なカスタム指示ファイルだ。プロジェクトのビルド手順やテストの流し方、コーディング規約、触れてはいけないファイルといった「このリポジトリの作法」を Markdown で書いておくと、Codex はそれを前提に作業する。OpenAI の公式ガイドは AGENTS.md を「どのリポジトリを開いても一貫した期待値を保つための仕組み」と位置づけている（https://developers.openai.com/codex/guides/agents-md ）。
本質は、人間の新メンバーに渡す README やオンボーディング資料を、エージェント向けに書き直したものだと考えると分かりやすい。README が人間に向けて「このプロジェクトは何で、どう動かすか」を説明するのに対し、AGENTS.md はエージェントに向けて「作業時に守るべき制約と手順」を渡す。AGENTS.md はオープンな記法として公開されており、Codex 以外の主要なコーディングエージェントも同じファイルを参照できる（https://agents.md/ ）。openai/codex のリポジトリ自身も、ルートに AGENTS.md を置いて開発の作法を固定している（https://github.com/openai/codex/blob/main/AGENTS.md ）。
なぜ今 AGENTS.md なのか — Goal Mode 正式版で「最初の指示」が効く
2026年6月3日にOpenAIが発表した「新しい Codex」では、長時間タスクを自律実行する Goal Mode が正式版となり、駆動モデルも GPT-5.5 へ刷新された（https://openai.com/codex/ ）。エージェントが数十分から数時間にわたって自律的に動くようになると、作業の途中で人間が細かく軌道修正する機会は減る。だからこそ、走り出す前に渡す指示の質が成果を大きく左右する。毎回のプロンプトに規約を書き連ねるより、AGENTS.md に一度固定しておけば、長時間の自律実行でも前提がぶれない。Goal Mode の正式版化は、AGENTS.md を「あると便利なメモ」から「自律実行の精度を担保する基盤」へと格上げした。
Codex が AGENTS.md を探す場所 — グローバル・プロジェクト・ネストの三層
Codex は AGENTS.md を決まった順序で探索する。理解しておくべきは、ファイルが一つではなく複数の階層で重なり、連結されて効くという点だ。
まずグローバル階層として、Codex ホーム（既定は ~/.codex、CODEX_HOME で変更可）を見る。ここに AGENTS.override.md があればそれを、なければ AGENTS.md を読む。次にプロジェクト階層として、Git ルートから現在の作業ディレクトリへと一階層ずつ降りながら、各階層で AGENTS.override.md → AGENTS.md → フォールバック名の順に確認する。見つかったファイルはルート側から順に空行で連結される。そして現在地に近いファイルほど後ろに連結されるため、近いファイルの指示が後勝ちで優先される（https://developers.openai.com/codex/guides/agents-md ）。
この「連結して、近いものが勝つ」仕組みにより、リポジトリ全体に効く共通規約をルートに、特定パッケージだけの規約を各サブディレクトリに、と段階的に重ねられる。一つの巨大なファイルに詰め込まず、効く範囲ごとに分けて置けるのが利点だ。
AGENTS.override.md の使いどころ — base を消さずに差し替える
ネストした AGENTS.override.md は、その階層において親ディレクトリからの指示を完全に置き換える。base となる AGENTS.md を消したり編集したりせずに、特定の領域だけ別ルールへ切り替えたいときに向く。たとえば一部のディレクトリだけ異なる規約で作業したい場合、AGENTS.override.md を専門作業の近くに置けば、親の指示に縛られず、かつ元の指示も残せる。公式ガイドも「上書きは専門的な作業のできるだけ近くに置く」ことを推奨している（https://developers.openai.com/codex/guides/agents-md ）。
config.toml で読み込みを調整する — フォールバック名と上限バイト数
既存リポジトリが AGENTS.md 以外の名前で指示ファイルを運用している場合や、読み込み量を制御したい場合は、~/.codex/config.toml で挙動を調整できる。
主に二つの設定がある。一つは project_doc_fallback_filenames で、AGENTS.md が無いときに指示ファイルとして扱う代替名を配列で指定する（例: ["TEAM_GUIDE.md", ".agents.md"]）。既存の TEAM_GUIDE.md などをそのまま活かしたいときに使う。もう一つは project_doc_max_bytes で、連結後の指示ファイルの合計サイズ上限を決める。既定値は 32 KiB で、連結サイズがこの上限に達すると、Codex はそれ以上ファイルを足さずに読み込みを打ち切る（https://developers.openai.com/codex/config-advanced ）。設定を変えたら、Codex を再起動するか新しいコマンドを実行して反映させる。
上限があるという事実は運用上重要だ。AGENTS.md に盛り込みすぎると、上限を超えた分の指示が読まれず、書いたつもりのルールが効かないという事態を招く。簡潔さは好みの問題ではなく、仕組み上の要請でもある。
AGENTS.md に何を書くか — 定番の 6 セクション
何を書くかは厳密に規定されていないが、実務で効果が出やすい定番のセクションがある。次の項目を出発点にすると過不足が少ない。
- プロジェクト概要: 何をするリポジトリか、主要なディレクトリ構成と責務を数行で示す。エージェントが全体像を素早く掴める。
- ビルドとテストのコマンド: 依存解決・ビルド・テストの実行コマンドを明記する。エージェントが自分で検証まで回せるようになる。
- コードスタイル: 命名規則、フォーマッタ、lint の方針を書く。生成コードが既存コードに馴染む。
- テスト方針: どのテストをいつ流すか、カバレッジの期待値を示す。完了条件が明確になる。
- セキュリティ上の注意: 触れてはいけない秘匿情報の扱いや、外部に送信してはいけない範囲を明示する。
- コミットと PR の規約: コミットメッセージの形式やレビュー観点を書く。履歴とレビューが整う。
これらは OpenAI 公式ガイドが挙げる定番項目に沿っている（https://developers.openai.com/codex/guides/agents-md ）。全部を一度に揃える必要はなく、チームが繰り返し説明している事項から書き始めるのが現実的だ。
最小構成から始める — 例で育てる AGENTS.md
最初の一歩は短くてよい。完璧な規約を最初から書き切ろうとすると、かえって手が止まる。むしろ、チームが新メンバーに口頭で繰り返し説明している事項を数行ずつ書き出し、運用しながら育てるのが堅実だ。次のような十数行から始めれば十分に効果が出る。
# AGENTS.md
## 概要
社内向けの記事配信 Web アプリ。Laravel + Markdown コンテンツで構成する。
## ビルドとテスト
- 依存解決: composer install
- テスト: php artisan test
- 整形: ./vendor/bin/pint
## 規約
- content/ 配下の Markdown は本文のみ編集し、frontmatter の画像パスは変更しない。
- コミットメッセージは「種別(範囲): 要約」の形式で日本語にする。
このように、エージェントが迷いやすい「どのコマンドで検証するか」「触ってはいけない箇所はどこか」を先に固定するだけで、やり取りの往復が目に見えて減る。書き始めの段階では網羅性より、頻出する指示を確実に押さえることを優先したい。育てる過程で重複や古い記述を削れば、上限バイト数にも無理なく収まる。
ネストと検証 — 精度を上げる二つの工夫
最小構成が回り始めたら、二つの方向で精度を上げていく。
サブパッケージごとにネストする
モノレポや複数パッケージ構成では、各パッケージのディレクトリに AGENTS.md を置く。エージェントは作業ディレクトリに最も近いファイルを優先して読むため、パッケージ固有のビルド手順や規約をそこに書けば、ルートの共通規約と自然に両立する。共通ルールはルートへ、個別ルールは近くへ、という住み分けが基本だ。これにより、ルート側の指示を膨らませずに、領域ごとの細かな作法を表現できる。
反映と内容を確認する
設定や AGENTS.md を変えたら、実際に Codex が何を読んでいるかを確かめる。公式ガイドは、現在の指示内容を要約させて点検する確認方法を案内している（https://developers.openai.com/codex/guides/agents-md ）。意図した規約がきちんと読み込まれているか、上限超過で末尾が切れていないかを早めに点検すると、後の手戻りを防げる。指示を書いた直後ほど、実際に効いているかを一度確認しておきたい。
よくある落とし穴 — 肥大化・矛盾・更新漏れ
AGENTS.md は便利な一方で、放置すると逆効果になりやすい。代表的な三つの落とし穴を押さえておく。
第一に肥大化だ。あれもこれもと書き足すうちに project_doc_max_bytes（既定 32 KiB）を超え、末尾の指示が読まれなくなる。重要な規約ほど上限に削られないよう、簡潔さを保つ。第二に矛盾だ。ルートとネストで食い違う指示があると、近いファイルが優先される仕様を理解していないかぎり、なぜその挙動になるのか分からなくなる。第三に更新漏れだ。ビルドコマンドやテスト方針が変わったのに AGENTS.md が古いままだと、エージェントは古い前提で動く。コード変更と同じレビューの俎上に AGENTS.md も載せ、規約が変わったら一緒に直す運用にすると鮮度を保てる。
まとめ — 最初の指示を磨くことが自律実行の精度を決める
AGENTS.md は、Codex に「このリポジトリの作法」を一度渡せば毎回説明せずに済む、永続的な指示ファイルだ。Codex はグローバル・プロジェクト・ネストの三層を連結して読み、現在地に近いファイルを優先する。~/.codex/config.toml の project_doc_max_bytes（既定 32 KiB）という上限があるため、簡潔さが要となる。まずはビルドとテストのコマンド、触れてはいけない箇所という最小構成から始め、サブパッケージごとのネストで精度を上げ、変更のたびに更新する——この運用が、Goal Mode 正式版で長くなった自律実行の成果を安定させる。次に試すなら、いま開いているリポジトリのルートに十数行の AGENTS.md を置くことから始めるとよい。
