Skip to main content

Parallel Development Workflow

Run independent tasks in separate working directories and integrate each result through normal review.

Introduction​

Parallel development cuts waiting time when tasks do not depend on each other. Each task gets its own branch and working directory, so edits and local build state never collide.

Running work in parallel only helps while review and merging keep up.

Understanding the Workflow​

A workstream is one bounded task with an owner, a workspace, and a clear way in.

Definition

Workstream

A bounded unit of work assigned to one owner and isolated branch or workspace until review and integration.

Workspace isolation gives each workstream its own working files. Git worktrees share refs and objects, so they keep edits apart but give you no security boundary.

Definition

Workspace Isolation

Keeping each task's working files and process state separate so concurrent work cannot overwrite another task's checkout.

Tasks are independent when you can build, review, and merge them in any order. Different file names are a hint, not proof: shared schemas, interfaces, generated output, and deploy order all tie tasks together.

Use a stacked PR workflow when one task must build on another.

Applying It in Practice​

Check each candidate task for:

  • overlapping files or symbols
  • shared database or API contracts
  • common configuration and generated files
  • required merge or deployment order
  • enough review ownership

Create one worktree and branch per task:

git fetch origin
git worktree add -b task/password-reset ../repo-password-reset origin/main
git worktree add -b task/search-index ../repo-search-index origin/main

Give each owner a clear task contract and a file boundary. Settle any shared interface before work starts, so two people are not left to invent the same one apart.

Open a pull request as soon as one workstream is ready, then review and merge it without waiting for the rest. Bring the other branches up to date before they land:

git -C ../repo-search-index fetch origin
git -C ../repo-search-index rebase origin/main

Only rebase a branch when rewriting it is safe. If other people are building on its commits, merge main into it instead.

When conflicts show up, fix them in whichever branch merges next and re-run its tests against current main. Restarting an agent task is often cheaper than saving a small stale patch, but compare the old and new behavior before you throw anything away.

Remove finished worktrees through Git:

git worktree remove ../repo-search-index
git branch -d task/search-index

Engineering Considerations​

Start with two or three workstreams. Add more only while reviews stay quick and conflicts stay rare. There is no single right number, because task size and review capacity differ from team to team.

Separate working directories do not separate databases, ports, caches, or outside services, and separate clones do not either. Give each concurrent test process its own resources wherever the app needs them.

Rebasing often is not a substitute for thinking about dependencies. It keeps you close to main, but a rebase with no text conflicts can still merge two behaviors that do not work together.

Feature flags let independent changes land before the feature is ready for users. They shift the coordination into runtime config, which then needs an owner, a cleanup plan, and testing in production.

Scaling and Operations​

Track each workstream's task, branch, workspace, owner, review state, and dependencies. Close dead work quickly and delete its workspace.

Watch how old the review queue gets and how often conflicts appear. Stop starting work once the queue grows faster than reviewers can clear it.

Automation should hand out unique branch names, directories, ports, and temporary resources, and clean them all up after a task fails or is interrupted. A branch naming pattern keeps those names predictable, and running coding agents in parallel covers how the rest of that allocation works.

When parallel work stops paying off, pause new tasks, finish or close what is open, and redraw the dependency boundaries before you scale back up.

Next Steps​