a4967df815
Conventions, community best practices research (Sept 2025 - March 2026), and prioritized improvement backlog for Claude Code workflows. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2.3 KiB
Multi-Agent Patterns
Why This Matters
Subagents are the most powerful tool for managing context — they explore in a separate context window, keeping the main conversation clean. However, multi-agent workflows are overkill for 95% of tasks and currently expensive.
Current State
- Built-in subagent support available (Explore, Plan, general-purpose)
- No custom orchestration
- No multi-terminal patterns
Patterns (Simplest to Most Complex)
1. Built-in Subagents (Already Available)
Delegate research, exploration, and file searches to subagents. They run in separate context windows and return summaries. This is the easiest win — just use the Agent tool more deliberately.
2. Git Worktrees for Parallel Work
Use git worktree to let multiple Claude instances work on separate branches without conflicts. Each instance has its own working directory but shares the git history.
3. The 4-Terminal Pattern
Simple but effective: 4 specialised Claude Code agents in separate VS Code / tmux terminals with distinct roles (e.g., planner, implementer, tester, reviewer). Often beats complex orchestrators.
4. Master-Clone Architecture
Rather than custom subagents with rigid workflows, use Claude's built-in Task(...) to spawn general-agent clones. Put key context in CLAUDE.md and let the agent orchestrate delegation dynamically.
5. Container Isolation
Local Claude Code controls another instance inside a Docker container via tmux — sandboxed autonomous worker for risky/destructive operations.
Orchestration Tools
| Tool | Description |
|---|---|
| Claude Squad | Terminal app managing multiple Claude Code agents in separate workspaces |
| Happy Coder | Spawn and control multiple Claude Codes with push notifications |
| Claude Swarm | Launch a Claude Code session connected to a swarm of other agents |
| Claude MPM | 47+ specialised agents with PM orchestration and automatic task routing |
When NOT to Use Multi-Agent
- Simple, single-file changes
- Tasks that take less than a few minutes
- When context window is not a constraint
- When the coordination overhead exceeds the work itself
The community consensus: master the single-agent workflow first. Multi-agent adds complexity and cost that only pays off for genuinely parallel, independent workstreams.