AGENTS.mdの書き方｜Codex対応の設定ファイル設計

AGENTS.md は、AIエージェントに毎回プロジェクトの作法を説明し直さなくて済むようにする、リポジトリ直下の「エージェント向けのREADME」です。
READMEが人間向けなのに対し、AGENTS.md はビルド手順、テスト、規約、触れてはいけない境界を1ファイルにまとめて渡す責務分離の仕組みで、OpenAI Codex 発祥のオープン標準として2026年中盤には28以上のツールと6万以上のOSSリポジトリに広がっています。
Cursor、Copilot、Codex が同じ1枚を読むからこそ、ツールごとに設定が乱立する問題をまとめて解けるのです。
ただし、書けば自動で効くわけではありません。
2500リポジトリ規模の分析では、コマンドをフラグまで書いた記述や実コードのスニペット、禁止に代替を添える書き方は挙動を変えましたが、散文の曖昧な指示や15個以上の連続したDon'tsは、かえってエージェントを保守的にしました。
実際、ツールごとに .cursorrules、CLAUDE.md、独自メモを分けていた頃は、同じ規約を3箇所にコピペして1箇所だけ更新漏れが起き、古いコマンドをエージェントが実行したことがあります。
だからこそ、書き方を詰めるだけでなく、ファイルパスの直書きを避け、陳腐化させない運用まで含めて設計する必要があります。
AGENTS.md の価値は、内容そのものと運用の両方にあるのです。

AGENTS.mdとは何か：エージェント向けのREADME

AGENTS.mdは、AIコーディングエージェントにとってのREADMEだと考えると分かりやすいです。
人間の貢献者に向けた概要や導線はREADMEが担い、ビルド手順、テスト、規約、触ってはいけない境界のような運用文脈はAGENTS.mdに寄せる。
役割を分けることで、読む相手ごとに必要な情報だけが届くようになります。

READMEと何が違うのか

READMEにビルドコマンドや「このディレクトリは触るな」という注意を書き足していくと、たいてい人間向けの説明は読みづらくなります。
そこで必要になるのが、エージェント専用の受け皿です。
AGENTS.mdはリポジトリ直下に置く単一のMarkdownファイルとして、AIコーディングエージェントが作業に入る前に読む前提で設計されており、READMEが人間向けであるのに対して、AGENTS.mdは人間には冗長でもエージェントには必要な詳細を引き受けます。

この分離は見た目の整理以上の意味があります。
READMEを短く保てれば初見の理解が速くなり、AGENTS.mdにはコマンドや境界条件をためらわず書けるからです。
実際、READMEに説明を継ぎ足していった結果、文書が重くなってしまい、エージェント向けの記述をAGENTS.mdへ切り出したら両方がすっきりした、という使い方がいちばん自然でした。
新しく入ったCursorとClaude Codeの両方に同じ説明を貼り付ける手間がなくなり、1ファイル直すだけで全ツールに効く感覚が得られます。

ツール非依存のオープン標準という設計思想

AGENTS.mdの強みは、特定ベンダーに縛られないことです。
OpenAI Codex 由来で、現在は Linux Foundation 系の Agentic AI Foundation が管理しており、仕様として求められるのは「リポジトリ直下にプレーンなMarkdownを置く」ことだけ。
必須の構造もフロントマターもないため、導入の障壁が驚くほど低いのです。

しかも採用規模が、その設計の強さを裏づけています。
2026年中盤時点で28以上のツール、6万以上のOSSリポジトリが採用しており、単なる流行ではなくデファクト標準になりつつある。
1ファイル書くだけで複数のエージェントに同じ文脈を配れるのは、運用コストを下げたい現場ほど効いてきます。
書くべき情報が散らばっているなら、まずここに集めるのが合理的です。

既存の .cursorrules や CLAUDE.md との位置づけ

既存の .cursorrules や CLAUDE.md は、AGENTS.mdと競合するものではなく、むしろ上位互換の共通レイヤーとして扱うのが2026年の定石です。
ツール固有の機能が必要な部分だけ各ファイルに残し、共通するビルド手順や規約、境界条件はAGENTS.mdに寄せる。
こうしておけば、内容の80〜90%を重複させずに済み、更新漏れも減ります。

複数ツール対応では、Codex、Cursor、Copilot は AGENTS.md をネイティブで読み、Claude Code は CLAUDE.md を使うため、必要に応じて @AGENTS.md import や symlink で橋渡しします。
モノレポならルートとネスト配置を組み合わせ、近い場所の指示を優先させる設計も有効です。
大きなリポジトリほどルールは陳腐化しやすいので、四半期レビューまで含めて運用にしておくと、ファイルは増えても迷いは増えません。

必ず入れる6つのセクション構成

AGENTS.md は、AI コーディングエージェントにとっての README に近い存在です。
人間向けの説明書ではなく、ビルド、テスト、触れてはいけない範囲、コミットの作法までを一枚に集約するからこそ、最初に読むべき情報をそこへ集める意味があります。
特に 2026 年の運用では、6 セクションの順番そのものが読みやすさを左右します。

まず置くべきはプロジェクト概要です。
ここでは「React 18 + TypeScript + Vite + Tailwind」のように、バージョンと主要依存まで含めて書き切ると、エージェントは曖昧な推測をせずに済みます。
続いて Commands、コードスタイル、テスト手順、セキュリティ境界、コミット/PR規約へ進む流れにすると、何のプロジェクトで、どう動かし、どこを守るかが上から順に入ってきます。

この並びが効く理由は単純です。
エージェントが最初に必要とするのは、装飾された思想ではなく、実行可能な情報だからです。
命名規約や抽象論より先に、走るコマンドと境界条件を渡したほうが、修正の迷いが減ります。

最優先はCommandsセクション

最も ROI が高いのは Commands セクションです。
ここは「いつものテストを流す」のような曖昧表現では足りず、フラグまで含めてそのまま貼れる形で書かなければなりません。
たとえば pytest tests/unit/test_handlers.py -v や npm run build のように、実行対象とオプションが一目でわかる形にしておくと、エージェントは存在しない npm script を探して迷うことがなくなります。

実際、最初に「テストを実行」とだけ書いた AGENTS.md を使ったとき、エージェントは存在しない script を叩いて失敗しました。
そこから、単一テストのパス、-v のようなフラグ、ビルド用コマンドまで明記した形に直したところ、一発で通るようになりました。
コマンドは説明文ではなく操作手順です。
だからこそ、正確さがそのまま品質になるのです。

テスト手順も同じ考え方で書きます。
スイート全体、単一テスト、何をモックするかの 3 点を分けると、エージェントは「どこまで実行すればよいか」を誤解しません。
曖昧な推奨より、実際に走る 1 行のほうが強い。
おすすめです。

コードスタイルは『言語デフォルトと違う点』だけ書く

コードスタイルは盛りすぎないのがコツです。
言語やフレームワークのデフォルトから外れる点だけを書き、一般論を並べないほうが遵守率は上がります。
200 行に膨らんだ AGENTS.md から、実際に必要な 5 項目へ削ったところ、エージェントの振る舞いはむしろ安定しました。
長い規約は読まれにくい。
短く、差分だけ、が基本です。

技術スタックも抽象化しないでください。
「React プロジェクト」では弱く、「React 18 + TypeScript + Vite + Tailwind」まで書くと、使う道具と期待される前提が噛み合います。
バージョンが入るだけで、API の振る舞いや設定ファイルの読み方まで推測しやすくなるからです。
ここは詳細を詰めるほど、あとで手戻りが減ります。

セキュリティ境界とコミット規約で事故を防ぐ

セキュリティ境界には、「読むな」「コミットするな」を明示します。
秘密情報、生成物、環境依存ファイルを線引きしておくと、エージェントが不用意に追跡対象へ触れる事故を防げます。
コミット/PR規約では、ブランチ命名、コミット形式、マージ戦略まで指定しておくと、出力がチームの作法から外れません。
ここを曖昧にすると、技術的には正しくても運用で弾かれます。

比較の軸が多いなら、見え方を揃えると整理しやすくなります。

AGENTS.md は本来、300 行以内くらいに収める設計が扱いやすいです。内容を足すより、重複を削って、必要な境界だけを残しましょう。おすすめです。

効くAGENTS.mdの書き方：実証された5原則

AGENTS.mdは、長い説明文を積む場所ではありません。
実コードの短いスニペットを1つ示し、禁止には必ず代替を添え、細部は別ファイルへ逃がすほうが、エージェントの判断は揃いやすくなります。
要点は3つで、再現できる形で見せること、迷いを減らすこと、本文を軽く保つことです。

散文ではなく箇条書きとコード例で書く

大規模リポジトリ分析では、実コードから抜いた3〜10行のスニペットが、3段落の説明文よりパターン遵守を改善した。
スタイルを言葉で説明するより、「この通りに書け」と実例を1つ見せるほうが効くのだ。
実際、あるコンポーネント1個分の断片を貼った途端、長く崩れていた命名、分割粒度、順序がそろい、文章だけでは動かなかった箇所が一気に安定した。
コードは抽象説明の補助ではなく、最短で伝わる仕様になる。

export async function runChecks() {
  const result = await apiClient.get("/health");
  return result.ok ? "ok" : "retry";
}

この種の例は、APIの呼び出し方や例外処理の置き場所まで含めて、エージェントに具体的な型を渡せる。
記述が3段落あると解釈の幅が広がるが、実コードは境界を狭める。
だからこそ、AGENTS.mdでは説明を増やすより、最小の再現例を置いたほうがよい。

禁止（Don't）には必ず代替（Do）を添える

禁止だけが並ぶ文書は、読む側を止める。
たとえば「HTTPクライアントを直接生成するな」とだけ書くと、次に何を使えばよいかが分からないままだが、「共有のapiClient（リトライ付き）を使え」まで書けば、進む方向が1つに定まる。
警告は注意を促すだけで、代替は実装を前に進める。
ここが決定的に違う。

禁止事項を20個も並べたときは、新機能の実装でエージェントが手を止めがちになった。
15個以上の連続したDon'tsに対応するDoがないと、探索が過剰になって保守的に傾き、作業量が落ちる。
そこで禁止を半分に減らし、各所に肯定形の指示を差し込むと、手つきが軽くなった。
禁止は最小限にして、行動を選べる状態を残すべきだ。

詳細は別ファイルに逃がす

AGENTS.mdに全部を詰め込むと、読むだけで重くなる。
そこで、タスク固有の手順は agent_docs/running_tests.md のように別ファイルへ分割し、AGENTS.mdには1行の概要とパスだけを書いておく。
必要なときだけ読ませる構成なら、本体は短く保てるし、更新箇所も追いやすい。
プログレッシブディスクロージャーは、エージェントに余計な分岐を増やさないための実務的な整理である。

さらに、技術スタックが絡む情報ほど分離の効果は大きい。
たとえばテスト手順、リトライの方針、共有クライアントの呼び方を同じ紙面に詰めるより、共通の骨格だけをAGENTS.mdに置き、詳細は別ファイルに逃がすほうが見通しがよい。
文書は長いほど親切ではない。
必要な場所に、必要な分だけ置く。
これが実装を進める文書になる。

やってはいけないAGENTS.mdのアンチパターン

AGENTS.md は、長ければ親切になる文書ではありません。
むしろ、変わりやすい情報を詰め込みすぎるほど、エージェントは迷いやすくなります。
書くべきなのは、頻繁に変わらない規約、コマンド、境界です。

ファイルパスの過剰な直書き

最大の地雷は、ファイルパスを本文に埋め込むことです。
「認証ロジックは src/auth/handlers.ts にある」と断定すると、リネームや移動のたびに古い座標へ誘導してしまいます。
パスはよく動くため、AGENTS.md は構造の固定図ではなく、探し方の方針を伝える文書として書くほうが安全です。
実際にディレクトリ構成を細かく書いたところ、リファクタ後にエージェントが消えたファイルを探し続け、余計な時間を失いました。

その失敗から得た教訓は単純です。
変わりやすい場所名ではなく、変わりにくい規約と境界を残すこと。
どのコマンドで確認するか、どこまで触ってよいか、どの挙動を優先するかを示せば十分であり、探索そのものはエージェントに任せたほうが精度が上がります。
パスの詳細を書き足すほど親切になるように見えて、実際には誤誘導の可能性を増やすだけではないでしょうか。

肥大化させない

2000行級のAGENTS.mdは、文書としての安心感よりも、作業文脈を圧迫する副作用のほうが大きいです。
推奨は300行以内、理想は60行、上限の目安は500行であり、この範囲を超えると、読むだけで注意力が削られていきます。
短く高シグナルなファイルほど、必要な制約だけが残りやすい。

さらに厄介なのは、ミスのたびにルールを継ぎ足す運用です。
追加そのものは対症療法になりますが、古い例外を削らないまま増やすと、矛盾するパッチが積み上がって判断が鈍ります。
実際、ルールが増え続けた時期はエージェントの判断がぶれやすく、四半期に一度まとめて削る運用へ変えたあとに安定しました。
追記したら削る、これが文脈エンジニアリングでは効きます。

散文・曖昧な指示・矛盾する優先度は無視される

散文の段落や「気をつけて」のような曖昧な言い回しは、実務ではほとんど効きません。
エージェントが拾うのは、箇条書きで明示された条件、具体コマンド、一貫した優先度です。
陳腐化したコード例も誤誘導源になるので、実際にコンパイルや実行が通るかを見直しておく必要があります。
書き方がぼやけているほど、読んだ側の解釈に逃げが生まれるのです。

優先度が食い違う記述も同じくらい危険です。
上では「常にAを優先」と書き、下では例外としてBを推す、そんな構造が増えると、どちらを守るべきかが曖昧になります。
だからこそ、AGENTS.md は文量を抑え、表現を揃え、古い重複をため込まないことが肝心です。
書き足すより、整えるほうが強い。

Codex・Cursor・Copilotなど複数ツールで共有する

AGENTS.md は、複数ツールで同じ運用ルールをそろえるための土台になります。
Codex CLI、GitHub Copilot、Cursor、Windsurf、Devin、Aider、Zed、VS Code、JetBrains系まで同じ1枚を読ませられるので、編集は一度で済みます。
規約や境界条件が変わったときに、各ツールへ別々に書き直す手間を消せるのが最大の利点です。

AGENTS.mdをネイティブで読むツール一覧

AGENTS.md をそのまま読むツールが多いほど、ルールのズレは起きにくくなります。
Codex CLI・GitHub Copilot・Cursor・Windsurf・Devin・Aider・Zed・VS Code・JetBrains系は、この1ファイルを共通の参照先にできるため、ビルドコマンド、コーディング規約、触ってよい範囲を横断して揃えやすいのです。
共通化の価値は「対応している」こと自体ではなく、同じ修正が複数エージェントに同時反映される点にあります。

Claude Codeと併用する

Claude Code だけは CLAUDE.md を読むため、AGENTS.md と分けて考える必要があります。
併用するなら、CLAUDE.md の先頭行に @AGENTS.md と書いて import し、その下に Claude 固有のルールだけを足す形が扱いやすいです。
Claude 固有の記述が要らないなら ln -s AGENTS.md CLAUDE.md で symlink にしてしまえば、二重管理は消えます。
Cursor と Codex と Claude Code を並行利用している環境で、この一行集約に切り替えたとき、規約変更が全ツールへ一度の編集で反映されるようになった。
以前は .cursorrules と CLAUDE.md の内容が少しずつずれていて、ツールごとに返答や修正方針が違ってしまったが、symlink で一本化して差異が消えたのははっきりした変化でした。

Gemini CLIや一部ツールの個別事情

Gemini CLI は GEMINI.md を使うので、そこだけは別枠で考える必要があります。
一部の未対応ツールは、両方のファイルを維持するか symlink で橋渡しする運用になるでしょう。
ただし実際に違いが出るのは内容の80〜90%ではなく残りの小さな差分で、ビルド・規約・境界はほぼ共通です。
だからこそ、共通部は AGENTS.md に寄せ、Claude 固有機能が要るときだけ CLAUDE.md に import や追加ルールを置き、Cursor 専用の glob スコープが必要なときだけ .cursor/rules を足す、という分担が現実的になります。
AGENTS.md は世界共通の1枚、CLAUDE.md は Claude 固有機能が要る場面、.cursor/rules は Cursor 専用の細かなスコープが必要な場面。
重複を最小化して土台を1か所に置く運用が、2026年の定石です。

モノレポ対応と陳腐化させない運用

モノレポのAGENTS.mdは、近い順に効くカスケードとして設計すると破綻しにくいです。
ルートに全体共通の方針を置き、各パッケージやサービスの直下にローカルな例外を重ねれば、祖先の指示を上書きしながら文脈を保てます。
実際にルートだけで運用していた頃は差異を吸収しきれず、パッケージ直下へネストしてからは文脈の取り違えが減りました。

ルート＋サブディレクトリのカスケード設計

エージェントはディレクトリツリーで最も近いAGENTS.mdを読むため、ローカルの指示が祖先より優先されます。
だからこそ、ルートにはセットアップや共通のコード規約だけを置き、パッケージごとのビルド手順や禁止事項はその配下に分けるのが筋です。
Codexのようなツールがルートから下へファイルを連結し、1ディレクトリにつき1ファイルだけ取り込む前提まで踏まえると、共通ルールと例外ルールを置く階層が自然に決まります。

この設計の利点は、説明を増やすほど強くなるのではなく、矛盾を減らすほど安定する点にあります。
たとえば同じnpm script名でも、ルートでは共通の流儀を示し、サブディレクトリではそのパッケージだけの実コマンドを明示しておけば、エージェントは迷いません。
逆に、全部をルートへ押し込むと、実際の差分を吸収できず、別サービスの手順を誤適用しやすくなる。
ポイントは3つです。

小さく始めて反復で育てる

AGENTS.mdは最初から完璧を狙わず、20〜30行から始めるほうが扱いやすいです。
セットアップ、テスト、コードスタイルの3点だけを先に固定し、エージェントが繰り返し同じところで間違えたときだけ追記していく。
肥大した文書は読む側の負担になるだけでなく、古い注意が新しい指示を覆ってしまうので、追記は「失敗が観測された場所」に限定するのが賢明でしょう。

小さく書くと、何を足すべきかも見えやすくなります。
ルートにだけAGENTS.mdを置いていた頃は、各パッケージの差異が吸収されず、同じ失敗が別の場所で何度も起きました。
ところがパッケージ直下にネスト配置してからは、エージェントがその場の文脈を取り違えにくくなり、指示は短くても効く状態に変わったのです。
おすすめです。

四半期レビューで陳腐化（stale）を防ぐ

AGENTS.mdは書いた瞬間より、数ヶ月後のほうが危ういです。
パスやnpm scriptは黙って変わり、9月に正確だった記述が12月には誤指示になる。
実際に一度放置したとき、ビルドコマンドが古いまま残っていてエージェントが失敗したため、四半期レビューをカレンダー登録してから運用が安定しました。

四半期ごとの点検では、古くなった記述を削ることと、コード例が今も動くかを確かめることを同時に行います。
更新がない期間でも、実装は静かに変わりますから、触っていない文書ほど劣化しやすいのです。
削る、確かめる、直す。
この流れを回しましょう。