Codex AGENTS.mdの書き方ガイド！置き場所・優先順位・効かない時の確認ポイント

監修者_SD以外

監修者プロフィール

森下浩志

日本最大級のAI情報プラットフォーム「romptn ai」編集長。著書に「0からはじめるStable Diffusion」「0からはじめるStable Diffusion モデル・拡張機能集編」など、AmazonベストセラーのAI関連書籍を多数執筆。AIにおける情報の非対称性を解消するための社内研修や出張講義も行う。

まず確認すること

ここでは、AGENTS.md が効いていない時に最初に切り分けるポイントを先に整理します。

最初に見るべきなのは、Codex をどのディレクトリから起動したかです。近い階層の instruction file ほど後から重なる前提なので、想定した repo root や subdirectory で始めていないと、正しい内容を書いていても別の指示が優先されます。

次に、どの層へ何を書いたかを見直します。全プロジェクト共通の個人ルールは ~/.codex/AGENTS.md、チーム共通は repo root、一部だけの例外は近い場所の override と分けると、どのファイルが効くか追いやすくなります。

最後に、1 ファイルへ詰め込みすぎていないかを確認してください。指示が長くなりすぎると読まれ方の事故を招きやすいので、長い手順は後ほど触れる skills へ分けた方が安定します。

置き場所の決め方

ここでは、global と project と例外ルールをどう分担するかの基準を整理します。

置き場所は『誰に対して、どこまで有効か』で決めると迷いません。自分だけが毎回守りたい作業姿勢は global、リポジトリ全体の build や review の約束は repo root、特定ディレクトリだけの特殊事情はその近くに寄せる、という 3 層で考えるのが基本です。

この分け方にすると、同じ指示を複数ファイルへ重ね書きしにくくなります。迷った項目は『この repo を離れても守るか』で判断すると整理しやすいです。

① ~/.codexに置く内容

全プロジェクトで変えたくない個人ルールは ~/.codex/AGENTS.md にまとめます。たとえば、作業前に差分を見る、危険なコマンドは避ける、説明は簡潔にする、といった自分の標準動作です。

ここへ repo 固有の build 手順や社内命名規則まで入れると、別案件でも不要な指示が混ざります。global は『どの codebase でも通用する習慣』に絞り、内容が増えたら要約だけ残して詳細は補助ドキュメントへ逃がす方が保守しやすいです。

個人ルールを先に固めておくと、新しい repo でも毎回ゼロから説明し直さずに済みます。結果として、project 側の AGENTS.md にはそのチーム固有の判断だけを書けるようになります。

② repo rootに置く内容

repo root の AGENTS.md には、そのリポジトリで全員が共有したい前提を書きます。典型的なのは、ディレクトリ構成の見方、実行すべき test、review 観点、命名規約、禁止事項、Done 条件です。

ここで大事なのは、抽象的な理想論より『変更したら何を確認するか』まで落とすことです。たとえば UI 変更ならどのコマンドを回すか、バックエンド変更ならどの test を通すかが明記されていると、Codex は実装だけで止まりにくくなります。

逆に、自分専用の好みや一部ディレクトリだけの例外まで root に詰めると、読む側は毎回ノイズを拾います。repo 全体の共通契約だけを置くのが基本です。

③ overrideに置く内容

subdirectory の override は、『この配下だけは別ルール』を短く差し込むために使います。たとえば packages/web だけ App Router 前提にする、infra だけ apply 前に review を必須にする、といった局所ルールです。

ここで root の内容を丸ごと書き直す必要はありません。基本は上位の指示を土台にして、差分だけを近い場所へ足します。すると、そのディレクトリで作業した時に何が追加で効くのかが読みやすくなります。

override を増やしすぎると構造が見えにくくなるので、作る基準は『その配下の複数ファイルで繰り返し必要か』に置くと安定します。単発の注意なら task ごとのメモや skill で十分です。

読み込み順の見方

ここでは、どの instruction file がどの順で重なるかを追う見方を整理します。

Codex の instruction は 1 枚だけで決まるのではなく、global から project、さらに現在の作業ディレクトリに近い指示へと重なっていきます。つまり『どこにファイルがあるか』と『どこから起動したか』の 2 つをセットで見ないと、本当に効いている内容は判断できません。

追い方は単純で、まず global、次に repo root、その後に今いる場所へ近いファイルを順に確認します。下の章で見るように、近い場所ほど局所事情を追加しやすく、全体の共通ルールは上位に残すのが読みやすい構成です。

この順序を頭に入れておくと、『書いたのに効かない』問題を感覚ではなく階層で切り分けられます。

① rootからcwdへ重なる

近いディレクトリほど後から読まれる、という前提を押さえると優先順位で迷いにくくなります。repo root の AGENTS.md が土台になり、その下で作業する時だけ近い場所の指示が差分として重なる、という見方です。

この仕組みでは、Codex をどこから起動したかがかなり重要です。想定より上の階層で始めると、近くに置いた override が scope に入らず、逆に深い場所で始めると局所ルールだけを強く見てしまうことがあります。

迷ったら、今編集しているファイルに一番近い instruction file は何かを先に確認してください。その一枚が『最後に足される差分』だと考えると、競合する指示の整理がしやすくなります。

② overrideとfallback

override と fallback は、『既存運用を崩しすぎずに instruction を整理したい時』に効く仕組みです。override は特定ディレクトリだけへ差分を足す役割で、基本ルールの置き換えではなく局所的な上書きとして考えると分かりやすいです。

一方で、既存 repo が別の instruction file 名を使っていてすぐに AGENTS.md へ寄せられない場合は、fallback filenames を使って読み込み対象を合わせる手があります。移行中の橋渡しとして便利ですが、長期的には正本を一つに絞った方が保守は楽です。

既存の CLAUDE.md や補助ドキュメントがある repo では、どれが正本でどれが互換窓口かを先に決めておくと、二重更新の事故を減らせます。

③ 効かない時の見直し

AGENTS.md が効かない時は、症状ごとに順番に潰すのが早道です。まず起動ディレクトリを見て、想定した scope で session が始まっているかを確認します。その後、global・repo root・override のどこに書いた内容なのかを切り分けます。

それでも挙動が合わない時は、session の持っている instruction が古いままではないかを疑ってください。official repo issue でも、global の読込や scope 変更の追従で混乱する例が出ています。場所を直した直後は、新しい session で再確認した方が安全です。

もう一つの盲点は、1 ファイルへ情報を詰め込みすぎることです。長い手順や例外が増えたら skills や近い補助ファイルへ分け、重要ルールだけを先頭で読める形にすると、切り捨てや見落としの事故を避けやすくなります。

書く内容の型

ここでは、AGENTS.md に書くと効果が出やすい内容を 3 つの型で整理します。

書くべきなのは『雰囲気』ではなく、作業判断に効く情報です。ベースルール、test と review、skills への分割基準の 3 つに分けて考えると、どこまでを AGENTS.md に置くか決めやすくなります。

この章のポイントは、読み手に期待する行動まで言語化することです。『丁寧にやる』より『変更種別ごとに何を確認するか』の方が、実装でぶれません。

① ベースルールを書く

ベースルールには、その repo で毎回ぶれやすい判断を先に書きます。たとえば、採用するアーキテクチャ、触ってよい範囲、禁止コマンド、レビュー前に満たす Done 条件です。

ここが弱いと、Codex は口調だけ守っても実装方針を外しやすくなります。『React は Server Component を優先する』『既存 migration は書き換えない』『危険な git 操作は禁止』のように、具体的で再利用される判断を書いた方が効きます。

逆に、毎回変わる task メモまで base rules へ入れると、正本がすぐに太ります。長く育てる前提の規約だけを残し、単発の背景説明は issue や task 指示へ分けるのが基本です。

② testとreviewを書く

test と review の記述は、『実装して終わり』を防ぐための土台になります。どの変更で何を実行するか、何を目で確認するかが明記されていると、Codex は最後の確認まで含めて動きやすくなります。

たとえば、frontend 変更なら表示確認と relevant test、API 変更なら contract test とログ確認、記事生成なら export 対象と commit 範囲、といった形です。review 観点も『性能』『回帰』『権限』『文言』のように具体名で置くと、自己点検しやすくなります。

Best practices の考え方に近いのは、追加の補助ドキュメントを参照させても、入口の AGENTS.md には何を読みに行くべきかを書くことです。確認観点の入口が曖昧だと、結局人が毎回補足することになります。

③ skillsへ分ける基準

skills へ分ける基準は、『何度も呼び出す長い手順かどうか』で考えると分かりやすいです。短い原則は AGENTS.md に残し、役割別のフロー、詳細なチェックリスト、特定ツールだけの作法は skills へ切り出します。

この分割をしておくと、通常の作業では軽い instruction だけを読み、必要な時だけ該当 skill の全文を読む構成になります。結果として、入口の AGENTS.md が太りすぎず、重要ルールが埋もれません。

目安としては、同じ手順を 3 回以上書きたくなった時点で分割を検討するとよいです。サイズ上限や保守性の問題を防げるだけでなく、担当別の責務も見えやすくなります。

CLAUDE.mdとの使い分け

ここでは、Codex の AGENTS.md と Claude Code の CLAUDE.md をどう共存させるかを整理します。

両者は似た役割を持ちますが、完全に同じ運用にせず、共有する土台と tool 固有の差分を分けるのが実務向きです。たとえば、repo の build・test・レビュー規約は共通化し、Codex 固有の lock 運用や Claude 固有の import 運用だけをそれぞれへ足します。

Claude 側の公式 docs では、既存の AGENTS.md を import や symlink で取り込む考え方が案内されています。つまり二重管理を避けたいなら、まず共通規約の正本を一つ決め、片方はそこを参照する形に寄せるのが安全です。

重要なのは、ファイル名を揃えることより、どの内容が shared でどの内容が tool-specific かを先に言語化することです。

よくある質問

まとめ

最後に、配置・優先順位・分割の 3 点だけ押さえれば運用はかなり安定します。

まずは今使っている instruction file を 3 層に色分けし、重複している項目を一つずつ移し替えてみてください。配置が整理できると、Codex への追加指示もずっと少なくなります。

一度きれいに分けておけば、repo が大きくなっても rules を育てやすくなります。