レビューや調査を任せるたびにメインの会話が膨らみ、本来の作業の文脈が押し流される。あるいは、調査だけのつもりで頼んだエージェントがファイルを書き換えてしまう。Claude Codeを小さなチームで使い始めると、この2つに早い段階で突き当たります。
どちらもサブエージェントの定義で解決できます。本記事では、エージェントガバナンスの実装レイヤーとして、カスタムサブエージェントの書き方と、権限を絞る設計の要点を公式ドキュメントに基づいて整理します。
カスタムサブエージェントとは何か
サブエージェントは独自のコンテキストウィンドウ・システムプロンプト・ツール権限を持つ専用エージェントで、YAMLフロントマター付きMarkdownで定義します。
定義ファイルのフロントマターで必須なのはnameとdescriptionの2つだけで、本文のMarkdownがそのままシステムプロンプトになります。descriptionはClaudeが「この仕事を任せるか」を判断する材料です。サブエージェントは親の会話履歴を引き継がず、中間の検索結果やファイル内容はサブエージェント内に留まり、親に戻るのは最終報告だけです。長いログを読ませる作業を切り出せば、メインの文脈を保てます。
どこに置き、どれが優先されるか
定義はプロジェクトなら.claude/agents/、個人なら~/.claude/agents/に置き、同名の場合は管理設定が最優先で適用されます。
優先順位は高い順に、組織の管理設定、--agentsフラグ（そのセッション限り）、.claude/agents/、~/.claude/agents/、プラグイン付属のagentsです。チームで共有したい定義は.claude/agents/に置いてリポジトリにコミットします。この場所にあれば、新しいメンバーも同じ定義を使えます。注意点として、新規作成したagentsディレクトリの最初のファイルは、セッションの再起動が必要です。
権限をどう絞るべきか
権限は
toolsで許可リスト、disallowedToolsで拒否リストを書き、調査系は読み取り系ツールだけに絞るのが基本です。
toolsを省略するとメインの会話のツールをすべて継承します。つまり、書かない設計が最も権限が広い設計です。レビューや調査を担う定義は、次のように読み取り系に限定します。
```markdown
---
name: code-reviewer
description: 変更差分のレビュー専用。修正は行わず指摘のみ返す。コード変更後に積極的に使う
tools: Read, Grep, Glob
model: sonnet
maxTurns: 20
---
あなたはレビュー担当です。指摘は重大度順に、該当ファイルと行を添えて報告してください。
```
ここでEditやWriteを渡していないため、このエージェントは書き換えようがありません。許可リストに載せなかったツールはセッションに存在しないため、プロンプトで「編集しないで」と頼むより確実です。maxTurnsは暴走時の上限になり、modelで調査系だけ軽量モデルに振り分けることもできます。
入れ子と並列数はどう制限するか
サブエージェントは既定で3階層まで入れ子になり同時実行は20件までなので、環境変数と予算上限で歯止めを掛けます。
サブエージェント自身も別のサブエージェントを起動できます。既定の深さ上限は3、同時実行の上限は20で、CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHとCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSで変更できます。Agent SDKではmaxBudgetUsdで1回のクエリの支出に上限を設けられ、上限に達するとサブエージェントの新規起動が拒否されます。各サブエージェントが独自にAPIを呼ぶため、無制限だと費用が読めなくなります。Anthropicのマルチエージェント研究システムの解説でも、並列の調査に向く一方で、密に連携するコーディング作業には向きにくいとされています。小規模な運用では、まず深さ1・同時数を少なく始めるのが安全です。
規模別の留意点（SMB）
数人のチームなら、読み取り専用のレビュアーと調査役の2種類から始めます。書き込みを伴う定義は、permissionModeと.claude/settings.jsonのdenyルールを併せて見直してから追加します。組織で統一したい制約は管理設定側に置きます。
参考
- Create custom subagents - Claude Code Docs
- Subagents in the SDK - Claude Agent SDK
- How we built our multi-agent research system - Anthropic Engineering
まとめ
カスタムサブエージェントは、コンテキストの分離とツール権限の限定を、Markdown1枚で実現する仕組みです。toolsを省略すると権限が全継承される点だけ押さえ、調査・レビュー系は読み取り専用で定義し、深さ・同時数・予算の上限を併せて設定してください。権限設計や運用ルールの整備は、Kuu株式会社のAI Opsにご相談ください。