Skip to content

parallel-agents-guide.md

Latest commit

 

History

History
798 lines (547 loc) · 18.4 KB

parallel-agents-guide.md

File metadata and controls

798 lines (547 loc) · 18.4 KB

Parallel Agents Guide

Coordinate multiple agents for complex tasks

This guide explains how to use parallel agent execution for complex scenarios that benefit from multiple perspectives or concurrent work streams.

When to Use Parallel Agents

Good Use Cases

  1. Multi-perspective evaluation - Get different viewpoints on a decision
  2. Large-scale refactoring - Process multiple files concurrently
  3. Comprehensive analysis - Analyze code from different angles
  4. Research synthesis - Gather information from multiple sources
  5. Testing in parallel - Run different test strategies simultaneously

When NOT to Use

  1. Sequential dependencies - Tasks that must complete in order
  2. Simple tasks - Overhead outweighs benefits
  3. Token-constrained - Parallel execution multiplies token usage
  4. Shared state - Tasks that modify the same files

Basic Pattern

Launching Parallel Agents

Use the Task tool with multiple invocations:

## Parallel Execution

I'll launch multiple agents in parallel:

1. **Agent A**: Analyze security aspects
2. **Agent B**: Analyze performance aspects
3. **Agent C**: Analyze maintainability aspects

[Launch all three using Task tool with different prompts]

Gathering Results

After agents complete:

## Synthesis

Results from parallel analysis:

**Security (Agent A)**:
- [Summary of security findings]

**Performance (Agent B)**:
- [Summary of performance findings]

**Maintainability (Agent C)**:
- [Summary of maintainability findings]

## Combined Recommendations
[Synthesize all findings into actionable items]

Patterns

Pattern 1: Multi-Perspective Review

Scenario: Review a design decision from multiple angles

Setup:

Launch 3 agents in parallel:

1. **spec-judge (Opus)**: Evaluate from architectural perspective
   - Focus: System design, scalability, patterns

2. **spec-judge (Opus)**: Evaluate from security perspective
   - Focus: Authentication, authorization, data protection

3. **spec-judge (Opus)**: Evaluate from performance perspective
   - Focus: Efficiency, caching, database queries

Synthesis:

## Combined Evaluation

### Unanimous Recommendations
[Things all three agreed on]

### Majority Recommendations
[2 out of 3 agreed]

### Conflicting Perspectives
[Where agents disagreed - needs human decision]

Pattern 2: Concurrent File Processing

Scenario: Refactor multiple independent files

Setup:

Launch agents for each file group:

1. **Agent 1**: Refactor app/Services/Auth/*
2. **Agent 2**: Refactor app/Services/Payment/*
3. **Agent 3**: Refactor app/Services/Notification/*

Prerequisites:

  • Files must be independent (no cross-references being changed)
  • Each agent gets clear scope
  • Common patterns defined upfront

Coordination:

## Shared Context (give to all agents)

### Refactoring Rules
- Apply new naming convention: [convention]
- Use new base class: [class]
- Follow pattern: [pattern]

### Do NOT Change
- Interface signatures
- Public method names
- Database interactions

Pattern 3: Research Synthesis

Scenario: Research a topic from multiple sources

Setup:

Launch research agents:

1. **Agent 1**: Research official documentation
   - Sources: anthropic.com, platform.claude.com

2. **Agent 2**: Research community best practices
   - Sources: GitHub, Stack Overflow, blogs

3. **Agent 3**: Research competing approaches
   - Sources: Alternative tools, comparison articles

Synthesis:

## Research Summary

### Official Guidance
[From Agent 1]

### Community Wisdom
[From Agent 2]

### Alternative Approaches
[From Agent 3]

### Recommended Approach
[Synthesized recommendation]

Pattern 4: Test Strategy Parallelization

Scenario: Generate tests from multiple strategies

Setup:

Launch test generation agents:

1. **Agent 1**: Generate happy path tests
   - Focus: Expected success scenarios

2. **Agent 2**: Generate edge case tests
   - Focus: Boundary conditions, empty inputs

3. **Agent 3**: Generate error handling tests
   - Focus: Failure scenarios, exceptions

Integration:

## Combined Test Suite

### Happy Path Tests (Agent 1)
[List of generated tests]

### Edge Case Tests (Agent 2)
[List of generated tests]

### Error Handling Tests (Agent 3)
[List of generated tests]

### Gaps Identified
[Any scenarios not covered]

Pattern 5: Selective Deep Plan Analysis

Scenario: Review a complex plan with multiple specialized agents without exhausting the context window.

Problem: Launching 5+ review agents simultaneously generates 100K+ tokens of output, often exceeding the context window and producing truncated, unusable analysis.

Solution: Tiered agent selection with context budget awareness.

Tier System

Tier Agents Token Budget When to Use
Tier 1 (Core) architecture-strategist, code-simplicity-reviewer ~30K tokens Always - minimum viable review
Tier 2 (Recommended) + security-sentinel, performance-oracle ~60K tokens Default for most plans
Tier 3 (Full) + all domain-specific agents 100K+ tokens Only when explicitly requested

Context Budget Calculator

Before launching agents, calculate the maximum safe count:

max_agents = (context_window - current_usage - plan_size) / avg_agent_output

Example:
  context_window  = 200,000 tokens
  current_usage   = 50,000 tokens (conversation so far)
  plan_size       = 20,000 tokens (the plan being reviewed)
  avg_agent_output = 25,000 tokens (per agent response)

  max_agents = (200,000 - 50,000 - 20,000) / 25,000 = 5.2 → 5 agents max

Safety margin: Always subtract 20% from max_agents to leave room for synthesis.

Agent Priority Matrix

Select agents based on project type:

Project Type Priority Agents Secondary Agents
Laravel/PHP architecture-strategist, security-sentinel, data-integrity-guardian performance-oracle, code-simplicity-reviewer
React/TypeScript architecture-strategist, typescript-reviewer, react-performance frontend-developer, code-simplicity-reviewer
API Design backend-architect, security-sentinel, performance-oracle graphql-architect, code-simplicity-reviewer
Data/Migrations data-migration-expert, data-integrity-guardian, deployment-verification architecture-strategist, security-sentinel
Mobile mobile-developer, architecture-strategist, performance-oracle security-sentinel, code-simplicity-reviewer

Implementation Patterns

Pattern A: Compact-Between-Agents

Run agents sequentially with /compact between each to free context:

1. Launch architecture-strategist -> Get results -> Save to summary
2. /compact (frees ~30K tokens)
3. Launch security-sentinel -> Get results -> Add to summary
4. /compact (frees ~30K tokens)
5. Launch performance-oracle -> Get results -> Add to summary
6. Synthesize from summaries

Pattern B: Background Agents

Use run_in_background: true to run agents in parallel without blocking context:

Launch all agents with run_in_background: true
  -> Each agent writes results to output_file
  -> Read output files after all complete
  -> Synthesize in main conversation

Advantage: Agents run in parallel (faster)
Disadvantage: Must read output files (extra step)

Pattern C: Selective Launch (Recommended)

Ask the user which tier before launching:

"This plan has 15 files across 3 modules. I recommend Tier 2 review
(4 agents, ~60K tokens). Options:

1. Tier 1 (Core): architecture + simplicity [~30K tokens]
2. Tier 2 (Recommended): + security + performance [~60K tokens]
3. Tier 3 (Full): + all specialists [~120K tokens, may need /compact]
4. Custom: specify agents by name

Which tier?"

Deep Plan Anti-Patterns

Avoid these common mistakes when using parallel agents for plan review:

Anti-Pattern 1: Launching All Agents at Once

# BAD: 8 agents launched simultaneously
Launch: architecture-strategist, code-simplicity-reviewer, security-sentinel,
        performance-oracle, data-integrity-guardian, deployment-verification,
        typescript-reviewer, react-performance

# Result: 200K+ tokens of output, context overflow, truncated results

Fix: Use the tier system. Start with Tier 1, escalate only if needed.

Anti-Pattern 2: Using Opus for Every Agent

# BAD: All agents on Opus (3x more tokens per agent)
architecture-strategist (opus) -> 40K tokens
security-sentinel (opus) -> 35K tokens
performance-oracle (opus) -> 38K tokens
# Total: 113K tokens for 3 agents

# GOOD: Match model to task
architecture-strategist (opus) -> 40K tokens  # Critical - worth opus
security-sentinel (sonnet) -> 20K tokens       # Standard review
performance-oracle (sonnet) -> 18K tokens      # Standard review
# Total: 78K tokens for 3 agents (31% savings)

Fix: Use Opus only for architectural decisions. Sonnet is sufficient for most reviews.

Anti-Pattern 3: No Prioritization

# BAD: All agents marked as "required"
"Run ALL review agents because quality matters"

# Result: Context overflow, no agent completes properly

Fix: Prioritize ruthlessly. Two thorough reviews > six truncated reviews.

Anti-Pattern 4: Ignoring Context State

# BAD: Launching 5 agents when context is already 70% full
Context: 140K/200K used + 5 agents x 25K = 265K > 200K

# Result: Later agents get truncated or fail

Fix: Always calculate context budget before launching agents. Use /compact to free space first.

Agent Types for Parallel Work

Exploration Agents

Best for: Research, discovery, analysis

subagent_type: Explore
model: haiku (fast, cheap)

Use when:

  • Searching codebase
  • Finding patterns
  • Gathering information

Implementation Agents

Best for: Code changes, refactoring

subagent_type: spec-impl
model: sonnet (balanced)

Use when:

  • Making code changes
  • Implementing features
  • Refactoring files

Evaluation Agents

Best for: Critical decisions, quality assessment

subagent_type: spec-judge
model: opus (thorough)

Use when:

  • Evaluating designs
  • Making architectural decisions
  • Assessing quality

Coordination Strategies

Strategy 1: Divide and Conquer

Split work by scope:

## Work Division

Total scope: 20 files across 4 modules

### Agent 1: Module A (5 files)
- file1.php
- file2.php
- ...

### Agent 2: Module B (5 files)
- file6.php
- file7.php
- ...

### Agent 3: Module C (5 files)
...

### Agent 4: Module D (5 files)
...

Key: Ensure no overlap, clear boundaries.

Strategy 2: Specialist Roles

Assign different perspectives:

## Role Assignment

### Security Specialist (Agent 1)
Focus exclusively on:
- Input validation
- Authentication
- Authorization
- Data protection

### Performance Specialist (Agent 2)
Focus exclusively on:
- Query efficiency
- Caching opportunities
- Algorithm complexity
- Resource usage

### Maintainability Specialist (Agent 3)
Focus exclusively on:
- Code clarity
- Documentation
- Test coverage
- Technical debt

Strategy 3: Pipeline Stages

When some dependency exists:

## Pipeline

### Stage 1 (Parallel)
- Agent A: Analyze requirements
- Agent B: Research similar implementations

### Stage 2 (After Stage 1)
- Agent C: Design solution (uses Stage 1 output)

### Stage 3 (Parallel)
- Agent D: Implement component 1
- Agent E: Implement component 2

### Stage 4 (After Stage 3)
- Agent F: Integration and testing

Token Management

Cost Implications

Parallel agents multiply token usage:

Agents Multiplier Example Task Total Tokens
1 1x 10K 10K
2 2x 10K 20K
3 3x 10K 30K
4 4x 10K 40K

Recommendation: Use parallel agents when:

  • Time savings justify cost
  • Quality improvement justifies cost
  • Task naturally parallelizes

Optimization

Reduce per-agent tokens:

  1. Share context - Load memories once, pass to all agents
  2. Narrow scope - Each agent gets only what it needs
  3. Use Haiku - For exploration/research agents
  4. Set limits - Define maximum tokens per agent

Error Handling

Agent Failure

When one agent fails:

## Handling Partial Failure

### Agent 1: ✅ Completed
[Results]

### Agent 2: ❌ Failed
Error: [Error message]
Action: [Retry / Skip / Manual handling]

### Agent 3: ✅ Completed
[Results]

## Recovery
[How to handle the failed agent's work]

Conflicting Results

When agents produce conflicting outputs:

## Conflict Resolution

### Conflict: [Description]

**Agent 1 says**: [Position]
**Agent 2 says**: [Different position]

### Resolution Options
1. **Accept Agent 1** - Because [reason]
2. **Accept Agent 2** - Because [reason]
3. **Combine** - Take [X] from Agent 1, [Y] from Agent 2
4. **Escalate** - Need human decision

### Decision
[Chosen resolution and reasoning]

Best Practices

Do

✅ Define clear, non-overlapping scopes ✅ Share common context efficiently ✅ Use appropriate agent types ✅ Plan for failure handling ✅ Synthesize results meaningfully ✅ Consider token cost vs benefit

Don't

❌ Parallel agents for sequential work ❌ Overlapping file modifications ❌ Excessive parallelization (>4 agents usually) ❌ Ignore conflicting results ❌ Skip synthesis step ❌ Use Opus for everything (expensive)

Example: Full Parallel Workflow

Scenario: Comprehensive Feature Review

# Feature Review: User Authentication Redesign

## Phase 1: Parallel Analysis (3 agents)

### Agent 1: Security Analysis
**Type**: spec-judge
**Model**: opus
**Scope**: Evaluate security implications
**Prompt**: "Analyze the authentication redesign for security vulnerabilities..."

### Agent 2: Performance Analysis
**Type**: spec-judge
**Model**: sonnet
**Scope**: Evaluate performance implications
**Prompt**: "Analyze the authentication redesign for performance impact..."

### Agent 3: Code Quality Analysis
**Type**: spec-judge
**Model**: sonnet
**Scope**: Evaluate code quality and maintainability
**Prompt**: "Analyze the authentication redesign for code quality..."

[Launch all three in parallel]

---

## Phase 2: Synthesis

### Security Findings (Agent 1)
- Critical: [X] issues
- High: [X] issues
- Medium: [X] issues
Recommendation: [Summary]

### Performance Findings (Agent 2)
- Impact: [X]% change expected
- Bottlenecks: [List]
Recommendation: [Summary]

### Code Quality Findings (Agent 3)
- Complexity: [Score]
- Test coverage: [X]%
- Technical debt: [Assessment]
Recommendation: [Summary]

---

## Phase 3: Combined Recommendation

### Must Fix Before Merge
1. [Critical security issue from Agent 1]
2. [Critical performance issue from Agent 2]

### Should Fix
1. [High priority items]

### Nice to Have
1. [Medium priority items]

### Overall Assessment
[Combined verdict: Approve / Approve with changes / Reject]

Quick Reference

Agent Launch Template

Launch parallel agents:

1. **[Agent Name]** ([Type])
   - Model: [haiku/sonnet/opus]
   - Scope: [What to analyze/do]
   - Output: [Expected deliverable]

Result Synthesis Template

## Parallel Results

### [Agent 1 Name]
- Status: [✅/❌]
- Key findings: [Summary]
- Recommendations: [List]

### [Agent 2 Name]
...

## Synthesis
### Agreements
[What agents agreed on]

### Conflicts
[Where they disagreed]

### Decision
[Final recommendation]

Git Isolation with Worktrunk

When parallel agents modify code (Pattern 2: Concurrent File Processing), they risk conflicts if working in the same directory. Worktrunk solves this by managing git worktrees — isolated working copies of your repo where each agent operates independently.

Why Worktrees for Parallel Agents

The "Shared state" anti-pattern (agents modifying the same files) is the #1 reason parallel code changes fail. Git worktrees give each agent its own full working directory on a separate branch, eliminating merge conflicts during execution.

Installation

# macOS
brew install worktrunk

# Cargo (any platform)
cargo install worktrunk

# Enable shell integration (cd into worktrees)
eval "$(wt shell-init zsh)"   # or bash/fish

Core Commands

Command Description
wt switch -c feature-name Create worktree + branch
wt switch pr:123 Checkout a PR into a worktree
wt list Show all worktrees with status and age
wt merge Squash/rebase/merge + cleanup in one step
wt remove Clean up worktree and branch

Claude Code Parallel Workflow

Launch multiple Claude agents, each in its own worktree:

# Terminal 1: Agent working on auth module
wt switch -x claude -c feat/auth-refactor

# Terminal 2: Agent working on payment module
wt switch -x claude -c feat/payment-refactor

# Terminal 3: Agent working on notification module
wt switch -x claude -c feat/notification-refactor

Each agent gets a fully isolated copy of the repo. No file conflicts, no lock contention, no shared state.

Merging Results

After all agents complete:

# Review what each agent did
wt list

# Merge each branch back (squash + cleanup)
wt switch feat/auth-refactor
wt merge --squash

wt switch feat/payment-refactor
wt merge --squash

wt switch feat/notification-refactor
wt merge --squash

Hooks Integration

Worktrunk supports hooks for automation:

# .worktrunk.toml
[hooks]
on-create = "npm install"          # Setup dependencies in new worktree
post-merge = "npm run lint"        # Validate after merge

When to Use Worktrunk vs In-Process Parallelism

Scenario Approach
Agents read code (analysis, review) In-process parallel agents (no isolation needed)
Agents modify different files Either approach works
Agents modify overlapping files Worktrunk worktrees (isolation required)
Long-running feature branches Worktrunk worktrees

Note: Worktrunk is free, open source (Apache 2.0), and available on macOS, Linux, and Windows. See worktrunk.dev for full documentation.

Use parallel agents strategically for complex tasks that benefit from multiple perspectives or concurrent execution. Balance the token cost against the value of parallelization.