Claude Managed Agents入門 — Subagentの全体像・優先順位・設計原則

本記事は 2026-04-10 時点で公開されているAnthropic/Claude公式ドキュメントを基に構成しています。

まず結論：Managed Agentsとは何か

Claude CodeにおけるManaged Agentsは、ざっくり言うと 「組織で配布・強制できるsubagent定義」 です。

subagent自体は、メイン会話とは別のコンテキスト窓で動作する専門エージェントです。たとえば「探索専用」「レビュー専用」「テスト実行専用」のように、役割を分けられます。

公式ドキュメント上では、subagentの保存場所ごとに優先順位が決まっており、最上位に Managed settings（組織管理） が来ます。

なぜManagedが必要か

個人開発では user/project subagent だけでも回りますが、チーム運用では次が問題になります。

人によってエージェント定義がバラバラ
権限（tools / permission mode）の統制が効かない
監査時に「どの定義が有効だったか」を追跡しにくい

Managed Agentsを使うと、組織で標準化した定義を上位から適用でき、同名agentの競合も解決しやすくなります。

subagentの優先順位（ここを最初に覚える）

公式の優先順位は次のとおりです（高 → 低）。

Managed settings（組織全体）
--agents CLI flag（そのセッションのみ）
.claude/agents/（プロジェクト）
~/.claude/agents/（ユーザー）
Pluginのagents/（プラグイン）

つまり、同名code-reviewerが複数場所にあっても、最上位が勝ちます。

subagentの構成要素

subagentファイルはMarkdown + YAML frontmatterで定義します。

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. Analyze changes and report actionable feedback.

重要ポイント：

name / description は必須
tools を省略すると親スレッドのtoolsを継承
model は sonnet / opus / haiku / inherit などを指定可能
permissionMode など追加制御も可能

Built-in subagentsも理解しておく

Claude Codeには最初から組み込みsubagent（例: Explore, Plan, general-purpose）があり、状況に応じて自動委譲されます。

特にExploreはread-only寄りで、探索ノイズを本線から切り離すのに有効です。Managed運用でも「まず既定挙動を理解 → 必要なものだけカスタム」の順で設計するのが安全です。

設計原則（実務で効く）

1) 1 agent 1責務

❌ なんでも屋agent
✅ code-reviewer, test-runner, migration-planner のように役割分離

2) descriptionを曖昧にしない

Claudeはdescriptionで委譲判断します。曖昧な説明は誤委譲の原因。

3) tools最小権限

書き込み不要のagentにEdit/Write/Bashを渡さない。まずread-onlyから始め、必要時だけ拡張。

4) modelを目的で分ける

探索/要約：Haiku
実装/レビュー：Sonnet
高難度推論：Opus

よくある落とし穴

Managed定義とproject定義の重複で「想定外のagentが動く」
プラグイン由来agentにpermissionMode等を設定しても無視されるケースがある
手動でファイル追加後、セッション再読込せず反映されない

まとめ

Managed Agentsを導入するときの本質は、

優先順位を理解する
権限を最小化する
同名競合と説明文品質を管理する

この3点です。

次記事では、組織配布（managed-settings.json / managed-settings.d）での具体的なガバナンス設計を掘り下げます。

参考（公式）

Claude Code Docs: Create custom subagents
https://docs.anthropic.com/en/docs/claude-code/sub-agents
Claude Code Docs: Settings
https://docs.anthropic.com/en/docs/claude-code/settings

S	公式ソース確認済み
A	成功実績多数・失敗例少数
B	賛否両論
C	動作未確認・セキュリティリスク高
Z	個人所感