Using AI assistants on legacy codebases

Start by feeding it the map

Before asking for any change, hand the assistant an architecture overview: directory purpose, key abstractions, naming conventions, and known foot-guns. A few hundred words of context dramatically improves output quality.

Many tools support a project-level instructions file (CLAUDE.md, .cursorrules, equivalents). Use it.

Refactors: small and reversible

• Constrain the scope explicitly — 'change only this function, do not touch callers'.
• Ask for a plan first, approve it, then ask for the diff.
• Run the existing test suite before and after, every time.

Bug fixes

Provide the failing case, the relevant file, and the suspected area. Ask the assistant to reproduce the bug with a test before fixing it. This single habit prevents the most common failure mode of legacy AI work — confidently 'fixing' the wrong thing.

What not to try

Whole-system rewrites. Cross-cutting renames that touch hundreds of files. Anything that requires the assistant to hold a mental model larger than its context window. These will produce plausible diffs that quietly break invariants.

The honest summary

AI assistants on legacy code are a force multiplier for engineers who already understand the system, and a hazard for engineers who don't. Pair them with the people who know where the bodies are buried.