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>
47 lines
2.3 KiB
Markdown
47 lines
2.3 KiB
Markdown
# 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.
|