Working in Large and Legacy Codebases
Get useful work out of agents in big, old, or unfamiliar codebases: orientation, mapping, safe refactors, and keeping changes reviewable.
Demos of coding agents almost always start from an empty folder. Your job probably doesn't. It's a decade-old monolith with three generations of patterns, a utils folder nobody fully understands, sparse tests, and a module everyone is afraid to touch. That's where agents can be most valuable, since reading unfamiliar code is slow for humans, and also where they fail most dangerously.
This lesson shows you how to get useful, safe work out of agents in big, old, or unfamiliar codebases. You'll learn how to orient an agent (and yourself) with a written map, how to run an impact analysis before changing anything, a refactoring workflow built on characterization tests and mechanical changes, how to keep large changes reviewable, and the specific traps legacy code sets for agents.
Why big codebases are hard for agents
An agent working in a large repository sees it through a keyhole. Its context window, the amount of text it can hold in mind at once, fits a tiny fraction of a big codebase. So it searches, reads a handful of files, and builds a mental model from what it found. When that sample is unrepresentative, the model is wrong, and every decision built on it inherits the error.
Large and legacy codebases make the sample unrepresentative in predictable ways:
- Several patterns for the same job. The agent finds the 2017 way of fetching data, copies it faithfully, and adds a fourth pattern to the three you're trying to retire.
- Hidden coupling. A function is called by name from a config file, a cron job, a template, or another service. Text search finds none of these, so the agent thinks it's safe to change.
- Dead code that looks alive, and live code that looks dead. Without runtime knowledge, the agent can't tell which is which.
- Few tests. The agent's main feedback loop, running the tests, is weak or missing exactly where changes are riskiest.
- Old toolchains. The agent writes modern syntax for a runtime that can't run it.
None of this means agents can't work in legacy code. It means you have to supply what the keyhole hides: a map, an impact analysis, and a safety net.