AGENTS.md の書き方：Codex にプロジェクト規約と作業習慣を伝える実践ガイド

Codex が「完了しました」と言った後で pnpm test を走らせたら、そもそもテストを実行していなかった。あるいは monorepo のルートで、別 package のテストを走らせていた。この手の説明を毎回繰り返すのは面倒です。npm run build、pnpm test、generated ディレクトリは触らない、終わる前に lint を走らせる。そうしたルールを書いておく場所が AGENTS.md です。次回から Codex に同じ説明をしなくて済みます。

Codex の入門と入口選びを済ませたばかりなら、次にやることは大規模リファクタリングではありません。まず、毎回口頭で伝えているプロジェクト規約を書き出します。

最初は 12〜20 行の種になるファイルで十分です。そのうえで、3 層の読み込み方法、読み込み確認、書いてはいけないもの、CLAUDE.md や Cursor Rules との共存、更新すべきタイミングを整理します。

AGENTS.md は README ではなく、Codex の長期的な作業指示書

README.md は人間の読者向けです。プロジェクトの概要、インストール方法、使い始め方を説明します。AGENTS.md は Codex 向けです。毎回の作業開始時に必要になるルール、つまり build 方法、test 方法、触ってはいけないディレクトリ、完了前のチェックを書きます。

OpenAI の公式ドキュメントでは、Codex は作業開始前に AGENTS.md を読み、現在のコンテキストの一部として扱うと説明されています。毎回チャットで「npm run build」「pnpm test」と打つのとは違います。AGENTS.md は永続的なプロジェクト指示なので、同じ内容を手で入力し直す必要がありません。

ただし境界はあります。AGENTS.md は長期記憶システムではなく、自動で学習する知識ベースでもありません。起動時に読み込まれる静的な指示ファイルです。セッションをまたいだ知識の蓄積や記憶管理が必要なら、以前の AI エージェントの記憶管理で、長期記憶とプロジェクト規約の分担を扱っています。

Codex は AGENTS.md をどう見つけるのか：3 層の読み込み

Codex の読み込み順は、グローバル層、プロジェクト層、結合順の 3 つで考えるとわかりやすいです。この仕組みを知っておくと、どの規約が効くのか、なぜ効いていないように見えるのかを判断できます。

グローバル層：個人の共通習慣

Codex はまずユーザーディレクトリの ~/.codex を見ます。この層には、たとえば日本語で返す、コードスタイルの好み、よく使うツールの癖など、個人の共通ルールを置きます。注意点として、グローバル層では最大 1 ファイルだけを読みます。順序は AGENTS.override.md -> AGENTS.md で、両方は結合されません。

プロジェクト層：Git ルートから現在のディレクトリまで順に見る

プロジェクト層では、Git ルートまたはプロジェクトルートから現在の作業ディレクトリまでを順に走査します。各階層でも AGENTS.override.md -> AGENTS.md -> fallback filenames の順で最大 1 ファイルだけを読みます。fallback ファイル名は project_doc_fallback_filenames で設定できます。たとえば TEAM_GUIDE.md を追加できますが、具体的な設定名は公式ドキュメントを基準にします。

結合順：近いディレクトリほど後ろに出て、より具体的になる

見つかったファイルは、ルートから現在のディレクトリへ向かう順に連結されます。現在のディレクトリに近いルールほど後ろに出るため、Codex はその具体的な指示を優先しやすくなります。

例を挙げます。monorepo のルートにある AGENTS.md が「テストは pnpm test」と書き、apps/web/AGENTS.md が「テストは pnpm --filter web test」と書いているとします。apps/web で Codex を起動すると、読み込み順はルートの規約 -> apps/web の規約です。apps/web の test コマンドのほうが、より具体的な指示になります。

3 層の読み込みまとめ

層	パス範囲	ファイル優先度	使いどころ
グローバル層	~/.codex/	AGENTS.override.md -> AGENTS.md（最大 1 ファイル）	個人の共通習慣。リポジトリには commit しない
プロジェクト層	Git ルート -> 現在のディレクトリ	各階層で AGENTS.override.md -> AGENTS.md -> fallback から最大 1 ファイル	プロジェクト規約。ルートに共通、サブディレクトリに固有ルール
結合層	ルートから現在のディレクトリへ順に連結	近いディレクトリほど後ろに出る	monorepo で package 固有の規約を共通規約に重ねる

チーム共通のルールはルートに置き、特殊なルールはサブディレクトリに置きます。たとえば、ある package だけ test コマンドが違う場合です。AGENTS.override.md は一時的な上書きや局所的な強い制約に向いています。チームの標準にしてしまうと、通常のルールが override の中に隠れてしまい、共同作業で混乱します。

最小テンプレート：最初に書く 6 つのブロック

OpenAI は AGENTS.md を「open-format README for agents」と説明しています。要点は、短く、事実に沿い、検証できることです。インターネットで見つけた 300 行の巨大テンプレートをそのままコピーする必要はありません。まず 6 つの基本ブロックを書き、必要になったら増やします。

種になるファイルには、この 6 つを入れます。

1. repo layout：技術スタックとディレクトリ構成。Codex が frontend、backend、test の場所を把握できます
2. Commands：具体的な build、test、lint コマンド。「テストを走らせる」ではなく pnpm test と書きます
3. Constraints：触ってはいけないディレクトリや行動。たとえば src/generated/
4. PR expectations：提出前に確認すること、review で期待されること
5. Done when：完了条件。たとえば pnpm test と pnpm build が通ること
6. package manager、コードスタイル、命名規則など、プロジェクト固有の小さな約束

SaaS 管理画面プロジェクトなら、最初の AGENTS.md はこの程度で十分です。

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Database: PostgreSQL
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review

## PR expectations
- Add tests for new features
- Run `pnpm test` before marking done

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

このテンプレートは短いので、コンテキストを汚しにくいです。まずはこの 6 ブロックから始め、問題が出たら少しずつ広げます。プロダクトビジョン、依存関係一覧、アーキテクチャ図、API ドキュメント索引を最初から詰め込むと、肝心の規約が埋もれます。

Codex が本当に AGENTS.md を読んだか確認する

AGENTS.md を書いたら、効いていると思い込まずに確認します。OpenAI 公式がすすめる検証コマンドは次のとおりです。

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

このコマンドは、Codex に現在読み込んでいる指示を要約させます。出力に test コマンドや触ってはいけないディレクトリが含まれていれば、読み込めています。まったく出てこない場合や別のルールが出る場合は、読み込み経路を確認します。

トラブルシューティング表

確認項目	起きやすい原因	対処
ファイル名の大小文字	Agent.md や agents.md など、AGENTS.md ではない名前になっている	AGENTS.md に直します。A と拡張子を大文字にします
バージョンが古い	古いバージョンでは symlink、NFS、mount パスまわりの問題がありました。境界となるバージョンは公式情報に従います	最新版へ更新します
パスの遮蔽	プロジェクトパスが symlink、NFS mount、bind mount で、探索経路に影響している	実体パスで起動しているか確認します
override が勝っている	AGENTS.override.md やサブディレクトリの規約が期待したルールを上書きしている	現在のディレクトリとグローバルディレクトリの override を確認します
サイズ上限	ファイルがデフォルト上限を超えている。公式では 32 KiB が基準として説明されています	古い一覧や長い説明を削って短くします
起動ディレクトリが違う	Codex が意図した repo や package の外で起動している	現在の作業ディレクトリを確認し、必要なら --cd を使います

それでも生効しない場合は、OpenAI の Custom instructions ドキュメントを確認するか、Codex を更新します。「必ず効く」と決めつけないほうが安全です。パス、バージョン、設定、起動ディレクトリが結果に影響します。

AGENTS.md に書かないほうがよいもの

AGENTS.md は万能の保管場所ではありません。入れるとセキュリティリスク、保守負担、コンテキストのノイズになるものがあります。次のものは避けます。

1. secret、API key、本番パスワード

secret、本番パスワード、API token は AGENTS.md に書きません。Codex はこのファイルをコンテキストに読み込みますし、チームメンバーに見えたり Git に commit されたりする可能性があります。secret は環境変数、commit しない .env、または専用の secrets 管理へ分けます。Codex が sandbox 内で secret を使う必要があるなら、それは実行層の制御として扱います。

2. すぐ古くなる巨大な一覧

依存関係、エコシステムの数字、料金、quota、全 route、全 DB field などの一覧は書かないほうがよいです。「React 18.2、Vue 3.4、TypeScript 5.0……」のような一覧は数か月で古くなります。依存関係を追加する手順を書くほうが、現在の依存関係を全部列挙するより保守しやすいです。

3. 抽象的なスローガン

「品質を高く保つ」「優雅なコードを書く」「保守しやすくする」は、そのままでは実行できません。pnpm test が通る、pnpm lint がエラーなし、新機能には test を追加する、Lighthouse Performance が合意した基準を下回らない、という形にします。

4. あいまいなコマンド

「テストを走らせる」「build を確認する」では足りません。pnpm test、pnpm build、lighthouse --preset=desktop のように、そのまま実行できる形で書きます。

5. 検証できない要求

「性能を保証する」「UX をよくする」には完了境界がありません。API 応答が 200 ms 未満、Lighthouse スコアが基準以上など、確認できる結果にします。

6. 個人の好みをリポジトリルートに置くこと

「日本語で返す」「回答は 100 字以内」「VS Code を前提にする」は個人のツール習慣であり、チーム共有のプロジェクト規約ではありません。こうした好みは ~/.codex/AGENTS.md に置きます。リポジトリルートにはチームの標準だけを置きます。

原則は、短く、事実に沿い、検証できること。AGENTS.md は繰り返し説明を減らすためのファイルであり、プロジェクト文書を全部貼る場所ではありません。

すでに CLAUDE.md や Cursor Rules がある場合

Claude Code や Cursor を使っているなら、リポジトリに CLAUDE.md や Cursor Rules があるかもしれません。その場合も、同じルールを 3 つにコピーする必要はありません。import と共存で整理します。

AGENTS.md vs CLAUDE.md：共通ルールを import する

Claude Code が読むのは CLAUDE.md で、AGENTS.md ではありません。リポジトリに AGENTS.md がすでにあるなら、次のような小さな CLAUDE.md を作って import できます。

@AGENTS.md

## Claude-specific
- Prefer Chinese responses
- Keep responses concise (under 100 words unless requested)

@AGENTS.md は import 構文です。Claude Code は AGENTS.md を読み、その下にある Claude-specific の指示を続けて読みます。これでプロジェクト共通規約は AGENTS.md に集約し、Claude 固有の好みだけを CLAUDE.md に置けます。

AGENTS.md vs Cursor Rules：Cursor には独自の Rules 体系がある

Cursor には Project、Team、User Rules などの独自体系があります。Cursor の公式ドキュメントや検索結果の要約では AGENTS.md 対応にも触れられていますが、具体的な読み込み仕様は Cursor の最新公式ドキュメントで確認するのが安全です。Cursor と Codex を併用するなら、ツール共通のプロジェクト規約を AGENTS.md に置き、Cursor 固有のエディタ動作は Cursor Rules に残します。

AGENTS.md vs config.toml、Rules、Skills、MCP

AGENTS.md は指示層です。Codex に「どう作業すべきか」を伝えます。一方で、権限、sandbox、コマンド制御、外部ツール連携は別の仕組みです。

比較項目	AGENTS.md	他の仕組み	違い
.codex/config.toml	build、test、触らないディレクトリなどのプロジェクト規約	model、sandbox、approval、network、shell environment などの実行設定	規約は AGENTS.md、実行設定は config.toml に分けます
Rules	「危険なコマンドを実行しない」といった指示	prefix_rule(pattern=["rm","-rf"], decision="forbidden") のようなコマンド制御	文章の指示は、強制ルールと同じではありません
Skills	常時読むプロジェクト規約	scripts や references を含む再利用可能な workflow	常時ルールは AGENTS.md、複雑な workflow は Skills へ
MCP	指示層	ツール連携層	AGENTS.md は MCP の代わりにはなりません

AGENTS.md は、繰り返し説明しているプロジェクト規約を解決します。Rules、config、sandbox、permissions は実行制御です。Skills は再利用可能な workflow、MCP は外部ツール連携。ここを混ぜないほうが、あとで壊れにくくなります。

AGENTS.md はいつ更新するのか

AGENTS.md は、プロジェクトが少し変わるたびに更新するものではありません。同じ摩擦が繰り返されたときだけ更新します。

更新のきっかけ

OpenAI の公式ドキュメントでは、次のような場面で更新するとよいとされています。

1. Codex が同じミスを繰り返す：2 回続けて違うディレクトリを変更した、毎回違う package の test を走らせる。この場合は「Do NOT edit src/generated/」や「テストは pnpm --filter web test」のような Constraints を 1 つ足します。

2. PR review で同じ指摘が続く：reviewer が毎回「この変更には test が必要」「generated code は触らない」「default export は避ける」と指摘する。そのパターンを PR expectations に入れます。

3. Codex が答えを見つけるまでに文書を読みすぎる：正しい test コマンドや build 手順を見つけるまで、毎回いくつもの docs を読む。この場合は repo layout や Commands に中核情報を追加します。

更新する場所は、問題が起きた近く

ミスが起きたディレクトリにルールを足します。何でもルートへ書く必要はありません。monorepo では package ごとにルールが違うことがあるので、サブディレクトリの AGENTS.md で管理します。

たとえば Codex が apps/web で誤った test を走らせたなら、apps/web/AGENTS.md にルールを足します。全 package に影響する root の AGENTS.md へ雑に足す必要はありません。

長期記憶との違い

AGENTS.md は起動時に読み込まれる静的な指示ファイルです。自動で学習する記憶ストアではありません。Codex があなたの修正から勝手に AGENTS.md を更新することはありません。明示的に更新を依頼した場合だけです。

セッションをまたぐ知識や記憶管理が必要なら、AI エージェントの記憶管理の記事を参照してください。

テンプレートを育てる：種から拡張版へ

最初から 300 行のテンプレートを作る必要はありません。12〜20 行の種から始め、繰り返し起きた問題だけを追加します。

種版：最小限の 6 ブロックだけ

種版は repo layout、よく使うコマンド、制約、PR 期待値、done/verify だけで十分です。たとえば次のように書けます。

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)

## PR expectations
- Add tests for new features

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

拡張のきっかけ：いつ 1 ブロック足すか

何度か使ってから、具体的な問題に合わせて増やします。

1. 初めて Codex が違うディレクトリを編集したとき：migrations/ や generated/ を触ったら、Constraints に「Do NOT commit migrations/ without team review」や「Do NOT edit any file in src/generated/」を足します。

2. 初めて PR review の指摘が繰り返されたとき：test を追加する、default export を避ける、といった指摘が続くなら、PR expectations に「Add tests for new features」「Use named exports, not default exports」を足します。

3. 初めて package manager を間違えたとき：pnpm プロジェクトで npm コマンドを使ったら、Commands に「Always use pnpm, not npm or yarn」を足します。

4. 初めて lint を忘れたとき：完了前に lint を走らせなかったら、Done when に「pnpm lint passes with no errors」を足します。

拡張版：30〜50 行

拡張版では、制約、PR 期待値、package manager、lint 要求が増え、30〜50 行くらいになります。

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint
- Always use pnpm, not npm or yarn

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review
- Do NOT modify .env files (use .env.example as template)

## PR expectations
- Add tests for new features
- Run `pnpm test` and `pnpm lint` before marking done
- Use named exports, not default exports
- Keep components under 200 lines; split if larger

## Done when
- `pnpm test` passes
- `pnpm build` succeeds
- `pnpm lint` passes with no errors
- New features have corresponding tests

基本は、予測で増やすのではなく、起きた問題から増やすことです。AGENTS.md の価値は、プロジェクト文書を見せることではなく、繰り返し説明を減らすことにあります。

まとめ

AGENTS.md は常時使うプロジェクト指示です。万能倉庫ではなく、長期記憶システムでもありません。解決するのは 1 つだけです。Codex が作業を始めるたびに、同じプロジェクト規約を繰り返し説明しなくてよくなります。

実際の進め方は次のとおりです。

1. 12〜20 行の種版から始める：repo layout、コマンド、制約、PR 期待値、done/verify。巨大テンプレートから始めません。

2. 読み込みを検証する：codex --ask-for-approval never "Summarize the current instructions." を実行し、出力に自分のルールが含まれるか確認します。

3. 繰り返した問題だけを足す：Codex が同じミスをする、PR review が同じ指摘をする、必要な情報を探すのに時間がかかる。このときだけ 1 つ足します。

4. 危険なものと古くなるものを入れない：secret、古い一覧、抽象スローガン、あいまいなコマンド、検証できない要求、個人の好みは root の AGENTS.md に入れません。

5. CLAUDE.md や Cursor Rules があるなら import と共存で整理する：共通のプロジェクト規約は AGENTS.md に集め、ツール固有の動作は各ツールのファイルに残します。

AGENTS.md は Codex に安定したプロジェクト文脈を渡します。この Codex シリーズでは、次に繰り返し workflow を Skills に分ける話、権限と secret の境界、失敗 review と PR check で done/verify を安定させる話へ進めます。