Learning objectives

By the end of this chapter, you will be able to:

1. Explain what plan mode is — a read-only permission mode for exploring and designing before any edits — how to enter it (the `/plan` prompt prefix, the `Shift+Tab` mode cycle, or the `--permission-mode plan` flag), what it can and cannot do, and how approving a plan transitions the session into execution.
2. Apply spec-driven development: use plan mode to produce a detailed specification, refine it through feedback, and persist it to a committed Markdown file so it becomes durable project context — and place this inside the explore → plan → code → commit workflow.
3. Run multiple Claude Code instances in parallel on a shared codebase to accelerate independent work, and explain why the chapter's same-branch approach is the simplest — and most fragile — form of multi-agent work.
4. Distinguish tasks that are safe to parallelize (independent) from those that must run sequentially (dependent), and describe how the engineer's role shifts from writing code to orchestrating and reviewing it.
5. Execute a parallel workflow end to end on independent files using scoped 'modify only / do not modify' prompts, then review and commit the combined result with `git status` / `git diff` / `git add` / `git commit`.
6. Contrast the main 'multiple-agent' mechanisms — multiple terminal instances (with Git worktrees for true file isolation), in-session subagents (which can parallelize work and even use worktree isolation), and agent teams (experimental, off by default) — while recognizing current Claude Code has further parallel-work surfaces, and explain why isolation is the documented answer to the conflict risk the same-branch demo exposes.

Before we start — planning, specs, and what "multi-agent" really means

Skim this if you're already comfortable with plan mode, what a "spec" is, the difference between tasks that can run at the same time and tasks that can't, and the several different things people mean by "running multiple agents." If any of that is fuzzy, read it first — the whole chapter is built on these ideas.

Plan mode is a mode Claude Code can run in where it is read-only: it reads files, searches, analyzes, and designs a solution, but it does not edit, create, or delete files, make commits, or take execution-level actions. You use it to get a plan you can inspect before Claude changes anything. It was introduced briefly in Chapter 2 (the Shift+Tab cycle); this chapter makes it the centrepiece.

A specification (spec) is just a written description of what you want built and how — the screens, the data, the behaviours, what's in scope and what isn't — produced and agreed before the code is written. "Spec-driven development" means you invest in getting that description right first, then implement against it, instead of discovering the design by editing.

Independent vs dependent tasks. Two tasks are independent if neither needs the other's result and they don't touch the same files — they can run in parallel (at the same time). They're dependent if one needs the other to finish first, or they'd edit the same lines — those must run sequentially (one after the other). You can't hang a door before the wall is built; but you can paint two different rooms at once. Telling these apart is the core skill of the second half of this chapter.

"Multiple agents" is a loose phrase — pin down which kind you mean. The book frames it around three ideas, and this chapter teaches the first; current Claude Code actually offers several parallel-work surfaces, so treat these three as the on-ramp, not the whole map:

• Multiple terminal instances — you open two (or five) terminals and run a full, separate Claude Code in each, working different tasks at the same time. Each has its own context window. This is what this chapter demonstrates. Git worktrees (covered near the end) give each instance its own isolated copy of the files so they can't collide.
• Subagents — one Claude Code session delegates a task to a specialized helper that runs in its own context window and reports a summary back. Subagents both keep side-work out of the main conversation's context and can run in parallel (and can even use worktree isolation). This is the next chapter's topic.
• Agent teams — a coordinated form where a lead session assigns work to teammates that each run in their own context and message each other. (It's experimental and off by default — enabled with the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS setting.)

Those three aren't the full list — current Claude Code also has Agent View (claude agents, a monitor for many background sessions), dynamic workflows (a script that runs many subagents and cross-checks their results), and /batch (which splits one big change into many worktree-isolated subagent PRs). We touch on them again in §6; for now just know the landscape is bigger than three. This chapter is about the first item — when you read "agent" or "instance" below, picture a separate terminal running its own Claude Code.

A word on Git, for the parallel half. A branch is an independent line of work in a repository; main is usually the shared, "real" branch. A commit is a saved snapshot. git status shows what changed, git diff shows the exact changes, git add stages them, and git commit saves them. The chapter runs several Claude instances against the same branch and then reviews everything together before committing once.

How to read this chapter. Each numbered section ends with an > Analogy — … box that restates the idea in plain language. Lean on them or skim them as you like.

Why this chapter matters

Everything so far has been Claude Code doing one thing at a time, reactively: you type a prompt, it acts, you review, you type the next prompt. That's fine for small, well-understood changes. It breaks down in two situations this chapter fixes.

The first is complexity. When the task is large or unfamiliar, letting Claude start editing immediately is how you get a confident-looking change that's subtly wrong — it guessed at structure it should have studied first. Plan mode is the answer: force a read-only understand-and-design pass, inspect the plan, and only then let it build. As systems grow, the book's opening line puts it well — "relying on ad hoc prompting increases the risk of unintended changes and unpredictable behavior." Structure beats improvisation.

The second is throughput. A single Claude session does one task at a time, and you sit watching it. But plenty of real work is independent — restyle this component while rewriting that unrelated page; fix three unrelated bugs. For independent work, one session is a bottleneck you're imposing on yourself. Running several Claude Code instances in parallel removes it, and your job shifts from typing code to deciding what can run at once and reviewing what comes back.

So the chapter has two halves that share one spine — structure before action. Plan first (don't edit blindly); split deliberately (don't parallelize tasks that secretly depend on each other). The running example is a small web app called HookHub — a catalog that displays Claude Code hooks as cards linking to their repositories — and we'll plan it, then split work across parallel agents to refine it. The chapter is honest that its parallel demo uses the simplest, most fragile setup (everyone on one branch); the last section shows the isolation that real teams use.

Lesson

1. Plan mode — think before you touch

Claude Code's planning mode is a read-only mode for the foundational part of any non-trivial change: research, analysis, and design. The book's framing: it "enables a transition from exploratory coding to spec-driven development." In plan mode Claude can read files, analyze the codebase, make MCP calls, search documentation, and design a solution. It cannot edit, create, or delete files, make Git commits, install packages, or perform execution-level actions. Nothing changes on disk until you approve the plan.

You can enter plan mode three ways — the book teaches the first; the other two are worth knowing:

# 1. As a one-prompt prefix (the book's method): start Claude, then
/plan

# 2. Cycle permission modes with the keyboard (introduced in Ch.2):
#    press Shift+Tab to move default → accept-edits → plan

# 3. Start a whole session in plan mode from the shell:
claude --permission-mode plan

All three land in the same place: Claude works read-only until you say otherwise. One nuance worth getting right — "read-only" doesn't mean "does nothing." Claude can still run read-only shell commands and searches to understand the code (and the usual permission prompts still apply to those); what it can't do is mutate your files or repo. The book's worked example opens Claude in a project and enters /plan, then hands it a design task — and you watch it explore and produce a plan instead of immediately writing files.

When the plan is ready Claude presents it and asks how to proceed. Approving exits plan mode and switches the session into an editing mode (you choose how much oversight you want — auto-accept edits, review each edit, or keep refining the plan with more feedback). The exact menu wording moves between releases; the durable facts are: nothing was edited while you planned, and approval is the gate between design and execution.

Why force this separation at all? Because the most expensive mistakes are structural — wrong data model, wrong file touched, wrong assumption about how a module works — and those are cheap to fix in a plan and expensive to fix in code that's already been written and half-reviewed. Plan mode makes the cheap fix the default.

Analogy — measure twice, cut once A careful carpenter doesn't grab the saw first. They measure, mark, and sketch the cut on the wood — then step back and check it against the plan — and only then cut. Plan mode is the measuring and marking: Claude studies the material and shows you the cut line, and the saw stays on the bench until you nod. Re-marking a line costs nothing; un-cutting a board is impossible.

2. Spec-driven development — and making the plan durable

Plan mode produces a plan; spec-driven development is the discipline of treating that plan as a real artifact. The book is clear on the payoff: "Planning mode is especially useful when designing complex systems or understanding large projects. The primary benefit is the clear separation between planning and execution, which reduces risk and improves reliability."

The HookHub example shows the loop. In plan mode, the book asks Claude for a detailed specification:

Create a detailed specification for a web application called HookHub.
The application should:
- Display available Claude Code hooks
- Render them as cards
- Link each card to its GitHub repository
- Support filtering by hook event type

Claude — still read-only — produces an initial spec, and it isn't quite right: it features the hooks in a carousel and includes only a subset of event types. So the book refines it through feedback: drop the carousel in favor of showing all hook cards on the home page, and add the missing event types (including events triggered after code generation). This back-and-forth is the point — you're shaping the design in cheap, reversible plan-space, not in code.

The move that makes this durable is the book's "Persisting the hook marketplace specification" step: export the finalized spec to a Markdown file and commit it to the repository (a natural home is the .claude/ directory, alongside your other project context). Once it's a committed .md file, the spec:

• becomes durable repo context — it's versioned in Git, survives the session, and a new Claude session can read it and implement against it with clean context. (One precise point: dropping a file in .claude/ does not make Claude load it automatically — only CLAUDE.md and the files it @-imports, plus Claude's own auto-memory, load at startup. To have the spec pulled in every session, @-import it from CLAUDE.md (@.claude/linkboard-spec.md); otherwise just point Claude at it explicitly, e.g. "implement .claude/linkboard-spec.md.")
• constrains later implementation so the code matches the agreed design instead of drifting;
• gives you a checkpoint to reset to if an implementation attempt goes sideways — you still have the agreed spec to start over from.

This is exactly the workflow Anthropic documents as explore → plan → code → commit: explore in plan mode (read, don't edit), plan (ask for a detailed plan), code (switch out of plan mode and implement against the plan), commit (save with a clear message, open a PR). Writing the plan to a file is their recommended way to make it survive across sessions — "the most useful specs are self-contained: they name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step." A precise spec, the docs note, pays off more than time spent watching the implementation.

Analogy — the blueprint before the build No one pours a foundation and then decides where the kitchen goes. An architect produces a blueprint, the owner marks it up ("move that wall, add a window"), and everyone signs it — and that signed drawing stays pinned to the site trailer for the whole build. The spec file is the signed blueprint: cheap to revise while it's paper, binding once construction starts, and there to settle any "wait, what were we building?" the moment it comes up.

3. Running multiple Claude Code agents in parallel

The second half of the chapter changes the number of agents. Claude Code "supports running multiple AI agents simultaneously to accelerate development workflows" — and the simplest form is exactly what it sounds like: open several terminals and run a separate, full Claude Code in each, each working a different task within the same project.

The book is careful to frame this as the introductory version of multi-agent work, and to name its limitation up front. In this chapter every instance works on the same shared branch and the same files on disk. That's the easiest thing to set up and the easiest to reason about — there's no extra machinery — but it's also inherently fragile: if two agents touch the same file, or make changes that don't fit together, you get conflicts. The whole approach therefore rests on one prerequisite, which is the subject of the next section: the tasks you hand out must be genuinely independent.

The payoff when they are independent is real. Instead of one agent grinding through three unrelated jobs in sequence while you watch, three agents do them at once. Running several Claude sessions in parallel for independent work is a documented practice: Anthropic's best-practices guide lays out a menu of parallel approaches to pick from depending on how much coordination you want to manage yourself — isolated Git worktrees for separate CLI sessions, the desktop app's parallel sessions, cloud sessions on the web, and (for automated coordination) agent teams.

Analogy — two cooks, one kitchen Two cooks share a kitchen. If one is at the stove making sauce and the other is at the board chopping salad, they fly — twice the food in the same time. But it only works because they're at different stations. Put both at the same cutting board reaching for the same knife and you don't get twice the salad; you get elbows and a dropped bowl. Parallel agents on one branch are two cooks in one kitchen: fast when their stations don't overlap, a mess the instant they do.

4. Which tasks can actually run in parallel?

Everything in the parallel half hinges on one judgment call: is this set of tasks actually independent? The book draws the line cleanly.

Parallel-safe (independent). Tasks that don't need each other's results and don't touch the same code. The book's examples: fixing unrelated bugs, building separate UI pages, or working on independent components of a library. These "can be executed concurrently without interfering with one another."

Must be sequential (dependent). Tasks where one needs another to finish first. The book's example is a full-stack feature: if a frontend is implemented and then connected to an API that doesn't exist yet, "this often results in mock implementations or assumptions that do not match the final API." The frontend depends on the API being defined, so doing them at the same time produces guesses that don't line up. These tasks "should be completed in order."

So the discriminating question for any candidate pair is simply: does either one need the other's output, or would they edit the same files? If yes to either, it's sequential. If no to both, it's a parallel candidate.

This is why the book says the engineer's role shifts. When you stop typing every change yourself and start handing independent slices to several agents, your scarce skill is no longer keystrokes — it's decomposition and oversight: cutting the work into genuinely independent pieces, scoping each agent so it stays in its lane, and reviewing the combined result. "The role of the engineer shifts from implementation to coordination and oversight of multiple AI agents."

Analogy — laundry and dinner vs. walls and paint You can run the washing machine and cook dinner at the same time — neither needs the other, so the evening takes as long as the slower of the two. But you can't paint a wall before it's built, and you can't frame the wall before the foundation sets. Independent chores overlap for free; dependent ones have a forced order, and pretending otherwise just means re-doing the paint. Sorting your tasks into "laundry-and-dinner" versus "walls-and-paint" is the planning skill here.

5. Walkthrough — parallel development in HookHub

The book makes this concrete on the HookHub app. The flow has four beats; follow the shape, because the practical exercise mirrors it exactly.

Beat 1 — establish a known starting point. Everyone begins from the same commit so the runs are reproducible. The book checks out the project branch and resets to a specific commit, then installs and runs it:

git checkout project/hookhub
git reset --hard <commit-hash>
npm install
npm run dev

At this point the app shows a basic hero section and hook cards in a simple layout — no visual polish yet. That plain baseline is deliberately the context for handing parallel work to multiple agents.

Beat 2 — identify two genuinely independent tasks. Looking at the running app, the book picks two improvements that touch different parts of the page: updating the hook card component to improve its visual design, and updating the hero section of the main page. Crucially, these live in separate files (HookCard.tsx and Hero.tsx), so concurrent edits won't collide — exactly the §4 independence test, applied.

Beat 3 — run two instances, each scoped to its own file. Open two terminal windows, start claude in each, and give each a tightly scoped prompt that names the one file it may touch and explicitly forbids the others:

# Terminal 1 — Hook Card component
Improve the visual design of the HookCard component.
Modify only: src/components/HookCard.tsx.
Do not modify other files.

# Terminal 2 — Hero section
Improve the visual design of the Hero section.
Modify only: src/components/Hero.tsx.
Do not modify HookCard.tsx.

The "Modify only … / Do not modify …" scoping is the load-bearing trick. The two agents run concurrently, each editing its own file. Because the components are implemented in separate files, the changes don't overlap and no conflict arises — and, as a bonus, keeping components in separate files is just good practice for maintainability, readability, and testability.

Beat 4 — review everything together, then commit once. When both instances finish, you look at the combined result before saving anything:

git status
git diff

If the changes look correct, stage and commit them as a single, well-described unit:

git add .
git commit -m "Refine HookCard and Hero using parallel Claude Code agents"

That's the whole loop: a known baseline, two independent tasks, two scoped agents running at once, one human review, one commit.

Analogy — two contractors, two rooms, one key rule You hire two contractors for the weekend: one redoes the kitchen, one redoes the bathroom. The rule taped to the door is short — "kitchen crew: kitchen only; bathroom crew: bathroom only." They work at the same time and never trip over each other, because their rooms don't share a wall they'd both be tearing into. Monday you walk both rooms together, like the work, and sign off once. The "modify only this file" prompt is that taped-up rule; git diff is the Monday walk-through.

6. Doing isolation right — worktrees, subagents, and agent teams

The book is upfront that its demo is "the simplest form of multi-agent execution: multiple Claude Code instances operating on the same branch with shared file access," and that this is "inherently fragile" — overlapping edits or incompatible changes produce conflicts. It explicitly flags that branch isolation and structured review workflows are covered later in the book, and that the next chapter introduces subagents. Two pieces of current Anthropic guidance are worth adding so you know where this leads.

Isolation, the documented way: Git worktrees. Sharing one branch is what makes the demo fragile. The robust answer is to give each instance its own copy of the working files. Claude Code has this built in: claude --worktree <name> starts a session in an isolated Git worktree — by default created under .claude/worktrees/<name>/ on a new branch named worktree-<name> — so edits in one session can never touch another session's files. Run it again with a different name in a second terminal and you have two genuinely isolated parallel sessions, building a feature in one while fixing a bug in the other. A few caveats the docs are specific about, and that bite if you skip them:

• **Worktrees branch from the remote default (origin/HEAD) by default, so they start from a clean tree matching the remote — which means local commits you haven't pushed won't be present** (if there's no remote, Claude falls back to your local HEAD). When a worktree needs your in-progress local work, set worktree.baseRef to "head" in settings to branch from local HEAD instead.
• Add .claude/worktrees/ to your .gitignore so worktree contents don't show up as untracked files in your main checkout.
• Cleanup is conditional, not guaranteed. Exit a worktree with no uncommitted changes, no untracked files, and no new commits and it (and its branch) are removed automatically — unless the session is named, in which case Claude prompts so you can keep it. If there are changes or commits, Claude prompts to keep or remove. And non-interactive runs (--worktree together with -p) are not cleaned up automatically — remove those yourself with git worktree remove.

This is the upgrade path from §5's same-branch demo to something you'd actually run on a real codebase.

# Each terminal gets its own isolated copy of the files:
claude --worktree hookcard-restyle     # terminal 1
claude --worktree hero-restyle         # terminal 2

A family of parallel-work surfaces — don't conflate them. "Run multiple agents" isn't one feature. The three the book leans on are the place to start, and current Claude Code adds more around them:

And beyond those three, the docs describe Agent View (claude agents — a monitor for many background sessions), dynamic workflows (a script that runs many subagents and cross-checks their results), and /batch (a skill that splits one big change into 5–30 worktree-isolated subagent pull requests). You don't need them for this chapter — the point is that "multiple agents" is a landscape, not a single switch.

The takeaway: this chapter's "multiple terminals on one branch" is the entry point. Reach for worktrees the moment tasks might touch overlapping files; reach for subagents to delegate work — both to protect the main context and to parallelize; and reach for agent teams (once enabled) when sessions genuinely need to coordinate. Picking the right one is the same decomposition skill from §4, one level up.

Analogy — shared bench, separate workshops, and an apprentice §5's two cooks shared one kitchen and stayed out of each other's way by agreement. A worktree gives each cook their own kitchen — they physically can't grab the same knife, so the agreement isn't load-bearing anymore. A subagent is different: it's an apprentice — or several at once — you hand a self-contained job (count the pantry, prep a garnish), each working on their own and reporting the result back, so you don't have to leave your station. And an agent team is a brigade with a shared ticket rail and a head chef calling out hand-offs. Same word — "help" — very different arrangements.

The whole chapter in one image — design it, split it, isolate it

Analogy — pedagogical summary, drawing on all six sections

Picture renovating a house with a smart, fast crew.

You design before anyone swings a hammer. You sit with the architect and produce a marked-up, signed blueprint — walls here, window there, kitchen not moving (plan mode: read-only, measure twice). You pin a copy to the site trailer so every crew works from the same drawing and you can settle any dispute by pointing at it (the committed spec — durable project memory). Nothing structural happens until you sign (the approval gate).

You split the work by what doesn't overlap. Kitchen and bathroom can go at once — different rooms, no shared wall (independent → parallel). But you don't paint a wall before it's framed (dependent → sequential), so you order those. Sorting the jobs is your work now; you've stopped holding the hammer and started running the site (the engineer's shift to oversight).

You run the independent crews at the same time, each in its lane. "Kitchen crew, kitchen only; bathroom crew, bathroom only" (two terminals, "modify only this file"). Monday you walk both rooms together and sign off once (git diff, then one commit). It's fast and safe — but only because the rooms didn't share a wall, and the book is honest that this is the training-wheels version.

For real jobs, you give each crew its own site. Worktrees hand each instance a private copy so they can't collide; subagents are the apprentice you send to take inventory; agent teams are a coordinated brigade. The renovation got faster the moment you learned to design first, split deliberately, and isolate properly — which is the whole chapter.

Activity — Spec it, then split it

Ten minutes, individual, no setup required. Pick a small feature you actually understand — from your own work or a side project (e.g., "add a CSV export button to a report page," or "add dark mode to a small site").

1. Write the five-line plan-mode spec. In five bullet points or fewer, write what you'd want Claude to hand you back from plan mode before it edited anything: the files/interfaces involved, what's in scope, what's explicitly out of scope, and one end-to-end check that would prove it works. This is the artifact you'd commit as spec.md.
2. Decompose into tasks. Break the feature into 3–6 concrete tasks (e.g., "add the export button to the UI," "write the CSV serializer," "wire the button to the serializer," "add a test").
3. Label each task independent or dependent, and for every dependent one, write what it depends on in a few words ("needs the serializer's function signature first").
4. Draw the run plan. List which tasks could run in parallel (independent, non-overlapping files) and which must run in order. If two "independent" tasks actually edit the same file, mark them as a hidden dependency — that's the most common mistake.

Keep the result. The "spec + a parallel/sequential map" is exactly what you'd produce in plan mode before unleashing one or several agents — and step 4 is the judgment the second half of this chapter is really teaching.

Practical exercise — Plan it read-only, then build it with two agents at once

~35–45 minutes. Hands-on. No web framework, no npm, no accounts — just Claude Code, git, and a browser to open a local HTML file. You'll do the chapter's two halves on one tiny sandbox: first drive plan mode and persist a spec, then run two Claude Code instances in parallel on genuinely independent files and commit the combined result. A stretch step upgrades the parallel run to worktrees.

Everything happens in a throwaway sandbox — nothing here touches the training repo.

Setup (5 min). Create a tiny static "linkboard" — a stand-in for HookHub: a page with a hero section and some cards, where the hero and the cards are styled by two separate files (so two agents can own one each):

mkdir -p ~/cct-ch6-lab/styles && cd ~/cct-ch6-lab
git init -q
cat > index.html <<'HTML'
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>Linkboard</title>
  <link rel="stylesheet" href="styles/hero.css" />
  <link rel="stylesheet" href="styles/cards.css" />
</head>
<body>
  <header class="hero"><h1>Linkboard</h1><p>A tiny catalog.</p></header>
  <main class="cards">
    <article class="card"><h2>Repo one</h2><a href="#">view</a></article>
    <article class="card"><h2>Repo two</h2><a href="#">view</a></article>
  </main>
</body>
</html>
HTML
echo '.hero { padding: 16px; }' > styles/hero.css
echo '.cards { display: block; } .card { border: 1px solid #ccc; }' > styles/cards.css
git add . && git commit -q -m "init linkboard baseline"

Open index.html in your browser to see the plain baseline (this is "Beat 1 — a known starting point").

Part 1 — plan mode, read-only (10 min). Start Claude in the sandbox and enter plan mode, then ask for a design without letting it edit:

/plan

Produce a detailed spec for improving this linkboard's visual design.
Cover the hero section and the cards separately, name the exact files
each change touches, state what is out of scope, and end with one
check I can run to confirm it looks right. Do not edit anything yet.

Expected outcome: Claude reads index.html, styles/hero.css, and styles/cards.css and returns a written spec — and does not modify any file (confirm with git status in another terminal: clean). That read-only behavior is the whole point of plan mode. Refine the spec with one round of feedback ("make the cards a responsive grid"), then persist it: approve/exit plan mode and ask Claude to write the spec to a file and commit it:

Write that finalized spec to .claude/linkboard-spec.md and commit it.

git log --oneline    # you should see the spec commit; the spec is now durable context

Part 2 — two agents in parallel (15 min). From the spec, you have two independent tasks that touch different files: restyle the hero (styles/hero.css) and restyle the cards (styles/cards.css). Open two terminal windows, run claude in each, and scope each one:

# Terminal 1
Improve the visual design of the hero section per .claude/linkboard-spec.md.
Modify only: styles/hero.css. Do not modify any other file.

# Terminal 2
Improve the visual design of the cards per .claude/linkboard-spec.md.
Modify only: styles/cards.css. Do not modify any other file.

Expected outcome: both run at the same time; each edits only its own CSS file. Because the files don't overlap, there's no conflict. Review the combined result before saving anything:

git status            # two modified files: styles/hero.css and styles/cards.css
git diff

Reload index.html in the browser — both the hero and the cards should look improved. If the diff looks right, commit once:

git add .
git commit -m "Restyle hero and cards using two parallel Claude Code agents"

Part 3 — see the failure mode, then fix it with worktrees (10 min, stretch). First, feel why independence matters. Start over conceptually: imagine you'd instead given both agents the task "improve the overall look in index.html." They'd both edit the same file — and you'd get a merge mess. Write one sentence in your notes naming which two tasks in your spec would collide if run in parallel.

Now do it the isolated way. Run the same two tasks in separate worktrees so they physically can't collide even if they did touch the same file:

claude --worktree hero-restyle     # terminal 1 — worktree at .claude/worktrees/hero-restyle on branch worktree-hero-restyle
claude --worktree cards-restyle    # terminal 2 — a second isolated worktree + branch

One gotcha to plan for: by default a worktree branches from your remote default (origin/HEAD), starting from a clean tree matching the remote — so local commits you haven't pushed (including .claude/linkboard-spec.md) won't be there. This sandbox has no remote, so Claude falls back to your local HEAD and the spec will be present; on a real repo with a remote, either push your spec first or set worktree.baseRef to "head" in settings so the worktree branches from local HEAD. Also add .claude/worktrees/ to .gitignore so the worktree copies don't appear as untracked files in your main checkout.

Expected outcome: each session works in its own worktree on its own branch; you merge the two branches afterward rather than relying on "please don't touch the other file." Heads-up on cleanup: a clean, unnamed worktree session is removed on exit, but anything with changes or new commits (and any non-interactive -p run) sticks around until you remove it with git worktree remove. This is the difference between the chapter's training-wheels demo and how isolation is actually done.

Success checklist

• [ ] In Part 1, git status was clean while Claude was in plan mode — it produced a spec without editing. You can state what plan mode can and cannot do.
• [ ] You persisted the spec to .claude/linkboard-spec.md and committed it (git log shows it).
• [ ] In Part 2 you ran two claude instances at once, each scoped with "modify only … / do not modify …", and git diff shows changes in two non-overlapping files.
• [ ] You reviewed with git status / git diff and committed the combined result once.
• [ ] You can name one pair of tasks in your spec that would be unsafe to parallelize (shared file or a dependency), and why.
• [ ] (Stretch) You ran the parallel tasks under claude --worktree and understand how that removes the same-branch fragility.

Common pitfalls - Treating plan mode as "slow mode." It isn't a speed setting — it's a no-writes setting. If git status shows modified files during planning, you've already left plan mode. - "Independent" tasks that share a file. Two restyles are only independent if they live in different files. If both agents edit index.html, you're back to one cook, one cutting board, two knives — expect a conflict. This is the §4 test; apply it before you open the second terminal. - Forgetting the scope line. Without "Modify only X. Do not modify other files," an agent may helpfully "fix" a neighbouring file and collide with the other agent. The scope line is what keeps lanes separate on a shared branch. - Committing without reviewing. The whole safety of the same-branch approach is the single human git diff before git add. Don't skip it — that review is where you'd catch two changes that individually look fine but don't fit together. - Reaching for parallel terminals when a subagent (or a worktree) fits better. If the goal is delegating a task in its own context — to keep the main conversation clean or to parallelize — that's a subagent (next chapter). If tasks might touch the same files, that's worktrees. Parallel terminals on one shared branch are only for independent work.

Knowledge check — try the quiz

Once you've read the lesson and worked the lab, take the chapter quiz from the navigation bar. Six questions: five grounded in the book chapter, one synthesis question that ties this chapter's "multiple terminals on one branch" to the broader family of isolation and multi-agent mechanisms. Retake it until you're confident.

Further reading & enrichment sources

• Anthropic docs — "Permission modes" (https://code.claude.com/docs/en/permission-modes). What plan mode is, the three ways to enter it (/plan, the Shift+Tab cycle, --permission-mode plan), the fact that it's read-only with permission prompts still applying, and how approving a plan transitions the session into an editing mode.
• Anthropic docs — "Claude Code best practices" (https://code.claude.com/docs/en/best-practices). The canonical explore → plan → code → commit workflow, why writing the plan to a file (or GitHub issue) makes it durable across sessions, and what makes a spec "self-contained." Also the writer/reviewer pattern that motivates running a second, fresh-context instance.
• Anthropic docs — "Git worktrees" (https://code.claude.com/docs/en/worktrees). claude --worktree <name> (default path .claude/worktrees/<name>/, branch worktree-<name>), per-session file isolation, the origin/HEAD vs worktree.baseRef: "head" base-branch choice, the .gitignore note, the isolation: worktree subagent option, and the conditional cleanup rules (clean+unnamed sessions auto-removed; changes/commits or -p runs are not) — the robust upgrade from this chapter's same-branch demo.
• Anthropic docs — "Subagents" (https://code.claude.com/docs/en/sub-agents). The next chapter's topic: delegating a task to a specialized helper that runs in its own context window and returns a summary — used both to keep side-work out of the main context and to parallelize work (subagents can even run in isolated worktrees).
• Anthropic docs — "Agents" overview (https://code.claude.com/docs/en/agents). The map of Claude Code's parallel-work surfaces — subagents, Agent View (claude agents), agent teams, dynamic workflows, and /batch — useful for seeing why "multiple agents" is a landscape, not one feature.
• Anthropic docs — "Agent teams" (https://code.claude.com/docs/en/agent-teams). Coordinated multi-session work with a lead, a shared task list, and inter-agent messaging — experimental and disabled by default (enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS).
• Anthropic docs — "Slash commands" (https://code.claude.com/docs/en/commands). Where built-in commands like /batch live, for when you outgrow hand-running parallel terminals.