Why Do AI Coding Agents Keep Building Too Much? — Tracing the Causes of Overengineering and Putting a Brake in the Instruction Files#

2026-11-22

On one side of a workbench lies a note with a small birdhouse sketched on it, while a robot carpenter has spread out a huge castle blueprint with towers and walls and is peering at it through a magnifying glass, and behind it a person holds out a single-page birdhouse blueprint

A Version Table to Store a Single Value#

I use Claude Code and Codex together when I develop. I wrote about how I combine the two in The Main Agent Only Sees the Question and the Answer. Lately, though, I kept getting the feeling that both tools try to implement far more at once than they used to.

Here is a typical example. I handed over a feature that only needed to add and edit values in a table. What came back included an extra table for version history, and to keep the two tables consistent, it wrapped the in a and called that. I had never said that edit history was needed.

A complex, airtight implementation is not always the right answer. It depends on the situation. For an application a startup is just getting off the ground, what matters is being able to build quickly and change things often. When you are changing an application that already has many customers, stability comes first. Yet the agents seemed to treat the latter as the right answer regardless of the situation.

It wasn’t just my impression. In the “Overeagerness” section of its official prompting guide, Anthropic writes that Claude Opus 4.5 and 4.6 “have a tendency to overengineer by creating extra files, adding unnecessary abstractions, or building in flexibility that wasn’t requested.” It also includes a sample prompt to curb this tendency. If the company that builds the model acknowledges the tendency itself, then the people using it have no choice but to put a brake in place on their side.

Five Reasons Agents Build Too Much#

Before choosing a brake, I tried to work out why this happens in the first place. Of the five reasons below, the first one, and the part of the third about training data, are my own inferences about how the models are built. The rest are things I observed while using them.

First, falling short gets punished, while going overboard barely does. Coding agents are known to go through against criteria such as passing tests and review ratings. Missing an edge case or leaving a concurrency bug is recorded as a failure. Building an unnecessary version table, on the other hand, rarely is. As this asymmetry accumulates, “add it just in case” becomes a habit.

Second, the brake that human developers had is missing. For a human developer, writing more code takes time and effort, and the person who has to maintain that code later is themselves. So, if only out of reluctance, they stuck to the principle of not building what isn’t needed yet. An agent doesn’t get tired, and it doesn’t factor in the burden of maintaining the code it writes now. The agent in the next session will find and read that code when it needs to, but that cost is paid later, not at the moment of writing. The cost of the extra code falls on the people who have to read and change it later, and on the agents that have to read it too whenever they work on something related. Every time a single table changes, the version table and the procedure have to be read and changed with it, so the token cost keeps growing as well.

Third, there is no way to know what stage the product is in. From a request like “save and edit a value” alone, you can’t tell whether there are zero users or a hundred thousand. On top of that, most of the “best practices” in the training data were written with mature, large-scale systems in mind. The empty context naturally gets filled in at production-grade.

Fourth, ambiguous requests get filled with the most complete interpretation. The agent asks itself, “If this is edited, the previous value disappears. Is that okay?” Up to that point, it’s a good habit. The problem is that it implements the answer without asking the user. Recent models are being tuned to work for long stretches without human confirmation, so this tendency may only get stronger.

Fifth, review loops grow complexity in only one direction. Run things through plan mode, a review agent, or a cross-check by another model, and you get comments like “there may be a .” Addressing the comment adds a transaction, and making the transaction safe adds a procedure. Reviewers who say “you can drop this,” on the other hand, are almost nonexistent.

Unclear requestno product stageLeaves out what's neededlogged as failure or flaggedAdds what's not neededmostly passes as isThe default tiltstoward production-grade
When only omissions get punished, adding more is always the safe choice for an agent that doesn't know the situation.

I Didn’t Choose the Methods That Rely on Human Filtering#

With the causes laid out, two easy countermeasures came to mind. One was to get a list of “new tables and files to be created” before implementation and filter it. The other was to state what not to do in each request, such as “no edit history needed.”

Both would probably work, but I didn’t choose them. In the end, both increase the work a human has to do. I can already ask for the unnecessary parts to be removed from the result. What I wanted was for the agent not to head in that direction in the first place. If it is information the agent should know up front, without a human adding something to every request, then putting it in instruction files that are read every time is practically the only way.

Opening the Instruction Files, I Found an Accelerator Instead of a Brake#

So I started by opening the instruction files I was already using. At work, the repositories where I felt the risk of overengineering was highest were three: the backend, the frontend, and a business automation agent. I looked at seven places in total: those three repositories, the work hub that ties them together, and the user-level global instructions for Claude Code and Codex. I described the structure of the work hub in Not That I Couldn’t Fix It, but That I Didn’t Notice It.

The results were worse than I expected. None of the seven places had a general principle against overengineering. There were only a few local rules such as “this prompt file does not need to consider ,” and the global instruction file for Codex was empty.

What stood out more were the elements that actually pushed complexity up.

  • The tone of the documents. The instructions in all three repositories were full of words like “,” “single source of truth,” “invariant,” and “guard,” along with numbered design decision records. Agents follow the tone of their context. After reading documents like these, they act as if they were handling a high-risk system even when changing a single line of UI text.
  • High-risk patterns that are always loaded. The business automation agent repository’s instructions contained the rule “when changing settings that move customers’ money, also write to the history table in the same transaction.” In that area, it is the right decision. The problem was that it came with a persuasive rationale, “a change with no history is itself the signal that someone bypassed the proper path,” and there was no sentence restricting the rule to that area. A pattern with the same shape as the version table case I first ran into was sitting right in the middle of a file that every session reads.
  • Layer rules with no criteria for when to create something new. The backend requires following the in the order of router, service, Repository (the data access layer), and entity. It’s a rule worth keeping for consistency. But with no criteria for when to add a method to an existing service versus creating a new one, even a simple feature starts out as four files.

I learned one more thing during this review. The team had already audited and stripped out overengineering in an internal operations screen not long ago. We had run into the problem and even fixed it, but the lesson never made it into the instructions that the agent reads for the next task.

Block the Premises with Facts Instead of Saying “Keep It Simple”#

I started by listing what needed to be blocked. The types of overengineering I had run into, or thought of while reading the instructions, fall roughly into five groups.

  • Data model: history and version tables, , multi-table transactions wrapped in procedures, locks against concurrent edits, indexes created in advance
  • Code structure: interfaces with only one implementation, , general-purpose utilities used only once, making configurable what could just be hardcoded
  • Defensive code: input validation on every internal call, retries with , fallbacks that hide failures, backward-compatibility shims that keep old names alive
  • Operations: cache layers, queues and background workers, logging and metrics no one asked for
  • Scope creep: delete, bulk edit, and search tagging along with a request for “edit,” refactoring the surrounding code while fixing something

The sample prompt in Anthropic’s official guide is a similar list. It includes lines such as “Only make changes that are directly requested or clearly necessary,” “Don’t design for hypothetical future requirements,” and “The right amount of complexity is the minimum needed for the current task.” It’s a good starting point. But two things kept me from using it as is.

First, the one judging what is “clearly necessary” is still the agent. Without stage information, the agent judges necessity by production-grade standards, and by those standards even a version table can count as “clearly necessary.” Since the agent will likely consider its own design appropriate already, I judged that the words “keep it simple” alone would hardly change its judgment.

Second, going minimal everywhere is risky for a company service. Changes to settings that move money, or permission checks, must not be treated lightly.

So I changed how I write the instructions: block the premises the agent uses to justify overengineering with facts. The justification “what if two people edit it at the same time?” loses its force once there is a single line saying “simultaneous edits practically never happen.”

The agent's justificationFact or rule in the instructionsWhat if two people edit at once?Simultaneous edits: practically noneWhat if outside services call this API?Only our own web client calls itWhat if the data grows?Few users; add it once it's slowWhat if the old value is needed?History only when the request asks
Instead of asking it to "keep it simple," pair each justification with the fact that neutralizes it.

Following this direction, I settled on five things to put in the instructions.

  1. Block the premises with facts. For each repository, write down the premises the agent uses as justification: the number of real users, the likelihood of simultaneous edits, whether any external API consumers exist, and data volume. For a service still in development, for example, “the schema and API can change freely” is enough. For a Chrome extension that is live but has few users, something like “keep existing values readable only when the storage format changes” fits, because extension updates are pushed to users automatically.
  2. Attach exceptions to the list of things not to add. Write down when something is allowed, as in “history tables only when the request mentions ‘history’ or ‘undo.’”
  3. Give it a way out. Have it leave a single “Further consideration” line at the end of its response instead of implementing something that seems necessary. A human reads the response anyway, so this adds no work. Without this way out, the agent ends up implementing the thing just to resolve its own worry.
  4. Name the areas that must not be cut down. Authentication and permission checks, secret keys, writes that move money, and irreversible loss of user data stay strict regardless of the stage. Without this boundary, a simplification guideline could spill over into security holes.
  5. State that the team’s verification procedures are not subject to simplification. The company repositories have a high test coverage threshold and a rule to leave a work record with every commit, both set deliberately by my colleagues. I left these rules untouched in this work. Changing them would require team agreement, but there is a bigger reason: the principle of “keep it simple” must not become grounds for skipping tests or records. I made it explicit that the principle applies only to the scope of product code.

For the company services, I added a principle of proportionality on top of this. These are production services with customers, so not everything can be done lightly. I decided to name the zones that must stay strict and keep everything else light. The strict zones are changes to settings that move money, permission checks, writes to the production database, and credentials. The light zones are UI display and text, read-only lookup screens, report formatting, and internal tools. The strict zones differ slightly by repository, so each repository’s instructions list them separately. For the history-in-the-same-transaction pattern I pointed out earlier, I decided to add a sentence saying “use this pattern only in that area and don’t replicate it to other tables.”

Here is the section I actually put in the global instructions (translated from Korean):

## Implementation scope and complexity

- The default is the simplest implementation that satisfies the request. Add complexity only in proportion to risk.
- Do not add unless requested: history, version, or audit tables, soft delete, multi-table transactions wrapped in procedures or RPCs, optimistic locking or concurrency control, caching, queues, retries, or fallbacks, interfaces or factories with only one implementation, backward-compatibility shims, adjacent features, UI states, or surrounding refactors that were not requested.
- If something seems necessary, do not implement it; leave a single "Further consideration" line at the end of the response.
- Follow existing patterns such as the repository's layer structure, but create a new Service, Repository, or module only when it cannot fit into an existing one.
- Do not extend a strict pattern defined for a specific domain (e.g., writing to a history table alongside each write) beyond that domain.
- Apply review comments only when they fit the current stage and risk.
- Never cut down, regardless of stage: authentication, permission, and scope checks, secret keys, writes that move money, irreversible loss of user data.
- Verification and documentation procedures set by the repository (test and coverage gates, handoffs, doc update rules) are not subject to simplification. This principle applies only to the scope of product code.
- If the repository's instructions define scope, stage, or strict zones more specifically, follow those.

The last line accounts for the fact that each repository has its own circumstances. The company frontend, for instance, has a team rule that screens must include loading, empty, and error states by default. In a repository like that, the team rule takes precedence over “UI states that were not requested” in the global list.

Where Should the Instructions Go to Actually Be Read?#

Instructions only work if the agent actually reads them. Confirming which tool reads which file turned out to be as important as writing the content. Here is what I confirmed in the official documentation (as of November 2026).

Claude Code reads ~/.claude/CLAUDE.md (user-level global) and the CLAUDE.md files from the working directory and every directory above it, concatenating them all. A CLAUDE.md in a subdirectory is read when Claude works on files in that subdirectory. Recent versions also read AGENTS.md directly, but only when there is no CLAUDE.md in that location or above it. When both files exist, the official documentation recommends importing it by putting a single @AGENTS.md line in CLAUDE.md.

Codex reads ~/.codex/AGENTS.md (user-level global). Then, from the repository root down to the working directory, it reads one AGENTS.md per directory and concatenates them. Empty files are skipped. It doesn’t read CLAUDE.md unless you add it to the fallback filename list in the config file. By default, it reads the concatenated instructions only up to .

Looking at these facts, I saw what I had missed. The CLAUDE.md in two of the company repositories only had a sentence saying “see AGENTS.md for the rules,” with no @AGENTS.md import. So whether the AGENTS.md that actually held the rules made it into Claude Code’s context depended on whether the agent chose to open that file itself. The work hub’s instructions are also read only by sessions started in the hub. They don’t apply to sessions started directly in a repository’s working directory.

So I decided to split the instructions into three layers.

Global instructions — principles shared by every repository~/.claude/CLAUDE.md · ~/.codex/AGENTS.mdWork hub instructions — strict and light zones for company servicesRead only by sessions started in the hubBackend repositoryAGENTS.mdrepo-specific strict zonesteammates' tools read itFrontend repositoryAGENTS.mdrepo-specific strict zonesteammates' tools read itAutomation agent repoAGENTS.mdrepo-specific strict zonesteammates' tools read itClaude Code reads CLAUDE.md, Codex reads AGENTS.mdOne @AGENTS.md line in CLAUDE.md lets both tools read the same file
Put the principles in the global layer that every session reads, and the facts that differ by repository in the repository files that every teammate's tools read.
  • Global: I put the shared principles, with identical content, into the global files for both Claude Code and Codex. They are read by sessions started in any directory. Since the two files have the same content, I left a note in each saying that changing one means changing the other.
  • Work hub: I wrote down the strict and light zones for the company services. In the definitions of the that the hub hands work to, I specified that they read the repository’s AGENTS.md first.
  • Repository: I’m adding the principles and the repository-specific strict zones to the AGENTS.md of all three repositories. This file is read not only by my tools but also by the Claude Code, Codex, and Cursor my teammates use. So, like any other change to team rules, it is going in through a for each repository.

What I Don’t Know Yet, and What Only People Can Do#

At the time of writing, I have only just applied the instructions, so I don’t know their effect yet. Over a period of real implementation work, I plan to watch four things.

  • Have unrequested history tables, caches, retries, and backward-compatibility shims decreased in the light zones? Are they showing up as a single “Further consideration” line instead?
  • Have the safeguards in the strict zones held up? Is something like the history record for changes to settings that move money still in place?
  • Has the agent started skipping tests or work records under the pretext of the simplification principle?
  • Has implementation quality instead dropped, increasing the back-and-forth between implementation and review? If I find myself asking again because even essential handling was left out, that would be a sign the principle is working too hard.

If something goes wrong, the repository changes can be reverted with a PR, and the global instructions can be restored from the backed-up files.

Here is where tracing the causes has left me. An agent’s default is “a production service with many customers.” Not because the agent is bad, but because when it doesn’t know the situation, that is the choice least likely to be wrong. The information that can change that default, namely what stage this product is in right now and where the real risks lie, is something only people know. Where human laziness used to be the brake on overengineering, writing that information into the instruction files is now the brake. It is also one piece of the harness described in Harness Engineering.

Of course, an instruction file is ultimately a mechanism that hopes the model will read and follow it. As I discussed in Rules from Memory to Code, rules written in a document are not enforcement. How well these instructions are followed, and how to make up for the parts that aren’t, I will write up in a follow-up after a few weeks of use.

References#