Git Worktrees and Claude Code: A Parallel Development Flight Deck

Most developers first experience Claude Code as an unusually capable pair programmer: open a terminal, describe a task, inspect the diff, repeat. That is useful, but it leaves a great deal of leverage on the table.

The more interesting model is to treat Claude Code as a specialist working at a dedicated flight deck. Each task gets its own runway, its own instruments, and its own pre-flight checklist. Git worktrees provide the physical separation. A task contract provides the mission. Tests, linters, and focused review commands provide air-traffic control.

This workflow is not about asking several agents to change the same repository at once and hoping Git resolves the consequences. It is about making parallel work legible: each Claude session has a bounded objective, a clean filesystem, a known branch, and a verification standard.

Why one working directory becomes a bottleneck#

A single checkout is a shared whiteboard. It works until two lines of investigation collide:

• You are diagnosing a production bug while an agent is upgrading dependencies.
• One task requires a broad refactor while another needs a narrow documentation fix.
• A long-running test suite blocks the same terminal session where you want to inspect a different change.
• An agent makes a promising but incomplete change, and you need to preserve that state without mixing it into unrelated work.

Claude Code amplifies this problem because it can move quickly through a repository. It may touch tests, implementation files, configuration, generated artifacts, and documentation in one session. That speed is valuable only when the change boundary is clear.

Git worktrees turn branches into separate directories. Instead of repeatedly stashing, resetting, or mentally tracking partial changes, each task receives an isolated filesystem.

Now each directory is an independent launch point for Claude Code. The agent working on authentication cannot accidentally absorb unfinished API documentation edits from your primary checkout.

The task contract: give the agent a mission, not a mood#

A strong Claude Code session starts with a compact task contract. The contract is not a long prompt full of implementation guesses. It is a small operational document that defines what success means and what must not change.

I keep one in the task description or a temporary file at the root of the worktree:

Then start Claude Code with an instruction that forces reconnaissance before implementation:

Read the task contract and inspect the relevant code paths. Do not edit yet. Summarize the current behavior, likely failure mode, files you expect to change, and the verification plan.

This opening move is disproportionately valuable. It separates repository understanding from code generation. If Claude identifies the wrong subsystem, you correct course before a diff exists. If it discovers that the apparent bug is actually handled by a database constraint or a message consumer, the task can be reframed while the cost is still low.

The phrase “do not edit yet” matters. It creates a deliberate first pass rather than a blur of tool calls and patches.

Build worktrees around change shape, not ticket count#

A tempting pattern is one worktree per issue. A better pattern is one worktree per coherent change shape.

For example, a TypeScript service might have these parallel lanes:

1. Behavior lane — implement a narrowly defined product or bug-fix change.
2. Evidence lane — add or improve tests that characterize current behavior.
3. Operational lane — update CI, Docker configuration, migration notes, or observability.
4. Exploration lane — investigate a risky refactor without committing to it.

These lanes should not all run automatically for every request. They are tools for work with enough uncertainty or breadth to justify separation.

The exploration lane is especially useful with Claude Code. Ask the agent to map dependencies, identify architectural seams, estimate the blast radius, and propose multiple implementation approaches. Explicitly tell it not to modify production code. Its output becomes a design brief for the behavior lane.

This is safer than letting the first implementation session become both researcher and surgeon. Research benefits from breadth; implementation benefits from constraint.

A practical session rhythm#

In each worktree, use a four-stage rhythm: orient, plan, change, prove.

1. Orient#

Ask Claude to inspect repository instructions first: CLAUDE.md, contributor guides, package scripts, CI workflows, and nearby tests. Then have it report the commands it intends to run.

This is where repository-local rules earn their keep. A useful CLAUDE.md can specify test commands, formatting expectations, architectural boundaries, and prohibited shortcuts. It should contain durable engineering facts, not an ever-growing archive of past prompts.

2. Plan#

Request a file-level plan with risks:

Propose the smallest viable implementation. List files to modify, invariants to preserve, tests to add or update, and any ambiguity that requires a decision.

For changes involving APIs, queues, caches, or persistence, ask for a compatibility inventory. A modification may compile while silently changing a REST response, Kafka message shape, Redis key convention, or database transaction boundary.

3. Change#

Authorize implementation in small checkpoints. For a medium-sized task, I prefer one logical step at a time: production behavior first, tests second, documentation third. After each step, ask Claude to summarize the diff and name anything it intentionally did not address.

This keeps the conversation navigable and makes it easier to discard a bad direction. It also reduces the tendency for an agent to “clean up” adjacent code that was not part of the mission.

4. Prove#

Do not end with “looks good.” End with evidence.

Ask Claude to run the narrowest relevant checks first, then broader checks when justified:

For a .NET service, that may become targeted dotnet test commands followed by the affected solution tests. For Docker or Kubernetes changes, validation might include rendering manifests, building an image, or starting a focused integration environment.

The key is to distinguish executed evidence from reasoned confidence. Claude may correctly explain why a change should work, but only command output can establish that a test actually passed in the current worktree.

Use Git as the handoff protocol#

When a session reaches a stable point, ask Claude to perform a review-oriented status report:

Inspect git diff and git status. Summarize behavior changes, test coverage, remaining risks, and files that appear unrelated to the task.

Then review the diff yourself with the task contract open beside it. The contract gives you a better review question than “Is this code elegant?” Ask instead:

• Does every changed file serve the stated goal?
• Did the agent preserve the listed invariants?
• Is the test asserting the failure mode rather than merely exercising new lines?
• Did configuration or generated files change unexpectedly?
• What happens when this branch is merged with the other active lanes?

Commit only coherent checkpoints. A clean commit is not just version-control hygiene; it is a portable handoff artifact. Another Claude Code session, a teammate, or your future self can inspect it without reconstructing a tangled workspace state.

The merge queue is where parallelism becomes engineering#

Parallel work is cheap at the start and expensive at integration. Treat merge readiness as a separate phase.

Before merging a worktree branch, rebase or merge the current target branch, rerun affected checks, and inspect the final diff again. If two branches touch the same service boundary, merge the branch that establishes the shared contract first. Then let the second branch reconcile against reality rather than against an earlier snapshot.

Claude Code can help here, but give it a precise role:

Compare this branch with the updated target branch. Identify semantic conflicts, not only textual conflicts. Pay special attention to changed interfaces, tests, configuration, and error handling. Do not resolve conflicts until you explain the options.

That instruction matters because Git can resolve text while leaving an invalid design. The costly failures are often semantic: duplicated validation, mismatched error formats, two incompatible migration assumptions, or a test that now proves the wrong behavior.

The durable habit#

The power-user workflow is not a collection of magic prompts. It is an operating model: isolate work, state intent, inspect before editing, make changes in bounded increments, and demand executable evidence.

Claude Code becomes more effective when it is given room to work and a clear definition of where its work must stop. Git worktrees provide the room. Task contracts provide the boundary. Tests and diffs provide the evidence.

Run that system consistently, and the terminal stops being a single crowded desk. It becomes a flight deck with multiple controlled runways—fast enough for ambitious engineering, structured enough to land safely.