Claude Code can add layers, options and dependencies nobody asked for. How to spot them in a diff, prompt against them, and why review can add more.
Claude Code can over-engineer, and a request that never says where to stop leaves the size of the solution to the model. The fix has two halves: give it a stopping point before it writes code, then audit the diff for the extra layers, options and dependencies nobody asked for. Neither half runs itself, and a review pass can add to the problem, which Anthropic's own docs warn about.
Disclosure: we build TLM Forge, a process layer for Claude Code, so weigh the product section accordingly. Most of this post applies with or without us.
What over-engineering looks like in a Claude Code diff
You asked for a bug fix or a small feature. The diff arrives with an interface that has one implementation, a factory in front of it, a config option nothing sets, retries around a call that cannot fail that way, and a new package for a few lines of logic. Each piece looks reasonable alone. Together they are code you now read, test and maintain without any requirement behind them. This post is about that: an excessive solution inside the task's scope. Touching files you never named is a separate failure, covered in Why Claude Code Edits Files You Never Named.
| Smell | What it looks like in the diff | Question to ask | Often fine when |
|---|---|---|---|
| Interface or factory with one implementation | An interface, base class or factory that returns a single concrete class | How many implementations exist today? | The spec names a second one, or it wraps an external service that tests fake |
| Option nothing sets | A new flag, environment variable or settings key with one possible value | Who sets this, and to what? | Operators must change it without a deploy |
| Defense against the impossible | Null checks, retries or validation on calls between your own functions | Can this input arrive from outside the system boundary? | The input comes from a user, a file or an external API |
| One-use helper | A utility file or function with a single caller | Would inlining it be shorter and clearer? | A second caller exists, or the name explains a hard step |
| New dependency | A package added for a few lines of logic | Can the standard library or an existing dependency do this? | The problem is hard and you chose the library on purpose |
| Extra folder layers | New services, adapters or managers folders for one feature | Does a sibling feature use the same structure? | The repo already organizes comparable features this way |
The last column matters, because not every abstraction is a mistake. Martin Fowler's note on Yagni (You Aren't Gonna Need It) covers capabilities built for a feature you only presume you will need, and he lists four costs of building one early: build, delay, carry and repair. It does not cover effort that makes software easier to modify. Sandi Metz argues that "duplication is far cheaper than the wrong abstraction". A wrong one collects parameters and conditionals as each new requirement arrives. The usual rule of thumb is the rule of three: two similar copies do not need extracting, the third does.
Sources: Martin Fowler: Yagni, Sandi Metz: The Wrong Abstraction, Wikipedia: Rule of three (computer programming)
What Anthropic documents, and where the guidance differs
Anthropic describes this tendency in several places, and the descriptions are not identical. They vary by model, and one of them points the other way.
Sources: Anthropic: Prompting best practices (Overeagerness), Anthropic: Prompting Claude Opus 5, Anthropic: Prompting Claude Sonnet 5.5, Claude Code docs: Best practices
| Source | What it says | What to take from it |
|---|---|---|
| Prompting best practices, "Overeagerness" | Claude Opus 4.5 and Claude Opus 4.6 have a tendency to overengineer by "creating extra files, adding unnecessary abstractions, or building in flexibility" that was not requested. | Add explicit guidance to keep solutions minimal. |
| Prompting Claude Opus 5 | The model can expand the scope of a task, adding steps that were not requested. | For narrow tasks, constrain the scope in the prompt. |
| Prompting Claude Sonnet 5.5 | It tends to add tests, documentation and small supporting files that fit repository conventions, at every effort level and more at higher effort. The requested change itself "stays close to what was asked." The guide adds that most teams will welcome this. | Decide whether you want the extras. The guide offers a paragraph for limiting changes to what was requested. |
| Claude Code best practices | Claude "tends to read a request conservatively and build the smallest thing that satisfies it", and cannot see how much you were hoping for. | The default can run small, so say how much you want when you want more. |
Read together, the pages say that behavior depends on the model, the effort level and how specific the request is. They describe tendencies, not measured rates, so the safe assumption is that you will sometimes get more than you asked for and sometimes less. Check the diff instead of trusting a model's reputation either way.
Developer reports match the over-building side of that description, with the usual caveat that each one is a single person's experience. One Hacker News commenter says Opus 5.5 has no sense of "good enough", keeps resolving edge cases on edge cases, and does not see that a half dozen classes is too much to close a hole when no such caller or possible condition exists at present. Another says that in plan mode for a large feature they cut about 30-60% of the proposed scope before any work starts, and still find things to cut in the final code. A third says Claude Code wrote noticeably less code for a feature in a clean codebase than in an over-engineered one. A bug report on the Claude Code repository is titled "Over-engineered changes for simple requirements; follows existing patterns without evaluating better approaches", and its text says Claude added too many changes and blindly followed a pattern the reporter considers wrong. None of this gives a rate.
Sources: Hacker News comment by xnorswap, Hacker News comment by jampa, Hacker News comment by jongjong, anthropics/claude-code issue 106058
Why it happens
These are likely contributors, drawn from the docs and the reports above, and most are things you can change.
- The request has no stopping point. The Claude Code docs turn "add a calendar widget" into a request that names a file whose pattern to follow and ends with "no new libraries". Without lines like those, the size of the solution is the model's call.
- Your own wording can push it. The best-practices page says a line telling Claude to keep going and not be lazy is "more likely to cause over-work than fix a stall", and that piling on emphasis "mostly makes Claude over-apply the rule." The same page endorses
be ambitiouswhen you want the fuller version, so use it on purpose. - The nearest code is the template. One commenter above says Claude produces more complexity when the codebase already has it, and the bug report complains that Claude followed a pattern the reporter thought was wrong. An instruction to follow a named file helps only if that file is a good example.
Why a review pass can make it worse
The obvious answer to over-engineering is more review, and Anthropic's own material warns that review can feed it. The Claude Code best-practices page tells you to keep skip style in a review prompt and explains why: "A reviewer that's asked to find problems will always find something. If you fix every finding, you end up with extra abstraction layers and tests for cases that can't happen."
Sources: Claude Code docs: Best practices (Review against your spec)
An Anthropic engineering article on migrating its source control system describes the same pattern. The team uses adversarial review extensively and says that, while it is effective in many ways, "it can also be myopic". Engineers needed to "steer Claude away from over-engineering parts of the system in response to hypothetical concerns." In the article's example, one review was overly defensive about trusting another internal service, which led Claude to add excessive validation and complexity.
Sources: Anthropic Engineering: Redesigning source control at Anthropic
A paper accepted to the ICML 2026 workshop on DL4C shows the mechanism in a trace. On one SWE-bench Verified task that asked for a single new argument, the zero-shot baseline produced a 24-line patch that passed the hidden tests. In the reviewer-and-critic version, the reviewer asked "what if the user calls read() separately?", the critic did not reject the question as out of scope, and the resulting 32-line patch added unrequested changes and failed the hidden tests. The authors write that the loop "can also turn plausible concerns into unnecessary edits." It is one case study of a failure mode the authors identify, in a paper that reports improvements over its baselines on SWE-bench Verified, so read it as a mechanism and not as a rate. The wider results are in Why 3 Adversarial Reviewers Beat a 5-Agent Team.
Sources: arXiv: Adversarial Review (2608.18167)
The practical rule is to treat each review finding as a proposal that has to justify its code. Ask whether a real caller or input can reach the case today. One Hacker News commenter describes a "skeptical pass" in which the main agent sorts review findings into buckets and then re-examines them, downgrading some to won't-fix. That is one person's workflow, but it applies the same test.
Sources: Hacker News comment by m12k
Fix it before the code: give Claude a stopping point
State the size of the solution in the request. The Claude Code docs advise naming the file and saying what "fixed" looks like up front. Adapt this shape:
Sources: Claude Code docs: Best practices (Write a specific prompt)
- Task: one sentence naming the file or function to change.
- Done means: the behavior, or the failing test, that must pass.
- Follow: the existing file whose structure to copy.
- Do not add: new dependencies, config options, or abstractions with a single user.
- Extras: list ideas at the end instead of building them.
The last line is adapted from the Sonnet 5.5 guide, whose sample paragraph tells the model to stop and report when the requested work is done and checked, and not to add features, tests, files, docs or refactors that were not asked for. If something would help, the model mentions it at the end instead.
Sources: Anthropic: Prompting Claude Sonnet 5.5 (Steer initiative and scope)
For rules that apply to every task, add a short block to CLAUDE.md. Anthropic's sample prompt for this problem covers four areas: scope, documentation, defensive coding and abstractions. Here is a starting block in the same spirit, with dependency and structure rules added:
Sources: Anthropic: Prompting best practices (Overeagerness)
- Make the smallest change that meets the request. No extra features, options or refactors.
- Do not add a dependency without asking. Prefer the standard library and what the repo already uses.
- Do not add an interface, factory, base class or helper that has a single implementation or caller unless the task calls for it. Leave two similar copies alone and extract on the third.
- Validate at system boundaries only, such as user input and external APIs. No error handling for cases that cannot happen.
- Copy the structure of the nearest existing file. If you think that structure is wrong, say so in one sentence and keep it.
- If something extra would help, list it at the end instead of building it.
Keep expectations honest. The memory docs say Claude treats CLAUDE.md as context, not enforced configuration, that shorter and more specific instructions are followed more consistently, and that a file should target under 200 lines. A block like this is a strong nudge and not a guarantee. Why rules fade is covered in Why Your CLAUDE.md Gets Ignored.
Sources: Claude Code docs: How Claude remembers your project
Use plan mode as the cheap checkpoint. Press Shift+Tab or start a prompt with /plan, and Claude researches and proposes changes without making them. At the approval prompt you can choose "No, keep planning" to send feedback, or press Ctrl+G to edit the plan yourself. A useful feedback line is "Which parts of this plan can be deleted and still meet every requirement?" Plan mode's edit blocks do not hold in every setup, and Claude Code Ignores Plan Mode? What Enforces It covers which ones do.
Sources: Claude Code docs: Permission modes (plan mode)
One part of this problem can be made mechanical: new dependencies. An ask rule makes Claude Code prompt before a matching command or file edit, and rules are checked deny first, then ask, then allow. In dontAsk mode, which never prompts, a matching call is denied instead. Add this to .claude/settings.json, merging it into any existing permissions block, and adjust the package managers to your stack:
Sources: Claude Code docs: Configure permissions, Claude Code docs: Permission modes (dontAsk mode)
{"permissions":{"ask":["Bash(npm install *)","Bash(npm i *)","Bash(yarn add *)","Bash(pnpm add *)","Bash(pip install *)","Bash(uv add *)","Bash(cargo add *)","Bash(go get *)","Edit(package.json)","Edit(pyproject.toml)","Edit(requirements.txt)","Edit(Cargo.toml)","Edit(go.mod)"]}}
The limits are in the docs. A Bash rule matches the command text Claude writes, so a different form of the same command, such as a full path or sh -c, is not matched, and the docs say such rules are not a security boundary. A bare npm install from a lockfile prompts too, and a script that rewrites a manifest by itself is outside what Edit rules see. The point is the pause: it forces the question of whether the package is needed before it lands.
Sources: Claude Code docs: Configure permissions (what a Bash rule does not match)
Fix it after the code: a five-minute diff audit
Run these from the feature branch, replacing main with your base branch. Commit first, because main...HEAD compares commits and ignores uncommitted edits.
Sources: Git docs: git-diff
git diff --shortstat main...HEADshows the size of the change, to compare with the size of the request.git diff --diff-filter=A --name-only main...HEADlists every new file. Each one needs a reason.git diff main...HEAD -- '*package.json' '*pyproject.toml' '*requirements.txt' '*go.mod' '*Cargo.toml'shows changes to dependency manifests at any depth, where new dependencies appear.git diff -U0 main...HEAD | grep -E '^\+[[:space:]]*(export |class |interface |abstract class )'lists added export, class and interface lines to check.git grep -n -w NewNamelists every use of a new name, so you can count the real callers. One implementation and one caller is a question, not a verdict.
Then ask three questions of each flagged item. Did the request, a spec line or a failing test require it? Does more than one caller use it today? Could it be deleted while every requirement still holds? Anything that fails all three is a candidate for deletion. Make the cut in its own commit so it is easy to review and easy to revert.
Take care in the other direction. Validation at system boundaries, tests for behavior that exists, and changes that make code easier to modify are not over-engineering, and Fowler's note says Yagni "is not a justification for neglecting the health of your code base." Anthropic's own sample prompt keeps validation at system boundaries such as user input and external APIs.
Sources: Martin Fowler: Yagni, Anthropic: Prompting best practices (Overeagerness)
Claude Code can help with the cut. According to the commands reference, /simplify runs four review agents in parallel covering reuse of existing helpers, simplification, efficiency, and whether the change is at the right level of abstraction, then applies the fixes. The docs say it does not look for correctness bugs. It is still a model reading a diff, so read what it removes and re-run your tests.
Sources: Claude Code docs: Commands
What the research can and cannot tell you
Studies of model-written code measure volume and complexity, which are proxies for over-engineering and not measures of it. Sonar's report on more than 4,400 Java assignments completed by six LLMs found that Claude Sonnet 4 produced more than three times the lines of code of OpenCoder-8B on the same problems. A study that compared GPT-4 with human programmers on 72 Python tasks reported that GPT-4 "frequently produces more complex code that may need more reworking to ensure maintainability", while also passing more test cases.
Sources: Sonar: The Coding Personalities of Leading LLMs, arXiv: Comparing Human and LLM Generated Code (2501.16857)
Both studies were published in 2025 and measured models on set programming tasks, in Java and in Python, so neither shows how Claude Code behaves on your repository. More lines can also be the right answer to a harder problem, and Sonar's own summary describes the most concise model, OpenCoder-8B, as creating "a technical debt minefield", so fewer lines is not a clean win either. The studies support measuring size and complexity in your own diffs. They do not give you a rate for your repository.
Sources: Sonar: The Coding Personalities of Leading LLMs
Where TLM Forge fits
TLM Forge sizes a task as Light, Medium or Deep. Medium and Deep show a design for your OK before anything is built, which is the moment to push back if the design is bigger than what you asked for. After the build, a final review wave of independent reviewer agents runs: code-reviewer and phase-auditor on Medium, with more reviewers on Deep, including an architect-reviewer. CRITICAL and HIGH findings are fixed test-first or brought to you, while MEDIUM and LOW are listed.
The limits matter here. Light tasks get no review agents. The reviewers are LLM agents and their CRITICAL and HIGH findings get fixed, so keep the warning above about review adding code in mind. The phase-auditor, which checks that the promised work was delivered and that out-of-scope items were respected, can miss things. Your own diff audit is still the check that matters.
Frequently asked questions
01Why does Claude Code add so much code for a simple change?
A short request leaves the size of the solution to the model. Anthropic's guides describe tendencies on some models to add extra files, abstractions, configurability or unrequested steps, and the guidance differs by model and effort level. Naming the file to follow and listing what not to add narrows the gap.
02How do I stop Claude Code from over-engineering?
Give a stopping point in the request: the file to copy, what done means, and what not to add. Put a short minimal-change rule in CLAUDE.md, review the plan before code, and audit the diff for new files, options and dependencies. Rules are context, not enforcement, so the diff check still matters.
03Does a CLAUDE.md rule against over-engineering work?
It helps but is not enforced. Anthropic's memory docs say Claude treats CLAUDE.md as context, not enforced configuration, and that shorter, more specific instructions are followed more consistently. Back the rule with plan review and a diff check instead of relying on it alone.
04Can AI code review make over-engineering worse?
It can. The Claude Code docs warn that a reviewer asked to find problems will always find something, and that fixing every finding adds abstraction layers and tests for cases that cannot happen. Decide which findings a real caller or input can reach before they become code.
05Is every abstraction Claude adds over-engineering?
No. Validation at system boundaries, tests for behavior that exists and changes that make code easier to modify are worth keeping. Ask whether a requirement or more than one caller needs the abstraction today. A common rule of thumb is to extract a shared abstraction on the third similar use, not the first.