--- title: "AI向けの手引き（AGENTS.md）：短く、正しく、役に立つ書き方" url: https://www.thinnd.site/ja/gijutsu/agents-md-no-kakikata/ language: ja author: "Nhu Duy Thin (Thinnd)" published: 2026-10-29 updated: 2026-10-29 section: "エンジニアリング" tags: ["AGENTS.md", "CLAUDE.md", "コンテキストエンジニアリング", "AIエージェント", "ガイド"] summary: "AGENTS.mdは、AIエージェントが自分では見抜けないこと（コマンド、全体像、決まり、禁止事項）を伝える、プロジェクト内のテキストファイルです。効果については2つの研究が食い違うので、短く、人が書き、コードから読み取れないことだけを書き、前後で測ってください。" license: "Cite with the author name and the canonical URL above." --- # AI向けの手引き（AGENTS.md）：短く、正しく、役に立つ書き方 > プロジェクトでAIエージェントと働くすべての人に向けた内容で、初心者も含みます。用語には必ず日常の例による説明を添えています。 > > 数字は末尾に挙げた公開の研究や記事によります。主な2つの研究は独立した確認を受けておらず、このテーマの研究はとても新しいものです。「このプロジェクトから」と書いた例は、このブログ自身のリポジトリの実データです。 --- ## 要点 - **AGENTS.md**（同じ考えの別名がCLAUDE.md）は、プロジェクトの中にあるテキストファイルで、**AIが自分では見抜けないことを伝えます**。チームに新しく入った人の机の上のノートのようなものです。 - 効果は**食い違っています**。ある研究では、AIが速く動き、トークンも減りました。別の研究では、手順も費用も増えました。どちらかを信じず、**自分で測ってください**。 - そこから出てくる原則：**短く、人が書き、コードから読み取れないことだけ**。 - 入れる価値のある6つの項目：コマンド、全体像、決まり、間違えやすい点、禁止事項、「完成とは何か」。 - このファイルは**生きた文書**です。AIが間違いを繰り返したら1行足し、古くなったら1行消します。 - 安全面：秘密情報は貼らず、**知らないリポジトリではこのファイルを丁寧に読む**こと。AIが従うからです。 --- ## むずかしい言葉をやさしく | 用語 | やさしい意味 | |---|---| | **AGENTS.md** | プロジェクトについてAIに伝えるファイルで、オープンな形式。「AI向けのREADME」とイメージできる。 | | **CLAUDE.md** | Claude Codeが読む、よく似たファイル。ツールごとに別々の名前があった。 | | **コンテキストファイル** | この種のファイルの総称。AIが作業を始める前に読めるもの。 | | **エージェント** | 答えるだけでなく、プロジェクトを読み、何か所も直し、試すAI。 | | **プロンプトインジェクション** | 文章に指示を紛れ込ませ、利用者ではなく紛れ込ませた側の意図にAIを従わせること。 | | **トークン** | AIが読み書きする文字のかけら。多いほど時間とお金がかかる。 | --- ## 1. AGENTS.mdとは何か、なぜ名前がいくつもあるのか AIエージェントは、仕事を始めるたびに**あなたのプロジェクトについて何も覚えていません**。コードを読み直し、動かし方を推測し、決まりを推測しなければなりません。それらを記したファイルがあれば推測の手間が省けます。新しい同僚にノートを渡すようなものです。 公開されている記事によると、AGENTS.mdの考えは2025年5月ごろに生まれました。ツールごとにCLAUDE.mdやGEMINI.mdなど別々のファイルを読むことに、開発者が不満を述べたためです。AGENTS.mdは共通の名前を提案しています。ある報告によると、この形式は現在、Linux Foundationのもとにある Agentic AI Foundationが管理しています（弱い情報源なので、再確認してください）。複数の情報源が、GitHubで2万を超えるリポジトリが使っていると伝え、対応が最もはっきり名指しされているツールはCodexです。他のツールそれぞれを確認できる情報源は見つからなかったので、すべてのツールがAGENTS.mdという名前を読むと思い込まないでください。 実際の対応：使うツールが別の名前を読むなら、その名前を使います（このプロジェクトはCLAUDE.mdを使っています）。または、AGENTS.mdを作り、ツールにそれを指すようにします。 --- ## 2. 本当に役に立つのか 新しい2つの研究が、2つの方向を向いています。 | | Lullaら（arXiv、2026年） | 「Evaluating AGENTS.md」（arXiv、2026年） | |---|---|---| | 規模 | 10のリポジトリ、実際の124のPR | 4つのエージェント、SWE-benchと新しいCTXBENCH | | 比較 | 同じ作業をAGENTS.mdありとなしで | コンテキストファイルありとなし | | 主な結果 | AGENTS.mdあり：実行時間の中央値が約28.6%、出力トークンが約16.6%減、完了の水準は同程度 | コンテキストファイルが費用と手順の数を増やした。成功率の変化は小さく、AIが生成したファイルはわずかに悪く、人が書いたファイルはわずかに良い | | 著者自身の注意 | 最初の一歩であり、結論ではない | 成功の差は小さく、統計的に有意ではない | 2つの研究は、違う課題で違うものを測っているので、どちらも最終的な答えとは言えません。私は要約を読んだだけで、2つの原論文を詳しくは読んでいません。 仕事での安全な読み方： 1. **コンテキストファイルは費用がかかりうる。** ファイルの各行は、作業のたびに読まれます。余計な行は本当の費用です。 2. **人が書いたもののほうが、AIが生成したものより良さそう。** 出発点のファイルはツール（たとえば`/init`コマンド）で作り、**手で刈り込みます**。 3. **前後で測る。** 同じ作業をファイルありとなしで走らせ、時間、修正の回転数、不具合を比べます。記録の付け方は[実際のプロジェクトでAIエージェントと働いた3時間](https://www.thinnd.site/ja/genba-noto/ai-agent-jissai-no-purojekuto-nikki/)にあります。 --- ## 3. 何を書き、何を書かないか 1行ごとに使うふるい：**AIはこれをコードから見抜けるか？** 見抜けるなら書きません。見抜けず、重要なら書きます。 | AIが見抜ける。書かない | AIが見抜けない。書く | |---|---| | 「プロジェクトはJavaScriptを使う」（ファイルを見れば分かる） | 正しいテストのコマンド（たとえば`npm run check`）と、それが何を走らせるか | | 「きれいで読みやすいコードを書く」 | 「利用者向けのメッセージはベトナム語、関数名は英語」 | | すべてのファイルとフォルダの一覧 | 多くのファイルを読まないと見えない全体像 | | フレームワークの文法の説明 | 意図的な決定：「XではなくYを使う。理由はZ」 | | APIのドキュメント全体 | 間違えやすい点：「ビルドの出力はdist/にあり、手で編集しない」 | | 一般的な助言 | 禁止事項：「レビュー担当なしでpaymentsフォルダを編集しない」 | 紹介文ではなく、**短い命令文**で書きます。「このプロジェクトにはかなり充実したテストがある」より、「完了と言う前に`npm test`を走らせる」のほうがよいのです。 --- ## 4. 入れたい6つの項目 1. **コマンド。** インストール、実行、ビルド、テスト、確認。**1つの**テストだけを走らせるコマンドも書きます。AIは1つだけ走らせたいことがよくあるからです。 2. **全体像。** 各部分がどうつながり、なぜそうなっているかの1、2段落。多くのファイルを読まないと分からないことです。 3. **決まり。** 命名、表示される文字の言語、エラー処理、コミットの書き方。 4. **間違えやすい点。** 過去に起きた誤り。繰り返した間違いごとに1行。 5. **禁止事項。** 聞かずに触ってはいけないフォルダ、コマンド、操作。 6. **完成とは何か。** 完了を報告する条件：テストがある、確認を走らせた、画面の写真がある。 どれも長くする必要はありません。目的は、1分で流し読みする読み手にも伝わることです。 --- ## 5. 実例：このプロジェクトのCLAUDE.md このブログのプロジェクトには、**49行、5項目**、約5 KBのCLAUDE.mdがあります。構成は次のとおりです。 | 項目 | 内容 | 入れた理由 | |---|---|---| | What this is | 2文：Markdownのブログ、手書きのページ生成器、依存は2つだけ | AIが規模をすぐ知り、フレームワークの追加を提案しないように | | Commands | `npm run dev`、`build`、`seo`、`check`、`og`のコマンドと環境変数 | 正しいコマンド、推測なし | | Architecture | `site/`の各主要ファイルの役割とつながり | 多くのファイルを読まないと見えない | | Content model | ファイル名、言語、frontmatter、パスの規則 | 記事を足すとき最も間違えやすい場所 | | Project skills | 4つの専用の手引きの一覧と使うべき場面 | AIが使うのを忘れないように | ファイルに**入れていないもの**：すべての記事の一覧、Markdownの文法の説明、手引きの詳しい内容（それらは別のファイルにあり、主ファイルは指すだけです）。 詳しい内容は、専用のフォルダにある4つの手引きファイル（合計327行）に分けてあり、AIは作業が関連するときだけ読みます。この分け方が主ファイルを短く保ちます。それらのファイルの多くの行は、実際に起きた不具合から生まれました。たとえば「マスコットには`overflow: visible`が必要」や「表示されるすべての文字は翻訳の仕組みを通すこと」で、まさに7章のループです。 --- ## 6. 前後の例 **あいまいな行** ```text きれいなコードを書き、ベストプラクティスに従う。 ``` AIはすでにそうしようとしているので、この行はトークンを使うだけです。 **具体的な行** ```text 表示される文字はsite/i18n.mjsにあり、常にvi、en、jaの3言語がそろう。テンプレートに文字を直接書かない。 ``` この行は、場所、理由、間違えたときの結果を示しています。 **理由つきの禁止事項** ```text dist/フォルダを手で編集しない。npm run buildのたびに再生成され、変更はすべて消える。 ``` 理由があれば、AIは規則の趣旨を似たケースにも当てはめられます。 --- ## 7. ファイルを正しく保つ 誰も手入れしないと、このファイルは時間とともに劣化します。小さなループ： 1. **AIが同じ間違いを2回目に繰り返したら、1行足す。** 間違いの名前だけでなく、何をすべきかと理由を書きます。 2. **行が古くなったら消す。** コマンドが変わった、フォルダが移った、規則をやめた。 3. **一度も役に立たない行は消す。** 外して、AIが間違えるかを見ます。 4. **ファイルの変更をコードと同じようにレビューする。** AIのすべての作業に影響します。 5. **四半期ごとに最初から読み直す。** すばやく流し読みできなければ、長くなりすぎています。 短く保つ2つの習慣：詳細を別ファイルに分けて指すだけにする（多くのツールは、あるファイルから別のファイルを取り込めます）。個人の好みは、リポジトリに入れない別ファイルに置く（ツールによっては、CLAUDE.local.mdのような名前を勧め、gitの無視リストに入れます）。 --- ## 8. 安全 - **ファイルに秘密情報を貼らない。** 鍵、パスワード、社内のアドレス。このファイルはリポジトリにあり、作業のたびにモデルに送られます。 - **知らないリポジトリでは、このファイルを読む。** AIは内容に従うので、他人が書いたファイルには、あなたが望まないことをAIにさせる行が入っているかもしれません。これはこの種のファイルの働き方からの推論で、私が確認した特定の出来事に基づくものではありません。信用していないリポジトリでエージェントを動かす前に、ファイルを開いて読んでください。 - **権限は別の場所で絞る。** このファイルを柵だと期待しないでください。文章での指示は本当の権限の代わりになりません（[AIを鵜呑みにしてはいけない理由](https://www.thinnd.site/ja/gijutsu/ai-wo-unomi-ni-shinai-riyu/)のReplitの件を参照）。 --- ## 9. コピーできる雛形 自分のプロジェクトに合わせて刈り込みます。1ページ未満に保ちます。 ```text # プロジェクト：<名前> ## 何か <2文：何をするか、何を使うか、覚えておくべき意図的な選択> ## コマンド - インストール：<コマンド> - 実行：<コマンド> - すべてのテスト：<コマンド> - 1つのテストファイル：<コマンド> - 完了と言う前の確認：<コマンド> ## 全体像 <1、2段落：主な部分とそのつながり> ## 決まり - <命名> - <表示される文字の言語> - <エラー処理> ## 間違えやすい点 - <過去に間違えたことと正しいやり方、理由つき> ## 禁止事項 - 聞かずに<操作>をしない。理由は<理由> ## 完成とは何か - テストがあり、<確認コマンド>を走らせ、差分を読み直した ``` --- ## 10. バランスの取れた見方 これらのファイルの効果を示す根拠は薄く、食い違っているので、**魔法のように扱わないでください**。長い、急いで書いた、あるいはAIが生成して刈り込んでいないファイルは、AIを遅く、高くするかもしれません。短く、人が書き、実際の不具合から更新されるファイルは役に立ちそうですが、自分のプロジェクトで確かめてください。 より確かなのは、別の利点です。このファイルは、**誰もが暗黙に分かっていることを、チームに書き出させます**。その行は新しく入った人も助け、チームが共通の決定をそろえる場にもなります。[AI時代のITチームの働き方](https://www.thinnd.site/ja/keiken/ai-jidai-no-chimu-no-hataraki-kata/)のとおりです。ファイルは、不具合を1つずつ学びに変える場所でもあり、これは[AIが書いたコードのレビュー](https://www.thinnd.site/ja/gijutsu/ai-ga-kaita-code-no-review/)が項目14（プロジェクトの決まりに従う）と呼ぶものです。 --- ## 11. かんたんチェックリスト 1. ファイルは1ページ未満で、1分で流し読みできるか？ 2. 各行は「AIはこれを自分で見抜けるか」に答えられるか？ 3. 1つのテストのコマンドと、最後の確認コマンドがあるか？ 4. 禁止事項のそれぞれに理由があるか？ 5. ファイルに秘密情報がないか？ 6. 繰り返した間違いを記録する場所があるか？ 7. 最後に古い行を消したのはいつか？ 8. ファイルありとなしで1つの作業を走らせて比べたか？ --- ## 12. 結論 AIエージェントは、毎回の作業を空の記憶から始めます。短く、正確で、手入れされた手引きは、推測の手間を省き、チームの人が同じ方向を見る助けになります。ただし効果は確実には証明されていないので、小さな実験として扱いましょう。短く書き、前後で測り、間違いが繰り返されるたびに1行足し、不要になるたびに1行消します。 3つから始めます。コマンド、全体像の1段落、そして理由つきの禁止事項1つ。1週間後、実際に出会った間違いから生まれた行を足します。 --- ## 参考資料 数字は2026年10月時点の公開情報によります。多くの出典は紹介記事で、このテーマの研究は新しいものです。引用する前に原典を開いて確認してください。 - AGENTS.md：[Socket.devの概説](https://socket.dev/blog/agents-md-gains-traction-as-an-open-format-for-ai-coding-agents)、[InfoQ](https://infoq.com/news/2025/08/agents-md/) - Lullaら、[On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404) - [Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?](https://arxiv.org/pdf/2602.11988) - コミュニティによるCLAUDE.mdの書き方ガイド：[DataCamp](https://www.datacamp.com/tutorial/writing-the-best-claude-md)（ベンダーの公式ドキュメントではありません） - このプロジェクト自身のデータ：リポジトリのCLAUDE.mdファイルと`.claude/skills/`フォルダ