マルチエージェントの例

エージェントとは

エージェントは、特定のタスクに特化した独立したサブプロセスです。専門的なシステムプロンプトと制限されたツールセットを持ちます。

エージェントの利点

専門化: 各エージェントは特定の役割に特化
並列実行: 複数のエージェントを同時に実行可能
ツール制限: 各エージェントは必要最小限のツールのみ使用
再利用: 同じエージェントを異なるコンテキストで再利用

例1: code-explorer エージェント（シンプル）

ファイル: `plugins/feature-dev/agents/code-explorer.md`

---
name: code-explorer
description: Deeply analyzes existing codebase features
tools: Glob, Grep, Read, TodoWrite, WebFetch, WebSearch
model: sonnet
color: yellow
---

You are an expert code analyst specializing in tracing and understanding feature implementations.

## Core Mission
Provide a complete understanding of how a specific feature works by tracing its implementation from entry points to data storage.

## Analysis Approach

**1. Feature Discovery**
- Find entry points (APIs, UI components, CLI commands)
- Locate core implementation files
- Map feature boundaries and configuration

**2. Code Flow Tracing**
- Follow call chains from entry to output
- Trace data transformations at each step
- Identify all dependencies and integrations

**3. Architecture Analysis**
- Map abstraction layers (presentation → business logic → data)
- Identify design patterns and architectural decisions
- Document interfaces between components

**4. Implementation Details**
- Key algorithms and data structures
- Error handling and edge cases
- Performance considerations

## Output Guidance

Provide a comprehensive analysis that includes:
- Entry points with file:line references
- Step-by-step execution flow
- Key components and their responsibilities
- Architecture insights
- List of files essential for understanding

解説

YAMLフロントマター

name: code-explorer
description: Deeply analyzes existing codebase features
tools: Glob, Grep, Read, TodoWrite, WebFetch, WebSearch
model: sonnet
color: yellow

フィールド:

name: エージェントの一意な名前
description: エージェントの説明
tools: 使用可能なツール（読み取り専用ツールのみ）
model: sonnet（バランス型）
color: ターミナル表示色

システムプロンプト

You are an expert code analyst...

エージェントの役割と振る舞いを定義します。

使用方法

コマンドから起動:

Launch a code-explorer agent to analyze the authentication feature.

実行フロー:

1. メインプロセスが code-explorer エージェントを起動
   ↓
2. エージェントが専門プロンプトで実行開始
   ↓
3. Glob, Grep, Read ツールでコードベースを探索
   ↓
4. 分析結果を返却
   ↓
5. メインプロセスが結果を受け取る

例2: 並列マルチエージェント（feature-dev）

コマンド: `plugins/feature-dev/commands/feature-dev.md`

---
description: Guided feature development
---

## Phase 2: Codebase Exploration

**Goal**: Understand relevant existing code and patterns

**Actions**:
1. Launch 2-3 code-explorer agents in parallel. Each agent should:
   - Trace through the code comprehensively
   - Target a different aspect of the codebase
   - Include a list of 5-10 key files to read

   **Example agent prompts**:
   - "Find features similar to [feature] and trace implementation"
   - "Map architecture and abstractions for [feature area]"
   - "Analyze current implementation of [existing feature]"

2. Once agents return, read all files identified by agents
3. Present comprehensive summary of findings

並列実行の仕組み

メインプロセス
   ↓
   ├─→ code-explorer #1: "Find similar features"
   ├─→ code-explorer #2: "Map architecture"
   └─→ code-explorer #3: "Analyze UI patterns"
   ↓
   [並列実行]
   ↓
   ├─← 結果1: 類似機能のリスト + ファイルリスト
   ├─← 結果2: アーキテクチャマップ + ファイルリスト
   └─← 結果3: UIパターン分析 + ファイルリスト
   ↓
メインプロセスが全結果を統合

例: 3つの並列エージェント

ユーザーリクエスト:

/feature-dev Add dark mode to settings

Phase 2 で起動される3つのエージェント:

Agent 1: 類似機能の探索

Prompt: Find features similar to theme switching and trace their implementation comprehensively.

Tasks:
- Search for existing theme/style switching code
- Trace how settings are persisted
- Identify UI components involved

Expected output:
- List of similar features
- Implementation patterns
- 5-10 key files to read

Agent 2: アーキテクチャ分析

Prompt: Map the architecture and abstractions for the settings system, tracing through the code comprehensively.

Tasks:
- Identify settings storage mechanism
- Map state management approach
- Trace configuration flow

Expected output:
- Architecture diagram (text)
- Key abstractions
- 5-10 key files to read

Agent 3: UI パターン分析

Prompt: Analyze UI patterns for settings pages and theme customization.

Tasks:
- Identify UI component patterns
- Find styling approaches
- Locate theme configuration

Expected output:
- UI patterns used
- Styling conventions
- 5-10 key files to read

結果の統合

All agents complete
   ↓
メインプロセス receives:
   - 15-30 key files to read
   - Multiple perspectives on the codebase
   - Comprehensive understanding
   ↓
メインプロセス:
   - Reads all identified files
   - Synthesizes findings
   - Proceeds to next phase

例3: 逐次マルチエージェント（設計 → 実装 → レビュー）

Phase 4: Architecture Design

**Actions**:
1. Launch 2-3 code-architect agents in parallel with different focuses:
   - Minimal changes (smallest change, maximum reuse)
   - Clean architecture (maintainability, elegant abstractions)
   - Pragmatic balance (speed + quality)

2. Review all approaches
3. Present to user with recommendation

Phase 7: Review

**Actions**:
1. Launch code-reviewer agent to review implementation
2. Address any issues found
3. Re-run tests if needed

逐次実行フロー

Phase 4: Architecture Design
   ↓
   ├─→ code-architect #1: "Minimal changes approach"
   ├─→ code-architect #2: "Clean architecture approach"
   └─→ code-architect #3: "Pragmatic approach"
   ↓
   [並列実行]
   ↓
   結果を受け取り、ユーザーに提示
   ↓
Phase 5: Implementation
   ↓
   選択されたアプローチで実装
   ↓
Phase 6: Testing
   ↓
   テストを実行
   ↓
Phase 7: Review
   ↓
   code-reviewer エージェントを起動
   ↓
   レビュー結果を受け取る
   ↓
   問題があれば修正

例4: code-architect エージェント

ファイル: `plugins/feature-dev/agents/code-architect.md`

---
name: code-architect
description: Designs feature architectures and implementation blueprints
tools: Read, TodoWrite
model: sonnet
color: blue
---

You are an expert software architect specializing in designing elegant, maintainable solutions.

## Core Mission
Design a clear implementation blueprint for a feature, considering the existing codebase patterns, constraints, and best practices.

## Design Approach

**1. Requirements Analysis**
- Understand the feature requirements
- Identify constraints and edge cases
- Consider performance and scalability

**2. Architecture Options**
- Propose 2-3 different architectural approaches
- Analyze trade-offs for each approach
- Recommend the best approach with reasoning

**3. Implementation Blueprint**
- File structure and new files needed
- Key interfaces and contracts
- Data flow and state management
- Integration points with existing code

**4. Risk Assessment**
- Potential pitfalls and how to avoid them
- Testing strategy
- Migration path if needed

## Output Guidance

Provide:
- Clear architectural decision with reasoning
- Step-by-step implementation plan
- Pseudo-code or interface definitions
- Files to create/modify

特徴

ツール制限:

tools: Read, TodoWrite

設計エージェントは：

✅ ファイルを読める（Read）
✅ TODOを管理できる（TodoWrite）
❌ ファイルを編集できない（Edit, Writeなし）

理由: 設計フェーズでは実装すべきではないため。

例5: code-reviewer エージェント

ファイル: `plugins/feature-dev/agents/code-reviewer.md`

---
name: code-reviewer
description: Reviews code for bugs, quality issues, and project conventions
tools: Glob, Grep, Read, Bash(npm test:*), Bash(git diff:*)
model: sonnet
color: red
---

You are an expert code reviewer focused on quality, correctness, and maintainability.

## Core Mission
Thoroughly review code for bugs, style issues, missing tests, and architectural concerns.

## Review Approach

**1. Correctness**
- Logic errors and bugs
- Edge cases and error handling
- Type safety

**2. Code Quality**
- Readability and maintainability
- Code duplication
- Naming conventions

**3. Testing**
- Test coverage
- Missing test cases
- Test quality

**4. Architecture**
- Consistency with existing patterns
- Separation of concerns
- Potential tech debt

## Output Guidance

Provide:
- Categorized list of issues (critical, important, nice-to-have)
- Specific file:line references
- Suggested fixes
- Overall assessment

特徴

ツール制限:

tools: Glob, Grep, Read, Bash(npm test:*), Bash(git diff:*)

レビューエージェントは：

✅ コードを読める
✅ テストを実行できる
✅ diffを確認できる
❌ ファイルを編集できない（レビューのみ）

エージェント設計パターン

パターン1: Read-Only Explorer

用途: コードベース探索、分析

tools: Glob, Grep, Read, TodoWrite

例: code-explorer

パターン2: Design-Focused

用途: アーキテクチャ設計、計画

tools: Read, TodoWrite

例: code-architect

パターン3: Review-Focused

用途: コードレビュー、品質チェック

tools: Glob, Grep, Read, Bash(test:*), Bash(git diff:*)

例: code-reviewer

パターン4: Implementation-Focused

用途: 実装、ファイル編集

tools: Glob, Grep, Read, Edit, Write, Bash, TodoWrite

例: メインプロセス（通常のClaude Code）

マルチエージェントのベストプラクティス

1. 明確な役割分担

❌ 悪い例: すべてのエージェントが同じツールセット

# すべてのエージェントが編集可能
agent1: tools: Glob, Grep, Read, Edit, Write
agent2: tools: Glob, Grep, Read, Edit, Write
agent3: tools: Glob, Grep, Read, Edit, Write

✅ 良い例: 役割に応じたツールセット

explorer: tools: Glob, Grep, Read         # 探索のみ
architect: tools: Read, TodoWrite         # 設計のみ
reviewer: tools: Read, Bash(test:*)       # レビュー + テスト

2. 並列実行の活用

❌ 悪い例: 逐次実行（遅い）

1. Launch explorer agent
2. Wait for result
3. Launch another explorer agent
4. Wait for result

✅ 良い例: 並列実行（速い）

Launch 3 explorer agents in parallel:
- Agent 1: Find similar features
- Agent 2: Map architecture
- Agent 3: Analyze UI patterns

3. 適切なモデル選択

タスク	推奨モデル	理由
シンプルな探索	`haiku`	高速、低コスト
複雑な分析	`sonnet`	バランス型
重要な設計判断	`opus`	最高品質

4. 明確な出力期待

❌ 悪い例: 曖昧な指示

Launch an agent to analyze the code.

✅ 良い例: 具体的な出力要求

Launch code-explorer agent to:
1. Find authentication-related code
2. Trace login flow from API to database
3. Return a list of 5-10 key files to read

実装例: カスタムマルチエージェントワークフロー

目標: `/api-review` コマンド

APIエンドポイントを複数の観点でレビューする。

ファイル構成

plugins/api-review/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── api-review.md
├── agents/
│   ├── security-reviewer.md
│   ├── performance-reviewer.md
│   └── api-design-reviewer.md
└── README.md

commands/api-review.md

---
description: Comprehensive API endpoint review
argument-hint: API endpoint path or file
---

# API Review Workflow

## Phase 1: Gather Context

- Target API: $ARGUMENTS
- Recent changes: !`git diff HEAD`

## Phase 2: Multi-Perspective Review

Launch 3 specialized reviewer agents in parallel:

1. **security-reviewer**: Check for security vulnerabilities
2. **performance-reviewer**: Analyze performance implications
3. **api-design-reviewer**: Review API design and consistency

Each agent should provide:
- Specific issues with file:line references
- Severity level (critical/important/nice-to-have)
- Recommended fixes

## Phase 3: Consolidate Findings

After all agents complete:
1. Consolidate all findings
2. Prioritize issues by severity
3. Present actionable recommendations

agents/security-reviewer.md

---
name: security-reviewer
description: Reviews APIs for security vulnerabilities
tools: Glob, Grep, Read
model: sonnet
color: red
---

You are a security expert specializing in API security.

## Review Checklist

**Authentication & Authorization**
- Proper authentication checks
- Authorization for all endpoints
- Token validation

**Input Validation**
- SQL injection prevention
- XSS prevention
- Input sanitization

**Data Protection**
- Sensitive data encryption
- Proper error messages (no data leaks)
- HTTPS enforcement

## Output Format

Provide findings in this format:

### Critical Issues
- [file:line] Description and recommended fix

### Important Issues
- [file:line] Description and recommended fix

### Nice-to-have Improvements
- [file:line] Description and recommended fix

agents/performance-reviewer.md

---
name: performance-reviewer
description: Reviews APIs for performance issues
tools: Glob, Grep, Read
model: sonnet
color: yellow
---

You are a performance expert specializing in API optimization.

## Review Checklist

**Database Queries**
- N+1 query problems
- Missing indexes
- Inefficient queries

**Caching**
- Appropriate use of caching
- Cache invalidation strategy

**Response Size**
- Pagination for large datasets
- Unnecessary data in responses

## Output Format

[Same as security-reviewer]

agents/api-design-reviewer.md

---
name: api-design-reviewer
description: Reviews API design and consistency
tools: Glob, Grep, Read
model: sonnet
color: blue
---

You are an API design expert.

## Review Checklist

**RESTful Design**
- Proper HTTP methods
- Consistent URL patterns
- Appropriate status codes

**Consistency**
- Naming conventions
- Error response format
- Data structure consistency

**Documentation**
- API documentation completeness
- Example requests/responses

## Output Format

[Same as security-reviewer]

使用例

claude

# プロンプトで
/api-review /api/users

実行フロー

1. ユーザーが /api-review /api/users を実行
   ↓
2. コマンドが Context を収集
   - git diff で最近の変更を確認
   ↓
3. 3つのレビューエージェントを並列起動
   ├─→ security-reviewer
   ├─→ performance-reviewer
   └─→ api-design-reviewer
   ↓
   [並列レビュー実行]
   ↓
   ├─← セキュリティ: 2 critical, 3 important
   ├─← パフォーマンス: 0 critical, 2 important
   └─← API設計: 0 critical, 1 important, 3 nice-to-have
   ↓
4. メインプロセスが結果を統合
   ↓
5. 優先度順に整理して表示
   ↓
6. アクションプランを提示

トラブルシューティング

問題1: エージェントが起動しない

症状: エージェントの結果が返ってこない

原因: エージェントファイルが見つからない

解決:

# ファイルの配置を確認
ls -la plugins/my-plugin/agents/

# 名前が正しいか確認
cat plugins/my-plugin/agents/my-agent.md | head -5

問題2: ツールが使えない

症状: “Tool not allowed” エラー

原因: toolsフィールドに含まれていない

解決:

# エージェント定義を確認
tools: Glob, Grep, Read  # これらのツールのみ使用可能

# 必要なツールを追加
tools: Glob, Grep, Read, Edit, Write

問題3: 並列実行が遅い

症状: エージェントが逐次実行されている

原因: プロンプトの書き方

解決:

❌ 悪い例:
1. Launch agent 1
2. Launch agent 2
3. Launch agent 3

✅ 良い例:
Launch 3 agents in parallel:
- Agent 1: ...
- Agent 2: ...
- Agent 3: ...

次のステップ

学習パスガイド - 実践的な学習方法
プラグインシステム詳解 - システムの詳細仕様