Claude Codeサブエージェントの作り方｜カスタムエージェント実践ガイド

Claude Codeのカスタムサブエージェントを作成し、テスト自動化に活用する方法を実践的に紹介します。サブエージェントの概念やメリットについては前回の記事で解説しています。

カスタムサブエージェントの作成方法

カスタムサブエージェントを作成する方法は2つあります。

方法1：/agents コマンド（推奨）

最も簡単な方法です。Claude Codeの対話形式で、ステップバイステップでエージェントを作成できます。

手順：

1. Claude Codeで/agentsを実行
2. Create new agentを選択
3. スコープを選択：
   • Personal（~/.claude/agents/）→ 全プロジェクト共通
   • Project（.claude/agents/）→ 現在のプロジェクト専用
4. Generate with Claudeを選択し、エージェントの説明を入力
5. 使用可能なツールを選択
6. モデルを選択（sonnet / opus / haiku）
7. 保存して完了

方法2：Markdownファイルを手動作成

より細かい制御が必要な場合は、Markdownファイルを直接作成します。

ファイルの配置場所

ファイルの書き方

YAMLフロントマター + Markdownの形式で記述します。

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

設定可能なフィールド一覧

サブエージェントの呼び出し方法

作成したサブエージェントを呼び出す方法は3つあります。

1. 自動委譲

Claude Codeがタスクの内容とエージェントのdescriptionを照合し、自動的に適切なエージェントに委譲します。descriptionにuse proactivelyと書くと、より積極的に委譲されます。

2. 明示的な呼び出し

3. フォアグラウンド vs バックグラウンド

• フォアグラウンド：メイン会話をブロック。権限確認やユーザーへの質問が可能
• バックグラウンド：並行実行。事前に権限を承認し、未承認の操作は自動拒否
• Ctrl+Bで実行中のタスクをバックグラウンドに切り替え可能

実践例：テスト実行＋検証の分離

ここからは、「テスト実行と検証の分離」を実際にサブエージェントで実装する例を紹介します。

テスト実行エージェント

~/.claude/agents/test-executor.mdとして保存します。

name: test-executor
description: テストシナリオを実行する専門エージェント。画面操作テストやAPIテストを実行し、結果を記録する。
tools: Bash, Read, Write, Glob, Grep
model: sonnet
memory: project

あなたはテスト実行の専門家です。

役割:
1. テストシナリオを受け取り、忠実に実行する
2. 実行結果（スクリーンショット、ログ、レスポンス）を記録する
3. 結果のみを報告し、合否判定は行わない

重要:
- 合否の判断は絶対にしないでください
- 事実（実行結果）のみを正確に記録してください
- 期待値との比較は検証エージェントに委ねてください

ポイントは「合否判定は行わない」というルールです。結果の記録に徹することで、検証エージェントが客観的に判断できます。

結果検証エージェント

~/.claude/agents/test-validator.mdとして保存します。

name: test-validator
description: テスト結果を独立した視点で検証するエージェント。テスト実行エージェントの結果を受け取り、期待値と比較して合否を判定する。
tools: Read, Grep, Glob
model: sonnet
memory: project

あなたはテスト検証の専門家です。

役割:
1. テスト実行エージェントが記録した結果を読み取る
2. テストシナリオの期待値と実際の結果を比較する
3. 厳密な基準で合否を判定する

重要:
- 実行には関与していないため、客観的に判断してください
- 少しでも疑わしい結果はNGとしてください
- 判定理由を必ず明記してください

検証エージェントのツールは読み取り専用（Read, Grep, Glob）に制限しています。コードを修正する権限がないため、純粋な検証に集中できます。

使い方

Claude Codeで以下のように指示するだけです。

test-executorエージェントでUT01のテストシナリオを実行して、
結果をtest-validatorエージェントで検証してください

メインエージェントがこの指示を受け取ると、まずtest-executorにテストを実行させ、その結果をtest-validatorに渡して検証させるという流れを自動的に組み立ててくれます。

実践例：Backlog連携テスト

MCPサーバーと連携したテストエージェントも作成できます。以下はBacklogのチケット操作をテストする例です。

name: backlog-tester
description: Backlogにチケットを登録し、登録結果を検証するテストエージェント
tools: Bash, Read, Write
mcpServers: backlog
model: sonnet

Backlog MCPサーバーを使用してチケット操作のテストを行う。

手順:
1. テストデータでチケットを登録
2. 登録結果を取得して検証
3. テストデータをクリーンアップ

mcpServersにBacklogを指定することで、このエージェントだけがBacklog MCPにアクセスできるようになります。

永続メモリ機能

サブエージェントには永続メモリ機能があり、会話をまたいで知見を蓄積できます。

例えば、コードレビューエージェントにmemory: projectを設定すると、レビュー時に発見したパターンや規約を記録し、次回以降のレビューに活用できます。

注意事項とTips

• ネスト不可：サブエージェントは他のサブエージェントを生成できません。チェーンする場合はメイン会話から順次呼び出します
• 重複管理：役割の近いエージェントが複数あると、意図しないエージェントが呼び出される可能性があります。目的が重複しないよう整理しましょう
• Desktop vs CLI：デスクトップ版ではプロジェクトごとのエージェント管理が制限される場合があります。CLIの方がより柔軟に設定できます
• セッション再起動：エージェントファイルを手動で追加した場合、セッションの再起動が必要です
• 結果の返却：サブエージェントの結果はメイン会話のコンテキストに返されるため、大量の結果を返すとコンテキストを消費します

まとめ

• サブエージェントは/agentsコマンドまたはMarkdownファイルで作成可能
• 自動委譲と明示的呼び出しの2つの呼び出し方法がある
• テスト自動化では実行と検証を分離するのがベストプラクティス
• 永続メモリで知見を蓄積し、エージェントを賢くできる
• MCP連携でBacklog等の外部ツールとの連携テストも可能

サブエージェントを活用することで、AIの品質管理を一段階上のレベルに引き上げることができます。まずはテスト実行と検証の分離から始めてみてはいかがでしょうか。