Does Claude Code Need Clean Code? I Tested It on 21k Lines
I handed Claude Code a feature. It came back, the tests passed, and I opened the diff. The function I asked it to extend was now 111 lines long, with a cyclomatic complexity of 35. It worked. I would never ship it.
The usual advice is to add guardrails: linters, complexity limits, duplication checks, and hooks that block the agent until the code is clean. Every one of those makes each task cost more and take longer. So I wanted to know if it’s worth it. Does clean code make the agent better, or does it only make the code look the way we were taught to write it? I ran the experiment on two codebases. Here is what the numbers say.
Clean code for AI agents: guardrail or muscle memory?
A lot of people are making the same argument right now, including Robert Martin, Erik Doernenburg on Martin Fowler’s site, and Lauren Tan. Agents read your code to understand it. Messy code gives them a worse picture, so they make more mistakes. Clean code is a guardrail, the same way tests are.
It sounds right. But these are people who spent decades teaching humans to write clean code, and the reasons we wanted it were human reasons. Humans have small working memory. They get tired. They forget what they wrote six months ago. An agent reads a 2,000-line file in a second and never gets bored. Maybe a 110-line function just isn’t a problem for it.
There is some data. CodeScene published Code for Machines, Not Just Humans in January 2026. It found that LLM refactoring breaks code less often in files with a high Code Health score. Two problems for my question, though. It measured refactoring of 5,000 single Python files from competitive programming, not an agent adding features to a large app. And CodeScene sells the tool that measures Code Health. I wanted my own numbers, on my own code, with tests the agent could not see.
A guardrail has to earn its cost
Here is how I define a guardrail for an agent: anything that changes what the agent produces without you typing a prompt. Tests, type checks and code health rules all count.
Every guardrail has a price. The agent reads more, runs more tools and fixes more things before it stops, and you pay for that in tokens and wall-clock time. So a guardrail is only worth it if it buys something you can measure: fewer bugs, fewer regressions, or code that stays workable over many changes.
That gives a clean test. Take the same app in two states, messy and healthy. Give the agent the same series of feature requests. Score everything with tests the agent never sees. Then compare correctness, cost and code health. If clean code is a real guardrail, the healthy version should be more correct. If it’s muscle memory, it will only be more expensive.
The code health tooling
I didn’t use CodeScene itself. I wanted something anyone can install from npm, so the stack is four tools:
- ESLint with eslint-plugin-sonarjs for function-level smells
- jscpd for duplicated code across files
- knip for unused files, exports and dependencies
- tsc for types
The ESLint limits are complexity 10, cognitive complexity 15, max depth 3, functions up to 60 lines, files up to 300 lines, and at most 4 parameters. On top of that, sonarjs rules flag nested conditionals, collapsible ifs and duplicated branches.
Two Claude Code hooks
The PostToolUse hook runs on every Edit or Write and lints only the file that just changed. That takes about three seconds. The Stop hook runs when the agent thinks it’s done. It runs the type check on the whole project, jscpd for new clones, and knip.
The hook’s error message also tells the agent what not to do: fix the code, don’t disable rules, don’t raise limits, and don’t reach for any or ts-ignore. Without that line, the agent will happily add an eslint-disable comment and call it done.
The config and hooks are in the healthy-code repo if you want to try them on your own project.
Experiment 1: a 700-line checkout engine
The first test was a small app: a checkout pricing engine with six products, quantity tiers, discount codes, and shipping and tax for a few regions. It has one entry point, priceCart. I ran six phases, each in a new Claude Code session, so the agent had to read the code again and couldn’t remember how it built it.
There were two variants. Baseline had no rules and no hooks. Health had the rules and the hooks. The prompts never mentioned code health, and the scoring ran hidden test cases, including edge cases no prompt ever showed.
On the baseline, priceCart had a complexity of 20 after the build phase. Then 25, 28, 30, 32 and 35. By the end it was a 111-line function. Every change made it worse. Nobody told the agent to keep it clean, so it didn’t.
Correctness didn’t care. Opus and Haiku both passed all 152 tests in both variants, including every hidden edge case. The health version cost 26% more with Opus and 31% more with Haiku, and took about 1.7 to 1.8 times as long.
So on the small app the answer was clear. The hooks did their job, and the job wasn’t worth paying for. But that also made the test unfair. The whole app was about 700 lines, and the agent can read all of it at once. The case for clean code is about codebases you can’t hold in your head. I needed a bigger one.
Experiment 2: a 21,000-line Next.js app
The second test used my own app, AllFamilyTree, a family tree builder. It runs on Next.js 16, Prisma and Postgres, with about 21,000 lines of source and 18,000 lines of tests. It has members, relationships, collaborators, public share links, GEDCOM import and export, and AI-generated family pictures. And it was messy: 212 health errors, 93 duplicated blocks and 29 unused exports.
This time I used three variants, so I could separate the effect of the code from the effect of the hooks:
- main is the app as it was, with no hooks.
- healthy is the same app after I refactored it to zero health errors, still with no hooks.
- code-health is the healthy code plus the hooks. It differs from healthy by one settings file.
Comparing main to healthy shows what the code itself does. Comparing healthy to code-health shows what the hooks add. In the small experiment, those two effects were mixed together.
Then I gave each variant five feature requests that build on each other:
- Birth and death places, with a database migration, the API, GEDCOM import and export, and the forms
- A privacy fix for public share links
- Approximate dates
- Merging two duplicate members
- Exporting one branch of the tree
The scoring tests live outside the repo, so the agent can’t read them. They call the real API routes against a real database, and each score builds a fresh database from the agent’s own migrations. If the agent forgets a migration, it fails.
I ran the whole chain with Haiku and Sonnet. Both have a smaller context window than Opus, and that was on purpose. If messy code hurts an agent, it should hurt most when the agent can hold less of the codebase in context.
Results: correctness was a tie
With Haiku, main passed 54 of 55 task tests, and healthy and code-health passed 55 of 55. With Sonnet, all three variants passed 55 of 55. No variant broke a single old test.
The one miss on main is interesting but weak evidence. In phase 1, the agent removed birth and death places from the public tree route for every member, which nobody asked for. In phase 2 it kept that choice, so deceased members lost their places on the public link. That’s the kind of failure I’d expect from messy code, an unrequested change that the next session treats as the way things are. But it’s one test in one run, and the prompt was ambiguous enough to allow that reading.
Results: messy code got messier
Code health is where the variants split, and both models told the same story.
| New over five phases | main | healthy | code-health |
|---|---|---|---|
| Health errors, Haiku | +12 | 0 | 0 |
| Health errors, Sonnet | +17 | +1 | 0 |
Main got worse in every phase that added code. Most of the new errors landed in new files, especially the merge feature. The agent didn’t only stretch the old messy functions. It wrote brand-new code in the same messy style.
The healthy variant, with no hooks at all, stayed almost clean. Haiku let in one clone and four unused exports. Sonnet let in one complexity error. The agent copies the style of the code it reads. For me that’s the biggest finding of the whole experiment: most of the health effect comes from the code, not from the hooks.
The hooks caught the rest. Code-health ended at zero in both runs, after ten blocks each. The Stop hook never fired once. Every block happened right after an edit, in the same places where main got worse.
Results: what healthy code costs
| main | healthy | code-health | |
|---|---|---|---|
| Haiku cost | $3.31 | $3.86 (+17%) | $3.88 (+17%) |
| Sonnet cost | $5.03 | $6.21 (+23%) | $6.49 (+29%) |
| Sonnet time | 42 min | 57 min | 64 min |
The part I didn’t expect: Sonnet used almost the same number of turns on all three variants, 367 to 381. So the extra money doesn’t come from more steps. It comes from more reading. Healthy code is split into more, smaller files, and every file the agent reads goes into every later request. With Haiku the healthy variants did take 8 to 12% more turns, so this effect is clearest with Sonnet.
What this experiment doesn’t prove
- One run per variant. I can’t tell how much of each number is noise. Treat them as signals, not proof.
- The tasks were too easy. Both models passed 54 or 55 of 55 on the messy code. A task that goes deep into the worst old code might show a difference these five didn’t.
- Five phases may be too short. Messy code got worse with every phase. After ten or fifteen, the gap might start to cost correctness.
Is clean code worth it for AI agents?
On a small project, no. The agent can see everything, it gets it right anyway, and you pay 25 to 30% more for code that only you will read.
On a medium project like my 21,000-line app, maybe. Correctness was the same, or one test apart. But the code went in two clearly different directions. Messy code got messier with every feature, and healthy code stayed healthy. Five phases weren’t enough for that to cost correctness, but the direction of the trend is clear.
On a large project, I can only guess. The messy codebase keeps growing in the wrong direction, the agent sees a smaller share of it, and at some point that has to show up as bugs. That’s extrapolation from the medium project, not data.
What I’d do
Don’t start with hooks. Clean up the one area your agent changes the most, then watch whether the agent keeps it clean on its own. In my runs that was most of the effect. Add the PostToolUse hook later for the last few percent, and keep the type check in the Stop hook.
The ESLint config and Claude Code hooks are in the healthy-code repo on GitHub, and the full walkthrough with the results charts is in the video.