Planning & Multi-Agent
Structuring work with planning mode and running parallel agents for complex tasks.
Planning Mode: Think Before You Build
Planning mode is a read-only operating mode where Claude explores the codebase, reasons about architecture, and produces a specification — without writing any code. This separation between planning and implementation is a form of spec-driven development that consistently produces better results than jumping straight into code generation.
How Planning Mode Works
- ▸Activate with Shift+Tab or by entering Plan mode from the interface
- ▸Claude uses read-only tools — it can read files, search code, and explore structure, but cannot write or edit
- ▸The output is a specification or plan document, not implementation code
- ▸The plan can be saved as a CLAUDE.md file and referenced during implementation
- ▸Switch to a code-generation model (like Sonnet) for the implementation phase
Benefits of Spec-Driven Development
| Benefit | Why It Matters |
|---|---|
| Alignment before code | Catch misunderstandings and scope issues before any implementation work begins |
| Optimized context | A spec file provides dense, high-quality context — better than accumulated conversation history |
| Iterative refinement | Specs can be reviewed, adjusted, and approved before committing to implementation |
| Reproducibility | The same spec can drive multiple implementation attempts if the first approach fails |
After planning, save the spec and start a fresh session for implementation. This avoids context rot — the accumulated noise from the planning conversation does not pollute the implementation context.
Running Multiple Agents in Parallel
Complex projects often contain tasks that are independent of each other. Claude Code supports spawning multiple agents that work concurrently, each in its own context window. This is context isolation in action — each agent focuses on its specific task without being distracted by unrelated work.
Identifying Parallelizable Tasks
Not all tasks can be parallelized. Good candidates for parallel execution are tasks that touch different files, have no shared state, and produce independent outputs. Tasks with dependencies or shared resources should be executed sequentially.
| Good for Parallel | Keep Sequential |
|---|---|
| Building independent UI components | Tasks that modify shared state or the same files |
| Writing tests for separate modules | Database migrations that depend on each other |
| Adding features to different pages | Refactors that change interfaces used by other tasks |
| Documentation for separate systems | Changes that require output from a previous task |
The Parallel Execution Workflow
- ▸Break the project into independent tasks during the planning phase
- ▸Assign each task to a separate agent with a clear, self-contained description
- ▸Agents execute concurrently, each in its own context window with its own tool access
- ▸Review results from all agents once they complete
- ▸Commit the combined changes after validation
# Open multiple Claude Code sessions in separate terminals
# Each session = isolated context window working on one task
# Terminal 1 — navbar work
cd ~/projects/my-app
claude
> Read @spec.md then build the responsive navbar component
with the mobile menu described in section 3.
# Terminal 2 — footer work (parallel session)
cd ~/projects/my-app
claude
> Read @spec.md then build the footer component with the
sitemap links and social icons described in section 4.
# Terminal 3 — tests (parallel session)
cd ~/projects/my-app
claude
> Write Jest tests for every route in app/api/.
Cover success and error cases.Planning + Parallel: The Combined Pattern
The most effective workflow combines planning mode with parallel execution. First, use planning mode to produce a spec that breaks the project into independent work units. Then spawn parallel agents for each unit, referencing the shared spec for consistency. This scales development while maintaining architectural coherence.
Each parallel agent operates in its own context window. This means agents do not see each other's progress or share conversation history. The shared spec file is what keeps them aligned — it acts as the single source of truth that all agents reference.