最終更新日：2026年9月28日 読了時間：約9分
AGENTS.mdを正しく設定すれば、Claude Codeのマルチエージェント動作を制御し、サブエージェントに対して独立した指示を与えられる。この記事では、CLAUDE.mdとの役割の違い・作成手順・つまずきポイントを具体的に解説する。
この記事で分かること：
- ✔ AGENTS.mdとCLAUDE.mdの役割の違いが分かる
- ✔ AGENTS.mdの作成〜動作確認の手順が分かる
- ✔ 設定ミスで詰まる前に防げる落とし穴が分かる
30秒で選ぶなら：
→ サブエージェントに個別の指示を与えたいならAGENTS.md、Claude Code全体の動作を制御したいならCLAUDE.md。
Claude CodeのAGENTS.md対応とは何か
AGENTS.mdは、Claude Codeがマルチエージェントモードで動作するとき、サブエージェントに対して適用される指示ファイルだ。
CLAUDE.mdがClaude Code全体のルール・コンテキストを定義するのに対し、AGENTS.mdはサブエージェントが参照する独立した指示セットを提供する。これにより、メインエージェントとサブエージェントで異なる制約・スタイル・ツール使用方針を持たせることが可能になる。
2026年に追加されたこの機能は、複数エージェントが協調して動作する複雑なタスク（コードレビュー・ドキュメント生成・テスト実行の並行処理など）で特に威力を発揮する。
AGENTS.mdとCLAUDE.mdの違いと選び方
役割の比較
| 項目 | CLAUDE.md | AGENTS.md |
|---|---|---|
| 適用対象 | Claude Code全体（メインエージェント含む） | サブエージェント（並行タスク実行時） |
| 読み込みタイミング | セッション開始時・常時 | サブエージェント起動時 |
| 主な用途 | プロジェクト全体の方針・禁止事項 | サブエージェント専用のタスク定義・制約 |
| 配置場所 | プロジェクトルートまたは上位ディレクトリ | プロジェクトルート（CLAUDE.mdと同階層も可） |
| 複数ファイル | ディレクトリ階層で複数配置可 | 1ファイル（現時点） |
| スコープ | 広域・全体制御 | 局所・エージェント個別制御 |
※2026年9月時点。仕様は変更の可能性があります。
どちらを使うべきか
CLAUDE.mdだけで十分なケースは多い。AGENTS.mdが必要になるのは「サブエージェントに、メインエージェントとは異なる制約を課したい」という明確な要件があるときだ。
たとえば、メインエージェントには広いファイル書き込み権限を与えつつ、テスト実行サブエージェントには読み取り専用に制限したい場合。あるいは、コード生成サブエージェントに特定のコーディングスタイルガイドを適用したい場合がある。
こんな人にAGENTS.mdが向いている：
- □ 複数サブエージェントを並行起動するワークフローを組んでいる
- □ サブエージェントに独立した権限・スタイルを設定したい
- □ Claude Code Hooksと組み合わせた精密なエージェント制御が必要
こんな人には向いていない：
- □ 単一エージェントで完結するシンプルな使い方をしている
- □ まだCLAUDE.mdの設定が固まっていない段階
AGENTS.mdの作成・設定手順
正直なところ、最初はCLAUDE.mdとの違いがピンとこない人がほとんどだ。この手順を上から順にやれば、確実に動作確認できる。
ステップ1：プロジェクトルートにAGENTS.mdを作成する
touch /path/to/your/project/AGENTS.md
CLAUDE.mdと同じディレクトリに配置する。サブディレクトリに置くと、そのディレクトリ配下のサブエージェント専用の指示として機能するが、まずはルートから始めるのが確実だ。
ステップ2：基本構造を記述する
AGENTS.mdには、サブエージェントに守らせたいルールをMarkdown形式で書く。
# Agent Instructions
## 役割と制約
このエージェントはコードレビューに特化しています。
ファイルの新規作成・削除は行わないでください。
## 出力形式
- 問題点は箇条書きで列挙する
- 各指摘に重要度（high/medium/low）を付ける
- 修正提案は diff 形式で示す
## 禁止事項
- `git push` は実行しない
- 本番環境の設定ファイルを変更しない
個人的にはこのステップが一番重要だと思う。 「何をしてはいけないか」をAGENTS.mdに明示しておかないと、サブエージェントがメインエージェントと同じ広い権限で動いてしまい、意図しない変更が発生する。
ステップ3：CLAUDE.mdとの役割分担を明確にする
CLAUDE.mdには「プロジェクト全体の方針」、AGENTS.mdには「サブエージェント固有の制約」を分けて書く。
# CLAUDE.md（メインエージェント用）
## プロジェクト概要
〇〇システムの開発・保守
## 全体方針
- TypeScriptを使用する
- テストカバレッジ80%以上を維持する
# AGENTS.md（サブエージェント用）
## タスク定義
テストの自動生成に特化する
## 制約
- テストファイル（*.test.ts）のみ編集可
- 本番コードは変更しない
この分離を怠ると確実に詰まります。CLAUDE.mdとAGENTS.mdに矛盾する指示が混在すると、どちらが優先されるか予測しにくくなる。
ステップ4：Claude Codeでサブエージェントを起動して動作確認する
マルチエージェントが動作するタスクを指示すると、サブエージェントがAGENTS.mdを参照して起動する。Claude Codeのログで[subagent]タグが付いた出力が確認できれば、AGENTS.mdが正しく読み込まれている。
ステップ5：ディレクトリ別にAGENTS.mdを配置する（応用）
大規模プロジェクトでは、サブディレクトリごとに異なるAGENTS.mdを置ける。
やってみると分かるのですが、この構造は大規模なリポジトリで特に効果が高い。モノレポ構成のプロジェクトで、フロントとバックで異なるコーディングルールを適用したいケースにぴったりだ。
よくある失敗と対処法
失敗1：CLAUDE.mdとAGENTS.mdに矛盾する指示を書く
症状： サブエージェントが指示通りに動かない、または想定外のファイルを変更する。
原因と対処： CLAUDE.mdに「すべてのファイルを自由に編集可」と書き、AGENTS.mdに「読み取り専用」と書くと動作が不安定になる。AGENTS.mdの記述が優先されるが、CLAUDE.mdの広い権限が「許可」として解釈されるケースがある。
対処法は「CLAUDE.mdでの権限付与を絞り込み、サブエージェントに必要な権限だけをAGENTS.mdで明示する」こと。権限は「広く与えてから制限」より「狭く与えてから拡張」が安全だ。
失敗2：AGENTS.mdを配置したのにサブエージェントが読み込まない
症状： サブエージェントが起動してもAGENTS.mdの制約が反映されない。
原因： 最もよくある原因はファイル名のミスタイプ（agents.md・Agents.mdなど）だ。ファイル名は大文字・小文字を含めてAGENTS.mdと完全一致させる必要がある。 このミスを見落とすと後で必ず詰まります。
確認コマンド：
ls -la | grep -i agents
失敗3：すべての制約をAGENTS.mdだけに書こうとする
症状： CLAUDE.md側の設定が薄くなり、メインエージェントの動作が不安定になる。
対処： AGENTS.mdはあくまで「サブエージェント専用の追加制約」として位置付ける。プロジェクト全体に適用すべきルール（コーディング規約・禁止コマンドなど）はCLAUDE.mdに書く。AGENTS.mdはCLAUDE.mdを「継承した上で上書きする」という思考モデルで書くと整理しやすい。
よくある質問（FAQ）
Q. AGENTS.mdはCLAUDE.mdを置き換えるものですか？
A. 置き換えではありません。CLAUDE.mdはメインエージェントを含む全体の制御ファイルで、AGENTS.mdはサブエージェント専用の追加設定ファイルです。両方を共存させて役割を分担させます。
Q. AGENTS.mdがない場合、サブエージェントはどの設定を参照しますか？
A. AGENTS.mdが存在しない場合、サブエージェントはCLAUDE.mdの内容を参照して動作します。AGENTS.mdは必須ではなく、サブエージェントを細かく制御したい場合にのみ作成します。
Q. AGENTS.mdに書けるのはテキスト形式の指示だけですか？
A. 現時点ではMarkdownテキスト形式の指示のみ対応しています。ツール使用の許可・禁止はClaude Code本体の権限設定（.claude/settings.json）で制御し、AGENTS.mdはその上位レイヤーのルール記述用として位置付けます。
まとめ
AGENTS.mdを使えば、サブエージェントの動作をメインエージェントとは独立して制御できる。まずはプロジェクトルートにCLAUDE.mdと並べてAGENTS.mdを作成し、サブエージェントに課したい制約を1つ書くところから始めてみてください。
複雑なマルチエージェントワークフローを組む前に、「CLAUDE.mdで全体方針・AGENTS.mdでサブエージェント制約」という役割分担を固めることが、安定した自動化の土台になる。
最終更新日：2026年9月28日