はじめに

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人で全部やる」ではなく「専門家に任せる」を習慣にすることで、品質と効率の両方を上げられます。

参考リンク

Claude Code 公式ドキュメント - Create custom subagents