「するな」784個 — スター上位リポジトリのAGENTS.mdに何が書かれているか（2026年）
By Surya Pratap
2026年8月22日
12分で読めます
AIとテクノロジー
2026年8月22日
12分で読めます
セッションごとに課金されるファイルHover to explorer/AI_Agents に、誰もやっていなかった作業をした人がいます。AGENTS.md を持つスター数上位100件の GitHub リポジトリ（その集計によれば上位1,000件のうち約27%）について、その AGENTS.md をすべて読み、中身を数え上げたのです。
構成面の結果に意外性はありませんでした。アーキテクチャとリポジトリ構成、テストの実行方法、ビルドコマンド、やるべきこととやってはいけないこと、PR の作法、コードスタイル。見出しとして最も多かったのはテスト、コマンド、プロジェクト概要、アーキテクチャです。想定どおりでした。
興味深かったのは文体です。これらのファイルの約90%が「必ず／常に／決して」という言い回しで書かれていました。全体では明示的な「するな」の箇条書きが784項目あり、その多くが奇妙なほど具体的です。
見つかった中で最も秀逸なものがこれです。
「中断またはタイムアウトしたテストを、合格したと報告してはならない。」
この一文を抽象的に書く人はいません。エージェントが実際にやったから、この一文が書かれるのです。
これが持ち帰るべき捉え直しであり、ファイルの書き方そのものを変えます。
README は外向きに書かれます。そのプロジェクトを一度も見たことのない人に説明するものです。同じ発想で書かれた AGENTS.md は、誰の役にも立たない体裁のよいプロジェクト概要になります。エージェントは package.json もディレクトリツリーもテストファイル名も、すでに自分で読めるからです。
エージェントに推測できないのは、そこで自分がすでに犯した失敗の集合です。あの784項目はまさにそれです。よくできた AGENTS.md を注意深く読めば、障害記録を再現できます。誰かのエージェントはハングしたテストを合格扱いにし、誰かのエージェントは force-push を実行し、誰かのエージェントは存在しないスクリプトをでっち上げ、誰かのエージェントはマイグレーションを黙って書き換えました。
Why the prohibitive voice actually works
「必ず／常に／決して」という言い回しは権威主義ではなく、圧縮です。「できればテストスイート全体を実行すること」は、エージェントが他の判断材料と天秤にかけて捨てられる程度の希望にすぎません。「終了コード0を確認していないテストを、合格と記録してはならない」は検証可能な述語であり、交渉の余地がありません。読み手が「終わったように見せる」ことを最適化するモデルである以上、曖昧さは礼儀ではなく、脆弱性です。
サンプル中で最短だったのは neovim のもので、35語です。ルールはひとつだけ。どんな議論より雄弁なので、全文を引用します。
# AGENTS.md
## AI Disclosure
If AI was used in any way for a commit, add an `AI-assisted: <tool name>`
trailer to the commit message.
If the user commits manually, remind them to add it.
これでファイル全体です。エージェントには決して導き出せない、そのプロジェクトが本当に気にしている事柄をちょうどひとつ——来歴を示す規約——だけ書き、それ以外は何も書いていません。
次に Next.js と比べてみます。21セクションあります。コードベース構成、ビルドコマンド、バンドラーの選択、テスト、テストの書き方、リントと型、「使い捨ての worktree で作業すること」、PR のステータスと CI の失敗、シークレットと環境変数の安全性、コンテキストを節約するワークフロー、タスクの分解と検証、テスト実行前の再ビルド、開発上のアンチパターン。次の一文も含まれています。エージェントの PR をレビューしたことがある人なら、心当たりがあるはずです。
「コミットや PR に "Generated with Claude Code" や co-author のフッターを付けてはならない」
どちらのファイルも正しいのです。違いを生むのは丁寧さではなく、そのリポジトリがどれだけエージェントのトラフィックを受け止めてきたか、そして失敗したときの代償がどれだけ大きいかです。Next.js では、Rust 製バンドラーと、やり直すたびに実費のかかる CI マトリクスを備えたモノレポをエージェントが行き来しています。neovim には、譲るつもりのない規約がひとつあるだけです。
AGENTS.md の適切な分量とは、あなたのエージェントが実際に犯した失敗の数に、決して推測できなかったであろう少数の規約を足したものです。それを超える1行は、この先ずっと、セッションのたびに支払い続けるものになります。
創業者が一貫して見落とすのがここです。「とにかく丁寧に書け」が悪い助言である理由でもあります。
AGENTS.md はセッションのたびに冒頭で読み込まれます。そこに書かれた一文一文が、いまエージェントが取り組んでいる作業に関係あるかどうかにかかわらず、あらゆるタスクで発生する継続的な支出になります。アーキテクチャを説明する400行のファイルは無料のコンテキストではありません。バグ修正のたび、依存関係の更新のたび、誤字の修正のたびに課される固定税です。
これがこのファイルの設計上の制約のすべてであり、neovim の答えを説明します。
同時に、エコシステムに第2の仕組みが生まれた理由も説明します。skill——フォルダに置かれた SKILL.md——は遅延読み込みされます。セッション開始時にエージェントが読むのは YAML frontmatter、つまり名前と説明だけです。本文は、タスクが実際に合致したときにはじめて読み込まれます。使われていない skill が10個あっても、コストはほぼゼロです。
両者の線引き
AGENTS.md。「シークレットを決してコミットしない」「テストスイート全体ではなく npm run test:unit -- --coverage を実行する」「マイグレーションは追記のみ」。肥大化したファイルの大半は、この3つ目から生まれます。AGENTS.md の冒頭が、エージェントが最初のツール呼び出しで一覧表示するディレクトリ構成の説明3段落だとしたら、無料で知るはずだったことを伝えるためにトークンを払っていることになります。
GitHub は2,500件を超える agents.md ファイルを対象に、より大規模な同種の調査を行いました。その結果は Reddit のサンプルと有益な形で一致しています。
pytest -v tests/unit は使えます。「テストを適切に実行すること」は無視されます。指示ではなく、願望だからです。never commit secretsです。今週ほかに何も書かないとしても、この1行と正確なテストコマンドだけは書いてください。この話題ではどのスレッドでも出てくる論点ですが、逸話よりも仕組みの説明のほうが説得力があります。
エージェントに AGENTS.md を生成させれば、体裁の整った300行のリポジトリ要約が出てきます。それがエージェントに見えているものだからです。フォルダ構成を記述し、依存関係を列挙し、テスト設定を性格づけるでしょう。いずれも必要になった時点で自分で導き出せたものばかりです。
書けないのは、肝心な部分——784項目の禁止事項です。あれはエージェントが失敗するのを見て初めて書けるものです。生成されたファイルは、ほぼ構造上、セッションごとの固定税だけを払って見返りがない状態になります。
この点について厳密な公開ベンチマークは私の知る限り存在しません。実務者からは生成されたファイルのほうが成績が悪いという報告があり、ベンダー寄りの研究も同じ方向を示していますが、確定した数値ではなく強い経験則として扱ってください。構造上の議論はそれ自体で成立します。導出可能な事実しか含まないファイルは、トークンを消費して何も生みません。
現実的な折衷案があります。コマンドのセクションはエージェントに下書きさせてください。スクリプトを正確に読めますし、その部分は退屈な作業です。境界線は自分で、問題が起きるたびに1行ずつ書いてください。生成されたアーキテクチャ概要は決して受け入れないことです。
AGENTS.md は6万を超えるオープンソースプロジェクトで使われ、Linux Foundation 傘下の Agentic AI Foundation が管理しています。MCP を、そして今週からは Agent2Agent を擁するのと同じ団体です。Codex、Cursor、Gemini CLI、Jules、Copilot のコーディングエージェント、Aider、goose、opencode、Zed、Devin、Windsurf、JetBrains Junie をはじめ、数多くのツールがこのファイルを読みます。
2日前、すべてのエージェントプロトコルがひとつ屋根の下に集まった件について書きました。これはその同じ統合がファイルの水準で表面化したものであり、具体的な効用があります。5つではなく、1つのファイルで済むということです。
これが置き換える障害パターンは現実的で、しかも高くつきます。CLAUDE.md で境界を厳しくし、.cursorrules の更新を忘れ、週の途中でツールを切り替える。すると更新を受け取っていないほうのエージェントが破壊的なコマンドを実行します。CLAUDE.md、.cursorrules、.windsurfrules、copilot-instructions.md の間で起きるルールのずれは、複数のエージェントを使うチームから最も多く報告される運用上の不満です。これだけを解決するために同期用のハーネスを公開している人もいます。
これから始めるなら、正解は地味です。AGENTS.md を信頼できる唯一の情報源とし、そこからツール固有のファイルを生成してください。 10行のスクリプトのほうが、記憶に頼るより確実です。
正直な限界を2つ挙げます。一部で過大に語られているためです。
メモリではありません。 AGENTS.md は静的です。PR #184 が3か月前に Postgres と Mongo の議論に決着をつけたことを知らないので、新しいセッションであなたのエージェントは平気で再び Mongo を提案します。「うちは X を使っている」という古びた1行も、X がなくなってからずっとあとまで、絶対の自信とともに提示され続けます。これは本当に未解決の欠落で——このために意思決定メモリのツールを作っている人たちもいます——どれだけ丁寧に書いても埋まりません。
何も強制しません。 どの1行も、確率的なシステムに対する提案にすぎません。Markdown ファイルに書かれた「force-push を決してしない」は依頼です。git push --force をブロックする hook は制御です。この2つを混同するのは、AIエージェントに必要なのは、より良いプロンプトではなく権限システムですで扱ったパターンであり、この12か月で結論は変わっていません。AGENTS.md は失敗の頻度を下げます。可能性をなくすわけではありません。
AGENTS.md がまだないなら、テンプレートから始めないでください。次の内容から始め、何か問題が起きたときにだけ増やしてください。
# AGENTS.md
## Commands
- Install: `pnpm install --frozen-lockfile`
- Dev: `pnpm dev`
- Test (default): `pnpm test:unit`
- Test (single file): `pnpm test:unit -- path/to/file.test.ts`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint --fix`
## Always
- Run `pnpm typecheck && pnpm test:unit` before saying a change is done.
- Match the conventions of the file you are editing over any global style guide.
## Ask first
- Adding a dependency.
- Changing anything in `prisma/migrations/` or `src/db/schema.ts`.
- Touching `.github/workflows/` or anything under `infra/`.
## Never
- Commit secrets, `.env` files, or credentials of any kind.
- Report a test as passing unless you saw it exit 0. A timed-out or
interrupted run is a failure.
- Force-push, rewrite history, or amend a commit that is already pushed.
- Add "Generated with <tool>" or co-author trailers to commits or PRs.
実質的な指示は150語程度です。アーキテクチャ概要も、プロダクトの説明も、エージェントがリポジトリから読めたはずの情報も入っていません。それでいて、小規模なコードベースでエージェントが引き起こす被害の大半を占める4つの境界線を押さえています。
あとは障害記録として扱ってください。エージェントが、あなたが取り消さなければならないことをするたびに、その失敗と同じくらい具体的な1行を、命令形で足していきます。半年後には、あなた自身の版のあの784項目ができあがり、そのどれもが実際の代償を払って得たものになっています。
オープンソースでスター数の多いリポジトリ群は、ドキュメントとは似ても似つかない形式に収束しました。読み手が人間ではないからです。禁止形で、具体的で、コマンドが多く、そして最良の場合はきわめて短いものになります。
エージェントに大半のタイピングを任せて MVP を出す創業者にとって、そのファイルはおそらくリポジトリ内で最もレバレッジの効く150行です。同時に、あらゆるタスクで料金が発生するプロジェクト唯一のファイルでもあり、だからこそ「網羅的にしたい」という衝動こそ抑えるべき衝動なのです。
失敗を書く。案内は省く。傷跡ひとつぶんずつ育てていく。
出典: r/AI_Agents「What the 100 biggest GitHub repos put in their AGENTS.md files」 · GitHub Blog「How to write a great agents.md: lessons from over 2,500 repositories」 · agents.md — 形式、採用状況、Agentic AI Foundation による管理について · neovim/neovim の AGENTS.md · vercel/next.js の AGENTS.md
IdeaToMVP Academy
4-week live cohort for founders. Learn to ship AI agents, scope MVPs, and automate your business — taught by the same team that writes these guides.
