AGENTS.mdはシンプルな慣習として始まった — AIエージェントにプロジェクトの作業方法を伝えるMarkdownファイルをリポジトリに置くだけ。2026年、それはマルチエージェントのClaude Code設定の基盤ファイルになり、6万以上のオープンソースリポジトリで使われ、Agentic AI Foundationによってオープン標準として正式採用されている。
Claude Codeのサブエージェントを使うなら、AGENTS.mdがその設定場所だ。このガイドでは実際に機能するものを解説する。ファイルフォーマット、一貫した結果を生むエージェントエントリの書き方、スコープ階層の動作、コミュニティが収束したパターンまで。
AGENTS.mdが何をするか
AGENTS.mdはコンテキストによって2つの役割を持つ。
エコシステム標準として、AGENTS.mdはコードベースのAIエージェントへの伝達ファイルだ。ビルド方法・テスト実行方法・従うべき規約・触れてはいけないディレクトリを伝える。AGENTS.md標準をサポートするエージェントはこのファイルを読み、動作を適応させる。これはマルチエージェントにおけるCLAUDE.mdの同等物だ。2つのファイルの直接比較はAGENTS.md vs CLAUDE.md: 何が違うのか?を参照。
Claude Code内では、AGENTS.mdは名前付きサブエージェントも定義する — 独自のシステムプロンプト・ツール権限・モデル設定を持つ特化したClaudeインスタンスだ。AGENTS.mdに ## code-reviewer エントリを書くと、Claudeが委譲できるサブエージェントが作成される。
両方の役割が同じファイルで共存する。トップレベルのMarkdownがプロジェクトを説明し、エージェントセクションが委譲可能なワーカーを定義する。
ファイルフォーマット
AGENTS.mdはプレーンMarkdown。YAMLスキーマ・JSON設定・特殊構文は不要。これは意図的だ — 人間が読める、任意のモデルがパース可能、ツールなしで書ける必要がある。
完全なAGENTS.mdの例。
# Project Overview
This is a TypeScript monorepo with three packages: API, web client, and CLI.
## Build
```bash
pnpm install
pnpm buildTesting
pnpm test # unit tests
pnpm test:e2e # end-to-end tests (requires running API)Conventions
- All API routes are in
packages/api/src/routes/ - Database models are in
packages/api/src/models/ - Tests live adjacent to source files as
*.test.ts - No
anytypes except in test files
Agents
code-reviewer
description: Reviews code for correctness, security issues, and TypeScript best practices. Use before committing or opening a pull request. tools: read, bash model: claude-sonnet-4-6
test-generator
description: Generates unit tests for existing TypeScript code. Use after implementing new features or when test coverage is below 80%. tools: read, write model: claude-sonnet-4-6
migration-writer
description: Writes database migrations for schema changes. Checks for backward compatibility and reversibility. Use when modifying database models. tools: read, write, bash model: claude-sonnet-4-6
`## Agents` セクションがClaude Codeのサブエージェント定義の置き場所だ。各 `###` 見出しがエージェント名で、インデントされたキーバリューペアが設定だ。
## スコープ階層
AGENTS.mdファイルはCLAUDE.mdと同様に階層的なスコープモデルに従う。1つのプロジェクトに複数のAGENTS.mdファイルを持つことができ、Claudeはファイルの場所に基づいてそれらをマージする。
/ ← グローバル（~/.claude/AGENTS.md） project-root/ AGENTS.md ← プロジェクト全体のエージェント packages/ api/ AGENTS.md ← API固有のエージェント web/ AGENTS.md ← web固有のエージェント
`packages/api/` で作業中は、3ファイルすべてで定義されたエージェントにアクセスできる。プロジェクトルートで作業中は最初の2ファイルのみ。
これにより、グローバルな名前空間を汚染することなく、パッケージレベルで特化したエージェントを定義できる。`api` パッケージでのみ意味のある `database-migrator` エージェントは `packages/api/AGENTS.md` に置き、プロジェクトルートには置かない。
**コンフリクト解決**: 異なるレベルの2つのAGENTS.mdファイルが同名のエージェントを定義した場合、より具体的なもの（ディレクトリツリーの深い方）が優先される。これにより特定のパッケージ向けにグローバルエージェントをオーバーライドまたは特化できる。
## 効果的なエージェントエントリを書く
descriptionフィールドがエージェントエントリで最も重要な部分だ。2つのことを制御する。Claudeの意思決定においてエージェントがどう見えるか、そしてClaudeが自律的にエージェントを呼び出すかどうか。
**弱いdescription:**description: Reviews code
**強いdescription:**description: Reviews TypeScript code for null pointer dereferences, missing error handling, and violations of the API conventions in this project. Use before committing any changes to packages/api/.
弱い版はClaudeにほとんど何も伝えない。強い版はClaudeに3つの情報を与える。エージェントが何をチェックするか、どのコードベース規約を知っているか、いつ呼び出すか。
自律的な呼び出し — あなたが頼まなくてもClaudeがエージェントを呼ぶ場合 — には、descriptionがコンテキストに明確にマッチする必要がある。ClaudeがAPIコードを書いていて「packages/api/への変更をコミットする前に使う」と書かれたエージェントを見れば、プロンプトなしで適切なタイミングにそのエージェントを呼び出す。
手動で常に呼び出すエージェントなら、descriptionはルーティングよりも発見性のために重要だ。
## ツール権限
エージェントエントリの `tools` フィールドはセキュリティの境界だ。サブエージェントは付与したツールにのみアクセスできる。
一般的なツールセット。
| ツール | ユースケース |
|---|---|
| `read` | 読み取り専用分析: コードレビュー、ドキュメントレビュー、監査 |
| `read, write` | コンテンツ生成: テスト作成、ドキュメント作成 |
| `read, bash` | 実行を伴う分析: テスト実行、コンパイル確認 |
| `read, write, bash` | 完全な開発タスク: 機能実装、マイグレーション実行 |
| `read, write, bash, web_search` | リサーチ集約タスク |
最小権限の原則がここでも適用される。コードレビュアーには書き込みアクセスが不要。ドキュメント作成者にbashは不要。権限を絞るほど、エージェントが誤動作したときの影響範囲を抑えられ、動作が予測しやすくなる。Claude Codeにおけるエージェントセキュリティの全体像は[AGENTS.md セキュリティガイド](https://thepromptshelf.dev/blog/agents-md-security-guide-2026/)を参照。
## モデル選択
ほとんどのエージェントエントリは `model: claude-sonnet-4-6` を使うべきだ。Opusより速くコストが低く、サブエージェントタスクの大部分に十分な能力がある。
`model: claude-opus-4-6` は本当に難しい推論が必要なエージェントのために取っておく。
- アーキテクチャ決定レビュー
- 複雑な脆弱性分析を伴うセキュリティ監査
- 大規模で複雑なコードベースをまたいで推論が必要なエージェント
シンプルで機械的なタスク — フォーマットチェック・ボイラープレート生成・単純なドキュメント — には `claude-haiku-3-6` がレイテンシとコストを大幅に削減する。
## 機能するパターン
**スペシャリストプール。** それぞれが1つのドメインをカバーするエージェントのセットを定義する: テスト・セキュリティ・ドキュメント・パフォーマンス。メインのClaude セッションにすべてをやらせるのではなく、スペシャリストに委譲する。これによりコンテキストをクリーンに保ち、各エージェントを集中させられる。
```markdown
### security-auditor
description: Audits code for security vulnerabilities including injection, broken auth,
sensitive data exposure, and insecure dependencies. Use before production deployments.
tools: read, bash
model: claude-opus-4-6
### performance-reviewer
description: Identifies performance bottlenecks: N+1 queries, unnecessary re-renders,
blocking operations, and memory leaks. Use when profiling indicates slow paths.
tools: read, bash
model: claude-sonnet-4-6
### docs-writer
description: Writes and updates technical documentation: README files, inline comments,
API reference, and architecture notes. Use when code changes are complete.
tools: read, write
model: claude-sonnet-4-6ゲートキーパーパターン。 別のエージェントが動く前に1つのエージェントが事前条件を確認する。デプロイワークフローでは pre-deploy-checker エージェントが先に走り、問題があればブロックする。
### pre-deploy-checker
description: Verifies deployment readiness: all tests pass, no TODO comments in new code,
environment variables are set, dependencies are pinned. Use before any deployment.
tools: read, bash
model: claude-sonnet-4-6
### deployer
description: Executes the deployment workflow. Always invoke pre-deploy-checker first.
tools: read, bash
model: claude-sonnet-4-6スコープ付きスペシャリスト。 モノレポでは特定のパッケージにスコープしたエージェントを定義する。APIパッケージのORMの規約とマイグレーションパターンを知っている database-expert エージェントは、汎用的なデータベースエージェントより役立つ。
やってはいけないこと
一度も使わないエージェントを定義しない。 20のエージェント定義を持つAGENTS.mdは包括的に見えるが、ノイズを増やす。Claudeはすべてのdescriptionを読み、推論に組み込む。無関係なエージェントはシグナルを希釈する。3〜4つから始め、明確な必要性があるときだけ追加する。
曖昧なdescriptionを書かない。 「必要なときに使う」はdescriptionではない。エージェントをいつ実行すべきか具体的に表現できないなら、まだそのエージェントを必要としていない可能性が高い。
全エージェントにフルアクセスを与えない。 過剰な権限は設計上の悪臭だ。エージェントが実際に何を必要とするかを十分に考えていないサインだ。
プロジェクトコンテキストのセクションをスキップしない。 AGENTS.mdのエージェント定義より前のトップ部分にはプロジェクトの説明が必要だ。このコンテキストはセッション初期化の一部としてClaudeに読まれる。最小限のプロジェクト説明 — 言語・構造・ビルドコマンド・規約 — があるだけで、全エージェントがコードベースの正確なメンタルモデルを持ってスタートするため有効になる。
CLAUDE.mdとの統合
AGENTS.mdとCLAUDE.mdは競合ではなく補完関係にある。
CLAUDE.md はメインセッション向け: コーディング標準・ファイル構造・ワークフロールール、Claudeに毎回覚えておいてほしいこと。
AGENTS.md はエージェント向け: メインのClaude セッションとサブエージェントの両方がコードベースを理解するのに役立つプロジェクトコンテキスト、加えてサブエージェントの定義。
実際には、AGENTS.mdの上部セクションがCLAUDE.mdの内容を一部繰り返すことが多い — ビルドコマンド・ディレクトリ構造・テスト規約。この冗長性は意図的だ。エージェントはメインセッションの記憶に依存するのではなく、必要なコンテキストの独自コピーを持つ必要がある。
両ファイルを維持することが重複に感じられるなら、プロジェクトコンテキストをCLAUDE.mdに置き、AGENTS.mdは ## Agents セクションのみにすることを検討する。Claude Codeは両方を読んでコンテキストをマージする。ただし、ツールアクセスが制限されたエージェントが読む必要のあるファイルには引き続きアクセスできることを確認する。
はじめ方
既存プロジェクトにAGENTS.mdを初めて追加するなら、小さく始める。プロジェクトコンテキストセクション（ビルドコマンド・ディレクトリレイアウト・テスト手順）を書き、エージェントを1つ定義する。何度か実行してみる。意図した使途に対してClaudeがどう呼び出すかをもとにdescriptionを洗練させる。
委譲する価値があるワークフローを発見するにつれ、ファイルは自然に育っていく。本番コードベースのベストなAGENTS.mdは最初から包括的だったわけではない — 1〜2のエントリから始まり、数ヶ月の使用を通じて進化した。
よくある質問
Q1. AGENTS.mdはCLAUDE.mdの前後どちらに書くべきですか？
CLAUDE.mdを先に書きましょう。CLAUDE.mdはメインのClaude Codeセッション向けのプロジェクト全体の指示と制約を設定します。AGENTS.mdはその上に特化したサブエージェントを定義します。CLAUDE.mdがない場合、サブエージェントは共有のプロジェクトコンテキストを持てません。
Q2. 典型的なAGENTS.mdにはエージェントエントリをいくつ書くべきですか？
本番のAGENTS.mdファイルのほとんどは3〜7のエントリを持ちます。10を超えると、モデルが適切なものを選ぶ能力が希釈し始め、ほとんどのチームが委譲作業の80%以上を同じ3〜5のエージェントで処理することに気づきます。明確に定義された1つのエージェントから始め、繰り返しのワークフローが正当化するときにだけ追加します。
Q3. AGENTS.mdはClaude Code以外のツールでも機能しますか？
はい。AGENTS.mdは2026年時点でOpenAI Codex CLI・Cursor・その他いくつかの新興AIコーディングツールが採用したクロスツール標準です。name・description・tools・model フィールドを持つ ## Agents セクションフォーマットは、サブエージェントのセマンティクスを実装したツール間で移植可能です。
Q4. エージェントエントリのツール制限の適切なスコープは？
エージェントが本当に必要なものに制限してください。ドキュメントジェネレーターはおそらく Read と Glob が必要ですが Bash や Edit は不要です。テストランナーは Read と Bash(npm test*) が必要ですがファイル編集は不要です。過剰な権限はAGENTS.mdで最も多い間違いです — エージェントの動作を予測しにくくし、レビューを困難にします。
Q5. AGENTS.mdのサブエージェントは他のサブエージェントを呼び出せますか？
はい。サブエージェントはTaskツール（ツールリストにある場合）を使って他のサブエージェントに委譲できます。ただし、深くネストした委譲はコンテキストを希釈しコストを増加させる傾向があります。ほとんどのチームは委譲を1段階の深さに保ちます: メインセッション → 1つのスペシャリスト → 結果。
Q6. モノレポでのスコープ階層と継承の仕組みは？
ルートの AGENTS.md はワークスペース全体に適用されます。サブディレクトリの AGENTS.md ファイルはそのスコープのルートを拡張またはオーバーライドします。Claudeがサブディレクトリで作業するとき、まずルートファイルを読み、次にローカルファイルとマージします。これにより組織全体のルールをルートに、チーム固有のエージェントをパッケージごとに持てます。
Q7. AGENTS.mdはGitにコミットすべきですか？
必ずコミットしてください。AGENTS.mdはチーム共有のエージェント動作を定義し、コラボレーションのためのものです。リポジトリルートのCLAUDE.mdと並べて追加します。Gitに入れないファイルは通常 .claude/settings.local.json（個人オーバーライド）だけです — AGENTS.mdとCLAUDE.mdはバージョン管理に属します。