AGENTS.mdの書き方｜Codexへ毎回同じルールを守らせる最小構成

Codexへ毎回「このフォルダは触らない」「変更後はテストする」と書いているなら、繰り返すルールをAGENTS.mdへ移せます。これはCodexが作業を始める前に読む指示ファイルです。

先に大事な前提を1つ。AGENTS.mdは「毎回自動で読み込まれる固定の指示」であって、違反を物理的に止める鍵ではありません。守られたかどうかは、テストや差分(変更内容の記録)で確かめます。この記事では、何を書くか、どこへ置くか、読み込まれたかをどう確認するかを、最小テンプレートと失敗例つきで説明します。個別依頼の整理には、AIに実装を頼むときの依頼文テンプレも使えます。

AGENTS.mdで解決すること

AGENTS.mdに向くのは、リポジトリ構成、命名規則、変更禁止箇所、検証コマンド、報告形式など、作業をまたいで使う情報です。OpenAIの公式ガイド「Custom instructions with AGENTS.md」でも、コードベースの案内、テスト方法、プロジェクト標準を伝える用途が示されています。

一方、「お問い合わせ画面の文言を変える」のような今回限りの目的は、依頼文へ書きます。AGENTS.mdに一時的なタスクを足し続けると、終了済みの指示が次の作業にも効き、誤変更の原因になります。

役割は、AGENTS.mdが固定の作業規則、依頼文が今回の目的と完成条件、READMEが人向けの利用方法、テストやlintが機械判定、と分けます。

置き場所	書く内容	具体例	見直すタイミング
AGENTS.md	繰り返し使う作業規則	変更禁止箇所、命名、検証コマンド	構成や正式コマンドが変わったとき
今回の依頼文	その作業だけの目的と範囲	対象ファイル、完成条件、期限	依頼ごと
README・設計資料	人にも残す詳しい背景	セットアップ、構成、設計理由	仕様や運用が変わったとき
テスト・lint	機械的に合否を判定する条件	単体テスト、型検査、リンク検査	挙動や品質基準が変わったとき

もう1つ、限界も知っておきます。Codex公式リポジトリの基本指示では、システム・開発者・ユーザーから直接与えられた指示はAGENTS.mdより優先されると定められています。つまりAGENTS.mdだけで権限や安全条件を変更できるわけではありません。重要な条件は、テスト・lint・権限設定のような機械の仕組みでも確かめます。

最初の1枚を置く場所と読まれる範囲

初心者はまず1枚だけ作れば足ります。手順は次のとおりです。

1. .gitフォルダがある場所(=プロジェクトルート)を確認する。公式の「Advanced Configuration」によると、Codexは既定で.gitを含むディレクトリをプロジェクトルートとして扱います(設定project_root_markersで変更可能)。
2. そのルートにAGENTS.mdを1枚作る。
3. 特定のフォルダだけ別ルールが必要になったときに限り、そのフォルダへもう1枚足す。最初から増やさない。
4. 新しいセッションでCodexを起動し、読み込まれたかを確認する(確認のしかたは後述)。

読まれる範囲の仕組みも短く押さえます。公式ガイドによると、Codexは実行開始時に指示の連鎖を組み立てます。Codexホーム(既定は~/.codex)の指示を確認し、プロジェクトルートから現在の作業ディレクトリまで探索します。各階層では空でないAGENTS.override.mdがあれば先に採用し、なければAGENTS.md、次に設定済みの代替名を確認して、最大1ファイルを採用します。

複数ファイルはルート側から結合され、作業場所に近い指示が後ろに置かれます。衝突したときは深い階層(作業場所に近い側)の指示が優先されます。だから全体規則はルートへ、特定サービスの規則はそのフォルダの近くへ置きます。

読み込める量には上限もあります。公式ガイドの執筆時点の説明では、既定の上限は32 KiBです。ただしこの値は設定(project_doc_max_bytes)で変えられ、ページによって説明の細部に差もあります。数値は変わり得るので、利用時点の公式案内で確認してください。上限に近づくほど後続の指示が入りきらない恐れがあるため、巨大な1ファイルへ集約しない方が安全です。

フォルダ構成に迷う場合は、Claude Codeで最初に見るフォルダとファイルも参考になります。製品は異なりますが、規則を適用範囲ごとに分ける考え方は共通です。

最小テンプレートと、書くルール・書かないルール

最初は、対象範囲、禁止事項、検証、報告の4点に絞ります。

# このリポジトリの作業ルール

## 対象と方針
- 変更は依頼された範囲に限定する。
- 既存の構成と命名規則を優先する。
- 新しい依存関係を追加する前に確認する。

## 触らないもの
- `.env`と認証情報を読み書きしない。
- 依頼なしに本番設定を変更しない。
- 関係のないファイルを整形しない。

## 検証
- JavaScriptを変更したら `npm test` を実行する。
- 表示を変更したらモバイル幅でも確認する。

## 完了報告
- 変更ファイル、実行した検証、残った問題を報告する。

npm testは、自分のリポジトリに実在するコマンドへ置き換えます。package.jsonや開発手順で正式名を確認してから書きます。「適切に確認する」ではなく、実行できるコマンドを書くことが重要です。実例として、OpenAI自身のCodexリポジトリのAGENTS.mdも、整形はjust fmt、変更したプロジェクトのテストはjust test -p <プロジェクト名>のように、条件と実行コマンドを対応させた具体的な規則だけを並べています。

検証欄は、変更の種類とコマンドの対応表にすると迷いません。

## 検証
- Markdownだけの変更: `npm run lint:content`
- TypeScriptの変更: `npm run typecheck`
- UIの変更: `npm test`の後、幅375pxと1280pxで主要画面を確認
- コマンドが失敗したら、終了コードとエラー要約を報告する

逆に、悪い例は、抽象的な理想、今回限りの作業、互いに矛盾する命令を一つに混ぜたものです。

- 常に最高品質にする。
- できるだけ速く終える。
- すべてのファイルを改善する。
- ファイルは必要最小限しか変更しない。
- 今日だけトップページの文章を直す。

「最高品質」には判定基準がなく、「すべて」と「必要最小限」は衝突します。「今日だけ」も次回には不要です。観察できる行動へ直します。

-- 常に最高品質にする。
-- できるだけ速く終える。
-- すべてのファイルを改善する。
-- ファイルは必要最小限しか変更しない。
-- 今日だけトップページの文章を直す。
+- 変更は依頼で指定されたファイルに限定する。
+- 挙動を変えたら関連テストを実行する。
+- テストを実行できない場合は、理由と未確認範囲を報告する。

書くかどうかの判定は2問です。「別の依頼でも守るか」「守った事実を確認できるか」。どちらかが否なら、個別依頼か説明資料へ移します。長文化しそうなら、AIへの指示が長すぎると失敗する理由も参考に、固定ルールと個別条件を分けてください。

読み込まれたか確認する方法と、長くなったときの分け方

作ったら、読み込まれたかを必ず確かめます。公式ガイドの説明では、指示の連鎖は実行ごとに、TUI(対話画面)では通常セッション開始時に構築されます。編集中のAGENTS.mdがいまのセッションへ即時反映されると決めつけず、対象ディレクトリから新しく起動して確認するのが確実です。

codex --ask-for-approval never "現在の指示を要約してください"
codex --cd src --ask-for-approval never "有効な指示ファイルと、その出どころを示してください"

オプションの意味は公式の「Developer commands」にあります。--cdは作業ディレクトリを指定するオプション、--ask-for-approvalはコマンド実行前に人の承認を求める条件(untrusted・on-request・never)を指定するオプションです。注意点が1つあります。neverは「承認の確認を省く」設定であって、「読み取り専用にする」設定ではありません。だから上のような、内容を要約させる読み取り目的の確認だけに使い、変更作業へそのまま流用しないでください。コマンド名や値は更新される可能性があるため、実行時点の公式案内で確認してください。

更新の基準はシンプルです。同じ注意や失敗が繰り返されたとき、新しい検証が正式運用になったときに足します。終了した移行作業、存在しないフォルダ、廃止したコマンドは削除します。見直しは月日ではなく「コマンドが変わった」「対象が増えた」などの変化を基準にします。

それでも長くなってきたら、目次化します。OpenAIの実運用記事「Harness engineering」では、巨大なAGENTS.mdを百科事典にせず、あるリポジトリで約100行の短い入口として使い、詳しい資料へ案内する目次にした例が紹介されています。この「約100行」はそのリポジトリでの実例で、仕様上の上限や全員への推奨値ではありません。持ち帰るのは考え方です。AGENTS.mdは短い入口にして、詳しい設計や手順は版管理された資料へ分け、機械判定できる規則はテストやlintへ移します。

Codexへテストを依頼する書き方と組み合わせると、規則に書いた検証を個別作業の完成条件まで具体化できます。権限エラーが出た場合は、規則を弱める前にCodexのsandbox・permissionエラーの切り分けで原因を分けてください。

よくある質問

AGENTS.mdはどこに置けばよいですか？

まずは.gitのあるプロジェクトルートに1つ置きます。特定のサービスやフォルダだけ別ルールが必要になったら、その階層へ追加します。Codexはプロジェクトルートから現在の作業ディレクトリまでを探索します。

AGENTS.mdとREADMEの違いは何ですか？

AGENTS.mdはCodexが作業時に守る短い指示、READMEは人が利用・開発するための説明です。詳しい背景をAGENTS.mdへ詰め込まず、必要ならREADMEや設計資料への参照を書きます。

AGENTS.override.mdはいつ使いますか？

同じ階層の通常ルールを一時的または限定的に置き換えたいときに使います。その階層では空でないAGENTS.override.mdが先に選ばれるため、不要になったら削除または退避し、通常のAGENTS.mdへ戻します。

AGENTS.mdを変更したのに反映されないのはなぜですか？

現在のセッションが変更前の指示を読み込んでいる可能性があります。ほかに、想定外の作業ディレクトリ、上位階層のAGENTS.override.md、空ファイル、合計サイズの上限も疑います。対象ディレクトリからCodexを新しく起動し、読み込んだ指示元と有効な内容を要約させて切り分けます。

AGENTS.mdを書けば必ずルールを守らせられますか？

いいえ。AGENTS.mdは毎回読み込まれる重要な指示ですが、テストや権限制御そのものではなく、システム・開発者・ユーザーの直接指示より優先されることもありません。重要な条件は、実在する検証コマンド、lint、CI(自動チェックの仕組み)、sandbox(隔離された実行環境)でも機械的に確かめてください。

まとめ

短く正確なAGENTS.md、具体的な依頼、実際に通る検証がそろえば、同じ前提を毎回説明する手間を減らせます。次にやることは3つです。

• .gitのあるプロジェクトルートに、4ブロック(対象と方針・触らないもの・検証・完了報告)のAGENTS.mdを1枚作る。
• 検証欄のnpm testなどの仮のコマンドを、自分のリポジトリに実在する正式コマンドへ置き換える。
• 新しいセッションでCodexを起動し、いま有効な指示を要約させて、読み込まれたことを確かめる。

公式一次情報

確認日: 2026-07-26

• OpenAI「Custom instructions with AGENTS.md」: 指示ファイルの探索順、階層ごとの結合と優先順位、AGENTS.override.md、既定上限32 KiBの説明。
• OpenAI「Developer commands」: --cdと--ask-for-approvalの意味、承認とsandboxを回避する危険なフラグへの警告。
• OpenAI「Advanced Configuration」: プロジェクトルートの判定(既定は.git)、project_doc_max_bytesやproject_doc_fallback_filenamesなどの関連設定。
• OpenAI「Harness engineering: leveraging Codex in an agent-first world」: 巨大なAGENTS.mdを百科事典にせず、短い入口と詳細資料への目次として使った実運用例。
• Codex公式リポジトリの基本指示(default.md): AGENTS.mdの適用範囲は配置ディレクトリ以下で、深い階層と上位の直接指示が優先されるという順位。
• Codex公式リポジトリのAGENTS.md: 実在する整形・テストコマンドを条件と対応させた、観察・実行できる規則の実例。