Most architecture handoffs we see go like this: a deck with diagrams, a Notion page with bullet points, and a meeting where someone explains the “why” out loud. Three months later, the team is rebuilding half of it because nobody remembers why a key decision was made.
This is what Architecture Decision Records — ADRs — exist to prevent.
What an ADR actually is
An ADR is a short document, usually one page, that captures a single architectural decision. The format varies, but the useful version always includes four parts:
- Context. What problem are we solving? What constraints are real?
- Decision. What did we decide?
- Consequences. What does this commit us to? What did we give up?
- Status. Proposed, accepted, deprecated, superseded by ADR-XXX.
That’s it. The whole document is rarely longer than a page. The discipline isn’t in the format — it’s in writing it down before everyone forgets the trade-offs.
Why consultancies skip them
Three reasons, in roughly this order:
They take time to write. A real ADR — one that captures the actual reasoning, not a sanitized version — takes 30-60 minutes per decision. On a 12-week engagement with 8-12 meaningful decisions, that’s a day of work. Most consultancies don’t include that day in their estimates.
They make the consultant replaceable. This is the uncomfortable one. A well-documented architecture is one a different team can pick up and extend. If your competitive advantage is being the only person who knows why things work the way they do, ADRs threaten that.
They show your reasoning. Some decisions look obvious in hindsight but were uncertain at the time. ADRs preserve that uncertainty — the alternatives considered, the trade-offs accepted. That transparency makes some consultancies uncomfortable.
What it costs the client
A client who doesn’t get ADRs from their architecture engagement is buying a system they can run but not evolve. Three to six months in, when the team faces its first real fork — a new integration, a scale problem, a regulatory change — they’re flying blind on every decision the original architect made.
What ends up happening:
- Someone “discovers” why a decision was made by breaking something.
- The team starts over on parts of the architecture because they can’t verify whether the original logic still holds.
- A second consultancy is hired to re-document what the first one delivered.
Each of these is expensive. None of them appear on the line item of the original engagement.
How we use ADRs at Kor-E
Every architecture engagement we run ships with an ADR log. The format is the four-part one above. We write them as we go — usually in the same session where the decision is made, while the reasoning is still fresh.
We commit them to the client’s repo, not ours. They belong to the client. We’ve had engagements where the client’s next engineer arrived six months after we left and built a feature correctly on the first attempt because they read the ADR for the decision they were extending.
That’s the whole point.