DEV Community: quintetkit

What Works and What Doesn't in CLAUDE.md

quintetkit — Fri, 04 Sep 2026 05:30:40 +0000

Writing "Write clean code" in CLAUDE.md changes nothing.

During the process of building 10 personal apps in three months, I rewrote CLAUDE.md many times.
Since it became clear what worked and what didn't, I will outline that distinction.

What Doesn't Work

Giving instructions with adjectives

- Write clean code
- Design for maintainability
- Handle errors appropriately
- Consider performance

None of these work. Because "clean" and "appropriate" cannot be objectively judged.
Instructions that cannot be judged cannot even be verified by yourself as to whether they are followed.

And the person who wrote them cannot verify later if they were followed.
Rules that cannot be verified are the same as non-existent.

Writing general best practices

- Follow the DRY principle
- Adhere to the Single Responsibility Principle
- Do not use magic numbers

The model already knows these. Writing them adds no information.
The role of CLAUDE.md is to convey what the model does not know (project-specific circumstances).

Writing things that can be understood by reading the code

- We use Zustand for state management
- We use Vitest for testing

You can see this in package.json. If you write anything, it should be "why we chose it" or "what not to do".

- State management is Zustand. Migration to Redux was considered but rejected due to boilerplate increase. Do not suggest it.

This is worth writing. You will stop receiving the same suggestions every time.

What Works

Writing prohibitions in a verifiable format

- Do not use pure black `#000000` or pure white `#ffffff`
- Do not use gradient backgrounds or gradient heading text
- Limit to 3 types of motion per screen

You can verify this with grep '#000000'. Because it is verifiable, you can mechanically inspect if it is followed.
The shape of a UI belongs in a UI specification, not in CLAUDE.md. What goes here
is the floor beneath the specification — the line you do not want crossed even
when no specification exists. The principle does not change: the persona that writes
the code does not decide how it looks.

"Make the UI clean" does not work, but "Do not use pure black" does. The difference lies not in the model's comprehension, but in whether the instruction is verifiable.

Reducing permissions

This was the most effective.

- Do not modify paths outside the scope described in the assigned Issue
- If changes outside the scope are needed, stop implementation and report it
- Only Reviewers may merge to main

"Cannot do ~" is more effective than "Do ~".
Instructions that increase what you can do have a wide range of interpretation, while prohibitions are narrow.

Especially the phrase "stop implementation and report it" was effective. Without this,
when the model hits constraints, it tries to push forward somehow.
Providing an exit allows it to retreat there.

Explicitly stating exceptions

When writing prohibitions, cases of "but what about this exception?" always arise. Write them in advance.

Things not treated as out-of-scope:
- Automatic updates of lock files due to dependency additions
- Test files corresponding to modified files

If you don't write them, judgments will vary each time. Inconsistent judgments hollow out the rules.

Writing order and dependencies

- Do not start issues involving UI until the UI specification status is:done
- Coders in the parallel execution group must be launched simultaneously within one message

The second point actually worked. Separating calls makes them serial, so
without explicit instruction, they will not run in parallel.

Using tables

For lists of states or labels, I have the impression that tables are referenced more often than bullet points.

| Label | Meaning | When to assign |
|---|---|---|
| `status:planned` | Issue created, not started | When Architect creates the Issue |
| `status:review` | PR created, waiting for review | When Coder creates the PR |

Writing "when to assign" is important. If you only write the meaning, you will forget to assign them
(in the end, I shifted this to GitHub Actions, but that's a different story).

Regarding Length

Shorter is better.

I once wrote a CLAUDE.md that swelled to 74KB, but the latter half was followed less.
I haven't verified this definitively, but the experience was clear.

The one I use now is around 7KB. The breakdown is as follows:

Section	Proportion
Permissions by role (what can and cannot be done)	40%
Overall flow (who receives what from whom)	30%
State management (labels and when to assign them)	20%
Explicit exceptions	10%

It contains zero general knowledge.

The cause of the swelling was "just in case I write it." Lines written "just in case" tend to become unjudgable instructions. Unjudgable instructions don't work, so writing them only dilutes the file.

How to Verify

Whether a written rule works is judged by whether you can notice when it is broken.

Scope violation → Can be seen with gh pr diff --name-only
Hardcoded colors → Can be seen with grep
Missing labels → Can be seen by checking the Issue list
"Clean code" → Cannot be seen

There is no verification method for the last one. That's why it doesn't work.
Before writing, asking "can I notice if this is broken?" helps you avoid writing ineffective lines.

Summary

Do not give instructions with adjectives. Unjudgable instructions don't work.
Do not write general best practices. The model already knows them.
Do not write things that can be understood by reading the code. If writing, include "why" and "what not to do".
Write prohibitions in a mechanically inspectable format.
"Cannot do ~" is better than "Do ~". And always provide an exit (stop and report).
Explicitly state exceptions in advance. Inconsistent judgments hollow out rules.
Keep it short. Lines written "just in case" tend to be ineffective.
Before writing, verify "can I notice if it is broken?"

I have published the CLAUDE.md written with this approach and sub-agent definitions for four personas under the MIT license.

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.

Assigning 5 Personas to Claude Code for Parallel Development

quintetkit — Fri, 04 Sep 2026 04:44:37 +0000

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

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.

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.

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

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.

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.