2 posts tagged with "documentation"

Most of your team's real decisions don't happen in a doc. They happen in Slack. Two engineers are debating a bug, a third jumps in, someone says "ok let's go with option 1," and that's it. The decision is made. Then the thread scrolls away and the reasoning goes with it.

A few weeks later someone asks "wait, why does this work this way?" and nobody can find the answer. It's in Slack somewhere. Good luck.

An architecture decision record (ADR) is a short document that captures one significant decision: what you decided, why, what you considered, and what it costs you later. One decision per file. Plain text, in the repo, next to the code it governs.

That's the whole idea. The reason ADRs are having a comeback in 2026 isn't nostalgia. It's that AI coding agents now write a lot of your code, and an agent that can't see why something was built a certain way will happily refactor the reason away.