6. Limitations & Gotchas

Read-Heavy vs Write-Heavy Trade-off

Core limitation: Agent teams excel at read-heavy tasks but struggle with write-heavy tasks where multiple agents modify the same files.

Why this matters:

Read-heavy (✅ Good for teams):
- Code review: Agents read code, provide analysis
- Bug tracing: Agents read logs, trace execution
- Architecture analysis: Agents read structure, identify patterns

Write-heavy (⚠️ Risky for teams):
- Refactoring shared types: Multiple agents modify same file → merge conflicts
- Database schema changes: Coordinated migrations across files
- API contract updates: Interface changes require synchronization

Mitigation strategies:

1. Clear boundaries: Assign non-overlapping file sets to agents
2. Interface-first: Define contracts before parallel implementation
3. Single-writer pattern: One agent writes shared files, others read only
4. Human review: Manually resolve merge conflicts when they occur

Merge Conflict Scenarios

Automatic resolution works:

• ✅ Different files modified by different agents
• ✅ Different functions in same file (clean git merges)
• ✅ Additive changes (new functions, no edits)

Automatic resolution struggles:

• ❌ Same lines modified (classic merge conflict)
• ❌ Conflicting logic (Agent A removes validation, Agent B adds it)
• ❌ Circular dependencies (Agent A needs Agent B's output, vice versa)

Example conflict:

// Agent 1 changes:
function processUser(user: User) {
  validateEmail(user.email); // Added validation
  return save(user);
}

// Agent 2 changes (same time):
function processUser(user: User) {
  return save(sanitize(user)); // Added sanitization
}

// Conflict: Both modified same function
// Resolution: Human decides order (validate → sanitize → save)

Token Intensity Implications

Why token-intensive:

• Each agent runs separate model inference (3 agents = 3x base cost)
• Context loading for each agent (1M tokens × 3 = 3M token capacity)
• Coordination overhead (team lead synthesis)

Budget impact example (Opus 5 pricing):

Single agent session:
- Input: 50K tokens @ $5/M = $0.25
- Output: 5K tokens @ $25/M = $0.13
- Total: $0.38

Agent teams (3 agents):
- Input: 150K tokens @ $5/M = $0.75
- Output: 15K tokens @ $25/M = $0.38
- Total: $1.13

Cost multiplier: 3x

Justification required:

• ✅ Time saved > cost increase (production issues)
• ✅ Quality critical (financial services, healthcare)
• ✅ Complexity justifies parallelization (multi-layer analysis)
• ❌ Simple tasks (use single agent)
• ❌ Personal learning projects (budget-constrained)

Experimental Status Caveats

What "experimental" means:

• ⚠️ No stability guarantee: Feature may change or be removed
• ⚠️ Bugs expected: Report issues to Anthropic (GitHub Issues)
• ⚠️ Performance variability: Coordination speed may fluctuate
• ⚠️ Documentation evolving: Official docs still minimal

Production usage considerations:

1. Fallback plan: Be ready to revert to single-agent if issues arise
2. Monitoring: Track token costs carefully (can escalate quickly)
3. Validation: Human review of agent team outputs (don't trust blindly)
4. Feedback: Report bugs/experiences to help Anthropic improve feature

Practitioner reports (as of Feb 2026):

• ✅ Paul Rayner: "Pretty impressive" (production usage validated)
• ✅ Fountain: 50% faster (deployed in production)
• ✅ CRED: 2x speed (15M users, financial services)
• ⚠️ Community: Mixed reports (some merge conflict issues)

Context Isolation

What agents can't do:

• ❌ Share context windows: Agent 1's full context (1M tokens) not visible to Agent 2
• ❌ Auto-sync discoveries: Agent 2 won't see Agent 1's findings unless explicitly messaged
• ❌ Coordinate timing: Agents work independently, may finish at different times

What agents CAN do:

• ✅ Send messages: Via mailbox system (peer-to-peer or via team lead)
• ✅ Challenge approaches: Debate solutions, ask questions to each other
• ✅ Share findings: Explicit messaging (not automatic context sharing)

Implications:

Scenario: Agent 1 discovers critical bug that affects Agent 2's work

Without messaging:
- Agent 2 doesn't see Agent 1's discovery automatically
- Agent 2 may continue with flawed assumption

With messaging (built-in):
- Agent 1 messages Agent 2: "Found auth issue in line 45"
- Agent 2 adjusts approach based on message
- Team lead synthesizes all findings at end

Mitigation:
- Agents can message each other via mailbox system
- Team lead synthesizes findings after all agents complete
- Human can interrupt and redirect agents mid-workflow (Shift+Down to cycle teammates)
- Design tasks with minimal inter-agent dependencies

When NOT to Use Agent Teams

Single agent is better for:

• ❌ Simple tasks: Straightforward implementations (overkill)
• ❌ Small codebases: <5 files affected (coordination overhead not justified)
• ❌ Write-heavy tasks: Lots of shared file modifications (merge conflict risk)
• ❌ Sequential dependencies: Task B requires Task A completion (no parallelization benefit)
• ❌ Budget constraints: Personal projects, learning (token cost multiplier)
• ❌ Tight interdependencies: Circular dependencies between tasks

Example of poor fit:

Task: Update authentication logic in shared auth.ts file

Why single agent better:
- One file modified (no parallelization benefit)
- Write-heavy (multiple changes to same file)
- No clear subtask boundaries (logic intertwined)
- Sequential flow (test after each change)

Result: Agent teams would create merge conflicts, no time savings