The short answer
Do not start by changing things. Start by capturing what the system currently does in tests, so that any change can be checked against the behaviour people depend on. Then change under that protection.
This feels slow and it is the fastest safe route. Teams that skip it spend longer fixing regressions than the characterisation would have taken.
Why legacy work is different
- The behaviour is the specification, and it is not written down
- Some of that behaviour is a bug someone now depends on
- The original authors are usually gone
- Tests are absent or no longer run
- The build or environment may be difficult to recreate
- One person understands it, and they are busy
The second point is the one that catches people. Fixing an apparent bug can break a downstream process built around it, and nobody finds out for a month.
Characterisation before change
- Get the system running locally, however awkward. Document every step.
- Write tests that capture what it does now, including behaviour that looks wrong.
- Note the things that look like bugs, without fixing them yet.
- Get the current expert to confirm which of those are intentional.
- Only then start changing, with the tests as the safety net.
Steps one and two are genuine work and should be scoped as such. Presenting them as overhead before the real work starts is how they get cut.
Protect the one expert
| Approach | Effect |
|---|---|
| Route all questions to them | They become the bottleneck, nothing improves |
| Fixed short sessions, answers written down | Knowledge transfers, their week survives |
| Pair on the first changes | Fastest transfer, highest cost |
| Leave the newcomer to work it out | Slow, and produces wrong assumptions |
The second row is usually the best balance. Regular short sessions where answers are captured in writing means the same question is not asked twice.
Set expectations about pace
The first weeks on a legacy system produce understanding rather than visible progress. If that is not agreed in advance, it reads as poor performance and the engagement gets judged on the wrong thing.
Say it plainly at the start: the first phase is characterisation and documentation, and the deliverable is tests and written knowledge rather than features.
What you gain beyond the work
A legacy system with characterisation tests, a documented build and a second person who understands it is materially less risky than it was, regardless of what features were added.
That reduction in risk is worth naming as an outcome, because it is usually the larger part of the value and it does not appear in a feature list.