コンテンツにスキップ

AGENTS.md によるカスタム指示

Codex は作業を始める前に AGENTS.md ファイルを読み込みます。グローバルなガイダンスにプロジェクト固有の上書きを重ねることで、どのリポジトリを開いても、一貫した期待事項で各タスクを開始できます。

Codex がガイダンスを検出する方法

Codex は起動時に指示チェーンを構築します（1 回の実行につき 1 回。TUI では通常、起動したセッションごとに 1 回です）。検出は次の優先順位に従います。

  1. グローバルスコープ: Codex のホームディレクトリ（デフォルトでは ~/.codex。CODEX_HOME を設定している場合を除きます）で、Codex は AGENTS.override.md が存在すれば読み込みます。存在しない場合は AGENTS.md を読み込みます。Codex はこのレベルでは、最初に見つかった空でないファイルのみを使用します。
  2. プロジェクトスコープ: プロジェクトルート（通常は Git ルート）から現在の作業ディレクトリまで、Codex は下へ向かって探索します。Codex がプロジェクトルートを見つけられない場合は、現在のディレクトリのみを確認します。パス上の各ディレクトリで、AGENTS.override.md、次に AGENTS.md、その後 project_doc_fallback_filenames に指定されたフォールバック名を確認します。Codex は各ディレクトリから最大 1 ファイルを含めます。
  3. マージ順: Codex はルートから下に向かってファイルを連結し、空行で区切ります。現在のディレクトリに近いファイルほど後に配置されるため、先にあるガイダンスを上書きします。

Codex は空のファイルをスキップし、結合後のサイズが project_doc_max_bytes で定義された上限（デフォルトでは 32 KiB）に達すると、ファイルの追加を停止します。これらの設定項目の詳細については、プロジェクト指示の検出を参照してください。上限に達した場合は、上限を引き上げるか、ネストしたディレクトリに指示を分割してください。

グローバルガイダンスを作成する

Codex のホームディレクトリに永続的なデフォルトを作成すると、すべてのリポジトリで作業上の合意事項を継承できます。

  1. ディレクトリが存在することを確認します。
mkdir -p ~/.codex
  1. 再利用可能な設定を記述した ~/.codex/AGENTS.md を作成します。
# ~/.codex/AGENTS.md

## Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.
  1. どこからでも Codex を実行して、ファイルが読み込まれることを確認します。
codex --ask-for-approval never "Summarize the current instructions."

期待される結果: 作業を提案する前に、Codex が ~/.codex/AGENTS.md の項目を引用します。

ベースファイルを削除せずに一時的なグローバル上書きを適用する必要がある場合は、~/.codex/AGENTS.override.md を使用します。共有ガイダンスを復元するには、上書きファイルを削除します。

プロジェクト指示を階層化する

リポジトリレベルのファイルを使用すると、グローバルなデフォルトを継承しながら、Codex にプロジェクトの規約を認識させることができます。

  1. リポジトリルートに、基本的なセットアップを記述した AGENTS.md を追加します。
# AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.
  1. 特定のチームに異なるルールが必要な場合は、ネストしたディレクトリに上書きを追加します。たとえば、services/payments/ 内に AGENTS.override.md を作成します。
# services/payments/AGENTS.override.md

## Payments service rules

- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.
  1. payments ディレクトリから Codex を起動します。
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

期待される結果: Codex は最初にグローバルファイル、次にリポジトリルートの AGENTS.md、最後に payments の上書きを報告します。

Codex は現在のディレクトリに到達すると探索を停止するため、専門的な作業にできるだけ近い場所に上書きを配置してください。

グローバルファイルと payments 固有の上書きを追加した後のリポジトリの例を次に示します。

フォールバックファイル名をカスタマイズする

リポジトリですでに別のファイル名（たとえば TEAM_GUIDE.md）を使用している場合は、フォールバックリストに追加すると、Codex が指示ファイルとして扱うようになります。

  1. Codex の設定を編集します。
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536
  1. Codex を再起動するか、新しいコマンドを実行して、更新された設定を読み込みます。

これで Codex は各ディレクトリを次の順序で確認します: AGENTS.override.md、AGENTS.md、TEAM_GUIDE.md、.agents.md。このリストにないファイル名は、指示の検出では無視されます。大きいバイト上限により、切り詰められる前に、より多くのガイダンスを結合できるようになります。

フォールバックリストを設定すると、Codex は別名のファイルを指示として扱います。

プロジェクト固有の自動化ユーザーなど、別のプロファイルを使用する場合は、CODEX_HOME 環境変数を設定します。

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

期待される結果: 出力には、カスタム .codex ディレクトリを基準とした相対パスでファイルが一覧表示されます。

セットアップを確認する

  • リポジトリルートから codex --ask-for-approval never "Summarize the current instructions." を実行します。Codex は、グローバルファイルとプロジェクトファイルのガイダンスを優先順位どおりにエコー表示します。
  • codex --cd subdir --ask-for-approval never "Show which instruction files are active." を使用して、ネストした上書きによってより広い範囲のルールが置き換えられることを確認します。
  • Codex が読み込んだ指示ファイルを監査するには、codex -c log_dir=./.codex-log を使用してプレーンテキストの TUI ログを有効にし、./.codex-log/codex-tui.log を確認します。または、セッションログを有効にしている場合は、最新の session-*.jsonl ファイルを調べます。
  • 指示が古いように見える場合は、対象ディレクトリで Codex を再起動します。Codex は実行のたびに（また、各 TUI セッションの開始時にも）指示チェーンを再構築するため、手動で消去するキャッシュはありません。

検出に関する問題をトラブルシューティングする

  • 何も読み込まれない: 意図したリポジトリにいること、および codex status が想定したワークスペースルートを報告していることを確認します。指示ファイルに内容が含まれていることを確認してください。Codex は空のファイルを無視します。
  • 誤ったガイダンスが表示される: ディレクトリツリーの上位、または Codex のホームディレクトリに AGENTS.override.md がないか確認します。通常のファイルにフォールバックするには、上書きファイルの名前を変更するか削除します。
  • Codex がフォールバック名を無視する: project_doc_fallback_filenames に名前を誤りなく記載していることを確認し、Codex を再起動して更新された設定を有効にします。
  • 指示が切り詰められる: project_doc_max_bytes を引き上げるか、大きなファイルをネストしたディレクトリに分割して、重要なガイダンスを完全な状態に保ちます。
  • プロファイルが混乱している: Codex を起動する前に echo $CODEX_HOME を実行します。デフォルト以外の値が設定されている場合、Codex は編集したものとは異なるホームディレクトリを参照しています。

次のステップ

  • 詳細については、公式の AGENTS.md Web サイトを参照してください。
  • 永続的なガイダンスと相性のよい会話パターンについては、Codex へのプロンプトを確認してください。