CodexのAGENTS.mdの書き方｜失敗を防ぐ指示設計

2026年9月23日
Codex

こんにちは。Osukeラーニング、運営者の「osuke」です。

Codexに仕事を頼むたび、「このコマンドでテストして」「このフォルダは触らないで」「変更後は差分を見せて」と同じ注意を入力していませんか。AGENTS.mdへ共通ルールを置けば、リポジトリを開くたびに作業の前提を揃えられます。

ただし、思いつく注意をすべて追加すれば安定するわけではありません。長すぎる指示、上位と下位の矛盾、古いルールは、Codexを迷わせたり必要以上に停止させたりします。この記事では、現行のOpenAI公式資料を仕様の基準にし、Xで公開されている複数の活用例と失敗例を分けて確認しながら、配置、優先順位、短い書き方、読み込みの検証まで順番に整理します。

筆者本人がAGENTS.mdを運用して得た体験談ではありません。公式仕様で確認できることと、公開投稿から見えた個別の使い方を混同せず、初めて作る人が再現できる手順へまとめています。

記事のポイント

AGENTS.mdと通常プロンプトの役割分担が分かる
ルートと下位フォルダの配置基準が分かる
短く守りやすいルールの書き方が分かる
読み込みと上書きを確認する方法が分かる

CodexのAGENTS.mdの書き方

まずは、何をAGENTS.mdへ残し、何を通常の依頼、Skill、テストへ分けるかを決めます。ここを曖昧にすると、ファイルが巨大な手順書になり、今回だけの条件まで次の仕事へ持ち越してしまいます。前半では、適用範囲、短いルール、完了条件、危険操作の境界を一つずつ作ります。

役割を通常プロンプトと分ける

AGENTS.mdに向くのは、リポジトリで繰り返し必要になる作業上の合意です。使用するパッケージ管理ツール、変更してよい範囲、テストコマンド、生成物の保存先、既存コードの扱いなどが該当します。一方、「今日だけログイン画面の文言を変える」「このIssueの再現だけを行う」といった一回限りの目的は通常プロンプトへ残します。両方を混ぜると、後日の別タスクでも古い目的が効き続けるためです。

もう一つ分けたいのが、文章で伝える規則と機械的に判定できる規則です。たとえば「既存の公開APIを壊さない」は判断方針としてAGENTS.mdに置けますが、フォーマット、型検査、依存方向、テスト成否はlintやCIで検出したほうが確実です。長い作業手順や特定業務だけで使う知識はSkillや参照ドキュメントに分け、AGENTS.mdから「いつ読むか」を案内します。

Xの公開投稿では、Codexへ細かな単発命令を増やすより、上位の目的と背景を渡すことが役立ったという所感がありました。別の投稿では、AGENTS.mdをSOPやエスカレーション条件を置く運用マニュアルとして使う例も見られます。どちらも個人の使い方であり仕様ではありませんが、毎回共通する判断軸を残すという点は一致しています。個別タスクの答えではなく、答えを選ぶ基準を置くのがコツです。

置き場所	向く内容	置かない内容
AGENTS.md	共通方針、境界、検証、完了条件	今回だけの機能要件
通常プロンプト	今回の目的、対象、期限、期待結果	毎回繰り返す共通規則
Skill・資料	特定業務の詳しい手順や知識	全タスクで必ず読む短い規則
CI・lint	形式、型、テスト、依存関係の機械判定	人の判断が必要な目的や例外

最初の仕分け

毎回守る判断基準はAGENTS.md
今回だけの完成物は通常プロンプト
長い専門手順はSkillや資料
自動判定できる規則はCIやlint

適用範囲を先に決める

ルールを書く前に、どの範囲で効かせるかを決めます。OpenAI公式ドキュメントでは、CodexはまずCodexホームのグローバル指示を確認し、その後にプロジェクトルートから現在の作業ディレクトリまで下りながら指示ファイルを集めます。すべてのリポジトリで共通する好みはグローバル、リポジトリ全体の決まりはルート、特定サービスだけの差分はそのサービスのディレクトリへ置くのが基本です。

たとえばモノレポにfrontend、api、paymentsがある場合、ルートには共通のセットアップ、変更方針、基本テストを書きます。frontendには画面確認、apiにはAPI互換テスト、paymentsには決済用の専用テストと危険操作の境界だけを追加します。下位ファイルへ上位と同じ文章を複製すると、更新漏れで矛盾が生まれます。下位には「その領域だけで違う内容」を書くと管理しやすくなります。

Codexは現在の作業ディレクトリまで探索するため、同じリポジトリでも開始位置によって有効な下位指示が変わります。専門領域のルールをルートへ集めすぎると、無関係な作業まで制約します。反対に下位へ置きすぎると、別の場所から開始したタスクで読み込まれません。まず対象を「全環境」「リポジトリ全体」「特定ディレクトリ」の3段階に分けてから配置しましょう。

迷ったときは、最も広い範囲に一般原則だけを置き、例外が必要になった時点で一段下へ差分を追加します。最初から全フォルダへファイルを作るより、実際に異なるコマンドや禁止事項がある場所だけを増やすほうが、読み込み経路も説明しやすくなります。

配置の3段階

グローバル: どのリポジトリでも変わらない作業上の好み
ルート: そのプロジェクト全体のセットアップと品質基準
下位: 特定サービスだけのコマンド、例外、確認方法

必須ルールを短く書く

AGENTS.mdは、背景をすべて説明する設計書ではなく、作業時に何を判断すべきか分かる地図として書きます。見出しは「目的」「変更方針」「参照先」「検証」「禁止・承認」「完了条件」程度で十分です。各項目を一つの行動へ絞り、「品質を高くする」のような抽象語ではなく、「変更したパッケージのテストを実行し、失敗原因が今回の変更なら修正する」と観察できる言葉にします。

OpenAIの公式ブログでも、どんな修正でも大量の資料を先に読むよう求めるより、変更内容に応じて参照先を示す書き方が推奨されています。「毎回architecture.md、database.md、deployment.mdをすべて読む」ではなく、「サービス境界を変えるときはarchitecture.md、スキーマ変更時はdatabase.md」のように条件を付けます。これなら小さな文言修正で不要な資料を読み込まずに済みます。

Xでは、大型のAGENTS.mdがうまく機能せず、約100行の案内図へ縮めて詳細資料や機械的検査へつないだという紹介がありました。100行が万人に当てはまる上限ではありませんが、「詳しいほどよい」という反対事例として参考になります。行数を目標にするのではなく、毎回のタスクで使わない説明を外し、必要になったときに読める参照先へ移すことが大切です。

短い基本テンプレート

目的: このリポジトリで守る最上位の成果
変更: 既存変更の扱いと触れてよい範囲
参照: どの変更でどの資料を読むか
検証: 影響範囲に応じたコマンド
境界: 自律実行できる操作と承認が必要な操作
完了: 差分、テスト、報告が揃う条件

テストと完了条件を指定する

「必ずテストする」だけでは、全テストを毎回実行するのか、変更箇所だけでよいのか、失敗したらどこまで直すのかが分かりません。AGENTS.mdには、変更の種類と検証方法を対応させます。文書だけならリンクと形式、単一パッケージなら対象テスト、共有APIならAPI互換テスト、UIなら画面確認というように、影響に比例して検証を増やします。

完了条件は、実装が終わった状態ではなく、読者が確認できる状態まで書きます。「要求した挙動が再現できる」「変更した範囲のテストが通る」「意図しない差分がない」「残る不確実性を報告する」の4点が一例です。バグ修正では、最初に失敗を再現する検査を作り、その後に修正して通過を確認すると、偶然直っただけの状態を減らせます。

ただし、過去のモデル向けに「何があっても全テストを実行」と書いたままにすると、小さな変更でも長時間の検査を繰り返す可能性があります。公式ブログが指摘するように、モデルや開発環境が変われば適切な指示も変わります。安全なローカルテストは確認なしで実行してよい、失敗が今回の差分による場合だけ修正する、と範囲を明示すれば、停止しすぎと直しすぎの両方を防げます。

検査を実行できない場合の扱いも決めておきます。依存不足、時間上限、外部サービス停止などで未実行なら、成功したと推測させず、「実行できなかった検査」「理由」「代わりに確認したこと」を報告条件にします。これにより、テスト未完了を合格と取り違える危険を減らせます。

完了の4条件

依頼した挙動を確認できる
影響範囲に合う検査が通る
差分に無関係な変更が混ざっていない
未確認点と次の判断が明示されている

危険操作の境界を決める

AGENTS.mdには、Codexがそのまま進めてよい操作と、人へ戻す操作の境界を書きます。読み取り、対象を限定した編集、ローカルのテストなどは、自律実行を許しやすい作業です。一方、公開環境への反映、外部への送信、課金、機密情報へのアクセス、広い削除、履歴を書き換える操作は、対象と影響を確認してから進める条件を置きます。

ここで誤解しやすいのは、AGENTS.mdへ「禁止」と書くだけで技術的な権限制御になるわけではない点です。AGENTS.mdは判断を導く指示であり、sandbox、承認設定、アクセス権、CIの保護ルールを置き換えるものではありません。重要な境界は、文章、実行権限、機械的なチェックの複数層で守ります。権限そのものは別テーマなので、Codexの始め方と初回タスクで紹介した低リスクの試運転から確認すると安全です。

境界を書くときは「危険なら確認する」のような抽象表現を避けます。「本番環境への変更、外部メッセージ送信、課金、10件を超える一括更新は実行前に対象と件数を示す」と条件を具体化します。同時に、「読み取り調査、対象ファイル内の修正、ローカルテストは追加確認なしで完了まで進めてよい」と安全側の許可も書くと、何でも止まる状態を減らせます。

文章だけに頼らない境界

AGENTS.md: いつ止まり、何を確認するか
権限設定: 実際に到達できる範囲
CI・保護ルール: 破ってはいけない条件の機械判定
人の承認: 外部影響が大きい最終判断

CodexのAGENTS.mdの注意点

AGENTS.mdは作成して終わりではありません。階層の上書き、サイズ上限、古い指示、開始位置による読み込み差があるため、意図した規則が本当に有効か確認する必要があります。後半では、効かない・重い・矛盾するという代表的な失敗を順番に解消します。

優先順位と上書きを理解する

OpenAIの公式資料によると、Codexはグローバル範囲でまずAGENTS.override.mdを探し、なければAGENTS.mdを使います。プロジェクトではルートから現在の作業ディレクトリへ下り、各ディレクトリでoverride、通常ファイル、設定したfallback名の順に確認します。一つのディレクトリから採用するのは最大1ファイルです。

見つかった指示はルート側から現在地側へ連結されるため、下位ディレクトリの指示が後に現れ、上位の一般ルールを上書きできます。たとえばルートで「npm test」、paymentsで「make test-payments」と定めれば、payments配下の作業では専用ルールを使えます。overrideがあるディレクトリでは同じ場所の通常AGENTS.mdが無視されるため、両方を足し合わせるつもりで置かないでください。

公式資料では、空ファイルは読み飛ばされ、結合サイズはproject_doc_max_bytesの上限までとされています。既定は32KiBです。長い上位ファイルで上限へ達すると、重要な下位指示が入らない恐れがあります。探索順とサイズを理解せず「下位に書いたのに効かない」と判断する前に、どのファイルが採用されるか、結合量が大きすぎないかを確認しましょう。

優先順位の覚え方

全体はグローバルから始まる
プロジェクトはルートから現在地へ進む
同じ場所ではoverrideが通常版より優先
現在地に近い差分が後から効く

正確な探索順と設定例は、OpenAI公式のAGENTS.mdドキュメントで確認できます。画面やコマンドは更新される可能性があるため、配置トラブル時はこの一次情報を基準にしてください。

長すぎる指示を減らす

長いAGENTS.mdの問題は、単に入力文字数が増えることだけではありません。重要な禁止事項、参考情報、古い背景説明が同じ重さで並ぶと、どれを優先して判断すべきか分かりにくくなります。さらに、毎回適用されるため、小さな文言修正でも無関係な設計資料、全テスト、長い報告形式を要求してしまうことがあります。

減らすときは、各行へ「この規則は半分以上のタスクで必要か」「自動検査へ移せるか」「特定変更だけで必要か」「今も実行できるか」と質問します。半分未満なら条件付きの参照先やSkillへ、自動判定できるならCIへ、特定サービスだけなら下位ファイルへ移します。背景説明は設計資料へ残し、AGENTS.mdには資料を読む条件だけを書きます。

公開されたX投稿で紹介された「巨大な説明書ではなく地図にする」という考え方は、この整理に使えます。ただし、短さだけを競う必要はありません。安全上必須の境界、特殊なテスト、既存変更を守る規則まで削ると逆効果です。削る基準は文字数ではなく、常時必要か、観察可能か、他の仕組みで強制できるかの3点です。

参照先を増やす場合も、ファイル名だけを羅列しません。「データ構造を変えるとき」「公開手順を変更するとき」のように読み込む条件を一緒に書きます。条件がなければCodexは毎回全部読むか、必要な資料を見逃すかのどちらかになりやすく、地図として機能しません。

まず一つの不要な常時指示を参照先へ移し、次の小さなタスクで影響を確かめると安全です。

残す・移す・消す

残す: 毎回必要で、人の判断を助ける短い規則
移す: 特定作業だけの手順、長い背景、機械判定できる条件
消す: 重複、現状で実行不能、別ルールと矛盾する内容

矛盾と古いルールを監査する

AGENTS.mdは、失敗するたびに禁止事項を追記すると急速に古くなります。ある時点では必要だった「必ず承認を取る」「全テストを実行する」「特定ツールだけを使う」が、現在の権限、モデル、CI、チーム構成では不要かもしれません。古い制約は安全を高めるどころか、作業を途中で止めたり、より適切な手段を選べなくしたりします。

監査は月1回のような定期確認に加え、モデル変更、パッケージ管理の変更、ディレクトリ移動、CI更新、同じ失敗の再発をきっかけに行います。まず全階層の指示を一覧にし、同じ対象へ異なるコマンドが指定されていないか、参照先が存在するか、禁止と許可が衝突していないかを確認します。失敗ログがある場合も、原因が指示不足なのか、テスト不足なのかを分けます。

矛盾を見つけたら、より強い禁止を追加するのではなく、上位を一般原則、下位を差分へ戻します。たとえばルートに「影響範囲のテストを行う」、frontendに「画面テスト」、apiに「API互換テスト」と分けます。複数の開発環境を使う場合は、環境ごとに重複ファイルを増やすより、共通原則を一つにし、ツール固有の差分だけ別管理するほうが更新漏れを減らせます。

変更履歴には、追加した規則だけでなく削除した理由も短く残します。「以前の事故対策」なのか「現在も必要な品質基準」なのかが分かれば、将来の担当者が不安から同じ規則を復活させるのを防げます。監査の目的は規則を増やすことではなく、判断を明確に保つことです。

監査のきっかけ

同じ確認待ちや誤変更が2回起きた
モデル、CLI、CI、主要依存を更新した
ディレクトリやチーム担当が変わった
参照先の文書やコマンドが消えた

読み込みを実際に確認する

ファイルを正しい名前で置いたつもりでも、作業ディレクトリ、override、CODEX_HOME、fallback設定によって読み込み結果は変わります。公式資料では、リポジトリのルートからCodexへ「現在の指示を要約して」と依頼し、グローバルとプロジェクトの内容が順に入っているか確認する方法が案内されています。配置後は、いきなり重要な変更を頼まず、まず指示源と要約を出させます。

次に、サブディレクトリを作業場所として同じ確認を行います。ルートでは共通ルールだけ、専門領域では下位の差分が追加または上書きされていれば狙いどおりです。テストとして、ファイルを変更しない読み取りタスクを一つ頼み、使用するテスト、触れない範囲、完了報告の形式を説明させます。説明が合わなければ、本番タスクへ進む前に配置と文章を直します。

何も読み込まれない場合は、現在地が意図したリポジトリか、ファイルが空でないか、上位や同じ場所にoverrideがないかを確認します。fallback名を使うなら設定の綴り、別プロファイルならCODEX_HOME、長い場合はサイズ上限も対象です。内容を直したのに古い指示が出る場合は、新しい実行またはTUIセッションで指示チェーンを再構築します。

確認結果は、ルートで有効だった指示、下位で追加された差分、期待と違った点の3つに分けてメモします。同じプロジェクトをチームで使うなら、この確認例をREADMEなどから参照できるようにし、新しい下位ルールを追加した人が自分で再現確認できる状態にします。

安全な確認手順

ルートで有効な指示源と要約を確認する
下位ディレクトリで差分と上書きを確認する
読み取りだけの小さなタスクで判断を試す
合わなければ本番前に配置か文言を直す

CodexのAGENTS.mdまとめ

CodexのAGENTS.mdは、プロジェクトで繰り返し必要になる目的、変更方針、検証、危険操作の境界、完了条件を共有するためのファイルです。今回だけの要件は通常プロンプト、長い専門手順はSkillや資料、機械判定できる条件はCIやlintへ分けます。すべてを一枚へ集めるのではなく、Codexが必要な情報へたどり着く地図として設計します。

配置は、グローバル、プロジェクトルート、下位ディレクトリの3段階で考えます。Codexはルートから現在地へ指示を連結し、近い階層の差分が後から効きます。同じディレクトリではoverrideが優先され、結合サイズには既定32KiBの上限があります。書いた内容だけでなく、どのファイルが実際に読み込まれたかまで確認して初めて設定完了です。

最初から完璧な規則集を作る必要はありません。まず、毎回言い直している内容から「既存変更を壊さない」「影響範囲をテストする」「外部公開は事前確認する」のような3項目を選び、ルートAGENTS.mdへ置きます。その後、読み取りタスクで要約を確認し、必要な差分だけ下位へ足します。Codexの全体像から整理したい場合はCodexでできることと注意点、分離した作業環境も整えたい場合はCodexワークツリーの使い方へ進んでください。

運用開始後は、指示を守れなかった回数だけでなく、不要な確認や過剰なテストが増えていないかも見ます。安全性と進みやすさの両方を観察し、問題が出た箇所だけを小さく更新することで、AGENTS.mdを現状に合う作業基準として保てます。

今日の10分チェック