本文へ移動
BenriWorks LabBenriWorks トップ

ガイド更新日

AGENTS.mdで、同じ説明を繰り返さない

この記事で分かること

Codex 集中講座の第9回。毎回伝えている検査コマンドや作業の約束をAGENTS.mdに移します。短い規約の作り方、読み込まれる順番、フォルダごとの使い分けを学びます。

テキストエディタで規約ファイルを開いた画面の前で、こちらを向いている男性
目次 読みたいところから

「このプロジェクトでは、このコマンドで検査して」。毎回同じ説明を入力しているなら、作業の約束をファイルへ移せます。次の依頼でも必要なものから、少しずつ書きます。

AGENTS.mdは、Codexが作業前に読む規約のファイルです。実際に使う検査コマンドを入口に、何を書き、どこに置くかを考えます。

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

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

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

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

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

AGENTS.mdの読まれる順序を示した図。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 があれば同じフォルダの AGENTS.md の代わりに読まれる仕組みもあります。移行の途中など、期限つきの例外に使う想定です。期限つきのものは、期限つきだと分かる名前で置くというのは、この講座の外でも通用する習慣です。

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

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

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

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

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

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

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

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

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

規約の最初の数行

いま使っている検査コマンドと、どの作業でも守ってほしい約束を1つずつ選び、AGENTS.mdの下書きにします。プロジェクトで実際に通る内容だけを書いてください。

次の依頼で内容を読み、検査結果も確かめます。規約を置いたあとも、書いたことが守られたかを確認する仕事は残ります。

次の回

画像を用意するなど、その作業のときだけ使う長い手順は、必要なときに開ける形へまとめます。「Codexのスキルで、いつもの手順を呼び出す」へ進めます。

参照した公式情報

  • OpenAI「Custom instructions with AGENTS.md」「Customization」(learn.chatgpt.com/docs、2026年11月時点。developers.openai.com/codex から移転)
  • 引用した規約は BenriWorks のブログリポジトリで実際に運用している AGENTS.md

READ NEXT

次はこれを読む

Codex 集中講座の次の回へ

Codexのスキルで、いつもの手順を呼び出す

Codex 集中講座の第10回。特定の作業で繰り返す手順をスキルにまとめます。SKILL.md、名前、説明文の下書きを作り、AGENTS.mdとの役割の違いを整理します。

続きを読む →
書類のファイルが並んだ棚の前で、1冊を開いてこちらを向いている女性

よくある質問

AGENTS.md はどこに置きますか
リポジトリの中に置けばチーム全員に効きます。自分だけの好みは、Codex のホームディレクトリに置く全体向けのファイルに書きます。公式ドキュメントによれば、Codex はプロジェクトの根から現在のフォルダまで下りながら見つけたファイルを連結し、現在のフォルダに近いものがあとに来て前の内容を上書きします。
どのくらいの長さが適切ですか
長さより、書かれている内容が守られているかどうかで判断してください。守られていない規則が並んでいる状態は、書いていないのと変わりません。1つ追加したら、次の依頼で守られたかを確かめる。この往復ができる量に保つのが現実的です。
他のAIツールでも使えますか
AGENTS.md は複数のコーディングエージェントが読む共通の置き場所として広まっています。Codex 専用のファイルではないため、同じリポジトリで別のツールを使う人にも同じ規約が効きます。