Documenting a system nobody remembers building.
Including the newest kind of legacy code: what a coding agent wrote for you over several sessions that nobody has looked at as a whole.
The situation
A system exists, works, and is not understood. Classically that meant code inherited from people who left. Increasingly it means code produced across many agent sessions, each locally reasonable, with no one ever having reviewed the shape that resulted. Both produce the same position: you cannot safely change what you cannot describe.
Start with structure, not with reading
Reading legacy code linearly is the slowest way in, because the information you need is distributed across files and the parts that matter are not marked. Generating a diagram gives you the shape first, and then reading is targeted at the components that turned out to be central rather than at whatever file you opened first.
What it typically reveals
Two things, repeatedly. Duplicated responsibility, where the same job is done in two places by slightly different code, usually because two sessions solved the same problem independently. And a utility module that has quietly become the centre of the dependency graph, which is where every change becomes risky. Neither is visible in a file tree and both are obvious in a drawn graph.
Documentation that can be regenerated
The reason legacy systems are undocumented is not that nobody wrote documentation, it is that what was written stopped being true. Generating from code means the cost of refreshing is a command rather than an afternoon, which is the only version of this that survives contact with a busy team.
Getting oriented
Questions
Does this work on code an AI wrote?
Yes, and it is one of the most common uses. Agent-written code tends to be locally sensible and globally unshaped, which is exactly the failure a structural view exposes.
What about a system with no tests and no documentation?
That is the normal case here. The diagram becomes the first artifact describing the system, and it is worth reviewing with anyone who has touched it before trusting it.
Can it help decide what to refactor first?
It shows you the coupling, which is the input. Whether a given coupling is worth removing depends on change frequency and team boundaries, neither of which is in the code.
Related
- Architecture ReviewMost of the effort in an architecture review goes into producing the diagrams, and most of those diagrams describe the system as remembered rather than as built.
- System Design Interview PreparationThe diagram is the easy part. Interviews are decided by the tradeoffs you can defend when the interviewer pushes.
- Technical Design DocumentsThe diagram in a design doc usually gets drawn last, badly, because everyone is tired of the document by then.
- Migration PlanningMigrations fail on the intermediate states, which is exactly the part nobody draws.
Last updated