AI向けの手引き（AGENTS.md）：短く、正しく、役に立つ書き方

プロジェクトでAIエージェントと働くすべての人に向けた内容で、初心者も含みます。用語には必ず日常の例による説明を添えています。

数字は末尾に挙げた公開の研究や記事によります。主な2つの研究は独立した確認を受けておらず、このテーマの研究はとても新しいものです。「このプロジェクトから」と書いた例は、このブログ自身のリポジトリの実データです。

---

要点#

• AGENTS.md（同じ考えの別名がCLAUDE.md）は、プロジェクトの中にあるテキストファイルで、AIが自分では見抜けないことを伝えます。チームに新しく入った人の机の上のノートのようなものです。
• 効果は食い違っています。ある研究では、AIが速く動き、トークンも減りました。別の研究では、手順も費用も増えました。どちらかを信じず、自分で測ってください。
• そこから出てくる原則：短く、人が書き、コードから読み取れないことだけ。
• 入れる価値のある6つの項目：コマンド、全体像、決まり、間違えやすい点、禁止事項、「完成とは何か」。
• このファイルは生きた文書です。AIが間違いを繰り返したら1行足し、古くなったら1行消します。
• 安全面：秘密情報は貼らず、知らないリポジトリではこのファイルを丁寧に読むこと。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つの方向を向いています。

2つの研究は、違う課題で違うものを測っているので、どちらも最終的な答えとは言えません。私は要約を読んだだけで、2つの原論文を詳しくは読んでいません。

仕事での安全な読み方：

1. コンテキストファイルは費用がかかりうる。 ファイルの各行は、作業のたびに読まれます。余計な行は本当の費用です。
2. 人が書いたもののほうが、AIが生成したものより良さそう。 出発点のファイルはツール（たとえば/initコマンド）で作り、手で刈り込みます。
3. 前後で測る。 同じ作業をファイルありとなしで走らせ、時間、修正の回転数、不具合を比べます。記録の付け方は実際のプロジェクトでAIエージェントと働いた3時間にあります。

---

3. 何を書き、何を書かないか#

1行ごとに使うふるい：AIはこれをコードから見抜けるか？ 見抜けるなら書きません。見抜けず、重要なら書きます。

紹介文ではなく、短い命令文で書きます。「このプロジェクトにはかなり充実したテストがある」より、「完了と言う前に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があります。構成は次のとおりです。

ファイルに入れていないもの：すべての記事の一覧、Markdownの文法の説明、手引きの詳しい内容（それらは別のファイルにあり、主ファイルは指すだけです）。

詳しい内容は、専用のフォルダにある4つの手引きファイル（合計327行）に分けてあり、AIは作業が関連するときだけ読みます。この分け方が主ファイルを短く保ちます。それらのファイルの多くの行は、実際に起きた不具合から生まれました。たとえば「マスコットにはoverflow: visibleが必要」や「表示されるすべての文字は翻訳の仕組みを通すこと」で、まさに7章のループです。

---

6. 前後の例#

あいまいな行

きれいなコードを書き、ベストプラクティスに従う。

AIはすでにそうしようとしているので、この行はトークンを使うだけです。

具体的な行

表示される文字はsite/i18n.mjsにあり、常にvi、en、jaの3言語がそろう。テンプレートに文字を直接書かない。

この行は、場所、理由、間違えたときの結果を示しています。

理由つきの禁止事項

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を鵜呑みにしてはいけない理由のReplitの件を参照）。

---

9. コピーできる雛形#

自分のプロジェクトに合わせて刈り込みます。1ページ未満に保ちます。

# プロジェクト：<名前>

## 何か
<2文：何をするか、何を使うか、覚えておくべき意図的な選択>

## コマンド
- インストール：<コマンド>
- 実行：<コマンド>
- すべてのテスト：<コマンド>
- 1つのテストファイル：<コマンド>
- 完了と言う前の確認：<コマンド>

## 全体像
<1、2段落：主な部分とそのつながり>

## 決まり
- <命名>
- <表示される文字の言語>
- <エラー処理>

## 間違えやすい点
- <過去に間違えたことと正しいやり方、理由つき>

## 禁止事項
- 聞かずに<操作>をしない。理由は<理由>

## 完成とは何か
- テストがあり、<確認コマンド>を走らせ、差分を読み直した

---

10. バランスの取れた見方#

これらのファイルの効果を示す根拠は薄く、食い違っているので、魔法のように扱わないでください。長い、急いで書いた、あるいはAIが生成して刈り込んでいないファイルは、AIを遅く、高くするかもしれません。短く、人が書き、実際の不具合から更新されるファイルは役に立ちそうですが、自分のプロジェクトで確かめてください。

より確かなのは、別の利点です。このファイルは、誰もが暗黙に分かっていることを、チームに書き出させます。その行は新しく入った人も助け、チームが共通の決定をそろえる場にもなります。AI時代のITチームの働き方のとおりです。ファイルは、不具合を1つずつ学びに変える場所でもあり、これはAIが書いたコードのレビューが項目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の概説、InfoQ
• Lullaら、On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents
• Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
• コミュニティによるCLAUDE.mdの書き方ガイド：DataCamp（ベンダーの公式ドキュメントではありません）
• このプロジェクト自身のデータ：リポジトリのCLAUDE.mdファイルと.claude/skills/フォルダ