Claude Code: Planning and Multi-Agent Workflows

One of the biggest productivity mistakes developers make with AI coding assistants is jumping straight to implementation. You type a request, Claude starts writing files, and ten minutes later you realise the approach was wrong. You spend more time undoing work than the AI saved you.

Claude Code offers two powerful tools to address this problem: Plan Mode, which keeps Claude in a read-only, thinking-only state while you refine your approach together, and multi-agent parallel execution, which lets you run separate Claude instances on independent parts of a codebase simultaneously. This article explains both in detail.

Part 1: Plan Mode

What Is Plan Mode?

Plan Mode is a special operating mode in Claude Code where Claude is restricted to read-only operations. It can search the codebase, read files, ask you questions, and reason about what needs to be done — but it cannot write, create, or delete any files.

Think of it as sitting with a very experienced colleague at a whiteboard. They review the problem with you, propose a design, and answer your questions. No code gets written until you both agree on the plan.

This is especially useful for:

1. Multi-step implementations — when a feature touches many files and the order of changes matters.
2. Unfamiliar codebases — when you want Claude to first understand the structure before it touches anything.
3. Iterative direction — when you are not yet sure exactly what you want and need to think it through with Claude.
4. Risky refactoring — when a mistake could be costly and you want to review the full impact before any file changes.

How to Activate Plan Mode

Inside an active Claude Code session you can cycle through modes with Shift+Tab. Each press moves you to the next mode in this sequence:

When Plan Mode is active, you will see the indicator ⏸ plan mode on in the terminal prompt. Claude will now gather information, explore the codebase, and present its proposed approach without touching any files.

Starting a Session Directly in Plan Mode

You can tell Claude Code to begin in plan mode from the very first prompt using the --permission-mode plan flag:

Setting Plan Mode as the Default

If you want every Claude Code session to start in plan mode by default — useful when you always want to review a plan before Claude touches files — add this to your .claude/settings.json:

With this setting, Claude never writes a file until you explicitly switch out of plan mode with Shift+Tab or approve the plan and ask Claude to proceed.

Editing the Plan in Your Text Editor

When Claude presents its plan in the terminal, you can press Ctrl+G to open the current plan in your default text editor. This lets you annotate it, delete sections you do not want, or add notes — and then save and return to Claude for the next iteration.

A Typical Plan Mode Session

Imagine you are adding a distributed caching layer to an ASP.NET Core API. Here is what a plan mode session looks like step by step:

1. Start Claude in plan mode: claude --permission-mode plan
2. Describe the task: "Add Redis distributed caching to our ASP.NET Core order service. Cache individual order lookups for 5 minutes."
3. Claude reads Program.cs, OrdersController.cs, IOrderRepository.cs, and the existing DI registrations.
4. Claude proposes a plan:
5. Add StackExchange.Redis NuGet package
6. Register IDistributedCache in Program.cs
7. Create CachedOrderRepository.cs as a decorator around OrderRepository
8. Update DI registration to use the decorator
9. Add unit tests for cache hit and cache miss scenarios
10. You review and ask: "Don't add tests yet. Also use a cache-aside pattern rather than a decorator."
11. Claude revises the plan. You are satisfied.
12. Press Shift+Tab to exit plan mode, and Claude immediately begins implementing the revised plan.

Notice that zero files were written until you were happy with the direction. That is the entire value of plan mode.

Part 2: Spec-Driven Development

What Is Spec-Driven Development?

Spec-driven development takes plan mode one step further. Instead of discarding the plan after implementation starts, you save it as a persistent Markdown file in your project. This file becomes a living specification that Claude automatically loads at the start of every future session.

This is valuable because Claude's context window is finite. In a long session, early decisions and constraints can be "forgotten" as newer content pushes them out. A saved spec file is always present.

The Spec-Driven Workflow

1. Start in plan mode and work with Claude to generate a thorough plan for the feature or system.
2. Iterate until the plan accurately reflects what you want to build.
3. Ask Claude to save the plan to a Markdown file, for example SPEC.md or memory/SPEC.md.
4. Reference the spec by including it in your CLAUDE.md so it is auto-loaded, or by importing it with @SPEC.md at the start of each session.
5. Implement feature by feature, always working against the spec.
6. Update the spec when requirements change, and commit it alongside the code.

Example: Saving a Spec

During a plan mode session you might say:

Claude will write the agreed plan to the file. Then in your CLAUDE.md:

Switching Models for Planning vs Implementation

Claude Opus is Claude's most capable and thoughtful model — excellent for generating nuanced, high-quality plans. Claude Sonnet is faster and more cost-efficient — ideal for the repetitive work of implementation.

Use the /model command to switch:

A common workflow: write the spec with Opus, save it, then use Sonnet for all subsequent implementation sessions.

Part 3: Multi-Agent Parallel Execution

Why Run Multiple Agents?

Many real-world tasks are naturally parallelisable. A new feature might require changes to a backend controller, a frontend component, and a database migration — and all three can be developed independently. Running them sequentially in a single Claude session is slower than necessary.

Claude Code allows you to open multiple terminal sessions, each running its own claude instance, on the same project. Each agent works on its assigned sub-task while the others work in parallel.

A Practical Example

Suppose you are building a user profile feature for an ASP.NET Core application. It requires:

1. Task A: A new ProfileController.cs with GET and PUT endpoints
2. Task B: A new ProfileService.cs and IProfileService.cs
3. Task C: A ProfileDto.cs record and validation attributes

These tasks are independent — no task depends on another being finished first. You can open three terminals and run:

All three run simultaneously. When they finish you merge the results.

Identifying Tasks Safe to Parallelise

Not every task can safely run in parallel. The key rule is:

Two agents can run in parallel only if they do not modify the same files.

Use this checklist before parallelising:

1. Safe: Each agent creates brand-new files that do not exist yet.
2. Safe: Agents modify different existing files with no overlap.
3. Unsafe: Both agents need to modify Program.cs to register services.
4. Unsafe: Both agents modify the same database migration file.
5. Unsafe: One agent's output is required as input by another agent.

When tasks conflict, run them sequentially — finish one, review it, then start the next.

Practical Parallel Workflow for an ASP.NET Core Feature

A realistic parallel workflow for adding a new Orders module to an existing project:

Step 1: Identify independent chunks

Step 2: Run the independent tasks in parallel

Step 3: Run the sequential task last

Part 4: Git Worktrees for Safe Parallel Work

The Problem with Shared Working Directories

When multiple Claude agents modify files in the same working directory at the same time, you risk merge conflicts and race conditions. Agent A writes a file, Agent B overwrites part of it, and the result is broken code.

Git worktrees solve this problem by giving each agent its own isolated copy of the repository on a separate branch. The agents never touch each other's files.

Using the --worktree Flag

Claude Code has built-in worktree support. To start a session in an isolated worktree:

This command:

1. Creates a new Git branch called feature-orders-controller.
2. Sets up an isolated working directory at .claude/worktrees/feature-orders-controller/.
3. Starts Claude inside that directory — changes are isolated to the new branch.

You can run multiple worktree sessions simultaneously, each on its own branch, with zero conflict:

Cleanup

When a Claude worktree session ends:

1. If no changes were made, the worktree and branch are automatically removed.
2. If changes were made, Claude asks whether to keep or remove the worktree.

After all parallel agents finish, you merge the branches using a standard Git workflow:

Copying Gitignored Files Into Worktrees

Files listed in .gitignore — such as appsettings.Development.json, .env, or local secrets — are not copied into worktrees automatically. To include them, create a .worktreeinclude file at the root of your repository:

Claude Code reads this file and copies the listed items into each new worktree.

Manual Worktree Management

If you prefer to manage worktrees manually with standard Git commands:

Part 5: Combining All Techniques

A Complete Workflow Example

Here is a full workflow combining plan mode, spec-driven development, and parallel agents with worktrees to build a new feature from scratch.

Phase 1: Plan (Plan Mode + Opus)

Switch to Opus, describe the feature, and refine the plan with Claude. Ask Claude to save the plan to memory/SPEC.md when you are satisfied.

Phase 2: Identify Parallel-Safe Tasks from the Spec

Review memory/SPEC.md and categorise every task:

Phase 3: Execute in Parallel (Worktrees + Sonnet)

Phase 4: Merge and Finalise

Summary

Plan Mode, spec-driven development, and multi-agent parallel execution are three complementary techniques that make Claude Code significantly more productive on large or complex tasks.

1. Plan Mode (Shift+Tab or --permission-mode plan) keeps Claude read-only while you align on approach before a single file is written.
2. Spec-Driven Development persists the agreed plan as a Markdown file, giving every future session a reliable reference that does not depend on context window length.
3. Parallel Agents run independent tasks simultaneously in separate terminals, cutting total wall-clock time for large features.
4. Git Worktrees (--worktree) give each parallel agent an isolated branch and directory, eliminating the risk of conflicts between concurrent agents.

Applied together, these techniques allow you to treat Claude Code as a team of junior developers working in parallel under your direction — rather than a single assistant that works through a task one step at a time.