# Claude Codeサブエージェント設計——権限を絞る書き方

> Claude Codeのカスタムサブエージェントは.claude/agents/のMarkdown1枚で定義でき、toolsで権限を絞れます。中小企業が最初に作る読み取り専用レビュアーの設計手順を解説します。

- Canonical: https://kuucorp.com/blog/claude-code-custom-subagents-tool-scope-design-smb/
- Date: 2026-10-14
- Last modified: 2026-10-14
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
レビューや調査を任せるたびにメインの会話が膨らみ、本来の作業の文脈が押し流される。あるいは、調査だけのつもりで頼んだエージェントがファイルを書き換えてしまう。Claude Codeを小さなチームで使い始めると、この2つに早い段階で突き当たります。

どちらもサブエージェントの定義で解決できます。本記事では、[エージェントガバナンス](/glossary/agent-governance/)の実装レイヤーとして、カスタムサブエージェントの書き方と、権限を絞る設計の要点を公式ドキュメントに基づいて整理します。

## カスタムサブエージェントとは何か

> サブエージェントは独自のコンテキストウィンドウ・システムプロンプト・ツール権限を持つ専用エージェントで、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の[マルチエージェント研究システムの解説](https://www.anthropic.com/engineering/multi-agent-research-system)でも、並列の調査に向く一方で、密に連携するコーディング作業には向きにくいとされています。小規模な運用では、まず深さ1・同時数を少なく始めるのが安全です。

### 規模別の留意点（SMB）

数人のチームなら、読み取り専用のレビュアーと調査役の2種類から始めます。書き込みを伴う定義は、`permissionMode`と`.claude/settings.json`のdenyルールを併せて見直してから追加します。組織で統一したい制約は管理設定側に置きます。

## 参考

- [Create custom subagents - Claude Code Docs](https://code.claude.com/docs/en/sub-agents)
- [Subagents in the SDK - Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/subagents)
- [How we built our multi-agent research system - Anthropic Engineering](https://www.anthropic.com/engineering/multi-agent-research-system)

## まとめ

カスタムサブエージェントは、コンテキストの分離とツール権限の限定を、Markdown1枚で実現する仕組みです。`tools`を省略すると権限が全継承される点だけ押さえ、調査・レビュー系は読み取り専用で定義し、深さ・同時数・予算の上限を併せて設定してください。権限設計や運用ルールの整備は、[Kuu株式会社のAI Ops](https://kuucorp.com/services/ai-ops/)にご相談ください。