Custom instructions with AGENTS.md

概要

Codex は作業を始める前に AGENTS.md を読む。グローバルな指針とプロジェクト固有の上書きを重ねることで、どのリポジトリでも一貫した前提でタスクを始められる。

仕様

発見の順序

Codex は起動時に instruction chain を組み立てる（実行ごとに 1 回。TUI では通常、起動したセッションごとに 1 回）。

global スコープ: Codex home（既定 ~/.codex、CODEX_HOME で変更可）で、AGENTS.override.md があればそれを読み、無ければ AGENTS.md を読む。このレベルでは最初に見つかった空でないファイル 1 つだけを使う
project スコープ: プロジェクトルート（通常は Git root）から現在の作業ディレクトリまで降りていく。プロジェクトルートが見つからない場合は現在のディレクトリだけを見る。各ディレクトリで AGENTS.override.md → AGENTS.md → project_doc_fallback_filenames の順に確認し、1 ディレクトリにつき最大 1 ファイルを取る
マージ順: ルートから下へ連結し、空行で結合する。現在のディレクトリに近いファイルほど後ろに来るため、先の指針を上書きする

空のファイルはスキップされる
合計サイズが project_doc_max_bytes（既定 32 KiB）に達すると、それ以上ファイルを追加しない。上限に当たったら値を上げるか、ネストしたディレクトリに分割する
現在のディレクトリに達すると探索を止めるため、上書きは専門的な作業のできるだけ近くに置く

global な指針

~/.codex/AGENTS.md に再利用する設定を書く
基のファイルを消さずに一時的に global を上書きしたいときは ~/.codex/AGENTS.override.md を使い、戻すときは override を消す

code review 用のルール

GitHub 上の Codex code review 向けには、対象コードに最も近い AGENTS.md に ## Code Review Rules セクションを足す。リポジトリ全体のチェックはルート、サービス固有はネストしたファイルに置く
ルールは簡潔にし、指摘したい挙動と安全な代替・例外を説明する。フォーマットと lint のチェックは CI に任せることが推奨されている

フォールバックのファイル名

既に別のファイル名を使っている場合は project_doc_fallback_filenames に追加する
追加後、各ディレクトリで AGENTS.override.md → AGENTS.md → 追加した名前の順に確認する。この一覧に無いファイル名は instruction discovery では無視される

CODEX_HOME

CODEX_HOME を設定すると別のプロファイル（プロジェクト固有の自動化ユーザーなど）を使える

確認と切り分け

リポジトリルートで codex --ask-for-approval never "Summarize the current instructions." を実行すると、global とプロジェクトのファイルが優先順に反映されているか確認できる
codex --cd subdir --ask-for-approval never "Show which instruction files are active." でネストした上書きが広いルールを置き換えているか確認する
読み込まれたファイルを監査するには、codex -c log_dir=./.codex-log で opt-in の平文 TUI ログを有効にして ./.codex-log/codex-tui.log を見るか、セッションログを有効にしている場合は最新の session-*.jsonl を見る
Codex は実行ごと（TUI では各セッション開始時）に instruction chain を作り直すため、手動で消すキャッシュは無い。指示が古く見えるときは対象ディレクトリで再起動する

切り分けの指針:

症状	確認すること
何も読み込まれない	意図したリポジトリにいるか、`codex status` が期待するワークスペースルートを報告するか。空のファイルは無視される
想定と違う指針が出る	ディレクトリツリーの上位や Codex home に `AGENTS.override.md` が無いか
フォールバック名が無視される	`project_doc_fallback_filenames` の綴りを確認し、設定を反映させるため再起動する
指示が切り詰められる	`project_doc_max_bytes` を上げるか、大きなファイルをネストしたディレクトリに分割する
プロファイルの取り違え	起動前に `echo $CODEX_HOME` を確認する

設定

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

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

## 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.