TL;DR
Teams that see fast results from AI coding tools on new services often see slow, architecturally wrong output on the old system. On a large legacy codebase the tools help most when they read: explaining modules, mapping dependencies, drafting notes for review and writing tests that pin current behaviour. They do the most damage making broad edits in code whose reasons nobody wrote down. Decide module by module, then test the decision on real backlog items, so licences and expectations rest on your own evidence.
In this article
8 min read
Yes, but unevenly, and the unevenness is predictable. AI coding tools are useful on an old, many-handed codebase wherever the job is to read and explain it, and wherever a change is small, covered by tests and backed by written reasons. They make things worse where a change spreads across modules or touches code that is load-bearing for reasons that live only in people’s heads, because the tool treats every pattern it finds as intended and every abstraction it cannot explain as fair game.
That is close to what two developers described when they raised this. On the Cursor community forum in 2025, a developer working with large, unfamiliar codebases wrote that the tool kept generating and running changes before they had understood or approved them, and asked for a way to make it propose one surgical change at a time and wait; keeping it under control, not raw capability, was the problem. In April 2026, a developer with more than twenty years of experience, asked by a small medical-software company to find out how AI could help it, asked on Hacker News how others use these tools on a codebase over twenty years old, where the tool added bloat unless someone who already knew the code guided it.
The measured slowdown came from old repositories with unwritten context
The closest controlled evidence is METR’s randomized trial of early-2025 tools (METR, July 2025; paper). Sixteen experienced developers worked 246 real issues in open-source repositories they had contributed to for years. Tasks where AI was allowed took 19% longer, while the developers believed AI had sped them up. The paper’s factor analysis matters most here: the repositories averaged ten years old and more than 1.1 million lines, developers accepted fewer than 44% of AI generations, about 9% of their time went to reviewing and cleaning AI output, and they reported that the AI did not use important tacit knowledge or context. METR lists large, complex repositories and implicit repository context among the factors likely to have contributed.
Reading the system is where the help is strongest
Comprehension is the use with the most support. Thoughtworks moved “using GenAI to understand legacy codebases” to Adopt on its Technology Radar in November 2025, saying that tools such as Claude Code, Cursor and Copilot help developers surface business rules, summarise logic and identify dependencies, and that setup effort grows with the size of the codebase (Thoughtworks Technology Radar). In an earlier write-up, Thoughtworks engineers describe building a graph of the code so that only relevant parts reach the model, with subject matter experts validating what it says (Legacy Modernization meets GenAI, September 2024).
Four jobs fit a legacy system well:
- Explaining a module before anyone changes it, with file references a person can check.
- Tracing dependencies: which callers, jobs, tables and configuration a change would reach.
- Drafting the missing notes: what a module appears to do and which parts look deliberate, for someone who knows the code to correct.
- Writing characterisation tests, the tests Michael Feathers describes in Working Effectively with Legacy Code (2004) that record what the code does now, so a later change has a safety net. Meta’s TestGen-LLM work shows how to keep generated tests honest: candidates were kept only if they built, passed reliably and added coverage, and engineers accepted 73% of the recommendations that cleared those filters (Alshahwan et al., February 2024).
None of these changes production behaviour, and each gives a knowledgeable person something to correct rather than write.
Changes go wrong where the reasons were never written down
Michael Nygard described the underlying problem in 2011, long before these tools: a newcomer who does not know why a decision was made can only blindly accept it or blindly change it (Documenting Architecture Decisions). An AI tool is a newcomer in every session. In a legacy codebase that shows up in a few recognisable ways:
- It copies what it finds. DORA warns that tools grounded in internal code can replicate deprecated patterns and so amplify technical debt, and advises against indexing bad code (DORA, AI-accessible internal data). Twenty years of styles give it plenty to copy.
- It removes what it cannot explain. An odd guard clause or an extra layer of indirection may exist for a customer, a regulator or a past incident. Nothing in the code says so.
- It edits broadly. A change across many modules multiplies the places an unwritten rule can break, and reviewing it needs the very knowledge that is missing.
- More context is not a free fix. Chroma’s tests of 18 models found performance becoming less reliable as input length grows, even on simple tasks (Context Rot, July 2025).
The practical answer to the last point is placement rather than volume. Claude Code, for example, treats its instruction files as context rather than enforced configuration, suggests keeping each under about 200 lines, and loads a file in a subdirectory only when work reaches that directory (Claude Code memory documentation, checked 9 October 2026). A short note beside a module that says why it is shaped the way it is costs little context and reaches the session that needs it.
Decide module by module
The useful question is which modules suit AI help, and two checkable facts decide it: whether the reasons are written down and whether tests pin the behaviour.
Decision guide
- If a module has tests and written reasons, let the tools change it under normal review.
- If it has tests but no written reasons, let the tools explain it and draft the reasons; a person who knows the module confirms them before changes start.
- If it has neither, keep the tools reading: explanations, dependency maps and characterisation tests come first.
- If nobody left knows why it works as it does, no tool can recover the reasons from the code alone. Treat the work as discovery, with time to observe the module in production.
- Whatever the zone, keep changes inside one module unless a person who knows both sides reviews the crossing.
These zones work best as routing rules agreed in advance, like risk lanes for AI-assisted changes, and a reason written next to the change it explains survives longer than one in a chat thread (decisions need a trail in the repository).
Test the answer on your own backlog before committing licences
Most demos run on reasonable code, as the Hacker News author pointed out; a defensible decision needs a small trial on yours. Pick a handful of real backlog items, some in each zone, and record for each one the review corrections, the rework before merge, the review time, and any defect found in the weeks after. Compare them with how similar items went before, written down beforehand so the comparison is honest. DORA’s 2025 research describes AI as an amplifier of an organisation’s existing strengths and weaknesses (DORA 2025 report); a trial like this shows which of yours it is amplifying. Name one engineering lead who owns the conclusion and the zone map that follows from it.
The AI Delivery Programme is designed to do this work on one application over five weeks. In the Align week the team gathers its existing documentation, outdated material included; initial project and module documentation is generated from the code for the engineers to review, and the team writes down its conventions and their exceptions. In the Practise weeks, real backlog items are delivered through the workflow with a record for each, so the team sees where AI help holds up on its own code. No team has completed the Programme yet, the quality of generated documentation on an unfamiliar legacy codebase is untested, blocking enforcement before an edit applies only on Claude Code and Codex CLI, and it is a poor fit if nobody on the team still knows why the software works as it does. If that trial on your own legacy application is the decision in front of you, fix this for your team starts with a fit conversation.
Frequently Asked Questions
Can AI coding tools actually help on a large legacy codebase that nobody fully understands?
Yes, and the first help is usually understanding rather than code: explaining a module and drafting its missing notes, which Thoughtworks now treats as a default practice rather than an experiment. Treat each explanation as a claim to check against the code, because on a system nobody fully understands, nobody can confirm it from memory.
Where do AI changes on legacy code go wrong most often, and is the tool really the cause?
Look at where corrections cluster. If they gather in modules with no tests, the cause is the missing safety net; if they gather where old conventions conflict, it is inconsistent patterns; if they follow cross-module changes, it is scope. If corrections are spread evenly across well-documented and poorly documented code, suspect the tool or the way it is used instead.
How much time should we spend writing down the reasons behind load-bearing code, and which modules first?
Start with the modules on the backlog for the next quarter that someone still understands, and stop at a page per module: what it is for, what must not change and why, and the known exceptions. Writing more than a reviewer will read rarely pays back. Modules nobody plans to touch can wait.
What if we limit AI to well-understood modules and require an expert review elsewhere?
That rule fails in two predictable ways. Boundaries blur, because one change can reach a poorly understood module through a shared helper, so the zone has to be checked per change rather than assumed. And the experts become the queue: if two people review every change in the old code, their calendar sets your pace, which is a reason to spend part of their time writing down what they know.
What should we measure on real backlog items, and who decides whether AI help is a net gain?
Review corrections, rework before merge, reviewer time and defects found later, per item and per zone, against a baseline written before the trial. Developers’ own sense of speed is not enough; in METR’s trial it pointed the wrong way. One named engineering lead should own the verdict, and it can differ by zone.
