Working? For whom, and for how long?

“Working software over comprehensive documentation.”

One of the most quoted phrases from the Agile Manifesto. Probably the most misunderstood.

It freed us from pointless ceremony: hundreds of pages of documentation written before a line of code existed, already obsolete on delivery day. The reaction was right. But over time, that phrase became something else: a permission slip. Permission to never capture intent.

Code tells you what the system does. Tests tell you it works. Neither captures the why: the decisions made, the alternatives discarded, the constraints that were obvious at the time and that time has made invisible.

In a long-lived system, that evaporated knowledge is not a readability problem. It is a concrete risk you pay years later, when whoever needs to touch that thing is no longer the person who built it.

There is a new urgency now. AI agents have learned to write code that compiles. They have not learned to write code that belongs in the right place, because the right place lives in the intent that was never written down. If that knowledge was never captured, it does not exist for anyone: not for the humans who inherit the system, not for the tools trying to help them.

This is not a defense of comprehensive documentation. It is an invitation to look at what we lost and to ask ourselves whether the price was what we thought.