Claude Codeの「エージェント」を理解する — スキルとの違いと使い分け
前回の記事では、Claude Codeでアプリ開発を始める前に整えるべき「安全設定」「スキル」「記憶の仕組み」を紹介しました。
今回はその続き。前回あえて触れなかった「エージェント」の話です。
結論から言うと、スキルが「知識カード」だとしたら、エージェントは「別の人格を持った専門家」です。Claude Codeが一人で全部やるのではなく、専門家チームに仕事を振る仕組み——それがエージェントです。
---
目次
- [スキルとエージェントは何が違うのか](#スキルとエージェントは何が違うのか)
- [エージェント定義を入れる — everything-claude-code](#エージェント定義を入れる--everything-claude-code)
- [claude-code-orchestraのエージェント構成](#claude-code-orchestraのエージェント構成)
- [実際にどう動くのか — 具体例で見る](#実際にどう動くのか--具体例で見る)
- [まとめ](#まとめ)
---
スキルとエージェントは何が違うのか
前回紹介した「スキル」と今回の「エージェント」は、混同しやすいですが役割がまったく違います。
| スキル | エージェント | |
|---|---|---|
| **たとえるなら** | マニュアル・参考書 | 別の人間（専門家） |
| **動き方** | Claude Code本体が参照して行動する | Claude Codeとは別に独立して動く |
| **記憶** | メインのClaude Codeと共有 | 自分専用の記憶空間を持つ |
| **得意なこと** | 「やり方」を教える | 「重い仕事」を並行して進める |
| **具体例** | mcp-builder, artifacts-builder | code-reviewer, codex-debugger |
イメージとしては、病院に例えるとこうなります：
- スキル = 診療ガイドライン（医師が参照して判断する）
- エージェント = 他の専門医へのコンサルト（判断そのものを任せる）
スキルはClaude Codeの「知識」を増やし、エージェントはClaude Codeの「手」を増やします。
---
エージェント定義を入れる — everything-claude-code
GitHub: affaan-m/everything-claude-code
エージェントを使うには、まずエージェント定義ファイルが必要です。これは .claude/agents/ フォルダに置く .md ファイルで、「どんな専門家か」「どのモデルを使うか」「どのツールを使えるか」を定義します。
everything-claude-codeは、アプリ開発に必要な36個以上のエージェント定義がまとまったリポジトリです。
インストール方法
git clone https://github.com/affaan-m/everything-claude-code.git
# agents/ フォルダの中身を ~/.claude/agents/ にコピー
cp everything-claude-code/agents/*.md ~/.claude/agents/
~/.claude/agents/ に置いたエージェントは、すべてのプロジェクトで自動的に使えるようになります。
私がインストールしているエージェント
36個すべてを入れる必要はありません。以下は私が実際に使っているものです。
コードレビュー系
| エージェント | モデル | 何をしてくれるか |
|---|---|---|
| **code-reviewer** | Sonnet | コード品質・セキュリティ・保守性を自動レビュー。コード変更のたびに使う |
| **security-reviewer** | Sonnet | セキュリティ脆弱性の検出に特化。認証やAPI実装時に自動発火 |
| **typescript-reviewer** | Sonnet | TypeScript/JavaScriptの型安全性、async/await、Node.jsセキュリティを専門チェック |
設計・計画系
| エージェント | モデル | 何をしてくれるか |
|---|---|---|
| **architect** | Sonnet | システム設計・スケーラビリティ・技術選定の判断を行う |
| **planner** | Sonnet | 複雑な機能やリファクタリングの実装計画を立てる |
テスト・品質系
| エージェント | モデル | 何をしてくれるか |
|---|---|---|
| **tdd-guide** | Sonnet | テスト駆動開発のワークフローを強制。テスト→実装→リファクタの順番を守らせる |
モバイル・言語特化系
| エージェント | モデル | 何をしてくれるか |
|---|---|---|
| **flutter-reviewer** | Sonnet | Flutter/Dartのウィジェット設計・状態管理・パフォーマンスをレビュー |
| **kotlin-reviewer** | Sonnet | Kotlin/Androidのコルーチン安全性・Composeパターンをレビュー |
| **swift-reviewer** | Sonnet | Swift/iOSのメモリ安全性・async/await・SwiftUIパターンをレビュー |
エージェント定義ファイルの中身
中身はシンプルなMarkdownです。たとえば code-reviewer.md はこんな構造です：
---
name: code-reviewer
description: コード品質・セキュリティ・保守性を自動レビュー
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---
（レビュー手順や判断基準の詳細がここに書かれている）
model: sonnet は「このエージェントはSonnet（軽量モデル）で動かす」という指定です。レビューや設計判断にはSonnetで十分ですし、コストも抑えられます。判断が特に重要な場面では model: opus（最上位モデル）を指定することもできます。
---
claude-code-orchestraのエージェント構成
GitHub: DeL-TaiseiOzaki/claude-code-orchestra
everything-claude-codeが「個々の専門家の定義」だとすれば、orchestraは「専門家チームの運用ルール」です。orchestraを導入すると、Claude Codeは「自分でコードを書く人」から「チームを指揮する人」に変わります。具体的には、3つの専用エージェントと2つの外部エージェントが追加されます。
3つの内蔵エージェント
これらは .claude/agents/ ディレクトリに定義ファイルとして配置されます。
1. general-purpose（汎用実行エージェント）
チームの「何でも屋」です。コード実装、リサーチ、コードベース分析、ドキュメント作成などを担当します。Opus（最上位モデル）の100万トークンのコンテキストを持つので、大規模なコードベースでも一度に把握できます。
使われる場面：
- 「このプロジェクト全体の構造を調べて」
- 「この機能を実装して」
- 「Webで最新情報を調べて」
2. codex-debugger（エラー分析エージェント）
エラーが出たときに自動で呼び出される「トラブルシューター」です。3ステップで動きます：
- エラーの周辺情報を収集する
- Codex CLI（OpenAI製）に原因分析を依頼する
- 修正を適用するか、手に負えなければ人間に報告する
使われる場面：
- テストが失敗したとき
- ビルドエラーが出たとき
- 実行時に想定外の動作をしたとき
3. gemini-explore（マルチモーダルエージェント）
PDF、動画、音声、画像といったテキスト以外のファイルを扱う専門家です。内部でGemini CLI（Google製）を使います。
使われる場面：
- 「この論文PDFの内容を要約して」
- 「この会議の録音を文字起こしして」
- 「このUI設計画像を分析して」
2つの外部エージェント
orchestraは、他社のAIも「チームメンバー」として組み込みます。
| エージェント | 提供元 | 得意なこと |
|---|---|---|
| **Codex CLI** | OpenAI（GPT-5.4） | 設計判断、推論、デバッグの根本原因分析 |
| **Gemini CLI** | PDF・動画・音声・画像の読み取り |
つまりorchestraは、Anthropic・OpenAI・Googleの3社のAIを1つのチームとして使う構成です。
自動ルーティング — 誰に振るかを自動判断
orchestraの最大の特徴は、あなたが「誰に頼むか」を考えなくていいことです。
.claude/hooks/agent-router.py というフック（自動トリガー）が、あなたの指示内容を見て適切なエージェントに振り分けます。
あなた：「この設計、どう思う？」
→ agent-router が「設計」を検知
→ Codex CLI に自動で振る
あなた：「このPDFの内容を教えて」
→ agent-router が「.pdf」を検知
→ Gemini に自動で振る
あなた：「ログイン画面を作って」
→ agent-router が「実装系」と判断
→ general-purpose エージェントに振る
9つの自動フック
ルーティング以外にも、orchestraには9つのフック（自動トリガー）が組み込まれています。
| フック | いつ動くか | 何をするか |
|---|---|---|
| **agent-router** | 指示を入力したとき | 適切なエージェントに自動振り分け |
| **error-to-codex** | コマンドがエラーを返したとき | エラーをCodexに自動送信して原因分析 |
| **lint-on-save** | ファイルを保存したとき | コード品質を自動チェック |
| **post-test-analysis** | テスト実行後 | テスト結果を自動分析 |
| **check-codex-before-write** | ファイルに書き込む前 | Codexに「この変更、大丈夫？」と確認 |
| **suggest-gemini-research** | Web検索しようとしたとき | マルチモーダルならGeminiを提案 |
| **post-implementation-review** | コード実装後 | 自動でコードレビュー |
| **check-codex-after-plan** | 計画作成後 | Codexに計画の妥当性を確認 |
| **log-cli-tools** | タスク完了時 | 使ったツールを記録 |
特に重要なのは error-to-codex と lint-on-save です。エラーが出ても自動で原因を調べてくれるので、非エンジニアでも「エラーで詰む」場面が大幅に減ります。
Agent Teams — チームで並行作業
orchestraには「Agent Teams」という仕組みがあり、複数のエージェントをチームとして同時に動かすことができます。
team-implement（並列実装）
大きな機能を作るとき、モジュールやレイヤーごとにエージェントを割り当てて並行実装します。
/team-implement
→ エージェントA：フロントエンド（画面）を担当
→ エージェントB：バックエンド（API）を担当
→ エージェントC：データベース部分を担当
（同時に作業し、完了後に統合）
team-review（並列レビュー）
実装が終わったら、3人の専門レビュアーが同時にコードをチェックします。
| レビュアー | チェック内容 |
|---|---|
| **Security Reviewer** | セキュリティ脆弱性（SQLインジェクション、XSSなど） |
| **Quality Reviewer** | コード品質（可読性、保守性、設計パターン） |
| **Test Reviewer** | テストカバレッジ（テストが十分か、漏れがないか） |
人間のコードレビューと同じように、異なる視点から同時にチェックするので、見落としが減ります。
---
実際にどう動くのか — 具体例で見る
「業務改善アプリを作りたい」という場面で、everything-claude-codeのエージェントとorchestraの仕組みがどう連携するかを見てみましょう。
ステップ1：設計（architect + Codex CLI）
あなた：「問診票アプリを作りたい。まず設計して」
→ agent-router が「設計」を検知
→ architect エージェントがアーキテクチャを検討
→ Codex CLI に設計判断を確認
→ 技術スタック・DB構成・API設計が決まる
ステップ2：計画（planner）
あなた：「設計に沿って実装計画を立てて」
→ planner エージェントがタスクを分解
→ 「フロント3タスク、バック4タスク、DB2タスク」に整理
→ 依存関係と実装順序を決定
ステップ3：実装（team-implement + general-purpose）
あなた：「計画どおり実装して」
→ team-implement でフロント・バック・DBを並行実装
→ 各モジュールを general-purpose エージェントが担当
ステップ4：レビュー（code-reviewer + security-reviewer + team-review）
→ code-reviewer：「コード品質OK、命名規則に一部違反あり」
→ security-reviewer：「SQLインジェクションの脆弱性なし」
→ team-review の Test Reviewer：「カバレッジ85%、十分」
ステップ5：エラー対応（codex-debugger）
テスト実行 → 2件失敗
→ error-to-codex フックが自動発火
→ codex-debugger が原因を特定
→ 修正を自動適用
この一連の流れで、あなたが手動で行うのは「指示を出す」と「最終確認する」だけです。
everything-claude-codeの専門エージェント（architect, planner, code-reviewer）が個々の判断を担い、orchestraの仕組み（ルーティング、フック、チーム実行）がそれらを自動で連携させる——この組み合わせがポイントです。
---
まとめ
| 仕組み | 提供元 | 役割 |
|---|---|---|
| **code-reviewer / security-reviewer** | everything-claude-code | コード品質・セキュリティの自動レビュー |
| **architect / planner** | everything-claude-code | 設計判断・実装計画 |
| **tdd-guide** | everything-claude-code | テスト駆動開発の強制 |
| **言語特化レビュアー** | everything-claude-code | TypeScript/Kotlin/Flutter/Swift専門チェック |
| **general-purpose** | orchestra | 実装・調査の汎用エージェント |
| **codex-debugger** | orchestra | エラー自動分析 |
| **gemini-explore** | orchestra | PDF・動画・音声の読み取り |
| **agent-router + 9フック** | orchestra | 自動振り分け・自動チェック |
| **team-implement / team-review** | orchestra | チームでの並列実装・並列レビュー |
前回の記事で紹介した「スキル」がClaude Codeの知識を広げるのに対し、「エージェント」はClaude Codeの手足を増やします。
導入の順番としては：
- まず everything-claude-code — code-reviewer と security-reviewer だけでも、AIが書いたコードの品質が格段に上がる
- 次に orchestra — プロジェクトが大きくなってきたら、ルーティングとチーム実行で自動化を進める
スキルだけでも十分に開発は進められますが、複数ファイルにまたがる実装やセキュリティレビューが必要になったとき、エージェントの仕組みが効いてきます。
「一人の優秀な医師」よりも「チーム医療」のほうが安全で効率的なのと同じです。Claude Codeも、チームで動かしたほうが強い。
---
参考リンク
- [前回の記事：Claude Codeでアプリ開発を始める前に整えるべき3つのこと](/posts/claude-code-dev-setup)
- everything-claude-code — エージェント定義集（36+エージェント）
- claude-code-orchestra — マルチエージェント構成テンプレート
- Claude Code 公式ドキュメント
議論のタイムライン
読み込み中...