Contents
- 01Know What You Are Operating
- 02Orient to an Existing Project
- 03Turn Intent Into a Build Specification
- 04Make Project Context Durable
- 05Bound Permissions and the Sandbox
- 06Make Changes With Git and Worktrees
- 07Debug and Verify the Result
- 08Extend With MCP, Skills, and Hooks
- 09Delegate and Run Work in Parallel
- 10Operate in CI and Ship the Capstone
Delegate and Run Work in Parallel
Use subagents, parallel sessions, agent teams, and worktree isolation only when task boundaries and integration ownership make concurrency safer and faster.
By the end
A parallel execution plan with independent lanes, bounded context, explicit file or artifact ownership, worktree strategy, integration order, and adversarial verification.
Parallelism is a dependency decision
More agents do not automatically produce more useful work. Two tasks can run in parallel only when their inputs are available, their owned surfaces do not conflict, and their results can be integrated through a known contract. If one task defines the schema another must use, doing both simultaneously creates rework disguised as speed.
Draw the dependency graph before delegating. Parallelize independent research, isolated components, separate test investigations, or adversarial review. Keep tightly coupled implementation sequential until the shared interface is accepted. Include integration and final verification as real work rather than assuming separate outputs will assemble themselves.
Choose the parallel surface
Claude Code offers several parallel patterns. A subagent is delegated work in its own context and returns a result to the main conversation. Separate sessions are independent workstreams a human can monitor. Agent teams coordinate multiple Claude Code instances through shared tasks and messaging. Agent view provides a surface for managing many sessions. Each has different setup, communication, and context behavior.
Use the lightest mechanism that fits. A read-only investigation often belongs in a subagent because its many file reads stay out of the main context. Two independent feature branches may be clearer as named worktree sessions. A coordinated team is justified only when workers genuinely need shared tasks or peer communication. Experimental or plan-specific features should be checked against the current availability documentation before becoming a required workflow.
Delegate a self-contained packet
A custom subagent does not automatically receive the main conversation history or every file already read. Claude composes a delegation message, and the worker starts from its own context. Give it the outcome, relevant paths, constraints, tools, acceptance criteria, expected return artifact, and what it must not do. If context is too important to summarize, keep the task in the main session or use an appropriate fork pattern.
Restrict tools to the job. A research subagent may need Read, Grep, and Glob but no editing. A verification agent may run tests without owning the fix. A documentation worker may edit only docs. Tool limits reduce accidental authority and make the returned evidence easier to trust.
Isolate writes and plan integration
When workers edit source, give them isolated worktrees or non-overlapping ownership. Claude Code custom subagents can set `isolation: worktree`, and separate sessions can start with `--worktree`. Isolation prevents direct overwrites but does not eliminate logical conflicts: two branches can still make incompatible assumptions about the same interface.
Assign one integration owner who understands the accepted specification and base branch. Require each lane to return a commit or artifact, changed surfaces, tests, assumptions, and unresolved risk. Integrate in dependency order, inspect each diff, resolve conflicts deliberately, and run the full verification suite after assembly. A successful lane test is not proof that the combined system works.
Separate builders from verifiers
One valuable use of parallel context is independent verification. The agent that implemented a change has seen its own reasoning and may repeat the same assumptions when reviewing it. A fresh subagent can compare the diff with the original acceptance criteria, search for missed call sites, run adversarial examples, and attempt to disprove the completion claim.
Independence requires a different task, not just a different agent name. Give the verifier the specification, diff, proof claims, and authority to inspect, but not an instruction to confirm success. Ask for counterexamples, missing evidence, security or data risks, and exact file references. The integration owner decides which findings require repair before merge.
- Research lane: gathers source-backed facts and returns a decision-ready summary.
- Build lane: owns a bounded implementation and its targeted checks.
- Integration lane: owns shared contracts, merge order, conflicts, and combined behavior.
- Verification lane: tries to falsify the result against the original acceptance criteria.
- Human owner: controls consequential actions and resolves product tradeoffs.
Working reference
Commands and patterns
Define a worktree-isolated custom subagent
--- name: focused-implementer description: Implements one accepted, file-bounded task and returns a tested commit tools: Read, Grep, Glob, Edit, Bash isolation: worktree --- Read the delegated task packet. Confirm scope before edits. Preserve unrelated work. Run the named checks and return the commit, changed files, evidence, and remaining risk.
Save a reviewed definition under `.claude/agents/focused-implementer.md`. Tool and worktree isolation are job controls, not substitutes for a precise task packet.
Start separate isolated sessions
claude --worktree research-auth claude --worktree implement-profile
Run each command in its own terminal only when the branches have independent ownership and an explicit integration plan.
Request independent verification
claude "Use a fresh subagent to review SPEC.md and the current diff. Try to falsify each completion claim, run the named checks, find missed call sites, and return only evidence-backed findings. Do not modify files."
The verifier receives an adversarial goal and no edit authority, keeping its context and incentives separate from implementation.
When the happy path breaks
Failure modes
Symptom
Parallel lanes repeatedly wait for or redo one another's work.
Likely cause
Tasks with unresolved dependencies or shared design decisions were launched simultaneously.
Recovery
Return to the dependency graph, finish and accept the shared contract first, then restart only the lanes whose inputs are stable.
Symptom
Two workers produce conflicting edits to the same files or interfaces.
Likely cause
File ownership, worktree isolation, and integration responsibility were not assigned before execution.
Recovery
Stop one lane, preserve both diffs, choose an interface owner, and re-scope work into non-overlapping branches with an explicit merge order.
Symptom
A subagent returns a generic answer or solves a different problem.
Likely cause
The delegation assumed it could see the parent conversation and omitted essential paths, constraints, examples, or acceptance checks.
Recovery
Rewrite the task as a self-contained packet and include only the minimum source references needed for independent execution.
Symptom
Several agents agree the change is correct, but all repeat the same unsupported assumption.
Likely cause
The review tasks were framed as confirmation and inherited the implementation narrative rather than receiving an adversarial proof contract.
Recovery
Use a fresh, read-only verifier asked to find counterexamples and missing evidence against the original specification, then require independent runtime checks.
Hands-on lab
Run a three-lane change with independent verification
Choose a bounded feature whose research and implementation can be separated, then coordinate a research lane, an isolated build lane, and a read-only verification lane.
- 01Write the accepted specification and draw dependencies among research, implementation, integration, and verification.
- 02Create a read-only research packet with exact questions, source requirements, and a decision-ready return format.
- 03Use the research output to freeze the implementation contract before starting the build lane.
- 04Run the build lane in a dedicated worktree with explicit file ownership and targeted checks.
- 05Have the integration owner inspect the commit and run the combined project checks.
- 06Give a fresh read-only verifier the original specification, final diff, and claimed receipts; ask it to falsify them.
- 07Resolve findings, rerun verification, and document which work was parallel, sequential, or human-owned and why.
Deliverable: A lane ledger containing dependency graph, delegation packets, worktree and commit identities, returned artifacts, integration decisions, adversarial findings, and final evidence.
Reusable artifact
Parallel lane contract
A task packet and integration record that makes multi-agent execution reviewable rather than conversationally coordinated.
Lane: [research / build / integration / verification] Owner: [human, session, or subagent name] Outcome: [one bounded result] Inputs available now: [files, decisions, artifacts] Dependencies not yet available: [must be empty before start] Owned files or artifacts: [exclusive scope] Tools and permissions: [minimum set] Isolation: [read-only / same checkout / named worktree] Forbidden actions: [scope and authority boundary] Acceptance checks: [exact pass/fail criteria] Return packet: [summary, commit, diff, commands, evidence, risk] Integration order: [predecessor -> lane -> successor] Conflict owner: [person who resolves shared decisions] Final combined verification: [command and observer]
Before you move on
Receipt checklist
- Every parallel lane begins with all required inputs and has non-overlapping ownership or worktree isolation.
- Each subagent receives a self-contained packet and only the tools required for its job.
- The integration owner reviews lane commits and runs combined checks after assembly.
- A fresh read-only verifier attempts to falsify the completion claims.
- The final record distinguishes lane success, integrated success, and any external or production proof.
Primary sources
