2026-09-04  ·  claudecode · ai · github · productivity

Assigning 5 Personas to Claude Code for Parallel Development

When you give a large request to Claude Code, doesn't this happen?

• You asked for authentication logic, but it also included standardizing error handling.
• There are 40 changed files, and you lack the motivation to read them all, so you approve them based on intuition.
• Three days later, you can’t even explain why the implementation is the way it is.
• You want to run tasks in parallel, but fear of conflicts forces you to run them one by one.

While building 10 personal apps in three months and releasing two to the App Store, I encountered these issues extensively. Here is the architecture I arrived at.

The conclusion is that this was not a capability problem. It was a permission design problem.

What Is Happening

You are asking one persona to handle design, implementation, review, and merging.

You decide the design, implement it yourself, review it yourself, and merge it yourself. There is no check or balance anywhere. No human team would approve this configuration.

Divide Responsibilities and Lower Permissions

All use the same model. There is no difference in intelligence. The only difference is what they are allowed to do.

Why does this change the result? AI selects the most plausible next step within the given context. If you just say "build a login feature," it is plausible for it to do everything related to that topic. If you say "change only src/auth/** and satisfy these three acceptance criteria," the most plausible next step becomes completely different.

Constraints create context, and context determines output.

Overall Flow

Request → [Architect] Split into Issues (create groups with non-overlapping scopes)
         │
         ├─ [Coder] issue/12-xxx ─┐
         ├─ [Coder] issue/13-yyy ─┤ Parallel
         └─ [Coder] issue/14-zzz ─┘
                                   │ One by one per PR
                                   ▼
                            [Reviewer] Check acceptance criteria and scope → Merge
                                   │
                                   └─ Conflict → [Conflict Resolver] → Reviewer

Actual Configuration

.claude/agents/architect.md looks like this:

---
name: architect
description: Use to turn a feature request into GitHub issues for
  issue-driven parallel development. Defines per-issue scope (owned paths),
  dependencies, branch names, and acceptance criteria. Never implements code.
tools: Bash, Read, Grep, Glob
model: inherit
---

You are the **Architect**. You do not write code.
Your job is to "split Issues into units that can be executed safely in parallel."

## What to do when called

1. Read the request and identify necessary tasks.
2. Split tasks into **1 Issue = 1 scope = 1 branch**.
   - Keep scopes as narrow as possible and ensure they do not overlap with other Issues.
   - Group non-overlapping Issues together as a "parallel start group."
3. When creating an issue via `gh issue create`, always include:
   - Scope: Paths of files/directories you are allowed to modify
   - Branch: issue/<number>-<slug>
   - Depends on: Dependent Issue number (or "none")
   - Acceptance Criteria: Specific enough for the Reviewer to judge

## Rules to follow

- Do not write implementation or test code.
- Do not put Issues with overlapping scopes in the same parallel group.

On the Coder side, include this:

- Do not touch files or branches of Issues you are not assigned to.
- Do not merge to main yourself (only Reviewers may merge).
- Do not resolve conflicts on your own judgment.
- If implementation cannot be completed without changing files outside the scope, stop changes and return a report stating "Changes outside scope are required."

The last line is crucial. If the Coder silently expands its scope, the signal that "the Architect split incorrectly" disappears.

Most of the result is determined by how you cut scopes

To be honest, how you split Issues matters more than persona settings.

Consolidate shared files into a single Issue

In practice, conflicts usually occur in the following files:

• Routing definitions
• Aggregated type definition files
• DI containers, entry points
• package.json, migration indexes

If multiple Issues are designed to touch these, conflicts will inevitably occur. Create an Issue that changes only the shared file first, and make others depend on it.

Issue #10  Scope: src/routes/index.ts        (Add route definitions first)
Issue #11  Scope: src/pages/settings/**      Depends on #10
Issue #12  Scope: src/pages/billing/**       Depends on #10

This allows #11 and #12 to run in parallel. Since #10 is small, it finishes quickly.

Write acceptance criteria in a verifiable format

The Reviewer judges based solely on the acceptance criteria. If written in an unverifiable way, the review will pass through without scrutiny.

Cut vertically by feature

Splitting into "Model Layer Issues" and "View Layer Issues" creates linear dependencies, so they cannot run in parallel.

Two Pitfalls with Parallel Execution

Must launch simultaneously in one message to be parallel

(NG) "Have the coder do Issue 12" → Wait for completion → "Do 13"
(OK) "Implement Issues 12, 13, and 14 in parallel using the Coder.
       Issue three Agent calls simultaneously within one message."

Separating the calls makes them sequential. I wasted a significant amount of time here initially.

Merge sequentially

Even if implementation is parallel, merging must be done one by one. If you merge three at once, even if each is correct individually, you cannot isolate issues if the combination breaks. You end up re-examining all three, making it slower than sequential merging.

The practical upper limit for parallel tasks was 3–4. The constraint lies not with AI, but with review capacity.

Separate Working Trees

Even if scopes are respected, running multiple Coders in the same directory causes accidents. Build artifacts mix, and one git checkout affects the other.

Separate them at the filesystem level using git worktree.

git worktree add -b issue/12-upload ../worktrees/issue-12 main
git worktree add -b issue/13-profile ../worktrees/issue-13 main

What is shared is only the objects in .git. The working tree is copied. Measured locally: adding one worktree to a repository with 5,600KB of source added 5,608KB, while .git itself grew by 44KB. node_modules is not shared either. So each parallel branch costs you a full copy of the source and its dependencies.

When This Approach Is Not Suitable

To be honest, this adds overhead.

• Exploration/Prototyping (stage where acceptance criteria cannot be written)
• Changes contained in a single file (no point in creating a PR for a typo fix)
• Work with inherently linear dependencies (splitting does not enable parallelism)
• Tasks that take 30 minutes or less

It is only worth it when you want to run three or more tasks simultaneously, and when tracing history later has value.

There is one more limitation. The Reviewer uses the same model. If the model has systematic errors, such as consistently misremembering a library's API, the Coder will make the mistake, and the Reviewer will judge it as correct.

The countermeasure is to include executable verification in the acceptance criteria. "Tests passing" is one of the few ways to externally verify against the model's assumptions.

---

I publish the configuration for splitting Claude Code into separate personas — Architect, Coder, Reviewer, Conflict Resolver — under MIT. Copy it, run ./setup.sh, and it works. It does not depend on your tech stack.

https://github.com/quintetkit/quartet

I built one real tool using nothing but this workflow. Every Issue, PR, review and merge is still there. The parts that went wrong were not deleted.

https://github.com/quintetkit/mdlinkcheck

The version that adds a UI Designer persona, review criteria, a per-Issue parallel execution script and a 10-chapter guide is on the product page.