Why Your AI Agent Keeps Rewriting Your Codebase — And How to Stop It

yuqin lin — Thu, 28 May 2026 14:59:26 +0000

You ask your AI agent to add a small feature. It rewrites three files you didn't mention, extracts a utility function that didn't need extracting, and introduces an abstraction layer "for future extensibility."

Sound familiar?

This isn't a model problem. It's a protocol problem — and it happens specifically in the gap that no one has designed for yet.

The Gap Nobody Talks About

The AI-assisted development ecosystem has gotten very good at two things:

Starting fresh. Spec-driven development, PRDs, interview-me skills — lots of tooling helps you go from "I have an idea" to "I have a plan."

Executing steadily. Incremental implementation, TDD, thin vertical slices — once you know what to build, agents can implement it carefully.

But there's a gap between them that happens dozens of times in any real project:

You're mid-development. Something is half-built. And a new idea arrives.

Maybe you're testing what you built and realize it needs to work differently. Maybe a user gives feedback that changes the direction. Maybe you just think of something better while looking at the code.

When this happens, most agents do one of two things:

Rewrite the foundation to accommodate the new idea
Ask clarifying questions, then rewrite the foundation anyway

Neither is what you actually want.

Why Agents Default to Rewriting

The rewrite default isn't random. It comes from how agents reason about change requests.

When you say "I want to add X," the agent evaluates the current codebase, sees where X doesn't fit cleanly, and takes the most "correct" path: restructure until X fits.

This is locally rational but globally destructive. The agent optimizes for code cleanliness at the moment of the request. It doesn't know that:

You have three other things half-done that depend on the current structure
The restructure will force you to re-test things that were already working
The new idea might not survive contact with reality and shouldn't justify a rewrite yet

The agent treats every new idea as a confirmed requirement. But in real product development — especially AI-assisted development, where ideas surface faster than ever — most new ideas are hypotheses that need to be tested, not requirements that need to be built.

The Five Questions an Agent Should Ask

When a new idea arrives mid-development, five things need to be determined before a single line of code changes:

1. Is this idea worth acting on now?

New ideas aren't equal. Some are genuine blockers (a bug in the current main path). Some are improvements (the current thing works, but could be better). Some are extensions (a new feature or scenario entirely).

These need different responses. A blocker should be handled immediately. An improvement should be batched. An extension should be parked for 24 hours — most new feature urges either fade or crystallize into something clearer.

2. How destructive is this change?

Some changes are reversible: add a new field, add a new route, change a UI element. You can always undo them.

Others are one-way doors: change a database schema, modify an external API signature, delete files. These deserve more scrutiny — not because they're wrong, but because the cost of being wrong is high.

3. Does anyone actually consume what you're about to build?

Before creating a new module, function, or API, count its real call sites. If the answer is zero, you're building for a hypothetical future. If the answer is one, you don't need abstraction. If the answer is three or more, now abstraction is worth considering.

The "zero consumers" case is where the most over-engineering happens. An agent enthusiastically builds a general-purpose system that nothing actually calls.

4. What's the least destructive way to integrate this?

There's a spectrum of integration modes, ordered by how much existing code they disturb:

Wrap: Add a layer around the existing code. Don't touch the original.
Extend: Add a new branch, parameter, or route. Don't change existing paths.
Branch: Implement in parallel. Keep the old path, migrate consumers gradually.
Replace: Genuinely rewrite. Only when the old implementation is a real liability.

Most new ideas fit in Wrap or Extend. Agents default to Replace.

5. Is the same logic appearing in too many places?

When the same pattern shows up three or more times, that's worth flagging — but not necessarily worth fixing immediately. Surface it, let the developer decide.

What This Looks Like in Practice

Here's a real pattern from AI-assisted development.

The scenario: You're building a data dashboard. You've completed the user analytics page and the content analytics page. Mid-session, you think: "We should add real-time collaboration."

Default agent behavior: Begin evaluating the architecture for real-time support. Propose WebSocket integration. Maybe start refactoring the data layer to support shared state.

What should actually happen:

Classify the idea: new scenario, not a bug. C-class — new feature.
Log it to the inbox. Continue the current task.
24 hours later, revisit: Is real-time collaboration something current users are asking for? Is the core dashboard even validated yet?
If yes — then evaluate it properly, pick an integration mode, scope it as a real task.

The idea doesn't die. It gets a fair evaluation at the right moment, not an impulsive implementation at the wrong one.

Another scenario: An existing utility function appears in five different files with slight variations.

Default agent behavior: Silently copy it into a sixth place, or silently "refactor" all five to use a common version (touching files outside the current task scope).

What should actually happen:

The agent flags it: "I've found [X logic] duplicated 5 times. Consolidate now or log to inbox?"

If the developer says "log it" — it goes to the inbox as a polish item. The current task continues uninterrupted. When the consolidation is eventually done, it's a clean, dedicated task — not a side effect of something unrelated.

The build-forward Protocol

These five questions are the core of a SKILL.md I built called build-forward. It's a set of agent instructions that fires whenever a new idea appears mid-development.

Rule 1 — Classify first, don't code.
Every new idea gets an A/B/C label before anything is written. A (fix) = handle now. B (polish) = batch later. C (extend) = 24-hour cooldown.

Rule 2 — Assess destructiveness.
One-way door changes require an explicit impact matrix before proceeding. Two-way door changes proceed directly.

Impact Assessment:
- Direct change:      [file / interface name]
- Downstream effects: [which consumers are affected]
- Rollback cost:      [high / medium / low — reason]
- Recommendation:     [proceed / new branch / defer]

Rule 3 — Consumer audit.
Zero consumers → don't build. One consumer → inline, no abstraction. Three or more consumers → now consider a shared layer.

Rule 4 — Choose an integration mode.
Wrap → Extend → Branch → Replace, ordered by destructiveness. Pick the lowest one that works.

Rule 5 — Duplication alert.
Three or more occurrences of the same logic → surface it, ask whether to consolidate or log it.

There's also a fallback for when the developer overrides the protocol: the agent doesn't argue, but it does force-output the impact matrix and defaults to the most rigorous evaluation (Replace mode). Informed decision, not blind compliance.

What This Isn't

build-forward isn't about blocking ideas. It's not a PRD process or a change freeze.

It's about routing ideas to the right moment and the right path. An idea that arrives as a C-class impulse at 2pm might become a valid B-class task at the next planning session. The 24-hour rule doesn't kill ideas — it filters for the ones that survive examination.

It also isn't about making the agent more restrictive. An agent running build-forward will still implement what you ask. It just asks five questions first, and picks the integration path that preserves rather than destroys.

Getting Started

build-forward works with Claude Code, Cursor, Codex CLI, Gemini CLI — anywhere that supports SKILL.md files.

# English version
curl -L https://github.com/dmlin7777777/build-forward/raw/main/SKILL.en.md \
  -o .claude/skills/build-forward/SKILL.md

The skill is on GitHub at dmlin7777777/build-forward — English and Chinese versions both available.

The Bigger Picture

AI coding assistants have made it trivially easy to generate code. The new bottleneck isn't generation — it's integration. How do you connect new ideas to existing structure without creating the kind of churn that makes AI-assisted codebases feel like they're always being rebuilt from scratch?

build-forward is one answer to that question. The five rules aren't complicated, but they close a gap that most agent workflows leave completely open: the moment between "I just thought of something" and "the agent is already changing everything."

That gap is where most of the wasted time in AI-assisted development lives.

Have you hit this problem in your own AI coding workflow? What's your current approach? I'd love to hear in the comments.

DEV Community: yuqin lin