AGENTS.md は2026年に GitHub 上で60,000以上のリポジトリを突破した。このスケールは貴重なものを提供する: 何が効いて何が効かないかの大規模で多様なデータセットだ。n8n（178Kスター）、awesome-go（167Kスター）、LangFlow（145Kスター）などのプロジェクトは数ヶ月の実際の AI エージェント使用を経て AGENTS.md を洗練させてきた。
このガイドはそれらのリポジトリが収束したものを蒸留する。フォーマットの基礎ではなく——それは AGENTS.md vs CLAUDE.md 比較記事 で確認できる——高パフォーマンスな AGENTS.md を陳腐な情報が蓄積するファイルと差別化する設計原則と運用パターンだ。
根本的な設計の問い
すべての AGENTS.md の判断は一つの問いに帰着する: これを AI エージェントのために書いているのか、開発者のために書いているのか。
答えは両方だ。そしてほとんどの AGENTS.md の失敗は、片方だけに最適化することから生じる。
AI に最適化しすぎ: 密度が高く包括的で技術的に正確な指示。エージェントの挙動には最高。開発者のメンテナンスには最悪。誰も読まないテキストの壁は誰も更新しない。3ヶ月で事実として間違いになる。AGENTS.md で GitHub Copilot を使う場合のトークン効率問題は AGENTS.md × GitHub Copilot 完全ガイド に実測データがある。
開発者の可読性に最適化しすぎ: クリーンで読みやすいプロジェクト概要。人間のオンボーディングには最高。エージェントには無意味——エージェントはプロジェクトの哲学ではなく、具体的で実行可能な指示を必要とする。
最良の AGENTS.md は適切に構造化された運用ランブックのように読める: 人間がメンテナンスしやすく整理され、機械が行動できるだけ具体的。
パターン1: コンテキストより先にコマンド
高パフォーマンスなすべての AGENTS.md はコマンドから始まる。プロジェクトが何をするかの段落ではなく——コマンドだ。
# AGENTS.md
## Commands
```bash
# インストール
npm ci
# 開発
npm run dev # :3000 で dev サーバー起動
npm run dev:api # :4000 で API サーバー起動
# テスト
npm test # ユニットテスト（Jest）
npm run test:e2e # E2E テスト（Playwright、dev:api 起動必要）
npm run test:watch # ユニットテストのウォッチモード
# 品質
npm run lint # ESLint
npm run typecheck # TypeScript コンパイラチェック
# ビルド
npm run build # 本番ビルド
箇条書きではなくコードブロックを使う理由は？コードブロックは曖昧さがない。箇条書きの「npm run test」は散文として解釈されうる。コードブロック内ではリテラルコマンドだ。
n8n の AGENTS.md はこれをさらに発展させ、環境別のバリエーションを含む: Docker Compose vs. ローカルセットアップ、CI コマンド vs. dev コマンド。Claude が Docker 環境かローカルかを確信できない場合、両方のオプションが用意されている。
## パターン2: 懐疑的なエージェントのために書く
エージェントは愚かではないが、文字通りに解釈する。推論に依存する指示は、明示的に述べる指示より頻繁に失敗する。
**効果のない例:**
```markdown
既存のテストパターンに従う。効果のある例:
## Testing
テストはソースファイル横の `__tests__/` に、`[filename].test.ts` として配置する。
TypeScript に ts-jest を使った Jest。テストランナーのインストール不要。
テスト構造:
- `describe('[ComponentName]', () => {` でグループ化
- `it('should [期待される挙動] when [条件]', () => {` でテスト名
- テストデータには `__tests__/factories/` の `factory` 関数を使う — ID をハードコードしない
単一テスト実行: `npx jest --testPathPattern="path/to/file.test"`2番目のバージョンは、テストの場所・命名規則・テストデータの構成方法・イテレーションのための単一テスト実行方法をエージェントに伝える。1番目は周りを見回して判断するようにエージェントに伝える。
パターン3: 理由付きのスコープ境界
高パフォーマンスなリポジトリで最も普遍的に実践されているパターン: 明示的な境界と、各境界が存在する理由の簡単な説明。
## Boundaries
### 変更しない
- `src/generated/` — protobuf が生成、再生成は `make generate`
- `migrations/` — 新規作成は `make migration name=<説明>`
- `Makefile` — ビルドシステム、変更にはチームレビューが必要
- `.github/workflows/` — CI パイプライン、変更には人間のレビューが必要
### 削除しない
- `*.lock` ファイル — 依存関係更新時は必ず lockfile の変更もコミット
- `docs/api/` — コードから自動生成、ビルド時に再生成される
### 明示的な承認が必要
- 新しい npm/Go/Python 依存関係の追加
- テスト設定の変更
- データベーススキーマの変更（代わりにマイグレーションを使う）理由はエッジケースのために重要だ。「protobuf が生成」は、なぜファイルを変更してはいけないかをエージェントに伝える——できないだけでなく、変更は上書きされるということを。見かけ上の不整合に遭遇した時の遵守率を高める。
LangFlow の AGENTS.md には特に有用な詳細がある: 各保護ディレクトリに対して、代わりに何をすべきかを指定している。「migrations/ を変更しない」プラス「alembic revision --autogenerate を使う」でエージェントに前進する道を与える。
パターン4: アンチパターンカタログ
トップリポジトリは、コードベース固有のアンチパターンの明示的なリストを管理している。一般的なベストプラクティスではなく——AI エージェントがこの特定のプロジェクトで間違えがちな具体的なことだ。
Python マイクロサービスプロジェクトの例:
## Anti-Patterns
### 認証
- カスタムセッション処理を実装しない — `auth/` の `SessionManager` クラスを使う
- 実行時に環境変数にシークレットを格納しない — シークレットマネージャーを使う
- 直接データベースクエリで権限ミドルウェアをバイパスしない
### データベース
- 生の SQL を使わない — `models/` の SQLAlchemy ORM モデルを使う
- 更新に `Session.merge()` を使わない — 明示的な `query().filter().update()` を使う
- フィルタリングのためにすべてのレコードをロードしない — クエリレベルでフィルタリング
### エラー処理
- 例外をキャッチして握り潰さない — ログに記録して再 raise するかエラーレスポンスを返す
- 裸の `except:` を使わない — 常に例外タイプを指定する
- デバッグ出力に `print()` を使わない — 構造化ロガーを使う: `logger.debug()`具体性が有用性を生む。「N+1クエリを作るな」はどのエージェントも知っている標準的なアドバイスだ。「関連オブジェクトには .options(joinedload()) を使う」はプロジェクト固有で直接実行可能だ。
パターン5: 「成功の姿」セクション
洗練された AGENTS.md ファイルのいくつかに見られるパターン: 避けるべきことだけでなく、正しい挙動がどのようなものかを説明するセクション。
## 良い仕事の姿
タスクを完了する時:
- 既存テストが通る（`npm test`）
- 新しいコードがテストでカバーされている（周辺コードと同等のカバレッジ）
- `npm run lint` と `npm run typecheck` が新しいエラーなしで通る
- 変更が最小限 — タスクが要求するものだけ
- コミットメッセージが Conventional Commits に従う: `type(scope): description`
タスクスコープ外のバグや改善機会を見つけた場合:
1. コメントに記録する
2. 修正しない
3. 人間のフォローアップのためにレスポンスで言及するこれは完了の定義を確立する。なければエージェントはいつ終わったかを自分で判断する——早すぎる中断（不十分な成果）か過剰な成果（1つの関数を修正するよう頼まれてモジュール全体をリファクタリング）につながる。
パターン6: 明示的な設定としてのツール設定
持続的な AGENTS.md の失敗: ファイルがプロジェクトを説明するが、エージェントが探索に使うべきツールについて何も言わない。
## Navigation
コードベースを探索する時:
- テキスト検索には `grep -r` または `rg`（ripgrep がインストール済み）
- ファイル検索には `find`
- 最近の変更を理解するには `git log --oneline -20`
- 何が変わったかを見るには `git diff HEAD~1`
型や関数を理解する必要がある時:
- まずインラインの JSDoc/godoc コメントを確認する
- 不明なら使用例のテストファイルを確認する
- アーキテクチャ上の決定については `docs/architecture/` を確認する
プロジェクト固有の質問にウェブ検索を使わない — 代わりに質問する。書くコストは低いが、エージェントのナビゲーション効率を大きく改善する。なければエージェントは、ターゲット検索の方が速い場合でも非効率な探索戦略（ディレクトリ内の全ファイルを読む）を使いがちだ。
パターン7: バージョン付き意思決定記録
より成熟したプロジェクトが採用しているパターン: 現在の状態がなぜ存在するかをエージェントが理解できるよう、アーキテクチャ上の意思決定の簡単な履歴を AGENTS.md に保存する。
## Decision Log
- **2025-08**: Jest から Vitest にマイグレーション、テスト速度40%向上。設定は `vitest.config.ts`。
- **2025-10**: 内部サービス通信を REST から tRPC に変更。`packages/trpc/` を参照。
- **2026-01**: クラスベース React から関数コンポーネントに移行。新しいコンポーネントはすべてフック使用。
- **2026-03**: すべてのバリデーションに Zod を採用。手動バリデーション関数はもうない。これにより意図的に変更されたものを「修正」するエージェントを防げる。このログなしに、関数コンポーネントを見たエージェントはコードベースの一部がまだクラスコンポーネントを使っていることを「親切に」指摘するかもしれない。ログがあれば、方向性と予想される不整合を理解する。
パターン8: チーム別セクション構造
複数チームやドメインを持つ大規模なコードベースでは、チーム構造を反映したセクション構造が明確性を大幅に向上させる。
# AGENTS.md — プラットフォームモノレポ
## 共有インフラ
[全チームが共有するコマンド・境界・規約]
## フロントエンド (apps/web/)
Owner: フロントエンドチーム
- Stack: React 19, TypeScript, Vite
- Tests: Vitest + RTL
[フロントエンド固有のルール...]
## バックエンド API (services/api/)
Owner: バックエンドチーム
- Stack: Go 1.22, Chi router, PostgreSQL
- Tests: testify
[API 固有のルール...]Claude が services/api/ で作業する時、フロントエンドとデータパイプラインのルールをすべて読まずにバックエンド API セクションに集中できる。
パターン9: 一級市民としてのセキュリティセクション
セキュリティ要件は一般的なコーディング標準に埋もれがちだ。最良のセキュリティ態勢を持つプロジェクトは、それを独立したセクションとして明示する。
## Security Requirements
これらは交渉の余地がない。他の要件と競合する場合、
セキュリティ要件が優先される。
### シークレットと認証情報
- API キー・トークン・パスワード・接続文字列を絶対にコミットしない
- `config/` の型付き設定オブジェクト経由でのみ `process.env.VARIABLE_NAME` を使う
- `.env` ファイルは gitignore 済み; `.env.example` がテンプレート
### 入力処理
- すべてのユーザー入力は `validation/` のバリデーションスキーマを通す
- 文字列補間で SQL クエリを構築しない
- 明示的なサニタイゼーションなしに `innerHTML` を使わない
### 報告
作業中にセキュリティ上の潜在的な問題に気づいた場合:
レスポンスですぐに言及する。黙って修正しようとしない。「これらが優先される」というフレーミングが重要だ。優先度シグナルなしに、エージェントは他の目標と競合する時にセキュリティ要件を低優先化することがある。
AGENTS.md メンテナンスコミットメント
ファイル内ではなくメタな話だが重要: トップリポジトリは AGENTS.md のメンテナンスをドキュメントとしてではなく、開発ワークフローの一部として扱っている。
見られた具体的な実践:
トリガーベースの更新: 依存関係が変わったら、AGENTS.md コマンドの更新が必要かチェックする。依存関係を変更する PR でこれを行う。
マイグレーションとペア: migrations/ への変更は AGENTS.md データベースセクションのチェックをトリガーする。
品質ゲートとしてのオンボーディング: 新しい開発者がオンボーディングの一環として AGENTS.md を読む。彼らの質問が時代遅れや欠落コンテンツをフラグする。
CI ドリフト検出: いくつかのリポジトリは GitHub Actions チェックを追加している: 特定の設定ファイル（package.json、go.mod、requirements.txt）が AGENTS.md の対応する変更なしに変更された場合、チェックがリマインダー issue を作成する。
よくある AGENTS.md アンチパターン
README ダンプ。 AGENTS.md は README.md の複製であってはならない。人間にプロジェクトビジョンを理解させるコンテキストはエージェントにはノイズだ。AGENTS.md は運用に徹する: 何を実行するか、何に触れないか、どう作業するか。
漠然としたプロジェクトタイプの主張。 「これはベストプラクティスを使用したモダンなウェブアプリケーション」はエージェントに何も伝えない。具体性か沈黙か。
デフォルトを上書きしない。 エージェントは何百万ものリポジトリでトレーニングされている。ウェブアプリ・Go サービス・Python スクリプトがどう構造化されるべきかについて強い事前確率を持つ。AGENTS.md はプロジェクトがそれらの事前確率からどこで外れるかをエージェントに伝える必要がある。デフォルトはトレーニングデータだ。AGENTS.md はそれを上書きする方法だ。
まとめ: 最小限だが効果的な AGENTS.md
最小限だが効果的な AGENTS.md の出発点として、この4セクションから始める:
# AGENTS.md
## Commands
[プロジェクトをビルド・テスト・lint するためのすべてのコマンド]
## Boundaries
[変更しないもの、その理由]
## Project-Specific Conventions
[エージェントが仮定するデフォルトから外れる規約]
## Anti-Patterns
[このコードベースでエージェントが犯す具体的なミス]それ以外は加算的だ。ミスのクラスを防ぐときにアーキテクチャコンテキストを追加する。センシティブなデータを扱うときにセキュリティセクションを追加する。レガシーパターンの説明が必要なときに意思決定ログを追加する。
Claude Code サブエージェントとの AGENTS.md 統合の詳細は 著名リポジトリの AGENTS.md 実例分析 を参照してほしい。