ADR and SDD: documents that don't gather dust

Engineers have a well-known attitude to documentation: it gets written to be handed over, and never opened to do the work. Still, two practices have become real working tools for me in the last couple of years, and both are about documents.

First: ADR, a short architecture decision record. One page: context, options, what we chose and why, what the consequences are. Not a report for management, but a note for your future self and your colleagues. A year later, when someone asks why there is Kafka here instead of a database queue, the answer takes a minute, not a week of digging.

Second: SDD, spec-driven development. First we describe, briefly and explicitly, what must be built: interfaces, constraints, acceptance criteria. Then we write code. With the arrival of agents this stopped being bureaucracy and became a necessity: an agent writes code exactly as well as the task is stated. A garbage spec produces garbage code, just faster and in larger volumes.

A funny thing I noticed: teams that used to sabotage any documentation now write specs on their own. Because it is the only way to get a predictable result from a machine.

The takeaway is simple. A document is worth having when it is cheaper than the consequences of not having it. ADRs and short specs pass that test.

All posts