Why legacy code is hard for agents
Legacy codebases are large, inconsistent, and under-documented. An agent dropped into one has no way to know which patterns are current, which are deprecated, and which weird bits are load-bearing.
Without guidance it will pattern-match on whatever it happens to see — often the wrong thing.
Build a map first
Before any task, write a short map: the high-level architecture, the main entry points, the conventions that actually apply, and the directories to avoid. This is the agent's orientation.
Put it in the project memory file so every session starts from the same understanding instead of rediscovering the layout.
Scope the context per task
Don't hand the agent the whole repo. For a given task, point it at the specific modules and files involved and let retrieval pull related pieces.
Narrow, relevant context dramatically improves accuracy in a sprawling codebase.
Capture the landmines
Legacy systems are full of intentional weirdness — a workaround that must stay, an API that looks redundant but isn't. Document these so the agent doesn't 'clean them up' and break production.
Recording the why behind the quirks is some of the highest-value context you can give.
Start small and verify
Begin with small, well-bounded, verifiable tasks — a single function, a contained bug. Confirm the agent understands the codebase before trusting it with bigger refactors.
Each verified success expands the safe scope and your confidence.