コーディングエージェントに作業を頼むたびに、「このリポジトリは pnpm を使っていて」「テストはこのコマンドで」「日付は UTC で保存して」と、同じ前提を説明していませんか? 人間の新メンバーなら一度教えれば覚えてくれますが、エージェントは新しいセッションを始めるたびに、まっさらな状態から始まります。
そこで役に立つのが、リポジトリに置いておく「指示ファイル」です。CLAUDE.md や AGENTS.md という名前を聞いたことがある方も多いでしょう。ところが、いざ書いてみると「何を書けばいいのか分からない」「書いたら逆に遅くなった気がする」「書いたのに守ってくれない」という声もよく聞きます。
本記事では、指示ファイルに何を書けば効くのかを、最近の研究と各ツールの公式ドキュメントから整理します。シリーズ第 2 回。H1 で示した部品の地図でいう「指示ファイル」の話です。
指示ファイルとは
指示ファイルは、エージェントがセッションの開始時などに自動で読み込む Markdown のファイルです。ビルドやテストの手順、コードの書き方の決まりなど、毎回伝えたい前提を書いておくと、エージェントのコンテキスト(モデルがその時点で参照できる情報の全体)に入ります。どのファイルをいつ読み込むかは、ツールや機能ごとに違います(後の表を参照)。
主要な 4 ツールには、それぞれ指示ファイルの仕組みがあります。Claude Code は CLAUDE.md、Codex CLI は AGENTS.md、Gemini CLI は GEMINI.md、GitHub Copilot は .github/copilot-instructions.md が基本の名前です(2026 年 10 月時点)。
なかでも AGENTS.md は、特定のツールに縛られない共通の形式として広がっています。公式サイトによると、決まった項目はなく普通の Markdown で書けばよく、開発環境の準備・テストの手順・PR の決まりといった例が挙げられています。サブフォルダに別の AGENTS.md を置くと、編集するファイルに一番近いものが優先される、という考え方も示されています(AGENTS.md)。2026 年 10 月時点の公式ドキュメントでは、Codex CLI は AGENTS.md を標準で読み、Gemini CLI は設定でファイル名を AGENTS.md に変えられ、GitHub Copilot は cloud agent などで AGENTS.md も読みます。Claude Code は、既定では CLAUDE.md が無いリポジトリで AGENTS.md を読みます。
大切なのは、指示ファイルはあくまで「お願い」だという点です。Claude Code の公式ドキュメントは、CLAUDE.md は強制される設定ではなくコンテキストとして扱われると明記し、どんな場合でも止めたい操作にはフック(エージェントの動きの決まった時点で、決まった処理を必ず実行する仕組み)を使うよう案内しています(Claude Code「How Claude remembers your project」)。この「お願い」と「強制」の違いは、シリーズ第 4 回のフックの記事で詳しく扱います。
では、お願いとしての指示ファイルは、実際どれくらい効くのでしょうか。2026 年に入って、ちょうどこれを測った研究がいくつか出ています。
📄 論文: 指示ファイルは成功率を上げるか
Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?(Thibaud Gloaguen ほか、2026年2月、arXiv:2602.11988)は、ICLR 2026 のワークショップ(MemAgents)採録の論文です。
研究チームは、よく使われるベンチマーク(SWE-bench)の課題に LLM が自動生成した指示ファイルを付けた場合と、開発者が実際にコミットした指示ファイルを持つリポジトリから集めた新しい課題の 2 つの設定で、指示ファイルの有無によってエージェントの課題達成率がどう変わるかを比べました。
結果は意外なものでした。指示ファイルを与えても課題の成功率は概して上がらず、推論のコストは平均で 20% 以上増えました。この傾向は、モデルやエージェントの種類を変えても同じでした。本文によると、開発者が書いたファイルは自動生成のファイルより成功率が平均 7% 高く、この差は統計的に有意でしたが、ファイルなしとの差ははっきりしませんでした。一方で、指示ファイルに書かれた指示そのものはよく守られていました。効かなかったのは、モデルの提供元も勧めている「リポジトリの概要」の説明です。著者らは、指示ファイルは標準的でないコーディングの決まりを伝えるのには役立つとしています。
現場にとっての意味は、「リポジトリを見れば分かること」を長々と書いても成果にはつながらず、読み込むコストだけが増えるということです。書くべきなのは、そのプロジェクトだけの決まりです。
📄 論文: 速さとトークンへの効果
On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents(Jai Lal Lulla ほか、2026年1月、arXiv:2601.20404)は、ICSE 2026 の併設ワークショップ(JAWs)採録の、5 ページの短い報告です。
こちらは「成功するかどうか」ではなく「どれだけ速く・少ない量で終わるか」を測りました。10 個のリポジトリの 124 件の PR を題材に、AGENTS.md がある場合とない場合でエージェントを動かし、実行にかかった時間とトークン(モデルが文章を処理するときの単位)の量を比べています。
AGENTS.md があると、実行時間の中央値は 28.64% 短く、出力トークンは 16.58% 少なくなりました。課題の達成の度合いは同程度でした。ただし 10 リポジトリでの結果で、AGENTS.md の有無との関連を示したものです。
前の論文と結論が逆に見えますが、測っているものが違います。前の論文は成功率と推論コスト全体、こちらは実行時間と出力の量です。両方を合わせると、「指示ファイルで劇的に賢くなるわけではないが、迷う時間を減らす効果はありうる」と読むのが妥当でしょう。現場にとっての意味は、効果を確かめるなら自分のリポジトリで「何を」測るかを先に決めておく必要がある、ということです。
📄 論文: 2,300 ファイルの中身の実態
Agent READMEs: An Empirical Study of Context Files for Agentic Coding(Worawalan Chatlatanagulchai ほか、2025年11月、arXiv:2511.12884)は、ソフトウェア工学の論文誌 ACM TOSEM に 2026 年に掲載された論文です。
研究チームは、1,925 のリポジトリから集めた 2,303 個の指示ファイルを調べ、構成・更新のされ方・中身を分析しました。指示ファイルは一度書いて終わりの文書ではなく、小さな追記を何度も重ねて育っていく「設定ファイルのようなもの」で、読みにくくなりがちだと報告しています。
中身では、テストの手順(75.9%)などの「動かすための情報」が多く書かれていた一方、セキュリティ(14.8%)や性能といった品質面の要件はほとんど書かれていませんでした。
現場にとっての意味は、情シスやセキュリティ担当の目線で書き足す余地が大きいということです。たとえば「秘密情報のファイルは読まない・出力しない」「外部への送信を伴う変更は人に確認する」といった行は、多くのファイルに欠けています。ただし、この研究は書かれている内容を数えたもので、こうした行を書けば安全になるかを測ったものではありません。本当に禁止したい操作は、権限設定やサンドボックスで止めましょう(第 3 回)。
セッションをまたぐ記憶
指示ファイルとは別に、エージェント自身が作業の中で学んだことをメモとして残し、次のセッションで読み込む「記憶」の機能も各ツールに入り始めています。2026 年 10 月時点の公式ドキュメントでは、Claude Code の auto memory、Codex の Memories、Gemini CLI のメモリーファイル、GitHub Copilot の Copilot Memory(パブリックプレビュー)があります。
評価した研究はまだ少ないため、ここでは仕組みだけ紹介します。各社のドキュメントに共通するのは、「人が書く指示ファイル」と「エージェントが書く記憶」を分けて扱う考え方です。Codex のドキュメントは、必ず守らせたい決まりは AGENTS.md などに書き、記憶は補助的な思い出しの層として扱うよう勧めています(Codex「Memories」)。GitHub Copilot は、使われない記憶を 28 日で自動的に消すとしています(GitHub「About GitHub Copilot Memory」)。チームで守る決まりは、記憶に頼らず指示ファイルに書いておきましょう。
実践:指示ファイルを書いて育てる
研究と公式ドキュメントを合わせると、指示ファイルは次の手順で書くのがよさそうです。
- 共通の内容は AGENTS.md にまとめる: 複数のツールを使うチームなら、ツールをまたいで共通の決まりは AGENTS.md に書き、ツール固有の内容だけを各ツールのファイルに分けます
- 概要より「独自の決まり」を書く: 使うパッケージマネージャー、日付の扱い、エラーの返し方など、コードを読んでも分かりにくいプロジェクト独自の規約を優先します
- 確認の手順を書く: 変更したら通すべきリントやテストのコマンドを具体的に書きます。Claude Code のドキュメントも「コードをきちんと整形して」より「インデントは 2 スペース」のように、確かめられる書き方を勧めています
- 品質面の決まりを足す: 秘密情報の扱いや、触ってはいけないフォルダなど、論文で手薄だと分かった項目を書き足します
- 短く保ち、定期的に削る: Claude Code のドキュメントは 1 ファイル 200 行未満を目安に挙げ、長いほど守られにくくなるとしています。月に一度は古い行を見直しましょう
たとえば、共通の決まりを AGENTS.md に書き、CLAUDE.md ではそれを取り込んで Claude Code 固有の内容だけを足す形です。
AGENTS.md の例:
# AGENTS.md
## このリポジトリの決まり
- パッケージマネージャーは pnpm を使う(npm と yarn は使わない)
- 日付は必ず UTC で保存し、表示するときだけ日本時間に変換する
- API のエラーは src/lib/errors.ts の AppError で返す。素の Error は投げない
## 変更したら確認すること
- `pnpm lint` と `pnpm test` が通ること
- 画面を変更したら、スクリーンショットを PR に添付する
## 触らないもの
- db/migrations/ の既存ファイルは編集しない(新しいファイルを追加する)
- 秘密情報(.env など)は読まない・出力しない。必要なら人に確認する
CLAUDE.md の例(AGENTS.md を取り込み、Claude Code 固有の内容だけを足す):
# CLAUDE.md
@AGENTS.md
## Claude Code 固有
- 長い調査はサブエージェントに任せ、結論だけを受け取る
(設定の書き方は 2026-10-01 時点の公式ドキュメント Claude Code「How Claude remembers your project」・AGENTS.md 公式サイト で確認。仕様は変わるため、使う前に最新の公式ドキュメントを確認してください)
各ツールで、指示ファイルをどこに置き、どう読み込ませるかは次のとおりです。2026 年 10 月時点の各社公式ドキュメントに基づく。仕様は変わるため最新の公式ドキュメントを確認してください。
| 項目 | Claude Code | Codex CLI | Gemini CLI | GitHub Copilot |
|---|---|---|---|---|
| 指示ファイルの名前 | CLAUDE.md(無ければ AGENTS.md) | AGENTS.md・AGENTS.override.md | GEMINI.md(context.fileName で変更可) | .github/copilot-instructions.md・AGENTS.md |
| 個人用(全プロジェクト共通) | ~/.claude/CLAUDE.md | ~/.codex/AGENTS.md | ~/.gemini/GEMINI.md | 個人用カスタム指示(personal instructions) |
| フォルダ・パスごとの指示 | サブフォルダの CLAUDE.md・.claude/rules/(paths) | サブフォルダの AGENTS.md・AGENTS.override.md | サブフォルダの GEMINI.md(必要時に読み込み) | .github/instructions/*.instructions.md(applyTo) |
| 別ファイルの取り込み | @path | 公式ドキュメントで確認できず | @file.md | 公式ドキュメントで確認できず |
| セッションをまたぐ記憶 | auto memory | Memories | メモリーファイル | Copilot Memory |
GitHub Copilot の指示ファイルは、Copilot cloud agent(旧 coding agent)やコードレビューなどで使われ、対応するファイルの種類は機能や環境ごとに違います(GitHub の対応表)。読み込まれ方にもツールごとの違いがあります。Claude Code と Gemini CLI は、見つかったファイルをつなげて読み込みます。Codex CLI はリポジトリのルートから作業フォルダへ向かって順につなげ、合計が上限(既定 32 KiB、project_doc_max_bytes で変更可)に達するとそれ以上は加えません。長くしすぎないよう注意しましょう。
筆者の現場では:記憶の索引が黙って切り捨てられた
筆者のチームでは、Claude Code の auto memory を使い、作業で学んだことを 1 件 1 ファイルで残しています。ファイルは数百件になり、その入口として索引のファイル(MEMORY.md)を毎回読み込ませています。この索引で 2 つの事故がありました。
1 つ目は、上限を超えた末尾が読まれていなかったことです。索引には読み込みの上限があり、筆者の環境では 200 行を超えた分が末尾から捨てられました。その数日前に自分たちで測り、「上限は行数だけ」と結論していたところ、2026 年 9 月 8 日に 195 行でも「27.2KB (limit: 24.4KB)」という警告が出て、途中の見出しから後ろがまるごと読まれていませんでした。行数とは別に、大きさの上限もあったのです。しかも警告の数字は、日本語の多いファイルでは wc -c のバイト数と一致しませんでした。いまは wc -l(行数)と wc -m(文字数)の両方で確かめ、警告が出たら行数に余裕があっても削っています。
2 つ目は、追記が消えたことです。筆者のチームは複数の端末で記憶のフォルダを同期していますが、同期の方式はファイル単位で「新しい方を残す」ものでした。個別のファイルは名前が違うので問題ありませんが、全端末が書き足す索引は、片方の追記がまるごと上書きされます。2026 年 8 月 26 日に数えたところ、記憶のファイル 337 件に対し、索引から参照されていたのは 193 件で、144 件が索引から漏れていました。
直し方は、索引を「見つけやすくするための付録」と割り切ることでした。大事な事実は必ず個別のファイルに書き、索引には 1 行 1 件の短いリンクだけを置きます。長い行や古い行は、テーマごとの小さな索引ファイルへ移してリンク 1 本にまとめます。そしてエージェントには「索引に無いから記録も無い」と判断せず、フォルダ全体を検索するよう指示ファイルに書いています。
指示ファイルや記憶は、読み込まれて初めて効きます。上限の値はツールや版で変わるので、ファイルが長くなってきたら「どこまで読まれているか」を一度確かめてみてください。
指示ファイルの鍵は次の3点です
- 概要ではなく、そのプロジェクトだけの決まりを書く
研究では、指示ファイルで成功率は概して上がらず、効かなかったのはリポジトリの概要でした。コードを読めば分かることより、独自の規約と確認の手順を書きましょう。 - セキュリティなど品質面の決まりを足す
2,303 ファイルの調査で、セキュリティに触れていたのは 14.8% でした。秘密情報や触らないフォルダの扱いを書き足しましょう。 - 短く保ち、守らせたいことは強制の仕組みへ
指示ファイルはお願いです。長くすると守られにくくなるので定期的に削り、絶対に守らせたいことは権限設定やフックに移しましょう。
まとめ:指示ファイルは「短く・独自の決まりだけ」!
指示ファイルは、毎回同じ説明をする手間を減らしてくれる、いちばん手軽なハーネスの部品です。ただし研究からは、書けば書くほど賢くなるわけではなく、リポジトリの概要より独自の決まりが効くこと、実際のファイルにはセキュリティなどの記述が少ないことが見えてきました。
まずは今ある指示ファイルを開いて、「コードを読めば分かる説明」を削り、「このプロジェクトだけの決まり」と「確認の手順」が書けているかを見直してみましょう! そのうえで、どうしても守らせたいことは、お願いではなく仕組みで守らせる番です(第 4 回)。
次回は、エージェントに「どこまで許すか」を決める権限モードとサンドボックスを扱います。シリーズの一覧は /?p=209 へ。
参考文献
- AGENTS.md「AGENTS.md」(https://agents.md/)2026-10-01 確認
- Anthropic「How Claude remembers your project」Claude Code Docs(https://code.claude.com/docs/en/memory)2026-10-01 確認
- OpenAI「Custom instructions with AGENTS.md」Codex ドキュメント(https://learn.chatgpt.com/docs/agent-configuration/agents-md)2026-10-01 確認
- OpenAI「Memories」Codex ドキュメント(https://learn.chatgpt.com/docs/customization/memories)2026-10-01 確認
- Google「Provide context with GEMINI.md files」Gemini CLI ドキュメント(https://geminicli.com/docs/cli/gemini-md/)2026-10-01 確認
- Google「Memory files」Gemini CLI ドキュメント(https://geminicli.com/docs/tools/memory/)2026-10-01 確認
- GitHub「Adding repository custom instructions for GitHub Copilot」GitHub Docs(https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions)2026-10-01 確認
- GitHub「Support for different types of custom instructions」GitHub Docs(https://docs.github.com/en/copilot/reference/custom-instructions-support)2026-10-01 確認
- GitHub「About GitHub Copilot Memory」GitHub Docs(https://docs.github.com/en/copilot/concepts/agents/copilot-memory)2026-10-01 確認
- Thibaud Gloaguen ほか「Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?」arXiv:2602.11988(https://arxiv.org/abs/2602.11988)2026-10-01 確認
- Jai Lal Lulla ほか「On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents」arXiv:2601.20404(https://arxiv.org/abs/2601.20404)2026-10-01 確認
- Worawalan Chatlatanagulchai ほか「Agent READMEs: An Empirical Study of Context Files for Agentic Coding」arXiv:2511.12884(https://arxiv.org/abs/2511.12884)2026-10-01 確認

