AI Refactoring Legacy Systems: The 17 Unwritten Rules Agents Quietly Delete

Introduction: A Flashy Conclusion

The recent article "Plan mode is dead" went viral in AI coding circles. Its argument: models have become so strong that humans no longer need to write specifications; planning documents are a burden. The future is an endless "understand–act–check–act" loop where humans merely DJ between agents. It sounds cyber‑futuristic, but when held up against real software engineering practice the cracks appear immediately: someone who has never carried a large system uses personal side‑project experience to pronounce a death sentence on an entire engineering discipline. That is like declaring requirements analysis dead because one person wrote a bad requirements document.

Small Tools vs. System‑Level Complexity

The original author built a desktop AI application called Nuanced whose core pain point is "how humans keep up with the machine's code‑change speed." That is a genuine single‑point tool problem, not a system‑coordination problem. A true large system might be a core platform launched ten years ago: thirty‑plus requirement distortions layered on top, a special branch left from a 2016 compliance refit, a 2019 custom logic for a key client, a 2022 hot‑fix that left the state machine half‑broken. Business chains are long, implicit rules abound, external interfaces are too old to touch, internal calls resemble a tangled ball of yarn. Yet it must keep accepting new requests, fixing old bug s, and guarantee zero errors in midnight reconciliation, month‑end closing, and regulatory reporting. In such a system "understand first, then act, watch while changing" is correct, but it absolutely does not mean "stop planning, let the agent freestyle."

The Real Difficulty: Behavior Is Not Written Down

A system feels hard rarely because the code is old; old code is just the surface. The real hardness is that its behavioral logic exists nowhere in writing. Examples from the article:

A discount calculation looks odd because a lawsuit years ago forced legal to mandate that exact formula.

A retry loop runs exactly three times because the legacy vendor's interface hiccups every Tuesday afternoon.

A seemingly useless nullable column cannot be dropped because an unmaintained downstream report still reads it.

A batch job nobody claims ownership of, yet the whole company depends on it.

None of these live in README files, architecture diagrams, or model context windows. They survive in tickets, emails, veteran engineers' heads, and post‑mortem documents. The article compares this to a thirty‑year‑old building whose blueprints are lost: a renovation crew sees a horizontal pipe blocking the new toilet, finds it on no drawing, saws it off — and that afternoon the floor below starts leaking. Those "drawings" were lost not necessarily out of laziness; the rules grew from real incidents and compromises at a time when no one thought to record them.

What AI Agents Delete First: The Untested Rules

General‑purpose AI agent s excel at generating code that "looks modern, passes all unit tests, compiles cleanly." The catch: those untested business rules have no test cases. Deleting them leaves the test suite green. To the agent, those branches are unrelated to the happy path; removing them is not an error. Result: everything looks fine on Tuesday, but month‑end close reveals financial mismatch. Worse, the agent never warns "this part must not change"; it only reports "I refactored this logic more elegantly." It is like a new intern who tears down the office's ugly house‑rules poster on day one, wipes the wall clean — unaware the poster was put up thirty years ago after a serious incident.

What "Planning" Actually Means in Legacy Systems

Planning for complex business systems is neither waterfall PPT nor a heavy "session → spec → approval → implement" pipeline. It is five concrete activities:

Identify contract‑level invariants. Behaviors that must never change no matter how many rewrites — backed by contracts, regulations, downstream dependencies — irrespective of code elegance.

Pin current behavior with characterization tests. Characterization tests do not judge correctness; they snapshot "this is how it behaves today." Any future change must diff against that snapshot: what changed, and was it intentional?

Record "why this change, what alternatives were dropped" via ADR and RFC . Written for the person taking over three months later, not for yourself now.

Evolve incrementally with anti‑corruption layers and the strangler fig pattern. The strangler fig does not topple the old tree; it grows around it, slowly enveloping it. New logic lives outside; old logic retires piece by piece.

Every change must be rollback‑able, canary‑deployable, and accountable for production behavior. This is the baseline; the previous four serve it.

Legacy modernization fits "hypothesis‑driven + lightweight RFC + evolutionary architecture" — not big‑bang rewrite, not laissez‑faire. Banking cores, insurance claims, tax billing, telecom rating, hospital scheduling: stability weight dwarfs "lines of code this week." An agent left to loop freely will never volunteer that a block cannot move because a 2018 regulatory letter mandated preserving the original rounding deviation; it will simply think it did a beautiful job.

Bad Documents ≠ Dead Analysis

The original article proves that verbose, smelly AI‑generated planning documents are unwelcome — a point the author fully agrees with. But jumping from there to "planning mode is dead" crosses a chasm. Engineers who have actually maintained large systems reach the opposite inference: the stronger the model, the more critical it is to clarify goals, boundaries, invariants, rollback criteria, and compliance constraints up front. Previously these lived only in architects' heads, invisible; now AI forces them into explicit artifacts. Planning hasn't died — it has been forced into the open.

Conclusion

Do not rush to hand legacy systems over to agents. First, excavate the rules nobody wrote down: capture them as documentation, as characterization tests, as ADR s.

They used to live only in veterans' heads; now they must live in the repository.

Skipping this step saves this week's effort but borrows against next quarter's interest. The most expensive thing in a legacy system is not the old code — it is the rules that exist only in human brains and walk out the door when people leave.

Key takeaway:

The most expensive thing in a legacy system is never the old code; it is the rules that exist only in people's heads and leave when they do.