はじめに
Claude Codeを使っていて「大きな機能を一気に実装させると品質が落ちる」「レビューを自分でやるのが面倒」と感じたことはないでしょうか。カスタムエージェントを使えば、専門性を持ったAIアシスタントを定義し、役割分担させることができます。
本記事では、カスタムエージェントの定義方法から実践的な使い方までを解説します。
カスタムエージェントとは
カスタムエージェント（サブエージェント）は、メインのClaude Codeから呼び出せる「専門家AI」です。独立したコンテキストウィンドウを持ち、カスタムシステムプロンプト、特定のツールアクセス、独立した権限で動作します。
なぜカスタムエージェントが必要か
Claude Codeに大きなタスクをそのまま投げると、以下の問題が起きやすいです。
- コンテキストが膨らみすぎる: 1つのセッションで多くのファイルを扱うと精度が落ちる
- レビューが甘くなる: 自分で書いたコードを自分でチェックしても見落としがある
- 並列化できない: 1つずつ順番に実装するので時間がかかる
カスタムエージェントを使うことで、これらの問題を解決できます。
実際にやっていること
悩み: 1つの機能実装が大きすぎる
「ハッシュタグ機能を作って」と依頼すると、Claude Codeは一気に全部作ろうとします。結果として:
- PRが巨大になりレビューが大変
- 途中でコンテキストが溢れて品質が落ちる
- 何か問題があっても切り戻しが難しい
解決: 4つのエージェントで役割分担
私たちは以下の4つのエージェントを定義して、チーム開発のように作業を進めています。
| エージェント | 役割 | 実際にやること |
|---|---|---|
| planner | 計画者 | 「ハッシュタグ機能」→ 6つのPRに分割する計画を作成 |
| architect | 基盤担当 | Entity、Repository、Moduleなど土台を実装 |
| engineer | API担当 | 1つのAPIを完全に実装（TDD） |
| reviewer | 品質担当 | 実装をレビューして指摘 |
実際のフロー
ユーザー: 「ハッシュタグ機能を作って」
↓
planner: PR分割計画を作成
- PR1: 基盤（Entity, Repository Port, Module）
- PR2: createHashtag API
- PR3: getHashtag API
- PR4: getHashtags API（一覧）
- PR5: updateHashtag API
- PR6: deleteHashtag API
↓
architect: PR1（基盤）を実装
↓
reviewer: PR1をレビュー → 承認
↓
engineer x 5: PR2〜PR6を並列実装（TDD）
↓
reviewer: 各PRをレビュー
↓
完了
なぜこの構成にしたか
plannerとengineerを分けた理由:
最初は1つのエージェントで計画から実装までやらせていました。しかし「計画を立てながら実装も始める」と、計画がブレやすいことがわかりました。plannerにはEditを与えず、計画に集中させています。
reviewerを分けた理由:
engineerが自分で書いたコードを自分でレビューしても、見落としが多かったです。別のエージェントにレビューさせることで、「規約違反」「テスト不足」などを客観的に指摘できるようになりました。
ファイル構成
エージェント定義はMarkdownファイルで、YAMLフロントマターとシステムプロンプトで構成されます。
.claude/agents/
├── planner.md # PR分割計画
├── architect.md # 基盤実装
├── engineer.md # API実装
└── reviewer.md # コードレビュー
スコープと優先順位
| 配置場所 | スコープ | 優先度 |
|---|---|---|
--agents CLIフラグ |
現在のセッションのみ | 1（最高） |
.claude/agents/ |
現在のプロジェクト | 2 |
~/.claude/agents/ |
全プロジェクト共通 | 3 |
プラグインの agents/
|
プラグイン有効範囲 | 4（最低） |
同名のエージェントがある場合、優先度の高い方が使われます。
フロントマター仕様
必須フィールド
| フィールド | 説明 | 例 |
|---|---|---|
name |
一意の識別子（小文字とハイフン） | code-reviewer |
description |
いつ委譲すべきかの説明 | コードレビュー担当。品質検証を担当 |
オプションフィールド
| フィールド | 説明 | デフォルト |
|---|---|---|
tools |
使用可能なツール | 全ツール継承 |
disallowedTools |
禁止するツール | なし |
model |
sonnet / opus / haiku / inherit
|
inherit |
permissionMode |
権限モード | default |
skills |
事前読み込みするスキル | なし |
hooks |
ライフサイクルフック | なし |
ツール制限の設計
悩み: エージェントが余計なことをする
最初は全エージェントに全ツールを与えていました。すると:
- plannerが計画中に「ついでに実装も」と始めてしまう
- reviewerが「修正しておきました」と勝手に直す
役割がブレると、責任の所在が曖昧になります。
解決: 役割に応じてツールを制限
| エージェント | ツール | 制限の理由 |
|---|---|---|
| planner | Read, Glob, Grep, Write | Editがないので実装できない |
| architect | Read, Edit, Write, Glob, Grep, Bash | 実装に必要な全ツール |
| engineer | Read, Edit, Write, Glob, Grep, Bash | 実装に必要な全ツール |
| reviewer | Read, Glob, Grep | Editがないので修正できない |
ポイント:
- plannerにEditを与えない: 計画に集中させる
- reviewerにEditを与えない: 指摘だけさせ、修正はengineerに任せる
- 全員にTaskを与えない: サブエージェントの入れ子を防ぐ
定義例: reviewerエージェント
実際に使っているreviewerの定義を紹介します。
---
name: reviewer
description: PR単位でコードレビューを行うエージェント。品質検証、セキュリティチェック、コーディング規約準拠を確認
tools: Read, Glob, Grep
model: sonnet
---
あなたは品質保証の専門家です。PR単位で成果物をレビューします。
## 役割
- コーディング規約への準拠確認
- セキュリティチェック
- テストの網羅性確認
## レビュー観点
### コード品質
- [ ] CLAUDE.md の規約に準拠しているか
- [ ] 単一責任の原則が守られているか
### セキュリティ
- [ ] 機密情報がハードコードされていないか
- [ ] 入力値の検証が適切か
## 出力形式
### 総合評価
[承認 / 要修正 / 差し戻し]
### 指摘事項
| 重要度 | ファイル | 行 | 内容 | 修正案 |
|--------|----------|-----|------|--------|
| 必須 | xxx.ts | 42 | [問題点] | [修正案] |
## 心構え
- 建設的なフィードバック
- 「なぜダメか」だけでなく「どうすれば良いか」を示す
Tips
descriptionを詳細に書く
Claudeはdescriptionを見て委譲を判断します。「いつ使うべきか」を明確に書きましょう。
# 良い例
description: PR単位でコードレビューを行うエージェント。品質検証、セキュリティチェック、コーディング規約準拠を確認
# 悪い例
description: レビュー
CLAUDE.mdとの連携
システムプロンプト内で「CLAUDE.mdに従う」と明記すると、プロジェクトルールを引き継げます。
## コーディング規約
作業ディレクトリのCLAUDE.mdに必ず従う
/agentsコマンドで管理
/agents
エージェントの一覧表示、作成、編集、削除ができます。
まとめ
カスタムエージェントを使うことで、Claude Codeに役割分担させ、チーム開発のように作業を進められます。
- 1エージェント = 1専門性で焦点を絞る
- ツールは最小限に制限して役割をブレさせない
- descriptionを詳細に書いて適切な委譲を促す
-
.claude/agents/をGitで共有してチームで改善
「1人で全部やる」ではなく「専門家に任せる」を習慣にすることで、品質と効率の両方を上げられます。