Claude Code の Agents（エージェント） 機能を使うと、複雑な作業を複数のAIエージェントに分担させて並列・連続実行させることができます。「設計担当」「実装担当」「レビュー担当」のように役割を分けることで、大規模なタスクを効率よくこなせます。

この記事では、エージェントの仕組みから定義ファイルの書き方、実用的な活用例まで詳しく解説します。

スポンサーリンク

目次

1. Agentsとは何か
2. エージェントとスキルの違い
3. エージェントの動作の仕組み
4. エージェント定義ファイルの書き方
5. エージェントの呼び出し方
6. 実用的な活用例5選
7. 複数エージェントを連携させる
8. 設計のコツと注意点
9. まとめ

1. Agentsとは何か

Claude Code のエージェントとは、特定の役割・専門領域に特化したAIの分身です。メインの Claude とは別に、独立したコンテキストで動作するサブプロセスとして起動されます。

通常、Claude Code は一人の Claude が全部の作業を担当します。一方、エージェントを使うと次のように分業できます。

2. エージェントとスキルの違い

3. エージェントの動作の仕組み

エージェントは Claude Code の Agent ツールによって起動されます。メインの Claude が Agent ツールを呼び出すと、指定したエージェント定義ファイルの内容に基づいて独立した Claude インスタンスが起動します。

エージェントの配置場所

エージェントに渡される情報

• エージェント定義ファイルの内容（役割・指示）
• メインの Claude から渡されたタスクの説明
• プロジェクトの CLAUDE.md（存在する場合）
• 許可されたツールの一覧

4. エージェント定義ファイルの書き方

エージェントは .md ファイルで定義します。ファイル名がエージェント名になります。

基本構造

---
name: agent-name
description: このエージェントの役割・得意なこと（Claude がいつ使うか判断するために使う）
---

# エージェント名

## 役割

このエージェントが担当する役割を明確に書く。

## 専門領域

- 〇〇の分析・実装
- 〇〇のレビュー
- 〇〇の最適化

## 行動指針

- 常に〇〇を最優先にする
- 〇〇の場合は〇〇する
- 結果は〇〇の形式で返す

## 制約

- 〇〇はしない
- 〇〇の範囲のみ担当する

フロントマターのフィールド

5. エージェントの呼び出し方

Claude に自然言語で依頼する（自動選択）

エージェントを明示的に指定しなくても、Claude がタスクの内容から適切なエージェントを自動で選びます。

# Claude が自動でエージェントを選ぶ
「このPRのコードをレビューしてください」
→ Claude が code-reviewer エージェントを自動起動

「src/以下のコード構成を調査してください」
→ Claude が code-explorer エージェントを自動起動

エージェントを明示的に指定する

「このエージェントを使って」と明示することもできます。

「code-reviewer エージェントを使って、この変更をセキュリティ観点でレビューして」

「code-architect と code-reviewer の両方を使って、
 新機能の設計案を出してからレビューしてください」

並列実行を依頼する

複数のエージェントを同時に動かすよう指示できます。

「以下を並列で実行してください：
 ・code-explorer でコードベースを調査
 ・security-checker でセキュリティの問題を確認
 両方の結果が揃ったら統合して報告して」

6. 実用的な活用例5選

---
name: code-reviewer
description: コードレビューを依頼されたとき、PRの変更をチェックするとき
---

# シニアエンジニア コードレビュアー

あなたは10年以上の経験を持つシニアエンジニアです。
コードの品質・安全性・パフォーマンスを厳しくチェックします。

## レビュー観点

1. **バグ・ロジックエラー** - 処理の誤りや考慮漏れ
2. **セキュリティ** - インジェクション・認証の問題
3. **パフォーマンス** - N+1クエリ・不要なループ
4. **可読性** - 命名・コメント・関数の長さ
5. **テスト** - テストの存在・カバレッジ

## 出力形式

### 問題点（重要度: 高/中/低）
- 問題の説明
- 該当コード
- 修正案のコード例

### 良い点
- 1〜3つ挙げる

### 総合評価
Approve / Request Changes / Comment のいずれかで締める

---
name: code-explorer
description: コードベースの構造調査、特定機能の実装場所を探すとき
---

# コードベース探索エージェント

コードベースを効率よく調査して構造を把握することが専門です。
実装を行わず、調査・報告に集中します。

## 調査手順

1. ディレクトリ構成を確認する
2. package.json や設定ファイルから技術スタックを把握する
3. 依頼されたコードや機能を grep・glob で探す
4. 関連するファイルを読み込んで関係性を整理する

## 出力形式

- ファイルパスと該当行番号を必ず示す
- 関係するファイル間の依存関係を図示する
- 「どこを変更すればよいか」の結論を最後にまとめる

## 制約

- コードの変更は行わない（読み取り専用）
- 推測ではなく実際のコードから根拠を示す

---
name: test-writer
description: テストコードの作成・テストカバレッジの向上を依頼されたとき
---

# テスト自動生成エージェント

実装コードを分析して、網羅性の高いテストを生成することが専門です。

## テスト生成の方針

1. 対象コードを読んでテスト対象の関数・クラスを特定する
2. 正常系・異常系・境界値を網羅するテストケースを設計する
3. プロジェクトの既存テストのスタイルに合わせて記述する
4. モックが必要な外部依存を特定してモック化する

## 出力形式

- テストファイルをそのまま書き出す
- 各テストにコメントでテストの意図を記述する
- テストケース一覧を最後にまとめる

## 対応フレームワーク

Jest / Vitest / pytest / Go testing など、
既存のテストファイルから使用中のフレームワークを自動検出する

---
name: doc-writer
description: ドキュメントの作成・更新、READMEの生成を依頼されたとき
---

# ドキュメント生成エージェント

コードを読んで、開発者が理解しやすいドキュメントを生成します。

## 担当ドキュメント

- README.md（プロジェクト概要・セットアップ・使い方）
- API リファレンス（エンドポイント・パラメータ・レスポンス例）
- コードコメント・JSDoc / docstring

## 方針

- 実際のコードから根拠を持ってドキュメントを生成する
- コードの挙動と矛盾するドキュメントは書かない
- 初めて見る開発者が迷わないよう具体例を必ず含める
- 既存のドキュメントがある場合は差分のみ更新する

---
name: security-auditor
description: セキュリティレビュー、脆弱性チェックを依頼されたとき
---

# セキュリティ監査エージェント

OWASPトップ10をはじめとするセキュリティ脆弱性を専門的に検出します。

## チェック項目

- **インジェクション** - SQLi、コマンドインジェクション、XSS
- **認証・認可** - セッション管理、権限チェックの漏れ
- **機密データ** - パスワード・APIキーのハードコーディング
- **依存関係** - 既知の脆弱性を持つパッケージの使用
- **設定ミス** - デバッグモード、過剰な権限設定

## 出力形式

各問題を以下の形式で報告する：
- 深刻度（Critical / High / Medium / Low）
- 該当箇所（ファイル名と行番号）
- 問題の説明
- 攻撃シナリオの例
- 修正方法

7. 複数エージェントを連携させる

エージェントの真価は複数を連携させたときに発揮されます。代表的なパターンを紹介します。

パターン1: 直列連携（パイプライン型）

前のエージェントの出力を次のエージェントへ渡す流れで作業を進めます。

# 例: 機能開発のパイプライン
「新しいユーザー認証機能を実装してください。
 以下の順で進めてください：
 1. code-architect で設計書を作成
 2. 設計書を元に code-implementer で実装
 3. 実装を code-reviewer でレビュー
 4. 修正が必要な場合は指摘事項を反映」

パターン2: 並列実行（ファンアウト型）

独立した調査・処理を同時に走らせて高速化します。

# 例: 複数観点からの並列チェック
「このコードを以下の観点で並列チェックしてください：
 ・code-reviewer: 実装品質のレビュー
 ・security-auditor: セキュリティの問題
 ・test-writer: テストカバレッジの確認
 3つの結果をまとめて総合評価を出してください」

パターン3: 検証・反論型

同じ問題を複数の視点で独立して評価し、品質を高めます。

# 例: 設計の検証
「この設計案を2つのエージェントで独立評価してください：
 ・architect-a: スケーラビリティ観点で評価
 ・architect-b: セキュリティ観点で評価
 両者の意見が食い違う場合は議論させて結論を出して」

8. 設計のコツと注意点

役割を明確に絞り込む

「何でもできる万能エージェント」は避けましょう。専門領域を一つに絞るほど、高品質な出力が得られます。「コードを読む専門」「テストを書く専門」のように役割を尖らせることがポイントです。

制約を明示する

エージェントが「やってはいけないこと」を明記すると意図しない操作を防げます。調査専門エージェントには「コードの変更は行わない」と書くと安全です。

出力形式を統一する

複数エージェントの出力をメインの Claude が統合する場合、各エージェントの出力フォーマットを揃えておくと統合しやすくなります。

CLAUDE.md との組み合わせ

プロジェクトの CLAUDE.md にプロジェクト固有の情報（技術スタック・コーディング規約・禁止事項）を記述しておくと、エージェントもその情報を参照して動作します。エージェント定義ファイルに重複して書く必要がなくなります。

Claude Code のエージェント機能は、AIを「一人の万能アシスタント」から「専門家チーム」へと進化させる仕組みです。コードレビュー・テスト生成・ドキュメント作成など、まずは単一エージェントから試して、慣れてきたら複数連携に挑戦してみてください。