Ten developers using Claude Code without shared rules are running ten different tools that happen to share a name. Each developer's output is shaped by their own habits, their own prompts, and whatever happens to be in their context window that morning. The quality ceiling is the best developer on the team. The quality floor is the worst day of the least careful one. Reviewers pay for the gap.
Here are the four failure modes I think matter most, why the three obvious fixes don't hold, and the structure that does.
1. Code before understanding
Claude Code is fast, and speed hides the most expensive mistake in software: building the wrong thing well. A developer pastes a ticket, four minutes later there are 300 working lines, tests pass, the merge request is open. Two days later someone points out that the ticket meant something else. The code was correct; the requirement was never checked.
On teams where requirements cross a language barrier — translated, relayed through an intermediary, sometimes arriving as a screenshot or a two-line chat message — this compounds. The gap between what was written and what was meant is already wide before anyone opens a terminal. An assistant that starts coding immediately turns that gap into shipped code.
2. Unreviewable output
AI-generated changes tend to be large, touch more files than the task needed, and rename or reformat things nobody asked about. A human reviewer facing a 40-file diff does one of two things: skims and approves, or sends it back wholesale. Both are failures. The first lets defects through; the second throws away the time saved.
The cause is not that the model writes bad code. It is that nobody told it what a reviewable change looks like on this team: how many files, how many lines, what gets touched and what is off limits.
3. Context waste
Every session starts by loading instructions into the context window. CLAUDE.md is loaded in full, every time. Teams that discover it tend to grow it: coding standards, architecture notes, deployment steps, the history of every past mistake. Within a month it is 800 lines, loaded on every task, including a one-line typo fix.
The instinct to document everything is right. Loading everything always is wrong.
Skills are the opposite: only a skill's name and description are loaded up front, and the body loads when it matches. That gives one rule that sorts out most of this:
-
Facts about the repo →
CLAUDE.md - Procedures → skills
There is a detail here that surprised me. The skill listing itself is capped at roughly 1% of the context window, and when it overflows, Claude Code drops descriptions starting with the least-invoked skills. A team carrying twenty skills it never uses does not just waste context — it can quietly lose the trigger words on the three skills that actually matter, and those skills stop firing on their own. They still work if you type /skill-name, which is exactly why this is easy to miss. /skill-doctor shows which skills have never been invoked.
4. Drift
Even when a team writes good rules, the rules decay. One developer edits CLAUDE.md to fix a local problem. Another copies an older version into a new repo. A third keeps personal overrides that contradict the team's. Six weeks in, nobody knows which version is current, and the rules carry no authority because nobody owns them.
Rules without versioning and an owner are suggestions. Suggestions do not survive a deadline.
Why the obvious fixes don't hold
A shared prompt document in the wiki: nobody opens it, and it is not in the model's context anyway. A longer CLAUDE.md: that is failure mode 3. Code review as the safety net: that is asking the most expensive people on the team to catch, by hand, every problem the tooling could have prevented upstream.
Each fix addresses one failure mode and worsens another. What is missing is structure, not effort.
The structure: three layers
1. A thin root file. CLAUDE.md under 40 lines: what the repo is, where things live, and three rules for every task — no code before a written requirement check; touch only the files the task names; self-review every change before a human sees it.
2. One skill per phase of work, each loaded only while its phase is active:
- requirement-first — restate the task, list assumptions and open questions, name the files in scope, stop until confirmed. Make it offer a best guess beside every open question so most confirmations are a single "OK".
- implement — scope, size limits and test rules for the whole task. Aim under 300 changed lines; above 500, stop and propose a split.
- review — a fixed-format self-review that becomes the MR description. The most useful line: "look here first" — the one or two places most likely to be wrong.
3. Role blocks for everyone else. BA, QA and PM use Claude in a browser, so .claude/skills/ does nothing for them. Give them the same gates as a one-screen block in their Claude Project. The BA block produces tickets in exactly the shape the requirement gate expects.
What keeps it from rotting
A changelog every rule change goes through, enforced by a PreToolUse hook that blocks edits to CLAUDE.md and .claude/ unless CHANGELOG.md is already being changed.
One reviewer habit: read the self-review first, then the diff, and send back any MR without one. Without that habit, the rest is decoration.
What this does not claim
It does not promise your team ships faster. What it makes measurable: the share of MRs carrying a self-review, median changed lines, MRs sent back for scope or size, and the number of tickets where an open question changed what got built. That last number is the structure paying for itself.
Originally published at hungledn.com. I packaged this structure as drop-in files — CLAUDE.md, three skills, permissions, the changelog hook, role blocks in EN/VI/JA, and a two-week rollout guide — on Gumroad.
Top comments (2)
"Unreviewable output" is the one that sneaks up on teams. The agent isn't wrong, the PR is just too big to judge. Scoping every task to an explicit file list and a done-when turns review size into something you plan instead of something you discover. Which of the four tends to show up first?
The core breakdown is an unpriced negative externality between author and reviewer. When generating 300 lines takes four minutes, the author captures all the perceived speed while the reviewer absorbs all the verification latency and cognitive fatigue. A 40-file diff creates an asymmetric payoff: the reviewer either spends an hour verifying edge cases or rubber-stamps it to protect throughput, turning senior review into the scarcest resource on the team. Enforcing a 300-line ceiling and mandatory scope confirmation works because it forces the author to pay the bounding cost at the terminal before passing the cognitive debt downstream.