Legacy is code that works and nobody knows why. An agent helps here, but only if you do not start with edits.
Step 1. Reconnaissance without changes
The first run should be read-only. No edits, just a map.
Ask for answers rather than a file-by-file retelling:
- what the entry points are
- where business logic lives versus plumbing
- what gets called most often
- what the external dependencies are and what happens when they fail
A retelling of files is useless, you can read them yourself. Relationships are what you need.
Step 2. Work out what you can break safely
Before any edit you need an answer to how you would know you broke something.
If there are no tests, the first change is not a refactor, it is a test around the area you intend to touch. Even a crude one, even for a single scenario.
Agents write these well, because the task is formal: pin current behaviour without improving it.
Step 3. Pin what is, not what should be
A common legacy mistake is writing a test for how it ought to work. It fails immediately and you cannot tell whether that is a bug or your misunderstanding.
First a test for how it is. It must pass against unchanged code. Then you can change things.
Step 4. Edit in small steps
A ten-file diff in an unfamiliar project cannot be reviewed. Five two-file diffs can.
Watch deletions especially. Agents refactoring tend to drop what looks redundant, and in legacy the thing that looks redundant is often exactly the guard the whole file exists for.
What to ask to get value
Bad: "refactor this file".
Good: "explain why this check is here and what breaks if I remove it".
The second question buys understanding; the first buys a diff you cannot verify.
About spend
Reconnaissance across a large repository is large context, and context is billed on every step. So do the reconnaissance once and write the result to a file rather than re-asking in every session.
After that work with the files that matter, not the whole project. The bill usually differs by an order of magnitude.
In short
Map first, then a test that pins current behaviour, then small edits. Ask about reasons rather than requesting a refactor. Save the reconnaissance so you do not pay for it twice.