AGENTS.md / CLAUDE.md に何を書くべきか — 効く指示と効かない指示

AIエージェントに開発を任せると、多くの人が最初にぶつかるのが「同じ注意を毎回書いている」という状態です。テストの実行コマンドを毎回伝え、触ってほしくないディレクトリを毎回伝え、コミットの粒度を毎回伝える。これを1か所にまとめて自動で読ませる仕組みが指示ファイルで、AGENTS.md や CLAUDE.md といった名前でリポジトリのルートに置きます。

この形式はすでに事実上の標準になりつつあります。agents.md によれば AGENTS.md は6万を超えるオープンソースプロジェクトで使われており、20以上のコーディング支援ツールが対応しています。

ただし、ここに書けば書くほど賢くなるわけではありません。むしろ書きすぎたせいで肝心の指示が効かなくなることは、ツールの公式ドキュメント自身が明記しています。この章では、公式が何と言っているかを確認しながら、何を書き、何を書かず、どう育てるかを整理します。

学習者

READMEに書いてあることを、なんでもう一回書かないといけないの？

指示ファイルは「毎回支払うコスト」である

READMEと指示ファイルの決定的な違いは、読まれるタイミングにあります。agents.md はこの分離の理由を「READMEは人間のためのものだから」と説明しています。READMEは人間が必要なときに開くもので、開かなければコストはゼロです。

対して指示ファイルは、エージェントがセッションを開始するたびに自動で読み込まれます。Claude Codeの公式ドキュメントは、CLAUDE.mdが「セッション開始時にコンテキストウィンドウへ読み込まれ、会話と並んでトークンを消費する」と明記しています。

重要なのは、公式が分量と遵守率の関係にまで踏み込んでいることです。

この性質を踏まえると、「とりあえず全部書いておこう」という発想が成立しないことが分かります。指示ファイルの設計は、書く内容を選ぶ作業であると同時に、書かない内容を捨てる作業でもあります。

何を書くべきか — 規約が挙げている項目

では何を書くのか。ここは筆者の意見ではなく、規約とドキュメントが実際に列挙している項目を見るのが早いです。

agents.md が挙げる代表的なセクションは、プロジェクト概要、ビルドとテストのコマンド、セットアップ手順、コーディング規約、テストの実行方法、開発環境のヒント、PRの出し方、コミットメッセージの規約、セキュリティ上の注意です。Claude Code側も、プロジェクト用のCLAUDE.mdに書くものとして「ビルドとテストのコマンド、コーディング規約、アーキテクチャ上の決定、命名規則、共通のワークフロー」を挙げています。

両者に共通して現れるものを整理すると、おおむね次の4つに寄ります。

この中で実行方法を最初に埋めることを勧めます。これは筆者の優先付けですが、根拠はあります。agents.mdもClaude Codeの /init も、まずビルドコマンドとテストの実行方法を拾いにいく設計になっており、規約側がこの情報を中心に据えていることが読み取れます。理由も理解しやすく、テストの走らせ方を知っているエージェントは、自分の変更が壊れているかどうかを自分で確認できるからです。確認できるエージェントは間違えても自力で戻ってきますが、確認できないエージェントは間違えたまま「完了しました」と言います。

## 開発コマンド
 
- 型チェック: `npm run typecheck`
- テスト: `npm test`（単体）/ `npm run test:e2e`（E2E）
- lint: `npm run lint -- --fix`
 
コードを変更したら、コミット前に型チェックとテストを必ず通すこと。

先生

迷ったら「これを知らないと、エージェントは自分の間違いに気づけないか？」で選ぶといいよ。気づけないものが最優先だ。

何を書くべきでないか

書かないほうがよいものについても、公式に明快な基準があります。Claude Codeの /doctor は肥大化したCLAUDE.mdのトリムを提案する機能を持っていますが、その判断基準がコードベースから導ける内容を削り、落とし穴・判断の根拠・ツールの既定と異なる規約を残すというものです。削る側の例として、ディレクトリ構成、依存関係の一覧、アーキテクチャの概要が挙げられています。

つまり、エージェントがファイルを読めば分かることを書き写すのは、公式の基準では削除対象です。

同じく避けるべきなのが曖昧な一般論です。Claude Codeのドキュメントは、検証できる具体性で書くよう求めており、対比の例まで示しています。

3つ目が頻繁に変わる事実です。ライブラリのバージョン番号の一覧などは、更新を忘れた瞬間に嘘の情報を毎回読ませる状態になります。公式も、古くなった指示や矛盾する指示を定期的に見直して削除するよう促しています。

「書いたのに守らない」が起きる理由

指示ファイルを整備した人がほぼ必ず経験するのが、書いたはずのルールをエージェントが守らないという現象です。これは不具合ではありません。公式ドキュメントが、そもそもそういう仕組みだと説明しています。

Claude Codeのドキュメントは、CLAUDE.mdを「コンテキストであって、強制される設定ではない」と位置づけています。内容はシステムプロンプトの一部ではなく、その後のユーザーメッセージとして届けられるため、厳密な遵守は保証されないと明記されています。曖昧な指示や矛盾する指示の場合は特にそうだ、とも書かれています。

では、なぜ数が増えると守られなくなるのか。ここには研究側の知見があります。IBMの研究チームによるBoosting Instruction Following at Scale（2025年10月）は、指示の数を増やしていくと追従率が下がることを確認し、その主要因として指示どうしの緊張・衝突を挙げています。

ここから導かれる対策は3つです。

• 数を絞る — 衝突が主因である以上、20個書いて15個守られるより、5個に絞るほうが結果は安定します
• 具体的に書く — 前節の対比表のとおり、検証できる粒度まで落とします。公式も、矛盾する指示があるとどちらか一方が恣意的に選ばれると述べています
• 機械で強制する — これが本命です

これも筆者の主張ではなく、公式が明示的に案内している道筋です。Claude Codeのドキュメントは、エージェントの判断にかかわらず動作をブロックしたい場合は指示ファイルではなくフックを使うよう指示しており、「コミット前」「ファイル編集後」のように決まったタイミングで必ず走らせたいものはフックとして書けと明記しています。

指示ファイルはお願いであり、仕組みは保証です。お願いで済ませていいのは、破られても致命的でないことだけです。

学習者

じゃあ、指示ファイルってあんまり意味ないの？

そうではありません。機械で強制できることには限りがあります。「このディレクトリはレガシーなので新規実装では使わない」「このドメイン用語はこういう意味だ」といった判断や文脈に関わることは、フックでは表現できません。指示ファイルの役割は、仕組みにできない部分を引き受けることです。

肥大化したら分割する — ただし節約にはならない

書くべきことが増えてきたら、1ファイルに詰め込まず分割します。Claude Codeは @path/to/file の記法で他のファイルを取り込め、取り込んだ先からさらに取り込むこともできます（最大4ホップ）。Cursorも、大きなルールは複数の合成可能なルールに分割せよと明記しています。

# プロジェクトの指示
 
開発コマンドは @docs/commands.md を参照してください。
ドメイン用語は @docs/glossary.md にまとめています。
Gitの運用ルールは @docs/git-workflow.md に従ってください。

ここで必ず押さえておきたい落とし穴があります。Claude Codeの公式ドキュメントは、インポートしたファイルも起動時に展開されてコンテキストに入るため、分割してもコンテキストの消費量は減らないとはっきり書いています。「整理には役立つが、コンテキストの削減にはならない」という表現です。

本当に消費を減らしたい場合の手段も公式に用意されています。Claude Codeの .claude/rules/ に置くルールは frontmatter で対象パスを指定でき、該当するファイルをエージェントが読んだときだけコンテキストに入ります。常時読ませる必要のない指示は、こちらに逃がすのが筋です。

---
paths:
  - "src/api/**/*.ts"
---
 
# API実装のルール
 
- すべてのエンドポイントで入力バリデーションを行う
- エラーレスポンスは共通フォーマットに従う

ツール固有のファイルは薄いアダプタにする

ここが、この章でいちばん寿命の長い話です。そしてここも公式が推奨している形です。

まず知っておくべき事実があります。Claude Codeは AGENTS.md を読みません。読むのは CLAUDE.md です。一方でCursorは AGENTS.md に対応しています。素直に両方に書くと、同じ内容が2か所に複製され、片方だけ更新されて食い違います。

Claude Codeの公式ドキュメントは、この状況に対する解決策を明示しています。すでに AGENTS.md を使っているリポジトリでは、AGENTS.md をインポートするだけの CLAUDE.md を作れ、というものです。

@AGENTS.md
 
## Claude Code 固有の指示
 
`src/billing/` 配下の変更ではプランモードを使うこと。

シンボリックリンクを張る方法も案内されています（ツール固有の追記が不要な場合）。

つまり構造としては、ナレッジの本体をツール非依存の場所に一本化し、ツール固有のファイルは参照だけを担う薄い層にするという形になります。新しいツールを試すときに必要なのは、そのツールの流儀に合わせた数行の参照ファイルを1つ足すことだけで、本体には手を触れません。

人が書き続けない — 育てる仕組みにする

指示ファイルの敵は書き忘れではなく更新忘れです。プロジェクトは変わり続けるのに、指示ファイルだけが初期の状態で止まる。そして前述のとおり、古い指示は指示がないより有害です。

まず、いつ追記すべきかについて、Claude Codeのドキュメントに具体的な目安があります。

• エージェントが同じ間違いを2回したとき
• コードレビューで、エージェントが知っておくべきだった指摘が出たとき
• 前のセッションでも打ったのと同じ訂正をチャットに打ち込んだとき
• 新しく入るメンバーにも同じ説明が必要になるとき

いずれも「再説明が発生した」という観測可能なきっかけになっている点が実務的です。思いついたときに書くのではなく、再説明が起きたら書くという運用にできます。

そのうえで、更新を人間の意志だけに頼らない方向が2つあります。

エージェント自身に書かせる。 Claude Codeには初期生成の /init があり、既存ファイルがある場合は上書きせず改善を提案します。さらにauto memoryとして、ユーザーからの訂正や好みをエージェント側が自動で書き溜める仕組みも用意されています。

記録と昇華を分ける。 日々の記録は機械的に安く貯めておき、そこから繰り返し現れたパターンだけを人間が選んで指示ファイルに載せます。何でもかんでも追記すると前半の肥大化に一直線で向かうため、貯める場所と載せる場所を分けるのが要点です。Claude Codeのauto memoryが、常時読み込む索引と、必要なときだけ読む個別ファイルに分かれているのも同じ考え方です。

先生

指示ファイルは書いて終わりのドキュメントじゃなくて、育て続ける対象だと考えるといいよ。育たなくなった時点で、静かに足を引っ張り始めるからね。

よくあるハマりどころ

そもそも読み込まれていない。 ファイルを置いただけで読まれるとは限りません。ファイル名の綴り、置き場所、ツール側の設定のいずれかがずれていると丸ごと無視されます。公式のトラブルシュート手順も、最初にやることとして読み込み済みのファイル一覧を確認することを挙げています（Claude Codeなら /context、一覧と編集は /memory）。「守ってくれない」と悩む前に、まず見えているかを確認します。

矛盾する指示が同居している。 公式は、2つのルールが衝突した場合エージェントがどちらかを恣意的に選ぶ可能性があると述べています。ファイルが複数階層に散らばっていると、自分では気づかないまま矛盾が生まれます。定期的な棚卸しが必要です。

個人の設定をチーム共有ファイルに書く。 「日本語で返答して」「自分はこのエディタを使っている」といった個人の好みを、Gitで共有されるファイルに書いてしまう事故です。Claude Codeは組織全体・ユーザー個人・プロジェクト共有・プロジェクト個人の4階層を用意しており、個人用のものは .gitignore に入れる前提で設計されています。どのファイルが誰に届くのかは、中身の話とは別に押さえておく必要があります。

コードベースから読める情報を書き写す。 前述の /doctor の基準どおり、ディレクトリ構成や依存一覧は削除対象です。書いた本人は仕事をした気になりますが、枠を消費しているだけになりがちです。

ちゃんと使うためのポイント

• 指示ファイルは常設のコンテキストであり、分量はそのまま毎回のコストになる。Claude Codeは200行未満、Cursorは500行以内という目安を公式に示している
• 書く項目は規約が列挙している範囲（実行方法・前提・手順・禁止事項）に収める。コードベースから読める情報は書かない
• 指示は検証できる具体性まで落とす。「適切に」で終わる指示は効きにくい
• 指示ファイルは強制ではない。守らせたいものはフックなど機械側の仕組みに移す
• 分割は整理には効くが、インポートではコンテキストは減らない。減らしたいならパス限定のルールを使う
• ナレッジ本体はツール非依存の場所に置き、ツール固有ファイルは参照だけの薄い層にする
• 「再説明が発生したら追記する」を運用の合図にする

次の章では、この指示ファイルで書ききれないもの——エージェントに与えるタスクそのものの切り方を扱います。どれだけ指示ファイルを整えても、タスクの粒度が間違っていれば結果は安定しません。

参考リンク

• AGENTS.md — 規約が推奨するセクションと、採用しているツールの一覧
• How Claude remembers your project（Claude Code 公式） — 200行の目安、具体性の指針、フックへの誘導、@AGENTS.md インポートの推奨
• Rules（Cursor 公式） — 500行の目安と分割の指針
• Boosting Instruction Following at Scale（2025-10） — 指示数の増加による追従率の低下と、位置との関係についての報告