ChatGPT ドキュメント
日本語
お問い合わせ goolvyouyou@gmail.com

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

プロジェクトに関する追加の指示とコンテキストを Codex に提供します

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

Codex がガイダンスを検出する仕組み

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

  1. グローバルスコープ： Codex のホームディレクトリ（CODEX_HOME を設定していない場合、デフォルトは ~/.codex）に AGENTS.override.md が存在すれば、Codex はそれを読み込みます。存在しない場合は、AGENTS.md を読み込みます。この階層では、最初に見つかった空でないファイルだけを使用します。
  2. プロジェクトスコープ： プロジェクトルート（通常は Git ルート）から現在の作業ディレクトリまで、Codex が順にたどります。プロジェクトルートが見つからない場合は、現在のディレクトリだけを確認します。パス上の各ディレクトリで、AGENTS.override.md、AGENTS.md、project_doc_fallback_filenames に指定されたフォールバック名の順に確認します。各ディレクトリから取り込むファイルは最大 1 つです。
  3. マージ順序： Codex はルートから下の階層へファイルを連結し、各ファイルの間に空行を挿入します。現在のディレクトリに近いファイルほど結合後のプロンプトで後に配置されるため、それ以前のガイダンスをオーバーライドします。

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

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

すべてのリポジトリが作業上の取り決めを継承できるように、Codex のホームディレクトリに永続的なデフォルトを作成します。

  1. ディレクトリが存在することを確認します。

    mkdir -p ~/.codex

  2. 再利用可能な設定を記載した ~/.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.

  3. 任意の場所で 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.

  2. 特定のチームで異なるルールが必要な場合は、ネストしたディレクトリにオーバーライドを追加します。たとえば、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.

  3. payments ディレクトリから Codex を起動します。

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

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

Codex は現在のディレクトリに到達すると検索を停止するため、専門的な作業向けのオーバーライドは、対象にできるだけ近い場所に配置してください。

グローバルファイルと payments 固有のオーバーライドを追加した後のリポジトリ例を以下に示します。

<FileTree class="mt-4" tree={[ { name: "AGENTS.md", comment: "リポジトリの要件", highlight: true, }, { name: "services/", open: true, children: [ { name: "payments/", open: true, children: [ { name: "AGENTS.md", comment: "オーバーライドが存在するため無視されます", }, { name: "AGENTS.override.md", comment: "Payments サービスのルール", highlight: true, }, { name: "README.md" }, ], }, { name: "search/", children: [{ name: "AGENTS.md" }, { name: "…", placeholder: true }], }, ], }, ]} />

コードレビューのルールを追加する

GitHub での Codex コードレビューでは、ルールの対象となるコードに最も近い AGENTS.md に ## Code Review Rules セクションを追加します。リポジトリ全体のチェックはルートに配置し、サービス固有のチェックはネストしたファイルに配置してください。

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

ルールは簡潔に保ち、検出対象の動作と、安全な方法または例外を説明してください。書式設定や lint のチェックは CI に任せます。セットアップとルール作成のガイダンスについては、 Codex のレビュー内容をカスタマイズするを参照してください。

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

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

  1. Codex の設定を編集します。

    # ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

  2. 更新した設定を読み込むため、Codex を再起動するか、新しいコマンドを実行します。

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

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

<FileTree class="mt-4" tree={[ { name: "TEAM_GUIDE.md", comment: "フォールバックリストによって検出されます", highlight: true, }, { name: ".agents.md", comment: "ルート内のフォールバックファイル", }, { name: "support/", open: true, children: [ { name: "AGENTS.override.md", comment: "フォールバックのガイダンスをオーバーライドします", highlight: true, }, { name: "playbooks/", children: [{ name: "…", placeholder: true }], }, ], }, ]} />

プロジェクト固有の自動化ユーザーなど、別のプロファイルを使用する場合は、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 のプロンプト作成を参照してください。