When you give a large request to Claude Code, doesn't this happen?
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.
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.
| Persona | Can Do | Cannot Do |
|---|---|---|
| Architect | Create/split Issues | Write code |
| UI Designer | Write UI specifications | Write code |
| Coder | Change only within the assigned Issue's scope | Touch outside scope, merge, or decide structure |
| Reviewer | Review and merge | Implement or resolve conflicts |
| Conflict Resolver | Resolve conflicts | Merge or act before being called |
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.
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
.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.
To be honest, how you split Issues matters more than persona settings.
In practice, conflicts usually occur in the following files:
package.json
, migration indexesIf 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.
The Reviewer judges based solely on the acceptance criteria. If written in an unverifiable way,
the review will pass through without scrutiny.
| Writing Style | Verifiable? |
|---|---|
| "Login functionality works correctly" | No |
"Logging in with an unregistered email returns 401 and USER_NOT_FOUND " |
|
| Yes | |
| "Improve performance" | No |
| "Initial list display of 200 items completes within 500ms" | Yes |
Splitting into "Model Layer Issues" and "View Layer Issues" creates linear dependencies,
so they cannot run in 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.
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.
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
Since .git
is shared, disk usage increases by only the size of one branch.
To be honest, this adds overhead.
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