AGENTS.md に、毎回言い直していることを移す

同じ指摘を3回したら、それは依頼文に書くことではありません。ファイルに書くことです。

第6回の終わりに書いたとおり、依頼文の質を毎回の気合いで保つのは続きません。続かないものを続けようとする代わりに、置き場所を決めます。この回で扱う AGENTS.md は、その置き場所のうち一番広く効くものです。

いつ、どの順で読まれるか

AGENTS.md は、Codex が作業を始める前に読むファイルです。読み方には順序があります。

公式ドキュメントによれば、Codex はプロジェクトの根、ふつうは Git の根から始めて、現在の作業フォルダまで下りていきます。通り道の各フォルダで AGENTS.override.md、AGENTS.md の順に探し、見つかったものを空行でつないで1つにします。根が見つからない場合は、現在のフォルダだけを見ます。

大事なのはつなぐ順です。現在のフォルダに近いファイルほど、あとに置かれます。あとに置かれたものが前の内容を上書きするので、フォルダごとに規約を変えられます。

読まれる場所はもう1つあります。Codex のホームディレクトリに置く全体向けのファイルです。公式の説明では、こちらは開発者個人向けで、応答の詳しさやレビューの口調といった好みを書く場所とされています。リポジトリに置くファイルは、チームとコードベースの規則に集中させます。

何を書くか

4つに絞ると迷いません。

動かし方。どうやって開発サーバーを立てるか、どうやってビルドするか。依存をどう入れるか。第5回で見たとおり、既定ではネットワークが切られています。何が前提として入っている必要があるかを書いておくと、無駄な失敗が減ります。

規約。命名、ディレクトリの分け方、書いてよい場所と書いてはいけない場所。Codex はリポジトリの中身から書き方を推測しますが、推測は揺れます。

検査の通し方。ここが一番効きます。第6回で書いた「完了の条件」を、毎回の依頼文から外してここへ移せます。

やってはいけないこと。触ってはいけないファイル、生成してはいけない種類のコード、書いてはいけない情報。

実例として、このブログのファイル

BenriWorks のブログのリポジトリに置いている AGENTS.md から、いくつか引きます。全体で100行ほどです。

検査の通し方は、コマンドをそのまま並べています。

## 検証コマンド
npm run validate:content && npm run check:links
（加えて npm run typecheck / npm run lint / npm run test）

やってはいけないことは、この仕事の性質から来ています。

## 禁止事項
1. 実在しない利用者の声や導入実績を書かない。
2. 実測していない性能値を書かない。
3. 確認していない料金や最新仕様を書かない。
4. 権利関係が不明な画像を使わない。

そして、不明点の扱い方を決めています。

不明な事実を推測で補完しない。
不明点は本文に {/* TODO: 要確認 — ... */} として残し、PRで報告する。

この3行が一番働いています。分からないことを分からないと書く形式を先に決めておくと、埋めるために推測する動機がなくなります。この講座の各回の冒頭にある注記も、この規則から出ています。

書かないほうがよいこと

逆に、入れて失敗したものもあります。

一般論は効きません。「読みやすいコードを書くこと」のような文は、書いても書かなくても結果が変わりませんでした。判定できない規則は、守られたかどうかも分かりません。

変わりやすい事実も向きません。バージョン番号や依存の一覧をここに書くと、更新が漏れたときに古い情報が規約として効き続けます。そういうものは、実際の設定ファイルを読ませるほうが確実です。

長さそのものも問題になります。守られていない規則が並んでいる状態は、書いていないのと同じか、それより悪い。1つ足したら、次の依頼で守られたかを確かめる。この往復ができる量に保ってください。

フォルダごとに変える

大きなリポジトリでは、場所によって規則が違います。フロントエンドとバックエンドで書き方が揃わないのは自然なことです。

読まれる順序を使えば、これは素直に書けます。根のファイルにリポジトリ全体の規則を書き、各フォルダのファイルにそこだけの規則を書く。下にあるものがあとに来るので、狭いほうが勝ちます。

一時的に上書きしたいときのために AGENTS.override.md が先に読まれる仕組みもあります。移行の途中など、期限つきの例外に使う想定です。期限つきのものは、期限つきだと分かる名前で置くというのは、この講座の外でも通用する習慣です。

/init で作り、そこから育てる

第3回で /init を通しました。あれが出す下書きが出発点です。

育て方は、足すタイミングを決めておくと楽になります。BenriWorks では2つの場面で足しています。

ひとつは、同じ指摘を3回したときです。3回言ったということは、これからも言うということです。

もうひとつは、事故が起きたときです。触ってはいけないファイルを触られた、入れてはいけない情報が入った。そういうときは、原因を直すのと一緒に、規約へ1行足します。

どちらも、思いついたときではなく、必要が証明されたときに足すという点が共通しています。先回りして書いた規則は、たいてい守られません。

Codex 専用のファイルではない

最後に1つ。AGENTS.md という名前は Codex が決めたものではなく、複数のコーディングエージェントが読む共通の置き場所として広まったものです。

これが効いてくるのは、1つのリポジトリで複数の道具を使うときです。BenriWorks では、同じリポジトリを Codex と Claude Code の両方で触ることがあります。規約が1か所にあれば、どちらから触っても同じ制約がかかります。詳しくは「2つのエージェントに、同じ仕様書を渡してみた」に書きました。

次の回

AGENTS.md は、常に読まれる規約です。だから、どの作業にも関係することしか書けません。

特定の作業のときだけ出てくる手順は、別の置き場所が要ります。第10回で扱うスキルが、それにあたります。

参照した公式情報

• OpenAI「Custom instructions with AGENTS.md」「Customization」（developers.openai.com/codex、2026年9月時点）
• 引用した規約は BenriWorks のブログリポジトリで実際に運用している AGENTS.md