AGENTS.md・CLAUDE.mdに何を書くか｜コーディングエージェントの指示ファイルは「コードから読めないこと」だけを短く

コーディングエージェントを使い始めると、リポジトリの直下に置く指示ファイルの扱いで迷う場面が増えます。Claude CodeならCLAUDE.md、CodexならAGENTS.md、GitHub Copilotなら.github/copilot-instructions.mdと名前はばらばらでしたが、2026年9月時点ではClaude Codeの公式ドキュメントに「v2.1.277以降はCLAUDE.mdが無ければAGENTS.mdを読む」と明記され、主要ツールのほとんどがAGENTS.mdを読めるようになりました。1ファイルで運用しやすくなった一方で、「何を書けばよいのか」は置き去りのままです。しかも2026年に出た実証研究2本は、とりあえず長く書いた指示ファイルが成功率を上げない可能性を示しています。この記事では、指示ファイルを流行のツール設定ではなく、何を書けば効き、何を書くと逆効果かという時期に依存しにくい設計の問題として整理します。

指示ファイルとは何か#

指示ファイルは、コーディングエージェントがセッションを始めるときに自動で読み込むMarkdownファイルです。AGENTS.mdの公式サイトは、これを「エージェントのためのREADME」と表現しています。READMEが人間の利用者や新しい開発者に向けた説明であるのに対し、指示ファイルはエージェントが作業するために必要な、人間向けには細かすぎる情報(ビルド手順、テストの流し方、規約の細部)を置く場所という位置づけです。

ポイントは、指示ファイルの中身が毎回のセッションでコンテキストウィンドウに入ることです。Claude Codeのドキュメントは、CLAUDE.mdが会話と同じくトークンを消費し、長いほどコンテキストを使って指示への従い方(adherence)が落ちると説明しています。つまり指示ファイルの1行は、エージェントが毎回必ず読む1行です。書くことにはコストがあり、その前提で中身を選ぶ必要があります。

コンテキスト全体の設計については、別記事で整理しています。

いま主要ツールはどのファイルを読むか#

AGENTS.mdは特定ツールの設定ファイルではなく、決まったフィールドのない普通のMarkdownとして定義されたオープンな形式です。2025年8月にOpenAIが公開し、2025年12月にLinux Foundationが発表したAgentic AI Foundationの設立時に、OpenAIが拠出したプロジェクトの1つになりました。公式サイトには、現在はLinux Foundation配下のAgentic AI Foundationが管理していると書かれています。仕様上の読み込みルールは「ディレクトリツリーで最も近いファイルが優先される」「チャットでの明示的な指示はすべてに優先する」の2点です。

各ツールの読み込み方は、公式ドキュメントで確認できた範囲では次のとおりです。

研究が示した「書いても効かない」部分#

指示ファイルは各社が推奨しているため、書けば効くと考えがちです。しかし2026年に公開された2本の研究は、少なくとも「タスクの成功率」という尺度では、期待ほどの効果が見えないことを示しました。

1本目はGloaguenらの「Evaluating AGENTS.md」(arXiv:2602.11988)です。Claude Code、Codex、Qwen Codeに計4つのモデルを組み合わせ、有名リポジトリのSWE-bench Liteと、開発者が実際に指示ファイルをコミットしている12リポジトリから作った138件の新しいベンチマーク(CTXbench)で、「指示ファイルなし」「LLMが生成した指示ファイル」「開発者が書いた指示ファイル」を比べています。結果は次のとおりです。

• LLMが生成した指示ファイルでは、成功率は2つのベンチマークで平均0.5%と2%下がり(統計的に有意ではない)、ステップ数が増えて推論コストは平均20%と23%増えた
• 開発者が書いた指示ファイルでは、成功率は平均2.4%上がったが有意ではなく、コストは最大19%増えた。LLM生成のものよりは有意に良かった
• 指示ファイルの中身そのものはよく守られ、テストの実行や探索が増えていた。一方でリポジトリの概要説明は、関連ファイルにたどり着くまでの時間を短くしなかった

著者らは結論で、指示ファイルは「コードベースから得られる情報を超えた、具体的な追加の指示だけを含めるべき」と述べています。

2本目はKhatriの「Do Context Files Help Coding Agents?」(arXiv:2607.27250)です。Claude CodeとCodexの2つのエージェントで、3つのPythonリポジトリから作った17タスク、計288回の実行を評価し、AGENTS.mdを渡さない・常に渡す・話題別に分けて必要なときに読ませる、の3通りを比べました。正答率の差はどちらのエージェントでも測定できる水準に達せず、失敗の分析からは、落ちた原因はリポジトリ固有の知識不足ではなく、機能の設計やパターン選択、細部の配線といった実装力の側にあったと報告しています。

ただし同じ論文には、見落とせない例外もあります。AGENTS.mdに「フルテストスイートは20分以上かかる」と書かれていたリポジトリでは、指示を渡したほうがフルテストの無駄な実行が減り、Claude Codeの所要時間が約24%短くなりました(著者はタスク数が5件で検出力が足りないと注記しています)。これはまさに、コードを読んでも分からない運用上の事実です。

書くべきこと: コードから推測できない情報#

研究の結論と、各ツールの公式ドキュメントの推奨はほぼ同じ方向を向いています。Claude Codeのベストプラクティスは、含めるべきものとして「推測できないBashコマンド」「既定と異なるコードスタイル」「テストの手順と使うテストランナー」「ブランチ名やPRの作法」「プロジェクト固有の設計判断」「必須の環境変数などの開発環境のクセ」「よくある落とし穴や直感に反する挙動」を挙げています。これを実務の観点でまとめると、次の4種類になります。

書き方のイメージは次のとおりです。短く、検証できる粒度で書きます。

# AGENTS.md

## コマンド
- 依存関係: `pnpm install`(npm・yarnは使わない)
- 単体テスト: `pnpm test -- path/to/file.test.ts`(全件は10分以上かかるので最後に1回だけ)
- 型チェックとlint: `pnpm typecheck && pnpm lint`

## 触らないもの
- `src/generated/`は`pnpm codegen`の生成物。手で編集しない
- 本番DBへのマイグレーションは実行しない(人がCIから流す)

## 完了条件
- 変更後に型チェック・lint・関連テストが通っていること
- 公開APIの型を変えたら`docs/api.md`も更新する

## 規約
- コミットはConventional Commits(本文は日本語)

Claude Codeのドキュメントも、CLAUDE.mdに書くタイミングの目安として「同じ間違いを2回目にしたとき」「コードレビューで、エージェントが知っているべきだった指摘が出たとき」「前回のセッションと同じ訂正を打ち込んでいるとき」を挙げています。最初から完璧に書こうとせず、実際に困ったことを1行ずつ足していくほうが、効く内容だけが残ります。

書かないほうがいいこと#

逆に、次のような内容は削る候補です。

Claude Codeのベストプラクティスは、各行について「この行を消したら、Claudeは間違えるか」と自問し、そうでなければ削るよう勧めています。さらに、ルールがあるのに守られないなら、ファイルが長すぎてそのルールが埋もれている可能性が高いとも書いています。強調表現(IMPORTANTなど)は1行だけに使い、多用すると何も目立たなくなる点も指摘されています。

長さと分割: 必要なときだけ読ませる#

長さの目安は、ツールごとに公式ドキュメントに書かれています。Claude Codeは「CLAUDE.md1ファイルあたり200行未満」を目標とし、Cursorはルールを「500行未満」に保つよう勧めています。Codexは合計サイズの上限が既定で32KiBで、それを超えた分は読み込まれません。数字はツールごとに違いますが、どれも「短く」という方向は同じです。

長くなってきたときの手段は、分割して必要なときだけ読ませることです。

• パス単位のルール: Claude Codeの.claude/rules/は、frontmatterのpathsにglobを書くと、該当するファイルを読んだときだけ読み込まれます。Copilot・VS Codeの*.instructions.mdはapplyToで、Cursorのルールはファイルパターンで同じことができます
• 階層配置: サブディレクトリにAGENTS.mdやCLAUDE.mdを置くと、そのディレクトリで作業するときに追加されます(VS Codeでは実験的機能で既定オフ)。モノレポでパッケージごとに違うテスト手順を書くときに向きます
• 手順書は別の仕組みへ: 複数ステップの手順や、ときどきしか使わない知識は、Claude Codeならスキル(必要時に読み込む)に移すよう公式に勧められています

指示は強制ではない#

指示ファイルでいちばん誤解されやすいのがここです。Claude Codeのドキュメントは、CLAUDE.mdとauto memoryについて「Claudeはこれらを強制される設定ではなく、コンテキストとして扱う」と明記し、Claudeが何を判断するかに関係なく操作を止めたいならPreToolUseフックを使うよう案内しています。CLAUDE.mdの内容はシステムプロンプトの後にユーザーメッセージとして渡されるため、曖昧な指示や矛盾する指示では厳密に守られる保証はない、とも書かれています。ベストプラクティスでも、CLAUDE.mdの指示は助言的(advisory)で、フックは決定的(deterministic)に実行されると対比しています。

したがって、「本番に触らない」「このディレクトリは編集しない」「コミット前に必ずlintを通す」のように、破られたら困るものは次の層で止めます。

指示ファイルは「なぜその操作をしないのか」「代わりに何をすればよいか」を伝える場所として使い、止める役割は権限とCIに持たせる、という分担が安全です。承認をどこに挟むかの設計は別記事で扱っています。

複数ツール併用チームの運用#

チームの中でClaude Code、Codex、Copilot、Cursorが混在している場合、ツールごとに別々の指示ファイルを保守すると、すぐに内容が食い違います。現実的なのは、AGENTS.mdを正本にして、他のツールからはそれを参照させる形です。

• AGENTS.mdだけを置く: Claude Code(v2.1.277以降)、Codex、VS Code、CursorはいずれもAGENTS.mdを読めます。ツール固有の指示が無ければ、これが最も単純です。ただしGitHub Copilotは環境と機能によって対応が分かれ、GitHub.comのCopilot Chat、Visual StudioやJetBrainsのChat、VS Codeのコードレビューなどは、copilot-instructions.mdは読んでもAGENTS.mdは読みません。これらの機能も使うなら、copilot-instructions.mdにも必要な指示を置き、AGENTS.mdと内容を揃えておく必要があります
• CLAUDE.mdから取り込む: Claude Code固有の指示を足したい場合や、AGENTS.mdを直接読めない環境がある場合は、CLAUDE.mdの先頭に@AGENTS.mdと書いて取り込み、その下にClaude Code向けの指示を追記します。公式ドキュメントに記載されている方法です
• シンボリックリンク: ln -s AGENTS.md CLAUDE.mdでも共有できますが、Claude Codeのドキュメントは、Windowsで作業する人がいるなら@importを使うよう勧めています(シンボリックリンクの作成に権限が必要で、Gitの設定によっては1行のテキストファイルとしてチェックアウトされるため)

以前からAGENTS.mdを読ませる工夫をしていた場合の整理も、Claude Codeのドキュメントにあります。CLAUDE.mdに「AGENTS.mdを読むこと」と文章で書いているだけの場合は、Claudeがファイルを開くと判断しない限り読まれないため、@importに置き換えるか、CLAUDE.mdを消します。SessionStartフックでAGENTS.mdを出力していた場合は、直接読むようになると内容が二重に入るので、フックを外すよう案内されています。

効いているかを確かめる#

指示ファイルは、アプリに組み込むプロンプトと同じく「書いたら効くはず」で終わらせず、効いているかを確かめる対象です。1本目の研究の著者らも、性能を上げようとする試みは導入前に厳密に評価すべきだと結論づけています。チームで回せる範囲では、次の進め方が現実的です。

エージェントの挙動は実行ごとにばらつくため、1回ずつの比較では差が偶然か判断できません。2本目の研究でも、17タスク・288回の実行で10ポイント程度の差は検出できない設計だったと、著者自身が限界として書いています。社内では「明らかに悪化していないか」「特定の失敗が再発しなくなったか」を確かめる目的に割り切るのが現実的です。評価の組み立て方とプロンプトの変更管理は、それぞれ別記事で解説しています。

よくある質問#

まとめ#

指示ファイルは、書けば書くほどエージェントが賢くなる魔法の設定ではありません。コードを読めば分かることは書かず、コードからは絶対に分からないことだけを短く書く。そのうえで守らせたいことは仕組みで止め、効いているかは実際のタスクで確かめる。地味ですが、ツールの名前やバージョンが変わっても通用する運用の軸です。

各ツールの読み込み仕様は、AGENTS.md公式サイト、Claude Code Docs(memory、best practices)、Codex(OpenAI)のAGENTS.mdガイド、GitHub Docs、VS Code、Cursorの各公式ドキュメント(2026年9月24日時点)で確認しました。研究結果はarXiv:2602.11988(v2)とarXiv:2607.27250の本文、およびarXiv:2601.20404の要旨に基づきます。ツールの挙動はバージョンアップで変わるため、導入時は最新の公式ドキュメントを確認してください。