Parallel Development with Claude Code

In this post, I'll walk you through the pattern I've developed for orchestrating multiple Claude Code instances across separate worktrees, complete with the scripts, configuration templates, and philosophy that make this approach effective. Whether you're shipping features for a startup or maintaining a complex monorepo, this workflow can help you move faster without sacrificing code quality.

The Parallel Development Workflow

The core idea is simple: use Git worktrees to create isolated working directories for each task, then spin up separate Claude Code instances to work on them in parallel. Here's how the workflow unfolds in practice:

1. Define Well-Scoped Tickets

Start by creating clear, focused tickets in your project management system of choice. The key word here is well-scoped. Each ticket should represent a discrete unit of work that Claude Code can understand and execute without requiring massive refactors or complex architectural changes.

Good tickets include specific acceptance criteria, clear boundaries, and enough context for both human developers and AI agents to understand what success looks like. Think of tickets as prompts for your AI assistant—the better the prompt, the better the output.

2. Create a New Worktree

Using a worktree script (which we'll detail in the quick start), create a fresh working directory for your ticket. This script automates the process of setting up a new git worktree, creating a branch, and preparing the environment:

./worktree.sh create feature-new-api-endpoint

This command creates a new directory with your repository checked out to a fresh branch, completely isolated from your other work. You can have as many of these as your system resources allow—each one independent, each one ready for its own Claude Code instance.

3. Launch Claude Code in Planning Mode

Navigate into your new worktree directory and launch Claude Code. This is where your carefully crafted task prompt template comes into play. Paste your prompt template followed by the specific ticket description, then put Claude Code into planning mode.

In planning mode, Claude Code will analyze the task, explore the codebase, and develop a comprehensive plan for implementation. This is your chance to catch any misunderstandings early. The AI will propose specific files to modify, functions to create, and tests to write.

4. Iterate on the Plan

Review Claude's proposed plan carefully. This is not a rubber-stamp process. Ask clarifying questions, request alternative approaches, or guide the AI toward your preferred patterns. The goal is to reach agreement on an implementation strategy that aligns with your codebase's conventions and architecture.

This iterative planning phase is crucial. A few minutes of back-and-forth here can save hours of refactoring later. Once you're satisfied with the plan, you can move forward with confidence.

5. Execute in Automatic Mode

With a solid plan in place, switch Claude Code to automatic mode and let it execute. The AI will implement the changes, run tests, and iterate on the code. Your job shifts from implementer to reviewer—check in periodically to ensure Claude stays on track and doesn't drift from the agreed-upon plan.

Thanks to the minimal-friction Claude Code configuration you've set up (more on that in the quick start), the AI can operate autonomously within safe boundaries. It can run tests, make commits, and perform standard development tasks without constant permission prompts.

6. Wash, Rinse, Repeat

While Claude Code works on your first ticket in worktree #1, you can immediately move to worktree #2 and start the process again with a completely different task. Open multiple terminal windows, each with its own worktree, each with its own Claude Code instance grinding away on independent work streams.

Your role becomes orchestrator: spinning up new work streams, checking in on active ones, reviewing completed code, and merging finished features. Instead of being blocked by AI execution time, you're multiplying your effective development capacity.

Quick Start: Getting Your Environment Ready

Ready to implement this workflow? Here's a step-by-step guide to getting everything set up. You'll need three foundational pieces: the worktree script, a Claude Code configuration, and a task prompt template.

Step 1: Set Up the Worktree Script

First, grab the worktree management script from this gist. Save it somewhere accessible—I keep mine in a scripts directory alongside my active projects.

Edit the script to point to your repository by updating the DEFAULT_REPO_DIR variable at the top:

DEFAULT_REPO_DIR="~/path/to/your/repo"

Make the script executable and verify it works:

chmod +x worktree.sh
./worktree.sh list

The script provides several useful commands: create, list, remove, open, and cleanup. It creates worktrees in a ./worktrees directory relative to where you run the script, keeping your workspace organized.

Step 2: Configure Claude Code for Minimal Friction

Create your first worktree for the initial Claude Code configuration:

./worktree.sh create claude-config

Navigate into the worktree and launch Claude Code. Then, use the comprehensive configuration guidelines from this gist to set up a .claude/settings.json file in your repository root.

The configuration uses a three-tier permission system:

• Allow (Green Zone): Safe operations like reading files, running tests, git status checks

• Ask (Yellow Zone): Impactful operations like installing packages or pushing to remote

• Deny (Red Zone): Dangerous operations like deleting files with rm -rf, accessing credentials, or modifying lock files

Here's a minimal example configuration for autonomous development:

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git add*)",
      "Bash(git commit*)",
      "Bash(npm run *)",
      "Bash(make *)",
      "Read(./src/**)",
      "Write(./src/**)",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env*)",
      "Write(*lock*)"
    ],
    "ask": [
      "Bash(git push*)",
      "Bash(npm install*)"
    ],
    "defaultMode": "acceptEdits"
  }
}

Take time to get this right. Test the permissions by running various commands through Claude Code and adjusting the configuration until it feels smooth but safe. Once satisfied, commit the configuration file to your repository—it will now be shared across all worktrees.

Step 3: Create Your Task Prompt Template

The prompt template is your secret weapon for consistent, high-quality AI assistance. Use this template as a starting point, customizing it for your project's specific structure and conventions.

The template should include:

• Project layout: Describe your monorepo structure, applications, and key packages

• Build and test commands: Specify how to install dependencies, run tests, and build

• Coding patterns: Document any project-specific conventions or architectural patterns

• Success criteria: List all commands that must pass (build, lint, format, tests)

• Important constraints: Note any limitations like shared resources or port conflicts

Save your customized template somewhere accessible—I keep mine in a linear for quick copy-paste and collaboration with my team. Each time you create a new worktree, you'll paste this template followed by the specific ticket you're working on.

Step 4: Test Drive Your Setup

Merge your configuration worktree and create a test worktree for a real task:

# Merge your config changes
cd worktrees/claude-config
git add .claude/settings.json
git commit -m "Add Claude Code configuration"
git push

# Create a new worktree for actual work
cd ../..
./worktree.sh create feature-test

Launch Claude Code in the new worktree, paste your prompt template plus a well-scoped ticket, and watch the magic happen. You now have the foundation for parallel AI-assisted development.

Philosophy: When to Use This Approach (And When Not To)

Before you rush off to parallelize everything, it's important to understand what makes this workflow effective and where it breaks down. This isn't a silver bullet—it's a specialized tool that works best under specific conditions.

The Power of Well-Scoped Tickets

This workflow creates a powerful incentive structure: writing clear, well-scoped tickets directly translates to faster, higher-quality implementation. When you know that Claude Code will be working autonomously on your ticket, you're naturally motivated to be specific, provide context, and think through the problem carefully.

This is actually fantastic for your engineering process. Well-scoped tickets are easier to review, less prone to scope creep, and create a clear audit trail of decisions. Whether you're working with AI or humans, this discipline pays dividends.

Conversely, if you write expansive, poorly-defined tickets, Claude Code will struggle. The AI will ask clarifying questions, drift off course, or make incorrect assumptions. This feedback loop forces you to practice better ticket writing—a skill that benefits your entire team, not just your AI assistants.

Ideal Use Cases

This workflow excels when you have:

• Multiple non-conflicting tasks: Work that touches different parts of the codebase without overlapping file modifications

• Well-defined features or bug fixes: Tickets with clear acceptance criteria and minimal ambiguity

• Established patterns to follow: An opinionated codebase with clear conventions that Claude Code can emulate

• Good test coverage: Tests that can verify Claude's work and catch regressions automatically

• A backlog of discrete improvements: Feature additions, small UI updates, documentation fixes, or technical debt paydown

Think of this as "production-line development" for well-understood work. You're not exploring new architectural patterns or making fundamental design decisions in parallel—you're executing on a clear plan across multiple fronts simultaneously.

When NOT to Use This Workflow

This approach breaks down when you're dealing with:

• Large architectural changes: Refactors that touch dozens of files or require careful coordination

• Exploratory or research work: Tasks where you're still figuring out the problem space or evaluating approaches

• High-conflict situations: Multiple tasks that modify the same core abstractions or shared utilities

• Greenfield projects: New codebases without established patterns for Claude Code to follow

• "Vibe coding" sessions: Casual exploration or prototype work where you're not sure what you're building

This is not a framework for throwing poorly-thought-out ideas at AI and hoping something sticks. It's for executing well-planned work at scale. I like to see agents as sharing the burden in doing work that is maybe not quite worth my time — as an experienced software engineer and system architect, my time is best spent:

• Specifying new features

• Coming up with codebase conventions

• Designing systems

• and scoping work

If I can offload routine maintenance such that I can focus on those things, that’s an amazing win!

Dealing with failures

I cannot claim categorically that this workflow will execute cleanly for all tasks. Often you will run into situations where Claude Code:

• fails to complete a ticket independently

• goes down a bad rabbit hole it cannot pull itself out of

• or just plain hallucinates the achievement of its goal

My best advice is to verify outputs as your agents generate diffs in your code base. That is, if you are launching several instances in parallel, check in regularly, guide your agents in the right direction with follow ups, and nip bad paths in the bud before they become issues.

Your Critical Role as Reviewer

Here's the most important thing to understand: you are still the senior engineer on this team, even if most of your team members are AI agents. Your job shifts from writing code to:

• Writing clear specifications through well-scoped tickets

• Reviewing code quality to ensure it's maintainable and follows best practices

• Maintaining architectural integrity across all parallel work streams

• Teaching by example through code patterns and conventions

• Catching technical debt before it compounds across multiple features

If you neglect code review, thinking "the AI handles everything," you'll quickly find your codebase becoming bloated and brittle. Claude Code is powerful, but it can also amplify bad patterns if you're not vigilant. Think of it like leading a team of junior engineers—capable, but requiring guidance and oversight.

The good news is that reviewing code is often faster than writing it from scratch, so you can maintain quality while still achieving the velocity gains from parallel development.

The Importance of an Extensible Codebase

This workflow works best with opinionated, well-structured repositories. If your codebase is a tangled mess of anti-patterns, Claude Code will learn and perpetuate those patterns across multiple parallel work streams—compounding your problems rather than solving them.

Before investing heavily in this workflow, ensure your repository has:

• Clear directory structure and module organization

• Consistent coding conventions enforced by linters and formatters

• Good test coverage that catches regressions

• Documented patterns for common operations

• CI/CD pipelines that validate changes automatically

If your codebase doesn't meet these criteria, you might want to invest in foundational improvements before attempting parallel AI-assisted development. The time spent cleaning up your repository will pay dividends many times over when you start orchestrating multiple work streams.

I hope you enjoyed reading and learning something new. See you next time!

A Note on AI-Assisted Content

Transparency matters to me, so I want to share how this blog post came together. The first pass at this blog post was generated with following prompt before I went and edited it down:

"@blog-agent craft me a blog exploring using claude code and git worktrees together. I use this pattern to be able do work on non-conflicting, distinct tasks in parallel on a single code base.

here are gists that are relevant for the developer:

- config guidelines to get claude code working with minimal friction: https://gist.github.com/amiller68/5d19561e02a6077bd87cd0b881691795 - template for guiding claude code on how to best work on your project: https://gist.github.com/amiller68/c4497ca31cead66750386d9813b0b6de - gist describing a script to setup and clean up worktrees: https://gist.github.com/amiller68/606333fb8a8a37f6785419df45e7b173

The blog post should

- explain the general workflow we want to setup:

- i can define well scoped and described tickets in whatever project management system i choose to use

- i create a new worktree using our script to work on my ticket

- i CD into the worktree and paste my prompt and ticket together into claude code. i put claude code in planning mode and let it figure out an optimal path.

- iterate with claude code until it comes up with an acceptable plan - once a suitable plan is put in place, put claude code in automatic mode, and routinely check in in order to make sure its not getting off track

- wash rinse repeat acorss many terminals in order to get work done in parallel, checking in when needed

- describe the following quick start for the developer

- set up the worktree script in their development environment, next to their repo

- fill in the claude code task prompt template and maintain this somewhere accessible

- create your first worktree, and use out config guidlines prompt and the prompt template you wrote in order to set up your claude code config. pay attention to getting this right, and then merge when you think its acceptable.

- now you have a script to create worktrees, a top notch prompt for working with your project, and a minimal friction config custom built for your repo

- address the philosphy of this approach and when to use it:

- this encourages project and engineering leads to write well scoped, deacriptive tickets since it has the payoff of building effective context for both developers and agents. this is great for both auditing your own processes and for forcing you to think through a problem clearly, and minimize scope creep. ie if you write exapsnive, hard to land tickets, claude code will probably falter — so be specific and targetted! thats what you should be practcing anyway!

- use this in order to orchestrate multiple, non-conflicting tasks, that are well scoped and dont require large refactors, architectural lifts, or complicated overlapping changes. this is not a framework for vibe coding, and it will probably only work in the long term if you have an opinionated, extensible repo for claude code agents to work inside in the first place.

- it is your JOB to review the work of claude code and maek sure it is writing code that is extensible and following best practices. if you neglect this you will end up in a state where your code base id bloated, brittle, and no amount of agents will save you

come up with a well formed exploratory blog post that touches on all of these themes leave room for a disclaimer at the end that reocrds this very prompt — i want my readers to know when and how i use AI to generate content! orchestrate your work within a TODO list gogogogo