Codex AGENTS.md

AGENTS.md は Codex のカスタム指示ファイルであり、Codex にグローバルなガイダンスとワークフロー仕様を設定できます。

この節では、AGENTS.md の作成方法と使用方法について詳しく説明します。


AGENTS.mdとは何ですか?

Codexは起動時に自動的に読み取りますAGENTS.md「ファイルは、「グローバル設定+プロジェクトレベル上書き」の階層メカニズムにより、どのコードリポジトリを開いても、すべてのタスクが一貫した作業規約を継承できるようにします。」

AGENTS.md は、Codex が作業を実行する前に読み取る指示ファイルであり、あなたが以下のことを行うことを可能にします:

  • グローバルコーディング規約の設定
  • プロジェクト固有のワークフローを定義する
  • 異なるディレクトリに異なるガイダンスを提供する
  • 標準化チームの開発実践

AGENTS.mdを使うことで、Codexがコードベース全体で一貫した規約に従うことを保証できます。


Codex の発見方法ガイド

Codexは以下の優先順位で命令チェーンを構築します。

三層ローディングメカニズム

階層 ルールを読み込む 説明
グローバル層 読み取り~/.codex/AGENTS.override.md 存在しなければ読み取る~/.codex/AGENTS.md、最初の非空ファイルだけを取得する
プロジェクト層 Gitルートディレクトリから現在のディレクトリへと段階的にスキャンする。 各層を順に確認する。AGENTS.override.md → AGENTS.md → project_doc_fallback_filenames中の代替ファイル名
マージ層 根から葉へ順に連結する 現在のディレクトリに近いファイルほど出現が遅く、優先度が高い。

結合後の合計サイズの上限はデフォルトで32 KiB(によるproject_doc_max_bytes制御)、超過部分は切り捨てられます。


第一歩:グローバル設定を作成する

グローバル設定はすべてのプロジェクトに適用され、共通の作業取り決めを置くのに適しています。

設定ディレクトリを作成する

mkdir -p ~/.codex

Codex ホームディレクトリが存在することを確認し、すべてのグローバル設定をこのディレクトリの下に置きます。

グローバルな規約を書く

作成~/.codex/AGENTS.mdファイルに、すべてのプロジェクトに共通する規約を書き込む:

# ~/.codex/AGENTS.md

## 全局工作约定

- 修改 JavaScript 文件后,始终运行 npm test
- 安装依赖时优先使用 pnpm
- 新增生产依赖前先请求确认

設定が有効かどうかを確認する

次のコマンドを実行すると、Codex はあなたが書き込んだ項目をエコーバックするはずです。

codex --ask-for-approval never "Summarize the current instructions."

一時的なグローバルオーバーライドが必要な場合は、作成できます。AGENTS.override.md、そのファイルを削除すれば、元の設定を復元できます。


ステップ2:倉庫の階層に応じて設定する。

プロジェクトレベルのファイルにより、Codexはリポジトリ固有の規範を遵守しつつ、グローバル設定を継承します。

リポジトリレベルの規約を追加

プロジェクトルートディレクトリに作成AGENTS.md:

# AGENTS.md

## 仓库约定

- 提 PR 前运行 npm run lint
- 修改公共工具行为时,同步更新 docs/ 中的文档

サブディレクトリにオーバーライドを追加

特別な要件があるサブディレクトリについては(例えばservices/payments/)、作成AGENTS.override.md部分的な上書きを行う:

# services/payments/AGENTS.override.md

## 支付服务规则

- 使用 make test-payments 替代 npm test
- 轮换 API Key 前必须通知安全频道

完全なディレクトリ構造

以下は典型的な倉庫のロードです。AGENTS.md後のディレクトリ構成:

repo/
├── AGENTS.md                          # 仓库级约定(加载)
└── services/
    ├── payments/
    │   ├── AGENTS.md                  # 被跳过(override 优先)
    │   └── AGENTS.override.md         # 支付服务覆写(加载)
    └── search/
        └── AGENTS.md                  # 搜索服务约定(加载)

同じディレクトリ内で、AGENTS.override.md存在する場合、同レベルのAGENTS.mdスキップされます。

ロード順の検証

サブディレクトリからCodexを起動し、読み込まれた指示の出所を確認してください:

codex --cd services/payments --ask-for-approval never \
  "List the instruction sources you loaded."

期待結果:グローバルファイル、リポジトリのルートディレクトリのファイル、ペイメントサービスのオーバーライドファイルを順に列挙する。


詳細設定

以下の2つの機能は、命令ロード動作のさらなるカスタマイズが必要なシナリオに適用されます。

カスタムファイル名

もしプロジェクトに既に慣習が確立しているならTEAM_GUIDE.md設定ファイルのフォールバックリストに追加でき、Codexはそれを指示ファイルとして扱います:

# ~/.codex/config.toml
# 追加回退文件名并提高合并上限
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

修正後、各ディレクトリのチェック順序は次のようになります。AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md最初に存在するファイルを取る。

設定を変更した後は、Codexを再起動しないと有効になりません。config.toml変更が有効になります。

設定ディレクトリを切り替える

通過CODEX_HOME環境変数は、異なるプロジェクトや自動化プロセスごとに独立した構成プロファイルを使用できます:

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

この時、Codexは現在のディレクトリの.codexサブディレクトリはデフォルト設定ではなく、グローバル設定を読み取ります。~/.codex。


検証とデバッグ

以下のコマンドで、現在有効な命令の出所をすばやく確認できます。

クイックチェック

# 从仓库根目录检查全局 + 项目指令
codex --ask-for-approval never "Summarize the current instructions."

# 从子目录检查嵌套覆写
codex --cd subdir --ask-for-approval never "Show which instruction files are active."

詳細ログを有効にする

命令のロードプロセスを詳細に監査する必要がある場合は、TUIログを有効にできます:

# 输出 TUI 日志到本地目录
codex -c log_dir=./.codex-log
# 日志文件位于 ./.codex-log/codex-tui.log

よくある問題のトラブルシューティング

下表は、設定中に発生する可能性がある問題と、その調査の方向性をまとめたものです。

現象 調査の方向性
何も読み込まれていません。 ファイルが空でないことを確認して実行してください。codex statusワークスペースのルートディレクトリが正しいか確認してください。
誤った命令が発生しました。 上位ディレクトリに遺漏がないか確認する。AGENTS.override.md
ファイル名のロールバックが有効にならない 確認config.toml綴りは正しいので、Codexを再起動して有効にしてください。
指令内容が途中で切れました。 高めるproject_doc_max_bytes、または大きなファイルを複数階層のディレクトリに分割する
プロフィール混乱 実行echo $CODEX_HOME、指しているのが期待されるディレクトリであることを確認する
その他の拡張