You ask Claude Code to fix a null check in one function. What comes back is a new interface, a factory class, a config flag, two files of helpers and a test suite for code that did not exist an hour ago. The fix is in there somewhere. Finding it costs more than writing it would have.
Most teams blame the model. On the Sydney and Melbourne dev teams we work with, the cause is usually sitting in the repository: a CLAUDE.md written in adjectives instead of limits.
Why the instructions you wrote turn into overbuilding
Anthropic's Claude Code documentation is direct about the mechanism. CLAUDE.md files load into the context window at the start of every session, and because they are context rather than enforced configuration, how you write instructions affects how reliably Claude follows them. The documentation recommends instructions that are concrete enough to verify, using examples like "use 2-space indentation" in place of "format code properly".
The consequence for overengineering is the part teams miss. A line you wrote as a general standard is read as a standing instruction on every task, including the two-line ones. "Write production-quality code" has no off switch. It applies the same way to a typo fix as it does to a new payments service, and the model builds to it both times.
Why does Claude Code add abstraction nobody asked for?
Claude Code adds abstraction when the instructions it reads describe quality as a general standard rather than a scope. A CLAUDE.md line such as follow SOLID principles or handle all edge cases applies to every task equally, so a two-line bug fix inherits the same standard as a greenfield service. The model has no way to tell that this particular task was meant to be small, because nothing in the file says so.
The six wordings that cause it
These are the lines we find most often when a client asks why their agent keeps overbuilding. The replacement column is what we put in instead. Each replacement names a ceiling, which a model can check itself against, rather than a virtue, which it cannot.
| What you wrote | What Claude Code does with it | Write this instead |
|---|---|---|
| Write production-quality code | Adds error handling, logging and config to paths nobody asked about | Match the error handling already in the file you are editing |
| Follow SOLID principles | Splits a working function into interfaces and classes to satisfy the rule | Do not add an interface unless there are two implementations today |
| Handle all edge cases | Writes defensive branches for inputs no current caller can produce | Handle only inputs reachable from the callers that exist now |
| Always write tests | Generates tests for trivial accessors and for code it invented itself | Add tests only for a behaviour change, and only for that change |
| Make the code extensible | Adds flags, hooks and plugin points for requirements that do not exist | Build for the case in front of you. No flags for future work |
| Be thorough | Treats every task as a refactor and edits files outside the request | Change the smallest number of files that makes the task pass |
Read down the left column of your own file. If a line would look at home on an office poster, it is almost certainly costing you diff size.
Scope limits beat quality adjectives
The pattern behind every replacement above is the same. An adjective cannot be checked, so the model interprets it, and interpretation trends towards doing more. A limit can be checked, so the model stops. Four rules we write into client files:
Name a ceiling, not a standard. "Do not create new files unless the task cannot be done in the files that already exist" does more work than a paragraph about clean architecture.
Put the brake next to the request. "If a change needs more than three files, stop and explain why before writing code" turns an overreach into a question instead of a diff.
Say what counts as done. "A task is finished when the existing tests pass and the diff fits on one screen" gives the model a finish line it can see.
Delete the aspirational lines. Anything you wrote to feel good about the codebase is spending context and buying scope creep.
None of this makes Claude Code write worse code. It makes it write less code, which on a bug fix is the same thing as better code.
Where the removed rules should go
Some of what you cut is still worth having, just not in a file that loads on every task. The documentation draws the line clearly: if an entry is a multi-step procedure, or only matters for one part of the codebase, it belongs in a skill or a path-scoped rule rather than CLAUDE.md. A rule that only applies to the migrations folder can live under .claude/rules/ and load only when Claude touches those files.
That also keeps the main file short. Anthropic's guidance suggests targeting under 200 lines per CLAUDE.md, on the basis that longer files consume more context and reduce adherence. We have covered the context cost of an oversized file separately in our piece on CLAUDE.md anti-patterns. Overengineering is the other half of the same bill.
What CLAUDE.md cannot do about it
This is the limit worth knowing before you spend an afternoon rewording things. The documentation states plainly that CLAUDE.md is context, not enforced configuration, and that to block an action regardless of what Claude decides you use a PreToolUse hook. Wording changes the odds. It does not set a hard boundary.
So the split is: anything you would be annoyed about goes in the wording, and anything you would escalate about goes in a hook. No new dependencies without approval, no migration without a backfill, no writes to the payments module. Those are hook material. On a repository handling personal information under the Privacy Act, treat that distinction as a control, not a preference.
What overbuilding costs an Australian team
The cost does not appear as a line item, which is why it survives. It appears as review time. If six developers each lose 45 minutes a day reading and unwinding work nobody asked for, that is roughly 990 hours a year. At an indicative fully loaded rate of $110 an hour for a Sydney senior developer, that is about $109,000 a year of senior attention spent on code that should never have been written. Treat that as a budgeting anchor rather than a quote.
The second cost is slower and worse. Abstractions added speculatively stay in the codebase, and the next agent reads them as precedent. Overengineering compounds through the repository the same way it compounds through a CLAUDE.md.
A half-hour pass you can run today
Open your CLAUDE.md. Highlight every line containing an adjective about quality rather than a fact about the codebase. For each one, either delete it or rewrite it as a number, a file count, or a named command. Then run the same task that annoyed you last week and compare the diff size. On most repositories the difference shows up in the first session.
If you want an outside read on the file and the workflow around it, our AI readiness assessment covers agent guardrails alongside the data questions, and our services page sets out how we scope this work. The upstream reference is Anthropic's Claude Code memory documentation.
If your team is arguing about why the agent keeps gold-plating simple changes, that is usually a 30-minute conversation rather than a project. Book a time and we will look at the file with you.
