AGENTS.md で Codex にルールを伝える(/init)

AGENTS.md は、Codex が作業の前に読む指示書のファイルです。プロジェクトの説明や守ってほしい決まりを書いておけば、依頼のたびに同じ説明をしなくて済みます。この記事では、/init でひな形を作り、日本語で書いてもらうまでを、編集部の検証環境の画面で説明します。

AGENTS.md とは

AGENTS.md は、Markdown(# で見出し、- で箇条書きを書く書き方)で書くテキストのファイルです。Codex は作業を始める前にこのファイルを読み、書かれた指示を作業に生かします。

置き場所は 2 つあり、効く範囲が違います。

~ は自分のホームフォルダのことです。~/.codex は Codex のホーム(設定などを置くフォルダ)で、環境変数 CODEX_HOME で場所を変えられます。

読み込まれる順番

Codex は、次の順番で AGENTS.md を探します。

1. 全体: ~/.codex/AGENTS.md
2. プロジェクト: プロジェクトのいちばん上のフォルダ(ふつうは Git のルート)から、今いるフォルダまで、1 つずつ下りながら探す

見つかったものは、順につなげて読みます。今いるフォルダに近いファイルほどあとに来るので、そちらの指示が優先されます。Git(ファイルの変更の履歴を残す仕組み)のルートが見つからないときは、今いるフォルダだけを見ます。

1 つのフォルダの中では AGENTS.override.md → AGENTS.md の順に探し、先に見つかった 1 つだけを使います。空のファイルは飛ばし、合計が 32 KiB(既定)に達したところで読むのをやめます。

/init で AGENTS.md を作る

/init は、今いるフォルダに AGENTS.md のひな形を作るコマンドです。編集部では、家計簿の CSV を集計する Python のスクリプトのフォルダ(~/kakeibo)で試しました。第 4 回で権限を「Read Only」に切り替えた会話の続きです。

できた AGENTS.md の中身

編集部の AGENTS.md には、次の 6 つの見出しがありました。いちばん上の見出しは「Repository Guidelines」(英語)のままです。

1 行目の見出し「# Repository Guidelines」に続く、始めの部分は次のとおりです。

## プロジェクト構成

このリポジトリは、家計簿の CSV を読み込み、費目ごとの合計を表示する小規模な Python CLI です。

- `kakeibo.py`: CSV 読み込みの `load`、集計の `total_by_category`、実行入口の `main` を配置しています。
- `expenses.csv`: 動作確認用のサンプルデータです。

現在、テストやアセット専用のディレクトリはありません。機能追加時も、読み込み・集計・表示の役割を明確に保ってください。

## 実行・開発コマンド

- `python3 kakeibo.py`: カレントディレクトリの `expenses.csv` を集計します。
- `python3 kakeibo.py /path/to/expenses.csv`: 指定した CSV を集計します。

自分の決まりを書き足す

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 つめは「プルリクエストを出す前に npm run lint を実行する」、2 つめは「動きを変えたら、共通で使う関数の説明を docs/ に書く」という決まりです。

家計簿のフォルダなら、たとえば次のように日本語で書き足せます。

## 作業のきまり

- 変更したら `python3 kakeibo.py` を実行して、費目ごとの合計を確かめる
- 返事は日本語で書く

AGENTS.md は、ふつう会話を始めるときに 1 回だけ読まれます。書き足したあとは、Codex を起動し直してから作業を頼みます。

すべてのプロジェクトに効く AGENTS.md

どのプロジェクトでも守ってほしいことは、Codex のホームのフォルダ(既定は ~/.codex)の AGENTS.md に書きます。フォルダが無いときは、先に作ります。

mkdir -p ~/.codex

~/.codex/AGENTS.md の公式の例は次のとおりです。JavaScript のファイルを変えたら npm test を実行する、依存パッケージを入れるときは pnpm を使う、本番用の依存を足す前に確認する、という 3 つの決まりです。

## Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

編集部の撮影では、/init のあとで「日本語で書いてください」と頼み直しました。どのプロジェクトでも日本語の返事がほしいときは、その決まりを全体の AGENTS.md に書いておく方法があります。

読み込まれたかを確かめる

/status を実行すると、今の会話で読み込んだ AGENTS.md が「Agents.md」の行に表示されます。編集部の環境では、Codex を起動し直したあとの /status に、①のように「AGENTS.md」と表示されました。

公式のドキュメントでは、Codex に「今の指示をまとめて」と頼んで確かめる方法も紹介しています。

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

読み込まれていないときは、次のことを確かめます。

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

次の回では、Codex のよく使うコマンドと、設定ファイル config.toml の書き方を説明します。