Codexの設定 - AGENTS.md

概要

AGENTS.md は、OpenAI Codex CLIがタスク実行前に自動的に読み込む Markdown 形式の指示ファイルである。

Codexは会話開始時に、グローバル・プロジェクト・サブディレクトリの各スコープを走査して AGENTS.md を収集して、それらを結合したうえで作業に入る。
そのため、AGENTS.md に書かれた内容はユーザが毎回入力しなくても常にエージェントへ伝わる。

Codexの指示は「指示層 (instruction layer)」という一つの枠組みで管理される。
この枠組みは以下の 2 つのファセットで構成される。

• ガイダンス層 (AGENTS.md)

  「どのように作業するか」を制御する。

  リポジトリ規約、コーディング規約、ビルド・テストコマンド、PR チェックリスト等をエージェントに伝える。

• ポリシー層 (Rules)

  「何が実行可能か」を制御する。

  コマンドの許可・確認・禁止の判定ロジックを記述する。

Codexでは、AGENTS.md と Rules は独立した別概念ではなく、同じ指示層を構成する異なる役割分担である。
両者を組み合わせることにより、Codexの動作を細かく制御できる。

AGENTS.md を使用することにより、以下のメリットが得られる。

• プロジェクト固有の知識を永続化

  コーディング規約、技術スタック、ビルド手順を全セッションで共有する。

• 階層的なスコープ制御

  グローバル・プロジェクト・サブディレクトリの 3 層で指示を管理できる。

• チーム全体での共有

  Git 管理下に置き、チームメンバー間で一貫した指示を共有できる。

• 近いディレクトリの指示が優先

  サブディレクトリの AGENTS.md が親の内容を上書きできる。

ファイル探索順序

Codexは各ディレクトリで複数のファイル名を探索し、最初に見つかったものを使用する。

各ディレクトリでの探索順序を以下に示す。

ファイル探索順序

優先度	ファイル名	用途
1 (最高)	AGENTS.override.md	ディレクトリ固有の補強指示。通常の AGENTS.md よりも優先される。
2	AGENTS.md	標準的な指示ファイル。最も一般的に使用される。
3	TEAM_GUIDE.md	チーム向けガイドファイル。AGENTS.md が存在しない場合に使用される。
4 (最低)	.agents.md	ドット始まりの隠しファイル形式。非表示にしたい場合に使用する。

Codexは各ディレクトリで上表の順に探索を行い、最初に見つかったファイルを採用する。
同じディレクトリに複数のファイルが存在する場合、優先度の高いものだけが読み込まれる。

代替ファイル名は config.toml の project_doc_fallback_filenames オプションで追加できる。

詳細は、設定オプションセクションを参照すること。

スコープ階層

Codexの指示ファイルは、3つのスコープで管理される。

スコープが異なる指示ファイルは全て読み込まれ、後述の優先ルールに従って結合される。

グローバルスコープ

全てのプロジェクトで共通に適用される指示を定義する。

• 配置場所

  ~/.codex/AGENTS.md

  または

  ~/.codex/AGENTS.override.md

• 変更方法

  環境変数 CODEX_HOME に別のディレクトリパスを指定することで変更できる。

• 用途

  個人的なコーディングスタイル、汎用的なコミットメッセージ形式、全プロジェクト共通のエスカレーションルール

 # CODEX_HOME で別のグローバル設定ディレクトリを指定する例
 
 export CODEX_HOME="$HOME/.config/codex"

プロジェクトスコープ

特定のプロジェクト (Git リポジトリ) に適用される指示を定義する。

• 探索範囲

  Gitルートディレクトリから現在の作業ディレクトリ (CWD) まで、全階層を走査する。

• 優先ルール (closer wins)

  CWDに近いディレクトリの指示ほど優先される。

  例: services/payments/AGENTS.md は AGENTS.md (リポジトリルート) よりも優先される。

• 用途

  リポジトリ規約、ビルド・テストコマンド、プロジェクト固有のコーディング規約

探索経路の例を以下に示す。

 # CWD が services/payments/ の場合の探索経路
 # 以下の順に読み込まれ、後から読まれたものが優先される
 
 ~/.codex/AGENTS.md             # グローバル (最低優先)
 AGENTS.md                      # プロジェクトルート
 services/AGENTS.md             # 中間ディレクトリ
 services/payments/AGENTS.md    # CWD に最も近い (最高優先)

統合方法

複数のスコープから読み込まれた全ての指示ファイルは結合される。

• 結合ルール

  全レイヤーの内容が1つの指示として、Codexに渡される。

• 優先ルール

  CWDに近いディレクトリの内容が後に出現するため、実質的に上書きとなる。

• 信頼済プロジェクト

  プロジェクトスコープのファイルはプロジェクトが信頼済の場合にのみ読み込まれる。

  詳細は、信頼されていないプロジェクトでの動作セクションを参照すること。

スコープ階層のまとめ

スコープ	配置場所	常に読み込まれるか	主な用途
グローバル	~/.codex/AGENTS.md	はい	個人設定、全プロジェクト共通のルール
プロジェクト (Gitルート)	<プロジェクトルート>/AGENTS.md	信頼済のみ	プロジェクト全体の規約
サブディレクトリ	<プロジェクトルート>/<サブディレクトリ>/AGENTS.md	信頼済のみ	サブシステム固有の詳細指示

設定オプション

project_doc_fallback_filenames

config.toml の project_doc_fallback_filenames オプションを使用することで、AGENTS.md 以外の代替ファイル名を追加できる。

既存のドキュメントファイルを AGENTS.md の代わりに読み込ませたい場合に使用する。

 # ~/.codex/config.toml または <プロジェクトルート>/.codex/config.toml
 
 [project]
 # AGENTS.mdが見つからない場合に探索する代替ファイル名
 # デフォルトの探索順 (AGENTS.override.md --> AGENTS.md --> TEAM_GUIDE.md --> .agents.md) に追加される
 
 project_doc_fallback_filenames = [
    "CONTRIBUTING.md",
    "DEVELOPMENT.md",
    ".github/copilot-instructions.md"
 ]

代替ファイル名はデフォルトの探索順の後に追加される形で適用される。
既存の探索順 (AGENTS.override.md --> AGENTS.md --> TEAM_GUIDE.md --> .agents.md) は変更されない。

project_doc_max_bytes

読み込む指示ファイルのサイズ上限を設定できる。

• デフォルト値

  32[KB] (32,768バイト)

• 設定方法

  config.toml の project_doc_max_bytes に整数値で指定する。

 [project]
 
 # 最大読み込みサイズを64[KB]に変更する例
 project_doc_max_bytes = 65536

上限を超えた分のファイル内容は切り捨てられる。
AGENTS.mdが大規模になった場合は、ファイルを分割するか、このオプションで上限を拡大することを検討する。

AGENTS.mdに記述すべき内容

推奨される記述内容

AGENTS.mdに記述することにより、Codexの動作が改善される内容を以下に示す。

• リポジトリ規約

  ブランチ命名規則 (例: feature/、fix/)、コミットメッセージのフォーマット (Conventional Commits等)

• ビルド・テストコマンド

  npm test、cargo test、make build 等、プロジェクト固有のコマンドをフラグ付きで記載する。

• コーディング規約

  命名規則、インデント、ファイル配置等のルール。

  抽象的な説明より、具体的なコード例を優先する。

• PRチェックリスト

  マージ前に確認すべき事項を列挙する。

  Codexがコード変更後に自動チェックできるようになる。

• エスカレーションルール

  Codexが判断できない場合にどう行動すべきかを定義する。

  例: 「外部APIに影響する変更は必ずユーザに確認する」

推奨されない記述内容

AGENTS.mdに記述すると逆効果になる内容を以下に示す。

• 曖昧な指示

  「コードを読みやすく書くこと」のような抽象的な説明は効果が薄い。

  具体的なルールに置き換えること。

• 矛盾した優先度

  「常に最速を優先」かつ「常に最高品質を優先」のように矛盾する指示は、Codexを混乱させる。

• 実行例のない散文

  コマンドやソースコード例のない説明文のみのセクションは読み飛ばされやすい。

• 既存ドキュメントの複製

  READMEやCONTRIBUTING.mdの内容をそのままコピーするのではなく、Codexの動作に直接影響する内容に絞る。

AGENTS.override.mdの使い分け

AGENTS.override.md は、通常の AGENTS.md より高い優先度を持つ指示ファイルである。

「上書き」という名前ではあるが、機能的には 階層的指示の補強 として使用する。
同一ディレクトリに両方のファイルが存在する場合、AGENTS.override.md のみが読み込まれる。

主な用途を以下に示す。

• サブディレクトリ固有の追加ルール

  親の AGENTS.md の指示はそのまま有効で、このディレクトリ以下だけに追加の制約やコンテキストを与えたい場合に使用する。

• 一時的な指示の挿入

  特定の作業フェーズ (例: リリース前の凍結期間) だけ異なるルールを適用したい場合に使用する。

• チーム別の指示分離

  モノレポでチームごとに異なる規約がある場合、各サブディレクトリに AGENTS.override.md を配置して分離する。

# モノレポでの配置例

AGENTS.md                          # リポジトリ全体の共通指示
services/
├── payments/
│   └── AGENTS.override.md         # 決済サービス固有の指示
└── notifications/
    └── AGENTS.md                   # 通知サービスの指示

AGENTS.mdのサンプル

シンプルなサンプル

リポジトリルートに配置する標準的な AGENTS.md のサンプルを以下に示す。

• ファイルの配置場所

  AGENTS.md (プロジェクトルート)

 # Project Instructions
 
 ## Tech Stack
 
 - Language: TypeScript 5.x
 - Runtime: Node.js 20 LTS
 - Framework: Express 4.18
 - Test: Jest + Supertest
 
 ## Commands
 
 - `npm test` - 全テストを実行する
 - `npm run test:unit` - ユニットテストのみ実行する
 - `npm run lint` - ESLintを実行する
 - `npm run lint:fix` - ESLintを実行して自動修正する
 - `npm run build` - TypeScriptのコンパイルを実行する
 
 ## Coding Conventions
 
 - 関数名・変数名: camelCase
 - クラス名: PascalCase
 - 定数: UPPER_SNAKE_CASE
 - インデント: 半角スペース2つ
 - 行末セミコロン: 必須
 
 ## Commit Message Format
 
 Conventional Commitsに従う。
 
 - feat: 新機能
 - fix: バグ修正
 - docs: ドキュメント変更
 - test: テスト追加・修正
 - refactor: リファクタリング
 
 ## Escalation
 
 - 外部APIのインターフェース変更を伴う場合はユーザに確認する
 - データベーススキーマの変更を伴う場合はユーザに確認する

ネストされたサンプル

サブディレクトリに配置するオーバーライドファイルのサンプルを以下に示す。

• ファイルの配置場所

  services/payments/AGENTS.override.md

 # Payments Service - Additional Instructions
 
 ## Additional Context
 
 このサービスは、Stripe APIと連携する。
 全ての金額は日本円 (JPY) の整数値で管理する。(小数点なし)
 
 ## Additional Commands
 
 - `npm run test:payments` - 決済サービスのテストのみ実行する
 - `npm run stripe:mock` - Stripeモックサーバを起動する
 
 ## Security Requirements
 
 - カード番号・CVV を変数に保存しない
 - ログに金融情報を出力しない
 - StripeのWebhook署名検証を必ず実装する
 
 ## Escalation (Override)
 
 - 決済フローの変更は規模に関わらずユーザに確認する
 - Stripe API バージョンの変更はユーザに確認する

Rules

Rulesとは

Rulesは、AGENTS.mdと同じ「指示層 (instruction layer)」に属する「ポリシー層」である。

AGENTS.mdがエージェントに「どのように作業するか」を伝えるのに対し、Rulesは「コマンドレベルで何が実行可能か」を制御する。

AGENTS.md と Rules の役割の違い

項目	AGENTS.md (ガイダンス層)	Rules (ポリシー層)
制御対象	エージェントの思考・作業方法	コマンドの実行可否
記述形式	自然言語 (Markdown)	Starlark (Python 風の構造化言語)
適用タイミング	セッション開始時に読み込まれる	コマンド実行前に評価される
主な用途	規約・コマンド・コーディングスタイル	危険なコマンドのブロック・確認強制

Rulesの配置場所

Rulesファイルは、2箇所に配置できる。

• ユーザレイヤ

  ~/.codex/rules/

  全てのプロジェクトに適用される。

  信頼状態に関わらず常に読み込まれる。

• プロジェクトレイヤ

  <プロジェクトルート>/.codex/rules/

  信頼済プロジェクト (project_trust = true) の場合のみ読み込まれる。

ディレクトリ内の全 .rules ファイルが自動的に読み込まれる。
ファイル名に制約はなく、機能ごとに分割して管理できる。

# 配置例

~/.codex/rules/
├── network.rules        # ネットワーク関連のポリシー
└── filesystem.rules     # ファイルシステム関連のポリシー

<プロジェクトルート>/.codex/rules/
├── build.rules          # ビルドコマンドのポリシー
└── deploy.rules         # デプロイコマンドのポリシー

Decisionの種類

各ルールは以下の3種類のDecisionを返す。

Decision の種類

Decision	動作	使用例
allow	コマンドを確認なしで実行する	テストコマンド、リードオンリー操作
prompt	ユーザに確認を求めてから実行する	ファイル削除、設定変更
forbidden	コマンドの実行を拒否する	本番環境への直接アクセス、機密ファイルの読み取り

ルール優先度

複数のルールが同一コマンドにマッチした場合、以下の優先度で最終的なDecisionが決まる。

• 優先度順

  forbidden --> prompt --> allow

• 具体的な動作

  1つでも forbidden にマッチすれば、他のルールに関わらずコマンドは拒否される。

  forbidden がなく、1つでも prompt にマッチすれば確認ダイアログが表示される。

  全ルールが allow の場合のみ確認なしで実行される。

Rulesのサンプル

Starlark形式の .rules拡張子 のファイルの記述例を以下に示す。

ファイルの配置場所: ~/.codex/rules/filesystem.rules

 # ファイルシステム関連のポリシー
 
 def check(cmd):
    # 機密ファイルへのアクセスを禁止する
    if cmd.matches_glob("cat ~/.ssh/*"):
       return forbidden("SSH 秘密鍵へのアクセスは禁止されています")
 
    if cmd.matches_glob("cat ~/.aws/credentials"):
       return forbidden("AWS 認証情報へのアクセスは禁止されています")
 
    # /etc 以下の書き込みは確認を求める
    if cmd.matches_glob("*> /etc/*") or cmd.matches_glob("sudo tee /etc/*"):
       return prompt("システム設定ファイルの変更です。続行しますか?")
 
    # rm -rf は確認を求める
    if "rm -rf" in cmd.args:
       return prompt("再帰的な削除を実行します。続行しますか?")
 
    return allow()

config.toml 内でルールをインラインで記述することもできる。

• ファイルの配置場所

  ~/.codex/config.toml

 # config.toml内でのインラインルール定義
 
 [[rules]]
 name = "no-force-push"
 description = "force push を禁止する"
 policy = """
 def check(cmd):
    if "git push" in cmd.args and ("--force" in cmd.args or "-f" in cmd.args):
       return forbidden("force push は禁止されています")
    return allow()
 """
 
 [[rules]]
 name = "confirm-deploy"
 description = "デプロイコマンドは確認を求める"
 policy = """
 def check(cmd):
    if cmd.matches_glob("*deploy*prod*") or cmd.matches_glob("*release*"):
       return prompt("本番環境へのデプロイです。続行しますか?")
    return allow()
 """

ルール検証

定義したルールが意図した通りに動作するかを検証できる。

 # 特定コマンドに対してルールを評価する
 codex execpolicy check "rm -rf /tmp/work"
 
 # 出力例
 # Decision: prompt
 # Matched rule: filesystem.rules / check
 # Reason: 再帰的な削除を実行します。続行しますか?

このコマンドを使用することで、実際にコマンドを実行することなくルールの動作を確認できる。

AGENTS.md と Rules の役割分担

AGENTS.mdとRulesをどちらに何を書くべきかを、下表に整理する。

AGENTS.md と Rules の使い分け基準

記述したい内容	AGENTS.md	Rules
ビルド・テストコマンドの案内	記述する	記述しない
コーディング規約・命名規則	記述する	記述しない
PR チェックリスト	記述する	記述しない
危険なコマンドの実行禁止	記述しない	記述する
特定コマンドに確認ダイアログを挿入	記述しない	記述する
本番環境への操作をブロック	記述しない	記述する
コマンド実行を自動許可するホワイトリスト	記述しない	記述する

AGENTS.mdとRulesを組み合わせた統合パターンの例を以下に示す。

以下の例では、AGENTS.mdでビルド・テストコマンドを案内しつつ、Rulesでデプロイコマンドへの安全ガードを設けている。

• ファイルの配置場所

  AGENTS.md

   ## Commands
   
   - `npm test` - テストを実行する (自動許可)
   - `npm run build` - ビルドを実行する (自動許可)
   - `npm run deploy:prod` - 本番デプロイ (Rulesにより確認ダイアログが表示される)
   
   ## Escalation
   
   - データベースの変更を伴う場合はユーザに確認する
  

  
  

• ファイルの配置場所

  .codex/rules/deploy.rules
  

   def check(cmd):
      # テスト・ビルドは自動許可
      if cmd.matches_glob("npm test*") or cmd.matches_glob("npm run build*"):
         return allow()
   
      # 本番デプロイは確認を求める
      if "deploy:prod" in cmd.args:
         return prompt("本番環境へのデプロイです。続行しますか?")
   
      return allow()
  

信頼されていないプロジェクトでの動作

Codexはプロジェクトの信頼状態に応じて、読み込む設定ファイルの範囲を変える。

これは、悪意のある AGENTS.md やRulesによって危険なコマンドが自動許可されることを防ぐセキュリティ機構である。

信頼されていないプロジェクトでスキップされるもの

• <プロジェクトルート>/.codex/ 以下の全ファイル

  プロジェクトローカルの AGENTS.md、Rules、config.toml 等全て読み込まれない。

• サブディレクトリの AGENTS.md または AGENTS.override.md

  プロジェクト内の全階層の指示ファイルがスキップされる。

常に読み込まれるもの

• ユーザ・グローバル設定

  信頼状態に関わらず常に適用される。

  ~/.codex/AGENTS.md

  ~/.codex/rules/

  ~/.codex/config.toml

project_trust による信頼の付与

プロジェクトを信頼済にするには、config.toml の project_trust オプションを使用する。

 # ~/.codex/config.toml (ユーザ設定でプロジェクトを信頼する場合)
 
 [[trusted_projects]]
 path = "/home/user/repos/my-project"
 
 # または、プロジェクトローカルで自己申告する場合
 # <プロジェクトルート>/.codex/config.toml
 [project]
 project_trust = true

プロジェクトローカルの config.toml で project_trust = true を設定しても、ユーザが明示的に承認しない限り適用されない場合がある。
初回実行時にCodexがプロジェクトを信頼するか確認ダイアログを表示する。

推奨事項

200行以内に収める

AGENTS.mdのサイズは200行以内に収めることを推奨する。

ファイルが大きくなるほど、Codexがコンテキストウィンドウを消費し、推論コストが増加する。
また、過剰な指示は成功率の低下を招くことが知られている。

ファイルが大きくなった場合は、以下に示す方法で管理する。

• タスク別Markdownファイルへ分割するパターンを採用する。(後述)
• 既存のREADMEやCONTRIBUTING.mdと重複する内容を削除する。
• 具体性の低い抽象的な説明を削除する。

「同じミスを2回したら更新」パターン

AGENTS.md の更新タイミングの判断基準として、以下に示すパターンを推奨する。

Codexが同じ種類の誤りを2回繰り返した場合に、その誤りを防ぐ指示をAGENTS.mdに追記する。

• 1回目の誤り

  チャットで指摘して修正させる。

• 2回目の同種の誤り

  AGENTS.mdに該当するルールを追記する。

このパターンにより、実際に発生した問題のみがAGENTS.mdに蓄積される。
「将来起きるかもしれない問題」を予防的に大量に書くと、かえって成功率が低下する。

タスク別Markdownファイルへ分割するパターン

AGENTS.mdから専門的なタスク向けの指示を別ファイルに分割して管理できる。

 # ファイル分割の例

 .codex/
 ├── AGENTS.md           # 共通指示 (簡潔に保つ)
 ├── agents/
 │   ├── test.md         # テスト専用エージェントへの指示
 │   ├── docs.md         # ドキュメント生成エージェントへの指示
 │   └── refactor.md     # リファクタリングエージェントへの指示
 └── rules/
     └── safety.rules    # 安全ガード

タスク別ファイルを使用する場合は、AGENTS.md 内で参照先を明示する。

 ## Specialized Tasks

 テスト作業を行う際は `.codex/agents/test.md` を参照すること。
 ドキュメント生成を行う際は `.codex/agents/docs.md` を参照すること。

自動生成は避ける

AGENTS.md の内容を AI ツールで自動生成することは推奨しない。

自動生成した指示は冗長になりやすく、以下の問題を引き起こす。

• 推論コストの増加

  読み込むトークン数が増えるため、各リクエストのコストが上昇する。

• 成功率の低下

  過剰な指示は Codexの判断を鈍らせ、意図しない動作を招く。

• 保守性の悪化

  自動生成された内容は人間が理解・編集しにくい。

AGENTS.md は実際の経験から手動で追記する「ナレッジベース」として育てることを推奨する。

関連ページ

• Codexの設定 - 機能

  承認モード (approval mode) とサンドボックスの設定

• Codexの設定 - サブエージェント

  サブエージェントへのAGENTS.mdの継承動作

• Codexの設定 - SKILL

  Skillsとの指示層における使い分け

• Codexの設定 - Hooks

  AGENTS.mdとHooksを組み合わせたワークフロー自動化