AGENTS.md の書き方を学ぶ最善の方法は、大規模な本番環境で機能しているものを読むことだ。このガイドでは、GitHub 上で数万スターを持ち、AI エージェントを積極的に活用している著名なオープンソースリポジトリ8本の AGENTS.md を分析する。
目標はこれらのファイルを複製することではなく、パターンを抽出すること: すべてに共通するものは何か、最良のものだけがやっていることは何か、そして各プロジェクト固有の性質を反映したことは何か。
分析対象: n8n・awesome-go・LangFlow・Deno・Linear・Grafana・OpenAPI Generator・Astro。すべてパブリックな AGENTS.md を持ち、異なる言語・プロジェクトスケール・ワークフローを代表している。
これらおよび数百の他のリポジトリの実際の AGENTS.md は ルールギャラリー で確認できる。
8本すべてに共通すること
個別分析の前に、普遍的なパターン——これらすべてのファイルに存在するもの。
明示的なビルドとテストコマンド。 すべてのファイルがプロジェクトのビルド・テスト・検証に必要なコマンドで始まるか、それを目立たせている。ドキュメントではなく——実際に実行可能なコマンドだ。これは偶然ではない。AGENTS.md に入れられる最も高い価値のある単一のことだ。
立ち入り禁止ディレクトリ。 すべてのファイルがエージェントが変更すべきでない少なくとも1つのディレクトリを名指している。大抵は短い理由付きで。生成されたコード・CI 設定・マイグレーションディレクトリが8本すべてに登場する。
デフォルトから外れるプロジェクト固有の規約。 AGENTS.md の全要点はエージェントのデフォルトを上書きすることだ。8本すべてが、言語/フレームワークの「明らかな」アプローチとは異なる少なくとも1つの規約を明示的に取り上げている。
網羅性より簡潔さ。 これらのファイルはいずれも250行を超えない。平均は約120行。ドキュメントサイトではなく——運用ランブックだ。
n8n: ワークフローファーストのアプローチ
n8n は178Kスターのワークフロー自動化プラットフォーム、TypeScript/Node.js で記述されている。その AGENTS.md は複数モード（CLI・組み込み・クラウド）で動作し、1つのパッケージの変更が数十の統合に影響しうるプロジェクトを反映している。
独特の構造: n8n の AGENTS.md は動作モードマトリクスから始まる。エージェントが Docker コンテナ・Codespaces 環境・ローカルセットアップで動作している可能性があるため、ファイルは環境をコマンドに明示的にマッピングしている。
## Environment Detection
ローカル（Docker なし）:
install: pnpm install
build: pnpm build
start: pnpm start
Docker（cwd に docker-compose.yml があるか確認）:
start: docker-compose up
exec: docker-compose exec n8n <command>このパターンは使われ過ぎていない。ほとんどの AGENTS.md は単一の環境を前提とする。複数の標準環境を持つプロジェクトでは、環境検出パターンがエージェントが間違ったコマンドを実行し、なぜ動かなかったか診断するためにツール呼び出しを費やすことを防ぐ。
統合パッケージの規約: n8n は packages/nodes-base/nodes/ に約400の統合を持つ。各統合は自己完結したディレクトリだ。AGENTS.md は統合コントラクトを確立している:
## Integration Package Convention
各統合は packages/nodes-base/nodes/<ServiceName>/ に配置。
構造:
<ServiceName>.node.ts メインノードクラス
<ServiceName>.svg サービスアイコン（必須）
新しい統合を追加する際:
- packages/nodes-base/nodes/_template/ からテンプレートをコピー
- このパターンと異なるディレクトリ構造を作らない
- `pnpm test:node -- <ServiceName>` でテストテンプレートポインター（_template/）は具体的な方向性のアンカーだ。「既存の規約に従う」の代わりに、エージェントには具体的な参照点がある。
n8n が他と違うこと: マルチ環境セクション。プロジェクトが複数の標準環境で動作する場合、このパターンはすぐに採用する価値がある。
awesome-go: 最小限の精度
awesome-go は167Kスターの Go ライブラリのキュレーションリストだ。GitHub で最も貢献の多いリポジトリのひとつで、非常に特定の、厳格な貢献フォーマットを持つ。その AGENTS.md は完全でありながら極めて短いことで注目される。
AGENTS.md 全体は約60行で、正確に3つのことをカバーする:
- バリデーションスクリプトの実行方法
- 新しいエントリーの正確なフォーマット（例付き）
- CI チェックが検証すること
## エントリーの追加
フォーマット（正確に）:
- [library-name](https://github.com/owner/repo) - 短い説明。**末尾のピリオドなし。**
ルール:
- 1行説明、3〜12ワード
- 説明がピリオドで終わる？FAIL。ピリオドなし。
- カテゴリ内でアルファベット順にソート
- URL は GitHub/GitLab/Sourcehut への直接リンク、リダイレクトなし
変更後は `./scripts/validate.sh` を実行する。失敗したら進まない。FAIL アノテーション付きの 末尾ピリオドなし パターンはエージェント向けの優れた記述だ。強調が一般的なミスを示し、結果が明確だ。
awesome-go が教えること: 厳格な貢献フォーマットを持つプロジェクトでは、AGENTS.md は精密な道具だ。フォーマット自体の厳格さに合わせて書く。プロジェクトの実際の貢献プロセスが最小限のとき、最小限であることは怠慢ではない。
LangFlow: 複雑な依存関係チェーン
LangFlow は145Kスターの Python（バックエンド）+ TypeScript（フロントエンド）のローコード AI ビルダーだ。バックエンドの変更がフロントエンドのレンダリングを壊しうる複雑な開発セットアップを持ち、エージェントはコンポーネント間の関係を理解する必要がある。
コンポーネントモデルセクション: LangFlow の AGENTS.md にはコンポーネントアーキテクチャに関する異常に詳細なセクションがある——それが中心的な抽象概念だから。
## Components
LangFlow の「コンポーネント」は Component 基底クラスを継承する Python クラス。
コンポーネントは src/backend/base/langflow/components/ から自動検出される。
コンポーネントコントラクト:
- クラスに `display_name` クラス属性が必要
- `inputs` と `outputs` を langflow.io の Input/Output 型で定義
- 出力を返す `build()` メソッドを実装
- ファイル名はクラス名の snake_case と一致させる
Component 基底クラスまたは langflow.io 型を変更する場合、
変更はすべてのコンポーネントに影響すると仮定する。フルテストスイートを実行。「すべてのコンポーネントに影響すると仮定する」という行が核心的な洞察だ。共有抽象概念の変更に対する結果モデルをエージェントに与える——コード自体からは推測できないモデルを。
LangFlow が教えること: 複数のサービスにまたがる依存関係を持つ複雑なテストセットアップがある場合、詳細に説明する。適切な環境なしに pytest を実行するエージェントは、混乱するエラーに直面して複数のツール呼び出しを診断に費やすことになる。
Deno: 権威ある貢献者ガイド
Deno は106Kスターのランタイムで、AI ファイルを新しい貢献者への唯一の権威あるガイドとして扱うアプローチを取る。密度が高く、具体的で、エージェントを有能な新しいエンジニアとして扱う。
パフォーマンスに敏感なコードセクション:
## Performance Sensitive Code
Deno のコアランタイムはパフォーマンスに敏感。以下のコードについて:
- ext/core/、ext/node/、runtime/
ルール:
- ホットパスでのアロケーションを最小化
- 可能な場合ヒープよりスタックアロケーションを優先
- 変更前後に `cargo bench` でベンチマーク
- ホットパスで sync で十分な場所に async を導入しない
- パフォーマンストレードオフが許容できる理由を文書化
投機的最適化（「これの方が速いかもしれない」）は拒否される。
測定データに基づくプロファイル誘導の最適化のみ。「投機的最適化は拒否される」という行は重要だ。証拠に基づくエンジニアリングの文化を1行で確立する。これを読んだエージェントはベンチマークなしにパフォーマンスのためにコードを投機的に再構築しないことを知る。
Deno が教えること: 言語ランタイムやその他のパフォーマンスに敏感なプロジェクトでは、AI ファイルはパフォーマンス文化を明示的に取り上げる必要がある。コードの正確性は前提とされる; パフォーマンス規律は教える必要がある。
Grafana: 設定駆動のプロジェクト
Grafana の AGENTS.md はプラグイン重視のプロジェクト固有の課題を処理する: システムを拡張する正しい方法が数十あり、エージェントはどのタスクにどの拡張ポイントを使うかを知る必要がある。
## Extension Points
新しいデータソースを追加する必要がある？→ データソースプラグインを使う
新しいパネルタイプを追加する必要がある？→ パネルプラグインを使う
新しい認証メソッドを追加する必要がある？→ pkg/services/auth/ を変更
新しい HTTP エンドポイントを追加する必要がある？→ RegisterRoutes で pkg/api/ に追加
アーキテクチャの議論なしに pkg/ に新しいトップレベルパッケージを追加しない。この決定テーブルパターンは複雑なシステムに対して非常に効率的だ。エージェントがコードベース探索から正しい拡張ポイントを推測することに頼る代わりに、ルックアップテーブルを提供する。
Grafana が教えること: プラグイン重視または拡張重視のプロジェクトでは、拡張ポイントの決定テーブルは段落単位の説明より価値がある。現在のリポジトリの外に存在するコードについて明示的にする。
OpenAPI Generator: 規模での生成コード
OpenAPI Generator は OpenAPI 仕様から50以上の言語でクライアント SDK を生成する。課題: 各ジェネレーターは半独立で、独自のテンプレート・テスト・規約を持つ。
## ジェネレーターの変更
1. Java を変更する
2. `./bin/generate-samples.sh <language>` を実行してテストサンプルを再生成
3. samples/ の diff を確認 — 想定より大きい diff は調査する
4. `mvn test -pl modules/openapi-generator -Dtest=<Language>ClientCodegenTest` を実行
generate-samples.sh を実行せずに samples/ の変更をコミットしない明示的な「diff を確認する」指示が価値ある。OpenAPI Generator は、生成されたサンプルがレビュアーが正しいと仮定して見逃した方法で変更されたときにバグが導入された経験がある。
OpenAPI Generator が教えること: コードジェネレーターでは、AGENTS.md は生成-検証-レビューのサイクルを取り上げる必要がある。生成された出力はしばしば最も重要なテストアーティファクトであり、エージェントは生成された diff のレビューがワークフローの一部であることを理解する必要がある。
Astro: エコシステム貢献者
Astro は約50Kスターを持ち、統合・テーマ・アダプターのエコシステムを持つ。その AGENTS.md は多くの貢献者が異なる部分に同時に作業する貢献モデルを処理する。
## Contribution Scope
コア機能に取り組んでいる？→ packages/astro/ の変更
統合に取り組んでいる？→ packages/@astrojs/<name>/ の変更
ドキュメントに取り組んでいる？→ docs/ の変更
メンテナーと明示的に横断的変更を調整していない限り、
同じ PR でこれらのスコープをまたいだ変更をしない。「同じ PR でスコープをまたいだ変更をしない」という指示は、エージェントが親切心から隣接パッケージで見つけた関連する問題を修正しようとする一般的なパターンを防ぐ。
再現ケースの要件:
## Bug Fixes
すべてのバグ修正には以下が必要:
1. 修正「前」にバグを示す失敗するテストケース
2. 最小限の再現ケース（フルアプリではなく失敗するテストを優先）
3. GitHub issue へのリンクコメント
再現なしの修正: レビューで拒否される。これは AGENTS.md に記述された品質ゲートだ。ここに含めることで、レビューコメントではなくエージェントの「完全なバグ修正」の定義の一部になる。
Astro が教えること: 複数パッケージのエコシステムでは、スコープ境界を明示的にする。再現ケース要件パターンは、再現ケースが期待されるあらゆるプロジェクトに転用可能だ。
クロスプロジェクトパターン: 最良のものが共有するもの
8本すべてを見渡して:
指示対説明の比率。 最高パフォーマンスのファイルは説明より指示（「X をする」「Y を決してしない」）が多い。説明は特定のミスを防ぐために必要な場合にのみ現れる。
抽象的なルールより具体的な例。 「packages/nodes-base/nodes/_template/ のテンプレートを使う」は「既存の統合パターンに従う」より優れている。抽象的なルールを具体化できるものはすべて具体化すべきだ。
ネガティブな例。 これらのファイルのいくつかには正しいパターンと間違ったパターンの両方が含まれる:
# 良い例
fmt.Errorf("users: get by id: %w", err)
# 絶対にしない
log.Fatal("user not found") // ハンドラには不適切ネガティブな例はエージェントが生成する可能性のある正確なものと一致するため、よくある間違いに特に効果的だ。
これらのパターンの活用
このガイドのテンプレートはそのままコピーするためのものではなく——理解するためのものだ。自分の AGENTS.md を書くとき、問う:
- このリポジトリでの AI 支援開発で最も重要な3つのコマンドは何か？
- 誤って変更された場合に最大のダメージを引き起こすディレクトリはどれか？
- AI エージェントがここで犯す最も一般的なミスは何か？
- エージェントが遭遇しうる環境固有のバリエーションはあるか？
- ゼロから作る代わりにエージェントが使うべき拡張ポイントやテンプレートはあるか？
これら5つの問いに答えることで、汎用テンプレートに従うよりも有用な AGENTS.md が生まれる。
AGENTS.md を CI で最新に保つ実装パターンについては AGENTS.md CI/CD 自動化ガイド を参照。設計原則については AGENTS.md ベストプラクティス 2026 で詳しく解説している。