Skip to content

README.md

Latest commit

 

History

History
552 lines (416 loc) · 13.3 KB

README.md

File metadata and controls

552 lines (416 loc) · 13.3 KB

Claude Code Multi-Agent Guide

This document explains why multi-agent architecture is needed and how to design it.

Korean

Quick Start - Run the Example

Run Claude Code and enter this prompt:

Clone https://github.com/ailnk0/claude-multiagent-template.git and cd into it.
Then read docs/example-task.md and execute each Task using the Task tool (subagent).
After each Task completes, update the Progress Tracker and record the deliverables.

What the example does:

Task 0: Market Research (WebSearch to select 3 competitors)
    │
    ├── Task 1a: Competitor A Research ─┐
    ├── Task 1b: Competitor B Research ─┼── (parallel)
    └── Task 1c: Competitor C Research ─┘
                                        │
                                        ▼
            Task 2: Comparative Analysis (feature matrix, insights)
                                        │
                                        ▼
            Task 3: HTML Report (open in browser)

Final output: output/report.html - professional competitor analysis report

Quick Start - Create Your Own

Copy docs/task-template.md and work with Claude to customize it for your needs.

This step requires significant effort. Work iteratively with Claude to define:

  • Clear goals for each task
  • Prerequisites and dependencies
  • Success criteria (must be self-verifiable by the agent)
  • File-based knowledge transfer between tasks

The quality of your task definitions determines the success of multi-agent execution. Read the guide below to understand the principles.

That's it. For details on why this works and how to customize, read on.

Why Multi-Agent?

Limitations of Single Agent

Common issues when running complex tasks with Claude Code:

Attempt approach A
    ↓ fails
Switch to approach B
    ↓ fails
Return to approach A  ← failure loop
    ↓ fails
...repeat

Cause 1: Context is finite

  • Claude Code's context window is approximately 200K tokens
  • Large codebase + long conversation = quickly hitting limits

Cause 2: Context rot

  • As conversation lengthens, earlier decisions get "buried"
  • When Auto Compact runs, previous context is summarized and details are lost
  • Agent forgets "why we abandoned approach A earlier"

What Multi-Agent Solves

Main Agent (Orchestrator)
    │
    ├── Sub-agent 1: Execute Task 0 → Record results
    │
    ├── Sub-agent 2: Execute Task 1 (reads Task 0 results) → Record results
    │
    └── Sub-agent 3: Execute Task 2 (reads Task 1 results) → Record results

Each sub-agent:

  • Starts with fresh context
  • Reads only necessary information
  • Explicitly records results before terminating

Core Principles

1. Tasks Should Be "Completable by One Agent"

Bad example:

Task 1: Refactor entire system

Good example:

Task 1: Extract UserService class
Task 2: Define UserRepository interface
Task 3: Write UserService tests

Criteria:

  • Can it be completed in one session without Auto Compact?
  • Is there a single goal?
  • Can success/failure be clearly determined?

2. Knowledge Transfer Between Agents via Files

Agents don't share conversation history. Knowledge transfer must happen through files.

### Output
Files for the next Task:
- `docs/research/api-spec.json`
- `docs/research/decisions.md`
### Prerequisites
- Task 0 completed
- `docs/research/api-spec.json` file exists

3. Success Criteria Must Be "Self-Verifiable by Agent"

Bad example:

- [ ] Code is clean
- [ ] Performance is good

Good example:

- [ ] `./build.sh` succeeds (exit code 0)
- [ ] `./test.sh` all tests pass
- [ ] `./benchmark.sh` result < 100ms

The agent must be able to check the boxes itself.

4. Dependencies Must Be Explicit

### Dependencies
- Task 0 (needs api-spec.json)
- Task 1 (needs MyService.java)

This enables:

  • Main agent to determine execution order
  • Identify parallel execution opportunities
  • Decide where to restart on failure

Task Design Patterns

Pattern 1: Research → Implementation → Verification

The most basic structure:

Task 0: Research
    │   - Collect API specs
    │   - Analyze existing code
    │   - Document constraints
    ▼
Task 1: Implementation
    │   - Implement core functionality
    │   - Reference Task 0 results
    ▼
Task 2: Verification
        - Run tests
        - Document results

Pattern 2: Parallel Implementation

Develop independent modules simultaneously:

Task 0: Research
    │
    ├── Task 1a: Implement Module A  ──┐
    │                                  │
    ├── Task 1b: Implement Module B  ──┼── Task 2: Integration
    │                                  │
    └── Task 1c: Implement Module C  ──┘
                                       │
                                       ▼
                                Task 3: Verification

Pattern 3: Iterative Experiments

When optimization or tuning is needed:

Task 0: Measure baseline
    │
    ▼
Task 1: Experiment 1 → Record results
    │
    ▼
Task 2: Experiment 2 (reference Task 1 results) → Record results
    │
    ▼
Task 3: Experiment 3 (reference Task 1,2 results) → Record results
    │
    ▼
Task 4: Select and apply optimal configuration

Key: Each experiment result is recorded to file, so the next agent knows "what was already tried."

Handling Decision Points

Some decisions cannot be made before execution.

Example: API Response Structure

Need to call API in Task 0 to know response structure
→ Task 1's parsing logic depends on Task 0 results

Solution: Decision Points Section

## Decision Points (Runtime-Dependent)

### After Task 0 (based on API response)
| Decision | How to Verify | Impact |
|----------|---------------|--------|
| Response structure | Check Task 0 result JSON | Task 1 parsing logic |
| Pagination method | Check API response headers | Task 1 iteration logic |

After Task 0 completes, humans review Decision Points and update Task 1 specs.

Failure Patterns and Solutions

Pattern 1: Agent Repeats Same Mistakes

Symptom: A → B → A → B failure loop

Cause:

  • Task is too large (Auto Compact occurs)
  • Previous attempt results not recorded

Solution:

  1. Split task into smaller pieces
  2. Record each attempt result to file
### Output
- `docs/experiments/attempt-1.md` - Failure reason: X
- `docs/experiments/attempt-2.md` - Failure reason: Y

Pattern 2: Agent Ignores Prerequisites

Symptom: Task 1 doesn't read Task 0 results

Cause:

  • Prerequisites not clear
  • Missing "Context for Agent" section

Solution:

### Context for Agent
Instructions for the agent performing this task:
1. First read `docs/research/api-spec.json`
2. The `endpoints` section in this file is the implementation target
3. Reference existing code patterns in `src/existing/`

Pattern 3: Parallel Task Conflicts

Symptom: Task 1a and Task 1b modify the same file

Cause:

  • Output scope overlaps between parallel tasks

Solution:

  1. Clearly separate Output paths for each task
  2. Common files modified only in Integration Task
Task 1a Output: `src/moduleA/` (modify only this folder)
Task 1b Output: `src/moduleB/` (modify only this folder)
Task 2 (Integration): `src/main.java` (integration)

Incremental Scaling

Start: 3 Tasks

Research → Implementation → Verification

Extension 1: Add Design (4 Tasks)

Research → Design → Implementation → Verification
  • Architecture decisions in Design Task
  • Implementation follows Design document

Extension 2: Separate Integration (5 Tasks)

Research → Design → Implementation → Integration → Verification
  • When implementing multiple modules separately
  • Integration connects modules

Extension 3: Parallel Implementation (7+ Tasks)

Research → Design ─┬→ Impl A ─┐
                   ├→ Impl B ─┼→ Integration → Verification
                   └→ Impl C ─┘

Checklist: Task Design Verification

When creating a new Task, verify:

Size

  • Completable in one session?
  • Single goal?
  • Can finish before Auto Compact?

Input

  • All Prerequisites listed?
  • Required file paths specified?
  • Context for Agent section exists?

Output

  • Output file paths specified?
  • Clear how next Task uses this Output?

Verification

  • Success Criteria specific?
  • Agent can check boxes itself?
  • Test Method is executable command?

Dependencies

  • All Dependencies listed?
  • No circular dependencies?
  • Parallel execution possibility clear?

Prompt Guide

Option A: Using Task Tool (Recommended)

Using Claude Code's Task tool runs each Task in a separate context. This is the most effective way to prevent context rot.

Read task.md and execute each Task as a separate Task.
After each Task completes, update the Progress Tracker,
and get my confirmation before starting the next Task.

When to use:

  • 4 or more Tasks
  • Each Task is complex (code generation, analysis, etc.)
  • Failure loops are occurring

Option B: Manual Session Separation

Open a new session or use /clear for each Task. This is the most reliable way to separate context.

Session 1:

Execute only Task 0 from task.md.
When complete, update Progress Tracker,
and tell me the Output file paths.

Session 2 (new window or after /clear):

Execute Task 1 from task.md.
Task 0 results are in docs/research/.
Check Prerequisites and begin.

When to use:

  • Human review required between Tasks
  • Want to carefully check each Task result
  • First time trying multi-agent

Option C: Sequential Execution in One Session

Can be used simply for small projects. However, due to context rot risk, only recommended when 3 or fewer Tasks.

Read task.md and execute sequentially from Task 0.
Get my confirmation after each Task before proceeding.
Update Progress Tracker on each Task completion.

When to use:

  • 3 or fewer Tasks
  • Each Task is simple (file copy, simple edits, etc.)
  • Rapid prototyping

Option D: Parallel Execution

Used when running independent Tasks simultaneously. Run Claude Code simultaneously in multiple terminals/windows.

Window 1:

Execute only Task 1a from task.md.
Write Output only to src/moduleA/.
Do not modify other folders.

Window 2 (simultaneously):

Execute only Task 1b from task.md.
Write Output only to src/moduleB/.
Do not modify other folders.

When to use:

  • Tasks with no Dependencies exist
  • Want to reduce time
  • Output paths for each Task are clearly separated

What the Agent Does Automatically

  • Read Prerequisites files
  • Verify Success Criteria
  • Update Progress Tracker
  • Record deliverables to Output path

What Humans Must Do

  • Review results at Task transitions
  • Make directional decisions (when multiple options exist)
  • Instruct re-execution when quality is insufficient
  • Split Tasks or modify specs on failure

Scaling Guide

Current Structure (5 Tasks, with parallel)

Task 0: Research
    │
    ├── Task 1a: Feature A Implementation  ─┐
    ├── Task 1b: Feature B Implementation  ─┼── (parallel)
    └── Task 1c: Feature C Implementation  ─┘
                                            │
                                            ▼
                             Task 2: Integration & Verification

Simpler (3 Tasks, sequential)

For small projects without parallel needs:

Task 0: Research
Task 1: Core Implementation
Task 2: Verification

More Complex (Add Design phase)

For complex projects:

Task 0: Research
Task 1: Design (NEW)
    │
    ├── Task 2a: Feature A Implementation  ─┐
    ├── Task 2b: Feature B Implementation  ─┼── (parallel)
    └── Task 2c: Feature C Implementation  ─┘
                                            │
                                            ▼
                             Task 3: Integration & Verification

Notes for Adding Parallel Tasks

  1. Separate Output paths: Each Task writes to different folders
  2. Warning in Context for Agent: "Do NOT modify other folders"
  3. Integration Task required: Task to merge parallel results is mandatory

Failure Checklist

If the agent repeats the same mistakes:

Size Issues

  • Is scope focused on a single goal?
  • Can one agent complete within context?
  • Should the Task be split smaller?

Knowledge Transfer Issues

  • Are Prerequisites clear?
  • Is previous Task's Output path recorded?
  • Does Context for Agent section have necessary info?

Verification Issues

  • Can agent verify Success Criteria itself?
  • Is Test Method specific?

Conclusion

The key to multi-agent is memory, not intelligence.

  • Context is limited, and earlier decisions get buried as it lengthens
  • Both the size and structure of memory must be engineered

Split tasks, transfer knowledge via files, and make success criteria clear.

Then Claude Code escapes the failure loop.

Version

v1.0 - 2025-01-06