Writing Architecture Decision Records (ADRs) with AI
The decision nobody wrote down is the decision that gets silently reversed by someone who didn't know why it was made. A practical guide to ADRs, and how AI removes the excuse not to write them.
Six months after a decision, the code shows what was chosen but rarely why — and "why" is exactly what the next engineer needs before they change it. An Architecture Decision Record is a short, permanent document capturing one decision: the context that forced it, the options considered, and the reasoning for the one chosen. Teams that skip them don't avoid the decision-making work; they just repeat the debate every time someone forgets the outcome.
Why ADRs get skipped despite being cheap
A good ADR takes 20-30 minutes to write well — cheap compared to the hours lost re-litigating a decision, or worse, silently reversing one because nobody remembered the original constraint. They get skipped anyway because writing a clear, complete one from a blank page is friction most engineers avoid under deadline pressure. This is where AI genuinely helps: not by making the decision, but by removing the blank-page cost of documenting it.
The anatomy of a decision record that's actually useful later
| Section | What it must contain | What makes it useless later |
|---|---|---|
| Context | The forces at play — constraints, requirements, prior state — that made a decision necessary | Vague context ("we needed a caching solution") without the specific pressure ("read latency exceeded 200ms SLA under peak load") |
| Options considered | Every real alternative, including the ones rejected, and why | Only documenting the chosen option — the next reader can't tell if alternatives were even considered |
| Decision | The specific choice, stated unambiguously | Hedged language that doesn't commit to a clear decision |
| Consequences | What this decision makes harder, not just easier — every real decision has a trade-off | Only listing benefits — a one-sided ADR reads as marketing, not engineering reasoning |
Worked example
Context: We decided to use PostgreSQL with the outbox pattern instead of a message broker (Kafka/RabbitMQ) for reliable event publishing, because the team's current scale doesn't justify broker operational overhead, and we need transactional consistency between the domain write and the event.
Options we discussed: (1) direct message broker with no outbox — rejected, no transactional guarantee, (2) transactional outbox with Postgres — chosen, (3) dual-write with reconciliation job — rejected, added complexity without solving the consistency problem.
Task: Draft this as a full ADR using the standard Context / Decision / Options Considered / Consequences structure.
Constraints:
- State the decision in one unambiguous sentence at the top, before the detailed reasoning.
- For each rejected option, state the specific reason it was rejected, not just that it was considered.
- Consequences section must include at least one real cost of this decision (what does the outbox pattern make harder or slower), not only benefits.
- Keep it under 500 words — an ADR nobody reads is as useless as one that was never written.The value here is turning a decision already made in a conversation into a well-structured written record fast — not asking the model to make the architectural call itself. Feed it the actual discussion/reasoning; don't ask it to invent the trade-off analysis from scratch.
Where NFRs fit into this
Many architecture decisions are really responses to a non-functional requirement — latency, availability, compliance — that was never made explicit. A companion NFR deep-dive prompt (stating the specific numeric target: "p99 latency under 200ms at 500 req/s," not "needs to be fast") turns a vague constraint into something an ADR can actually reference and a design can be tested against.
The Documentation module pairs ADR generation with the requirements-mapping work from the Domain Discovery module — a decision record is only as good as the requirement it's actually responding to.