Ask a team for their requirements documentation and you get a link. Ask when it was last accurate and the room goes quiet. Someone wrote it, it was right at the time, and then the code kept moving. A hotfix. A workaround shipped the night before a demo. A “we’ll write this up later” that nobody came back to. The document didn’t move at all. It still describes the system as of eighteen months ago, and people are still planning against it.
Documentation is a snapshot. Code isn’t.
Every description of your system gets written once: the ticket, the spec, the wiki page, the architecture diagram someone made for a board deck. The code they describe changes daily. The only thing holding the two together is a person remembering to go back and update the doc, and that loses to a deadline. We have never once seen it win.
What makes the drift hard to catch is that no single gap looks like a problem. A retry count that went from five to three during an incident and never made it back into the spec. A flag nobody documented. A module the team knows not to deploy on a Friday, which is knowledge that exists only as a habit. None of that is worth raising a ticket for on its own. A year later you have a description of your system that is wrong in a hundred small places and confident about every one of them.
How do you know your requirements match what the code does? We put this to engineering leaders fairly often and have yet to get a satisfying answer. Usually you find out when something breaks, or when a new hire trusts the doc and builds against a system that disagrees with it.
What the gap costs
A wrong description of the system isn’t really a documentation problem. It becomes a decision problem, because decisions get made on it.
- Estimates anchor to the wrong system. You scope the change against the diagram, then find out in week two that the real code has three dependencies the diagram never had.
- Onboarding turns into archaeology. A new engineer reads the wiki, then spends a month working out where it lies. The fastest route to the truth is interrupting whoever already knows it.
- Nobody can reconstruct intent. Someone asks why a change was made. The answer is in a Slack thread from March, if it is anywhere. The requirement that justified it was never linked to the code that implemented it.
- Old findings become noise. Last quarter’s scan lists two hundred issues against a codebase that has moved on since. Which ones are still real? Nobody has gone back through them.
So we built ADIS on the opposite premise
Stop asking people to maintain a second, parallel description of the system by hand. Derive the description from the one artifact that cannot be wrong about itself, which is the code that is actually running.
Requirements synthesized from the codebase describe what the system does rather than what someone intended it to do two years ago. Each one carries a link to the specific files and tests that satisfy it, so the description and the implementation can’t quietly disagree. Debt and security findings point at real lines in the current code rather than at a snapshot that started decaying the day it was taken.
Synthesized from what is there, so they describe the system you have rather than the one that was planned.
Each one points at the files and tests that satisfy it. The link is what stops the two drifting apart.
Debt and security issues are anchored to the codebase as it stands, not to a report from three months ago.
A model of the real system to interrogate on day one, instead of two weeks spent learning which docs to distrust.
“Code can outrun its documentation. It can’t outrun itself.”
None of this makes documentation pointless. Design docs, decision records, the reasoning behind a trade-off you argued about for a week: write those down, they earn their keep. What we would stop doing is asking a person to hand-maintain a copy of what the code already says. That copy drifts. It always has, on every team we have worked with, including ours.