0:00 0:00
記事
Claude Code用カスタムエージェントの作り方と役割設計
Claude Codeのカスタムサブエージェントをゼロから作る手順を解説します。ファイル形式・配置場所・frontmatterフィールド・ツール制御・モデル選択・呼び出し方まで、実践的なテンプレートとともに整理します。
「コードレビューをするたびに同じ指示を書いている」「特定のモジュールを調査する専用エージェントが欲しい」――そんなときがカスタムサブエージェントを作るサインです。この記事ではClaude CodeのカスタムサブエージェントをMarkdownファイル一枚から始める手順と、効果的な役割設計のポイントを解説します。
カスタムサブエージェントを作るべき場面
まず、以下に1つでも当てはまったら定義ファイルを作る価値があります。
- 同じ種類の依頼（「レビューして」「テスト書いて」など）を毎回違う表現で頼んでいる
- 特定のタスクに使うツールを制限したい（たとえば調査専用エージェントには書き込みを禁止）
- 安いHaikuモデルで十分な処理を誰かがSonnetで実行している
- チームで共通の動作基準を持つエージェントを共有したい
逆に、一度きりのアドホックな作業や、インタラクティブな往復が必要な作業にはカスタムエージェントより直接依頼が向いています。判断基準は「Claude Codeのサブエージェントはいつ使うべき？」を参照してください。
ファイル形式：YAMLフロントマター＋Markdownシステムプロンプト
カスタムエージェントはMarkdownファイルです。YAMLフロントマターで設定を書き、その下に本体のシステムプロンプトを書きます。
---
name: code-reviewer
description: コードレビュー専門エージェント。コード変更後にすぐ呼び出して使う。
tools: Read, Grep, Glob, Bash
model: sonnet
---
あなたはシニアコードレビュアーです。
変更されたコードの品質・セキュリティ・保守性を確認します。
起動したら：
1. git diffで変更を確認する
2. 変更ファイルをレビューする
3. 優先度別（Critical/Should/Nit）で指摘をまとめる
ファイルの作成・編集は行わない。必須フィールドは2つだけ
nameとdescriptionだけあれば動きます。残りはすべて省略可能です。
| フィールド | 必須 | 説明 |
|---|---|---|
name | ✅ | 小文字とハイフンのみ。@-mentionで使う名前になる |
description | ✅ | Claudeがいつこのエージェントを使うか判断する基準。「Use proactively」と書くと積極的に使われる |
tools | - | 使えるツールのallowlist。省略すると親会話のツールをすべて継承 |
disallowedTools | - | 除外するツール。toolsと両方指定した場合はdisallowedToolsが先に適用される |
model | - | sonnet / opus / haiku / フルモデルID / inherit（デフォルト） |
permissionMode | - | default / acceptEdits / auto / planなど |
maxTurns | - | エージェントが実行できるターン数の上限 |
isolation | - | worktreeにするとgit worktreeの独立コピーで動く |
memory | - | user / project / local。セッション間で記憶を保持する |
color | - | タスクリストでの表示色（blue, green, redなど） |
skills | - | 起動時にロードするSkillのリスト |
hooks | - | エージェントのライフサイクルフックの定義 |
保存場所：スコープで使い分ける
ファイルの置き場所によって有効範囲が変わります。同じnameのエージェントが複数ある場合は、上の行が優先されます。
| 場所 | スコープ | 用途 |
|---|---|---|
| Managed settings | 組織全体 | 管理者がポリシーとして配布 |
--agents CLIフラグ | そのセッションのみ | テストや自動化スクリプト |
.claude/agents/ | 現在のプロジェクト | プロジェクト固有の役割（Gitで共有） |
~/.claude/agents/ | 自分のすべてのプロジェクト | 個人の定番エージェント |
チームで使うエージェントは.claude/agents/に置いてGit管理するのが公式の推奨です。プロジェクトルートのディレクトリを自動的に発見します。
ユーザーレベル（~/.claude/agents/）はコードレビュアーやデバッガーなど、どのプロジェクトでも使い回せる汎用エージェントに向いています。
/agentsコマンドで手軽に作る
手動でファイルを書く前に、/agentsコマンドのUIを試すと設定の感触がつかめます。
/agents 「Library」タブ→「Create new agent」→「Generate with Claude」の順に進むと、エージェントの用途を日本語で説明するだけでClaudeがname・description・システムプロンプトを生成してくれます。生成されたファイルを手動で調整するワークフローが効率的です。
新しくファイルを手動追加した場合はセッションの再起動か/agentsコマンドで即時読み込みができます。
ツール制御：最小権限の原則
エージェントに必要以上のツールを与えると、意図しない変更が起きるリスクがあります。調査専用エージェントには読み取り系だけを許可するのが基本です。
allowlist（toolsフィールド）
---
name: repo-scout
description: コードベースを横断的に調査する専門エージェント。変更は行いません。
tools: Read, Grep, Glob, Bash
---toolsを指定するとそこに挙げたツールのみ使えます。WriteもEditも使えなくなるため、調査専用エージェントに適しています。
denylist（disallowedToolsフィールド）
---
name: no-writes
description: 書き込み操作だけ除外したいエージェント。
disallowedTools: Write, Edit
---disallowedToolsは親の全ツールからそれだけ除外します。MCPツールなど全部引き継ぎたいが書き込みだけ禁止したいときに使います。
主なツール名
| ツール名 | 概要 |
|---|---|
Read | ファイル読み取り |
Write | ファイル作成・上書き |
Edit | ファイル部分編集 |
Bash | シェルコマンド実行 |
Grep | ファイル内容の検索 |
Glob | ファイルパターンマッチ |
Agent | 別のサブエージェントを起動（メインスレッドで動く場合のみ） |
モデル選択でコストとスピードを調整
エージェントに必要な処理の複雑さに合わせてモデルを選びます。
| モデル | 速度 | 費用 | 向くケース |
|---|---|---|---|
haiku | 速い | 安い | ファイル検索・キーワード調査・単純なフォーマット整理 |
sonnet | 標準 | 標準 | コードレビュー・テスト生成・デバッグ |
opus | 遅め | 高い | セキュリティ深掘り・アーキテクチャ相談・複雑な推論 |
inherit | 親と同じ | 親と同じ | 省略時のデフォルト |
調査系エージェントはhaiku、品質チェック系はsonnetという使い分けが費用対効果が高いです。opusはコストが高いので、精度がクリティカルなセキュリティレビューなど限定した場面で使います。
実践テンプレート集
コードレビュアー（Read-only）
---
name: code-reviewer
description: コードの品質・セキュリティ・保守性をレビューする。コード変更後にproactivelyに使う。
tools: Read, Grep, Glob, Bash
model: sonnet
---
あなたはシニアコードレビュアーです。
起動したら：
1. git diffで変更内容を確認する
2. 変更ファイルにフォーカスする
レビュー観点：
- 可読性・命名・重複コード
- エラーハンドリング・入力バリデーション
- APIキーやパスワードの露出
- テストカバレッジ・性能上の問題
指摘は優先度別で報告：
- Critical（必ず修正）
- Should（できれば修正）
- Nit（検討推奨）
ファイルの編集・作成は行わない。デバッガー（修正あり）
---
name: debugger
description: エラー・テスト失敗・予期しない動作のデバッグ専門。問題発生時にproactivelyに使う。
tools: Read, Edit, Bash, Grep, Glob
---
あなたはデバッグ専門エージェントです。
起動したら：
1. エラーメッセージとスタックトレースを取得する
2. 再現手順を特定する
3. 仮説を立てて最小限の修正を行う
4. 修正後にテストで確認する
出力：
- 根本原因の説明と根拠
- 修正内容（変更前→変更後）
- 再発防止のための提案調査専用（軽量・Haiku）
---
name: repo-scout
description: コードベースの構造・パターン・依存関係を調査・報告する。変更は行わない。
tools: Read, Grep, Glob, Bash
model: haiku
---
あなたはコードベース調査エージェントです。
指定されたパターン・ファイル・構造を検索し、以下の形式で報告します：
- 発見件数と該当ファイルの一覧
- 代表的なコードスニペット（最大3件）
- 注目すべき点・推奨確認箇所
ファイルの作成・編集・削除は一切行いません。呼び出し方：3つのパターン
カスタムエージェントを呼び出すには次の3つがあります。
自然言語で名前を指定する
もっとも手軽です。Claudeがdescriptionを読んで委譲するかどうか判断します。
code-reviewerエージェントで最近の変更をレビューしてください@-mentionで確実に呼び出す
@と入力すると候補が出ます。選択するとそのエージェントへの委譲が確定します。
@code-reviewer 認証モジュールの変更をレビューしてセッション全体をそのエージェントとして起動する
--agentフラグを使うとセッション全体がそのエージェントの設定で動きます。
claude --agent code-reviewer プロジェクトのデフォルトに設定したい場合は.claude/settings.jsonに書きます。
{
"agent": "code-reviewer"
}よくある設計ミスと対処
| ミス | 対処 |
|---|---|
| descriptionが短すぎてClaudeが呼び出し判断を誤る | 「Use proactively after code changes」のように使うタイミングを明記する |
| 調査エージェントにWriteを残したまま修正が走った | tools: Read, Grep, Glob, Bashでallowlist明示 |
| Haikuにしたら複雑な推論が必要な場面で精度が落ちた | 単純な探索はHaiku、論理推論が必要な作業はSonnetに分ける |
| セッション間で記憶が引き継がれず毎回同じ調査をしている | memory: projectを設定して蓄積させる |
| ファイルを追加したのにエージェントが見つからない | セッション再起動か/agentsコマンドで再読み込み |
注意点として、サブエージェントは他のサブエージェントを起動できません（ネスト不可）。多段階の委譲が必要な場合は、メイン会話から順番に起動する設計にします。
まとめ：カスタムエージェント設計チェックリスト
定義ファイルを保存する前に確認する7項目です。
-
nameはユニークで小文字ハイフンのみか -
descriptionに「いつ使うか」が書いてあるか - ツールは最小権限にしているか（調査専用なら書き込みを除外）
- モデルはタスクの複雑さに合っているか
- チーム共有なら
.claude/agents/に置いてGit管理しているか - システムプロンプトに「やること」と「やらないこと」が両方書いてあるか
-
/agentsコマンドまたはclaude agentsで表示されるか確認したか
次に読むおすすめ記事：
- 「複数のAIエージェントで調査を並列化する実践パターン」：作成したカスタムエージェントを並列調査に活用する方法
- 「Claude Codeのサブエージェントとは？使いどころと注意点」：サブエージェントの仕組み・スコープ・built-in種類の全体像
