Claude Code カスタムサブエージェント実践ガイド — YAML frontmatter全設計・Worktree分離・ツール制限で安全な並列自律開発を実現する
(更新: 2026年04月20日)
Claude CodeサブエージェントAI開発自動化Worktree
Claude Codeでチーム開発をしていると、ある壁にぶつかる。コードレビューを頼んだはずのエージェントが勝手にファイルを編集し、テスト生成を依頼したらビルドスクリプトまで書き換えていた——そんな経験はないだろうか。
.claude/agents/にMarkdownファイルを1つ置くだけで、コードレビュー専用・テスト生成専用・リファクタリング専用のエージェントが立ち上がり、Worktree分離で本番ブランチを汚さず並列実行できる。本記事では、YAML frontmatterの全フィールドを実コード付きで解説し、24時間稼働の自律開発デーモンで実際に運用して得た知見——ツール制限によるブラストラディウス制御、モデル使い分けによるコスト最適化、「CLAUDE.md指示の遵守率問題」への構造的解決策——を共有する。
Skills・Agent Teams・Subagents——3つの委譲レイヤーを整理する
Claude Codeには「タスクを委譲する」仕組みが3層ある。競合記事の多くがこの3つを混同しているので、最初に整理しておく。
Skillsは再利用可能なワークフロー定義だ。プロンプトテンプレートとして機能し、/commitや/reviewのようにスラッシュコマンドで呼び出す。定型作業の標準化に向いている。
Agent Teamsはマルチセッション協調の仕組みだ。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS環境変数を有効化した上で、通常のClaude Codeセッション内から自然言語でチーム作成を依頼する方式で、独立したセッション間で連携する。長時間の並列タスクに適している。
Subagentsはセッション内タスク委譲だ。Agent tool経由で同一プロセス内に子エージェントを起動し、結果を受け取る。親エージェントのコンテキストを消費せずに専門タスクを処理できる点が最大の強みだ。
使い分けの判断基準はシンプルで、以下のように考えるとよい。
code
定型ワークフローを標準化したい → Skills
独立した長時間タスクを別プロセスで実行 → Agent Teams
セッション中に専門タスクを委譲して結果を受け取りたい → Subagents
本記事が扱うのは3番目のSubagentsだ。
サブエージェント定義の基本——.claude/agents/にMarkdownを置くだけ
ファイル配置と読み込み優先順位
定義ファイルの読み込みには優先順位がある。
- Managed settings（組織管理者が配布）
--agentsCLIフラグで指定.claude/agents/（プロジェクトローカル）~/.claude/agents/（グローバル）- プラグインの
agents/ディレクトリ
プロジェクト固有のエージェントは.claude/agents/に、どのプロジェクトでも使う汎用エージェントは~/.claude/agents/に置くのが基本だ。ファイル名がそのままエージェント名になるので、kebab-case.mdで命名する。
最小構成で動かす
最小構成は驚くほどシンプルだ。.claude/agents/reviewer.mdを作成する。
markdown
---
name: reviewer
description: コードレビューを実行する読み取り専用エージェント
tools:
- Read
- Glob
- Grep
---
あなたはシニアエンジニアです。指定されたコードを読み、
バグ・セキュリティリスク・可読性の問題を指摘してください。
修正コードは書かず、問題点の指摘と改善提案のみ行ってください。
toolsにRead、Glob、Grepだけを指定しているため、このエージェントは構造的にファイルを編集できない。CLAUDE.mdに「編集するな」と書くより確実だ。
呼び出し方の違い
対話的に使うなら@reviewer このPRの変更をレビューしてと@メンションする。プログラム的に使うならAgent toolでsubagent_type: "reviewer"を指定する。@メンションは会話の流れで気軽に使え、Agent toolは自動化パイプラインに組み込むのに適している。
YAML frontmatter全フィールド徹底解説
identity系
| フィールド | 型 | 説明 |
|---|---|---|
name | string | エージェント名。@メンション時の識別子 |
description | string | エージェントの説明。親が委譲先を選ぶ際の判断材料になる |
color | string | ダッシュボードでの表示色 |
能力制御系
| フィールド | 型 | 説明 |
|---|---|---|
tools | string[] | 許可ツールのホワイトリスト。未指定=全許可、空配列=ツールなし |
disallowedTools | string[] | 禁止ツールのブラックリスト。toolsと併用時はdisallowedToolsが先に適用され、残りのツールプールに対してtoolsが解決される |
skills | string[] | 利用可能なSkillsの指定 |
mcpServers | object | サブエージェントに公開するMCPサーバーの指定 |
実行制御系
| フィールド | 型 | 説明 |
|---|---|---|
model | string | haiku / sonnet / opusのエイリアス、inherit（親モデル継承）、または完全なモデルID（例: claude-opus-4-6）を指定可能 |
permissionMode | string | default / acceptEdits / auto / dontAsk / bypassPermissions / plan |
maxTurns | number | 最大ターン数。無限ループ防止に必須 |
effort | string | 推論の深さ制御。low / medium / high / xhigh / maxから指定（利用可能なレベルはモデルに依存し、一部モデルでは特定レベルが利用不可） |
分離・安全系
| フィールド | 型 | 説明 |
|---|---|---|
isolation | string | worktree指定で一時的なgit worktreeで実行 |
hooks | object | PreToolUse / PostToolUseでサブエージェント固有のフック定義 |
memory | string | メモリのスコープ指定。user / project / localの3択 |
background | boolean | trueで非同期実行 |
初期化系
| フィールド | 型 | 説明 |
|---|---|---|
initialPrompt | string | エージェント起動時の初期プロンプト |
モデル解決の優先順位は4段階で、CLAUDE_CODE_SUBAGENT_MODEL環境変数 → Agent tool呼び出し時のmodelパラメータ → frontmatterのmodel → 親セッションのモデル、の順に評価される。
全フィールドを活用した実用例を示す。
markdown
---
name: security-reviewer
description: セキュリティ観点でコードレビューを行う専門エージェント
color: red
tools:
- Read
- Glob
- Grep
disallowedTools:
- Bash
- Edit
- Write
model: opus
permissionMode: default
maxTurns: 30
effort: high
isolation: worktree
background: false
---
あなたはセキュリティ専門のコードレビュアーです。
OWASP Top 10を基準に、以下の観点でコードを精査してください:
- SQLインジェクション、XSS、コマンドインジェクション
- 認証・認可の欠陥
- 機密情報のハードコード
- 依存パッケージの既知脆弱性
重大度（Critical/High/Medium/Low）を付けて報告してください。
Worktree分離による安全な並列実行パターン
なぜWorktreeが必要か
複数のサブエージェントが同じリポジトリで同時に作業すると、ファイル競合が発生する。エージェントAがsrc/utils.tsを編集中にエージェントBも同じファイルを変更すれば、どちらかの変更が失われる。ブランチも汚染される。
isolation: worktreeの動作メカニズム
isolation: worktreeを指定すると、gitが一時的なworktreeを作成し、完全に独立したディレクトリで作業が行われる。サブエージェントが変更を加えなければworktreeは自動クリーンアップされ、変更があればパスとブランチ名が結果として返される。
並列実行の実践パターン
レビュー・テスト生成・リファクタリングを3エージェント同時に走らせる例を示す。正直、これが動いた時は感動した。
markdown
<!-- .claude/agents/test-generator.md -->
---
name: test-generator
description: 指定モジュールのユニットテストを生成する
tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
model: sonnet
maxTurns: 20
isolation: worktree
---
指定されたモジュールに対してvitestのユニットテストを生成してください。
既存のテストパターンに合わせ、エッジケースも網羅してください。
テストファイルは __tests__/ ディレクトリに配置してください。
markdown
<!-- .claude/agents/refactorer.md -->
---
name: refactorer
description: コードのリファクタリングを実行する
tools:
- Read
- Glob
- Grep
- Edit
- Write
- Bash
model: sonnet
maxTurns: 25
isolation: worktree
---
指定されたモジュールをリファクタリングしてください。
変更後は必ず npm run build && npm test を実行して動作確認してください。
Agent toolから3つを並列起動する場合、親エージェントは以下のように呼び出す。
code
# 3つのサブエージェントを同時に起動（Agent tool × 3を1メッセージで）
- reviewer: isolation: worktree でコードレビュー
- test-generator: isolation: worktree でテスト生成
- refactorer: isolation: worktree でリファクタリング
各エージェントは独立したworktreeで作業するため、互いの変更が干渉しない。完了後、親エージェントが各worktreeの結果を確認し、必要に応じてcherry-pickやマージを行う。
ツール制限でブラストラディウスを制御する
「CLAUDE.md指示の遵守率問題」とは何か
CLAUDE.mdに「config/ディレクトリのファイルは編集しないでください」と書いても、エージェントがその指示を無視するケースがある。自然言語の指示には遵守率の限界があり、これは仕組み上避けられない。
構造的な解決策
サブエージェントのtools制限は、ツール呼び出し自体を構造的にブロックする。自然言語の「お願い」ではなく、システムレベルの「禁止」だ。これにより遵守率は100%になる。
3種の権限分離パターンを示す。
markdown
<!-- .claude/agents/analyzer.md — 読み取り専用 -->
---
name: analyzer
description: コードベースを分析し、レポートを生成する
tools:
- Read
- Glob
- Grep
model: haiku
maxTurns: 15
---
コードベースを分析し、構造・依存関係・潜在的問題を報告してください。
ファイルの編集は行わず、分析結果のみ返してください。
markdown
<!-- .claude/agents/editor.md — 編集専用（シェル実行禁止） -->
---
name: editor
description: 指定された変更をコードに適用する
tools:
- Read
- Glob
- Grep
- Edit
- Write
disallowedTools:
- Bash
model: sonnet
maxTurns: 20
---
指示された変更をコードに正確に適用してください。
シェルコマンドの実行は必要ありません。コード編集に集中してください。
markdown
<!-- .claude/agents/runner.md — 実行専用 -->
---
name: runner
description: テスト実行とビルド確認を行う
tools:
- Bash
- Read
model: haiku
maxTurns: 10
---
指定されたテストスイートまたはビルドコマンドを実行し、
結果を報告してください。ファイルの編集は行いません。
この3分割は個人的にかなり気に入っている。analyzerで問題を特定し、editorで修正し、runnerでビルド確認——という流れが、人間のコードレビュープロセスとよく似ている。
モデル使い分けとコスト最適化
haiku / sonnet / opusの使い分け指針
| モデル | 得意なタスク | コスト感 |
|---|---|---|
haiku | ファイル検索、パターンマッチ、分類、簡単な分析 | 最低 |
sonnet | コードレビュー、テスト生成、一般的な実装 | 中程度 |
opus | アーキテクチャ設計、複雑なリファクタリング、セキュリティ監査 | 最高 |
自律開発デーモンでの運用実績から言えるのは、探索系タスクをhaikuに委譲するだけで親のopusコンテキストを大幅に節約できるという点だ。ファイル検索や簡単な分析にopusを使う必要はない。
effortフィールドとの組み合わせも有効で、haiku+high effortはsonnet+low effortと近い品質になるケースがある。タスクの複雑さに応じて調整するとよい。
markdown
<!-- 探索用: 低コストで高速 -->
---
name: explorer
description: コードベースの高速探索
model: haiku
maxTurns: 10
tools: [Read, Glob, Grep]
---
<!-- 実装用: バランス重視 -->
---
name: implementer
description: 機能実装
model: sonnet
maxTurns: 30
---
<!-- 設計判断用: 品質最優先 -->
---
name: architect
description: アーキテクチャ設計と判断
model: opus
maxTurns: 20
tools: [Read, Glob, Grep]
---
よくあるハマりポイントとトラブルシューティング
Q: 定義ファイルが読み込まれない
ファイル名にスペースや大文字を使うと認識されないことがある。kebab-case.mdで統一すること。また、frontmatterの---の前に空行やBOMがあると解析に失敗する。
Q: permissionModeで制限をかけたのに効かない
親セッションがbypassPermissions、acceptEdits、またはautoで起動している場合、子エージェントでより制限的なdefaultにオーバーライドすることはできない。子エージェントのpermissionModeは無視され、親の設定が引き継がれる。これはセキュリティ上の仕様だ。ツール制限（tools/disallowedTools）で代替するのが現実的な解決策になる。
Q: worktreeが残り続ける
サブエージェントが変更を加えた場合、worktreeは自動クリーンアップされず残る。git worktree listで確認し、不要なものはgit worktree remove <path>で手動削除する。
Q: サブエージェントが無限ループする
maxTurnsを必ず設定すること。未設定だとエージェントが終了条件を見失い、延々とツールを呼び続ける可能性がある。実用上、読み取り専用なら10〜15、編集ありなら20〜30が目安だ。
Q: 親のコンテキストが急に消費される
サブエージェントは独立したコンテキストウィンドウで動作するため、親のコンテキストを直接消費しない。ただし、結果の返却時に親のコンテキストを消費する。大量の出力を返すサブエージェントには、プロンプトで「200語以内で要約して報告」と指示するのが効果的だ。
Q: backgroundモードの完了通知を受け取れない
background: trueで起動したサブエージェントは、完了時に自動で通知される。sleepやポーリングで待機する必要はない。通知が来るまで他の作業を進めればよい。
カスタムサブエージェントは「プロンプトで頼む」から「構造で制御する」へのパラダイムシフトだ。YAML frontmatterのtools制限は自然言語指示より確実にブラストラディウスを制御し、Worktree分離は並列実行の安全性を構造的に担保する。
まずは読み取り専用のコードレビューエージェントを1つ作るところから始めてほしい。.claude/agents/reviewer.mdを置いて@reviewerと呼ぶだけで、あなたのClaude Codeは「1人の万能アシスタント」から「専門チーム」に変わる。
もっと読む他の技術記事も読む