はじめに — 「さっきも言ったよね？」を、もうやめませんか
AIコーディングエージェントを使っていて、こんな経験ないですか。
- テストの実行コマンドを 毎回チャットで説明 している
- 「このプロジェクトはこのディレクトリ構成」と言ったのに、次のセッションでは忘れられている
- コミットメッセージの規約を守ってくれず、毎回手直ししている
- 「本番の設定ファイルは触らないで」と伝えたのに、また触られてヒヤッとした
正直に言いましょう。これ、エージェントが賢くないから ではないんですよね。多くの場合、原因は 「プロジェクトの前提を、毎回ゼロから説明している」 ことにあります。人間の新人さんだって、オンボーディング資料が一枚もなかったら、毎回先輩に同じことを聞くしかない。AIエージェントも、まったく同じなんです。
その「毎回説明」を一枚のファイルに固定して、エージェントが セッションの最初に自動で読む 仕組みが、この記事のテーマです。具体的には AGENTS.md と CLAUDE.md という2つの指示ファイル。2026年、この2つは「AIエージェントを使うなら最初に整えるべきもの」になってきました。
【線引き】以前、Claude Code の hooks（フック）で「危険なコマンドを仕組みで止める」話を書きました。あれは 実行を止める 仕組みでした。今回はその手前、「何を守るべきか・どういう前提で動くべきか」という文脈を渡す 設計の話です。層が違うので、両方セットで効きます。
そして最初に、いちばん大事なことを置いておきます。役割分担 です。
| 誰が | 何をやる |
|---|---|
| 人間 | 何をルール化するか選ぶ、優先順位を決める、チームで合意する、gitにcommitして標準にする最終承認 |
| AI / ツール | 初期ドラフトの生成（/init）、既存の暗黙知の言語化、肥大化した指示のチェック |
指示ファイルは「AIに丸投げして自動生成」ではなく、人間が"何を守らせたいか"を決めて、AIに言語化を手伝ってもらう もの。ここを押さえると、この後の話が全部つながります。
そもそも AGENTS.md って何ですか
ひとことで言うと、AGENTS.md は「AIエージェント向けの取扱説明書」 です。
README.md が「人間の開発者向けの説明書」だとしたら、AGENTS.md は「AIエージェント向けの説明書」。リポジトリのルート（一番上のフォルダ）に置いておくと、対応しているエージェントが 作業を始める前に自動で読んでくれます。
「READMEに書けばいいじゃん」と思うかもしれません。でも、READMEは人間向けなので「プロジェクトの魅力」や「使い方」が中心で、エージェントが本当に欲しい「テストの回し方」「触ってはいけない場所」みたいな実務情報は、埋もれがちなんですよね。AGENTS.md はそこを エージェント目線で分離 するための場所、というわけです。
中身はただのMarkdownで、決まったスキーマ（形式の縛り）はありません。よく書かれるのはこのあたりです。
- プロジェクトの概要と、開発環境のちょっとしたコツ
- ビルド・インストール・テストのコマンド
- コードスタイルと命名の規約
- テストやPR（プルリクエスト）の作法
- セキュリティ上の注意、デプロイ手順
標準化の現在地（2026年）
ここは事実確認した数字なので、根拠付きで書いておきます。
- AGENTS.md は 2025年に登場したオープンな標準 で、2026年時点で公式サイトによると 6万以上のOSSリポジトリ で使われています。
- OpenAI Codex / Cursor / GitHub Copilot / Google Jules / Aider / Windsurf / Zed / Sourcegraph Amp など、20以上のツールが対応。1つのAGENTS.md が、複数のエージェントに同時に効く のが最大の利点です。
- 現在は Linux Foundation 傘下の Agentic AI Foundation が旗振り役になっています。
つまり、ツールごとにバラバラの独自ファイルを書かなくても、AGENTS.md 一枚で"共通言語"になる 方向に世界が動いている、ということですね。（出典は記事末尾に置いておきます）
ひとつだけ注意。Anthropic の Claude Code は、この AGENTS.md をネイティブには読みません。Claude Code は独自の CLAUDE.md を使います。この2つの関係は後半できっちり整理するので、いったん「標準の AGENTS.md と、Claude専用の CLAUDE.md がある」とだけ覚えてください。
10分で書く「最小AGENTS.md」
理屈より先に、動くものを一枚 作りましょう。難しく考えなくて大丈夫です。まずはこれをリポジトリのルートに AGENTS.md という名前で置くだけ。汎用のサンプルなので、自分のプロジェクトに合わせて中身を差し替えてください。
# AGENTS.md
## プロジェクト概要
- TypeScript + React のWebアプリ。パッケージ管理は pnpm。
- ソースは `src/`、テストは各ファイルの隣に `*.test.ts` で置く。
## よく使うコマンド
- 依存インストール: `pnpm install`
- 開発サーバー: `pnpm dev`
- テスト（コミット前に必ず実行）: `pnpm test`
- Lint / 整形: `pnpm lint && pnpm format`
## コードスタイル
- 関数コンポーネントのみ。クラスコンポーネントは使わない。
- 日付は必ず `date-fns` を使う。`moment` は使わない。
- any 型は原則禁止。どうしても必要なら理由をコメントで残す。
## 作業のお願い（重要）
- `src/config/production.ts` は絶対に変更しない。
- 破壊的な変更（ファイル削除・DBマイグレーション）は、実行前に必ず確認を取る。
- PRのタイトルは `feat:` `fix:` `chore:` のいずれかで始める。
これだけで、対応エージェントは「pnpmを使う」「テストは pnpm test」「production.ts は触らない」を 毎回説明しなくても 分かってくれます。
ポイントは、「コードを読めば分かること」は書かない こと。たとえば「Reactを使っています」はコードを見れば一瞬で分かるので、わざわざ書く価値は薄い。逆に「なぜか production.ts だけは触らないでほしい」みたいな、コードからは読み取れない"人間の意図"こそ、ここに書く価値があるんです。
Claude Code を使っている人は、/init というコマンドを打つと、プロジェクトを自動で解析して CLAUDE.md の雛形を作ってくれます。ゼロから書くのがしんどい人は、まず /init で叩き台を出して、そこから削っていくのが速いですよ。
「守られる指示ファイル」と「無視される指示ファイル」の分かれ目
さて、ここがこの記事のいちばん大事なところです。
多くの人が、指示ファイルで 逆の方向に頑張ってしまいます。「守ってくれないなら、もっと細かく、もっとたくさん書けばいい」と。
でも、これは 逆効果 なんですよね。
Claude Code の公式ベストプラクティスは、はっきりこう言っています。指示ファイルは肥大化すると、かえって無視されやすくなる、と。目安として ルートのファイルは30行程度、長くても1ファイル200行未満 が推奨されています（これは目安であって絶対のルールではないですが、方向性としてとても正しい）。
なぜか。人間だって、A4一枚のオンボーディング資料なら読むけど、100ページの分厚い社内規程は誰も読まないですよね。AIエージェントも、大量の指示に埋もれると どれが本当に重要か分からなくなる。だから「全部書く」は「何も守られない」に近づいていくんです。
だから、指示ファイルを書くときの合言葉はこれです。
各行に「これを消したら、エージェントがミスするか？」と問う。ミスしないなら、消す。
この一問だけで、ファイルは驚くほど締まります。
載せる / 載せない の判断表
| 載せる（コードから読み取れない"意図") | 載せない（自明・すぐ陳腐化する） |
|---|---|
非自明なコマンド（make setup の裏で何が起きるか等） |
言語の標準的な書き方 |
| プロジェクト固有のコードスタイル | コードを見れば分かること |
| テストの好み・実行方法 | 詳細なAPIドキュメント（→リンクにする） |
| ブランチ／PRの作法 | 頻繁に変わる情報（バージョン番号の羅列等） |
| アーキテクチャ上の決定（なぜこうしたか） | 長いチュートリアル |
| 環境の癖・よくハマる落とし穴 | ファイル1つずつの説明 |
Before / After で見る
Before（無視されやすい） — 情報過多で、自明な内容が大半：
## コーディング規約
このプロジェクトはTypeScriptで書かれています。TypeScriptは型のある言語です。
変数はcamelCaseで書きます。関数もcamelCaseです。インデントはスペース2つです。
セミコロンは付けます。文字列はシングルクォートを使います。importは上に書きます。
（この調子であと150行……）
After（守られやすい） — 意図だけを、強調付きで短く：
## コーディング規約（重要）
- 整形は Prettier に任せる（手で整えない）。設定は `.prettierrc` が唯一の正。
- **YOU MUST**: 外部APIを叩くコードは必ず `src/lib/api/` 経由にする。直接 fetch 禁止。
- 日付処理は `date-fns` のみ。他のライブラリは追加しない。
Before は「TypeScriptは型のある言語」みたいな、AIがとっくに知っていること で行数を浪費しています。After は、このプロジェクトでしか通用しない約束 だけに絞って、YOU MUST で優先度を上げている。公式も「IMPORTANT や YOU MUST といった強調は効く」と述べています。エージェントに"効く"のは、量ではなく シグナルの濃さ なんですよね。
AGENTS.md と CLAUDE.md の関係を、正しく整理する
ここで多くの人がこんがらがります。「結局、どっちを書けばいいの？」問題です。表で一気に整理しましょう。
| 観点 | AGENTS.md | CLAUDE.md |
|---|---|---|
| 位置づけ | ツール横断のオープン標準 | Claude Code 専用 |
| 読むツール | Codex / Cursor / Copilot / Jules / Aider など20+ | Claude Code |
| 置き場所 | リポジトリのルート（monorepoはnested可） |
./CLAUDE.md（チーム共有・git管理） |
| 個人用 | 特に規定なし |
./CLAUDE.local.md（.gitignore に入れる） |
| 全体設定 | ― |
~/.claude/CLAUDE.md（自分の全プロジェクト共通） |
ここで疑問が湧きますよね。「じゃあチームでCursorもClaude Codeも使ってたら、AGENTS.md と CLAUDE.md を両方手で書く の？ それ二重管理じゃない？」と。
その通りで、両方を手でメンテすると、必ず片方が古くなって乖離します。これは避けたい。
解決策：@import で単一ソースにする
Claude Code の CLAUDE.md には import という機能があります。@ファイルパス と書くと、そのファイルの中身を 読み込み時にその場に展開 してくれるんです。別紙を綴じ込むイメージですね。
これを使うと、中身の本体は AGENTS.md 一枚に集約して、CLAUDE.md からはそれを取り込むだけ にできます。
# CLAUDE.md
このプロジェクトの共通ルールは AGENTS.md を唯一の正とします。
@AGENTS.md
## Claude Code 固有のメモ
- 大きな変更の前には plan mode で計画を出してから実装する。
こうしておけば、ルールを更新するときに触るのは AGENTS.md だけ。Cursor や Codex はそのまま AGENTS.md を読み、Claude Code は CLAUDE.md 経由で同じ内容を読む。一箇所を直せば全ツールに反映される ので、乖離が起きません。これが2026年の実務での定番パターンです。
import の細かい仕様も押さえておきましょう。
-
@path/to/file.mdの形。相対パス・絶対パス・~（ホームディレクトリ）が使えます。 - import された先がさらに import していてもOK（再帰的。深さはおよそ4〜5段まで）。
- パスを バッククォートで囲むと import されず、ただの文字列 として扱われます（
`@README`のように"言及だけ"したいとき用）。 - 初めて外部ファイルを import するときは、承認ダイアログが出ます。
- 注意点として、import はコンテキストの消費量を減らすわけではありません。中身は全部読み込まれます。あくまで「整理と単一ソース化」のための機能だと理解しておいてください。
monorepo と import で、大きなリポジトリに効かせる
小さなプロジェクトなら、ルートに一枚で十分。でも、monorepo（1つのリポジトリの中に、複数のアプリやパッケージが同居している構成）だと、話が変わってきます。
フロントエンドとバックエンドで、テストコマンドもコード規約も違う。それを全部ルートの一枚に書くと、あっという間に肥大化して"無視されるファイル"に逆戻りです。
そこで使うのが nested（入れ子）配置 です。AGENTS.md も CLAUDE.md も、サブディレクトリごとに置ける ようになっていて、エージェントは 作業している場所にいちばん近いファイルを優先 して読みます。
my-monorepo/
├── AGENTS.md # 全体の共通ルール（最小限に）
├── apps/
│ ├── web/
│ │ └── AGENTS.md # フロント固有: pnpm test, Reactの規約
│ └── api/
│ └── AGENTS.md # バックエンド固有: pytest, DBマイグレーションの注意
└── packages/
└── ui/
└── AGENTS.md # 共通UIライブラリ固有のルール
こうすると、エージェントが apps/api/ の中で作業しているときは、ルートの共通ルール ＋ apps/api/AGENTS.md の固有ルールが効きます。近い方が優先なので、「バックエンドは pytest」みたいな固有事情を、フロントに漏らさず渡せる。しかも子のファイルは そのディレクトリで作業するときに必要に応じて読まれる ので、常に全部を読み込ませてコンテキストを圧迫することもありません。
大きなリポジトリほど、「共通は薄く・固有は近くに」 が効いてきます。
AIに指示ファイルを"書かせる/棚卸しさせる"プロンプト3本
指示ファイル自体を、AIに手伝ってもらいましょう。そのまま使えるプロンプト例を3本置いておきます。役割分担でいう「言語化と棚卸し」の部分をAIに任せる イメージです。
プロンプト1：既存の暗黙知から AGENTS.md の草案を作る
あなたはこのリポジトリのオンボーディング担当です。
以下の情報から、AIコーディングエージェント向けの AGENTS.md 草案を作ってください。
# 制約
- 全体で30行以内。コードを読めば分かることは書かない。
- 「消してもエージェントがミスしないか？」を各行で自問し、必要な行だけ残す。
- セクションは「概要 / よく使うコマンド / コードスタイル / やってほしくないこと」。
# 素材
- package.json のscripts: {ここに貼る}
- チーム内でよく口頭で伝えている注意: {箇条書きで貼る}
プロンプト2：肥大化した指示ファイルを棚卸しする
以下は現在の CLAUDE.md です。肥大化していて、エージェントが指示を守りません。
次の基準で「削除候補」「残す」「リンクに置き換え」の3分類にして、理由を一言ずつ添えてください。
- 削除候補: 言語標準・コードから自明・古くなりやすい情報
- 残す: このプロジェクト固有で、消すとミスが増える意図
- リンク化: 詳細ドキュメントや長い手順（本文には要点だけ残す）
最後に、30行に収めた改訂版を提示してください。
# 現在のCLAUDE.md
{ここに貼る}
プロンプト3：守られない規約の原因を診断する
このプロジェクトでは「外部APIは src/lib/api/ 経由」という規約があるのに、
エージェントが直接 fetch するコードを書いてしまいます。
原因を、次の観点で切り分けてください。
1. 指示ファイルに書かれているか（書かれていないなら追記案）
2. 書かれているが埋もれていないか（優先度・強調・配置の問題）
3. 指示同士が矛盾していないか
それぞれについて、AGENTS.md をどう直せば守られやすくなるか、具体的な修正文を提示してください。
プロンプト3のような「守られない原因の診断」は特に便利で、たいていの原因は 「書いてない」か「埋もれている」か「矛盾している」 の3つに集約されます。人間がこの視点を持っておくと、闇雲に行数を増やさずに済みます。
人間とAIの役割分担（まとめ表）
| 工程 | 人間がやること | AI / ツールに任せること |
|---|---|---|
| 何を書くか決める | どのルールが重要かを選び、優先順位を付ける | 既存コード・設定から候補を洗い出す |
| 初期ドラフト | 方針とトーンを指定する |
/init や プロンプト1で草案を生成 |
| 棚卸し | 「残す/削る」の最終判断 | 肥大化のチェック、削除候補の提案 |
| 単一ソース化 | AGENTS.md を正とする設計判断 | CLAUDE.md からの import 文を用意 |
| チーム標準化 | レビューして git に commit する | 差分の要約、レビュー観点の下書き |
| 運用・改善 | 守られない事故が起きたとき原因を決める | プロンプト3で原因診断・修正案を出す |
一貫しているのは、「決める・承認する」は人間、「言語化・チェック・下書き」はAI という線引きです。指示ファイルは"チームの約束事"なので、最後に責任を持って commit するのは人間、という原則は崩さない方がいいです。
効かない条件・反証 — ここを外すと逆効果になります
良いことばかり書くのはフェアじゃないので、この方法が効かない・むしろ害になる条件 を正直に並べます。ひとつでも当てはまったら、立ち止まってください。
- 肥大化させると、無視される。 繰り返しますが、これが最大の落とし穴です。「守られないから増やす」は悪循環。守られないときは、まず削る を先に試してください。
- コードから自明な内容は、書くだけ逆効果。 シグナルが薄まって、本当に大事な指示が埋もれます。
- 頻繁に変わる情報は載せない。 バージョン番号や、今スプリントだけの一時的な事情を書くと、すぐ陳腐化して"嘘をつくファイル"になります。詳細は リンクで参照 させるのが安全です。
- 二重管理は乖離を生む。 AGENTS.md と CLAUDE.md を両方手で書くと、必ず片方が古くなる。前述の import で単一ソース化 して回避してください。
-
秘密情報を絶対に書かない。 APIキー・トークン・内部URL・個人情報・社内チャンネルIDなどを指示ファイルに書くと、gitに載って流出 します。指示ファイルはチームで共有・バージョン管理される前提。秘密は環境変数やシークレット管理へ。個人的なメモは
.gitignoreしたCLAUDE.local.mdに。 - チャットの明示指示が優先される。 指示ファイルは"デフォルトの前提"であって、絶対の強制力ではありません。その場のチャットで「今回は production.ts を触っていい」と言えば、そちらが優先されます。「ファイルに書いたから100%守られる」とは思わない こと。本当に危険な操作は、hooks のような"実行を止める仕組み"と併用するのが正解です。
この最後の点が、冒頭の hooks の話とつながります。指示ファイル（文脈を渡す）と hooks（実行を止める）は、役割が違う二段構え。片方だけでは守りきれない場面があります。
今日からの最初の一歩（4ステップ）
長くなったので、明日の自分がすぐ動けるように4ステップに畳みます。
-
最小の一枚を置く。 この記事の「10分で書く最小AGENTS.md」をコピーして、自分のプロジェクトのルートに
AGENTS.mdとして置き、中身を差し替える。Claude Code なら/initで叩き台を出してから削る。 - 30行に削る。 各行に「消したらミスするか？」を問い、しないなら消す。自明な行・古くなる行を落とす。
-
単一ソースにする。 Claude Code も使うなら、CLAUDE.md に
@AGENTS.mdを書いて、本体は AGENTS.md 一枚に集約する。 - git に commit してチーム標準にする。 レビューして取り込む。以後、規約が変わったら AGENTS.md を直す。これで"毎回説明"から解放されます。
指示ファイルって、地味なんですよね。派手な機能でもないし、書いても一瞬で世界が変わるわけじゃない。でも、これは 書くほど資産が複利で増える タイプの投資だと思っています。今日30行書いておけば、明日の自分も、来月のチームメンバーも、その分だけ「同じ説明」から解放される。
未来の自分やチームに向けて、"毎回の説明"を一枚に畳んでおく。 これはまさに、明日の自分が「あざっす」と言ってくれる仕込みなんじゃないかなと思います。小さく一枚、置いてみてください。
参考リンク（一次情報・2026-07-19 確認）
- AGENTS.md 公式サイト: https://agents.md/
- Claude Code ベストプラクティス（CLAUDE.mdの書き方・30行目安・
/init）: https://code.claude.com/docs/en/best-practices - Claude Code メモリ / import 構文（
@path・monorepo・階層）: https://code.claude.com/docs/en/memory - AGENTS.md 標準化の背景（InfoQ）: https://www.infoq.com/news/2025/08/agents-md/
※本文のコマンド・ファイル例は汎用サンプルです。ツールのバージョンによって挙動が変わる場合があるため、導入時は各公式ドキュメントで最新仕様をご確認ください。行数の目安（30行/200行）は公式が示す推奨値で、絶対の制約ではありません。
生成AI活用エンジニア＆3児のパパ。AI×開発の実践知を毎日発信しています → X: https://x.com/akira_papa_AI