Write the Decision Record Before the Code

A pattern where, before implementing a significant choice, you have Claude draft a short Architecture Decision Record — the context, the decision, the alternatives rejected, and the consequences — so the reasoning is written down and durable.

Decisions made only in a chat window evaporate. Six months later no one remembers why the queue is an outbox and not a hosted service, so someone 'fixes' it and reintroduces the problem it solved. An ADR captures the why at the moment you have the most context. Claude is well suited to turning a design discussion into this crisp, standard format.

Choices future maintainers will question — anything load-bearing, anything that looks odd without its history, anything a teammate might undo. Especially valuable on teams and in open source.

Trivial or easily reversible decisions. An ADR per function is bureaucracy; reserve them for the handful of choices that shape the system.

We've decided <decision> for <system>. Write a short Architecture Decision Record with these headings: Context (the forces at play), Decision (what we chose, stated plainly), Alternatives considered (2–3, with why each was rejected), Consequences (what this makes easy, what it makes harder, what we're now committed to). Keep it under a page. Be honest about the downsides we're accepting.

After choosing the outbox pattern, Claude drafts an ADR whose Consequences section notes 'ordering is not guaranteed across aggregates'. A year later, when someone assumes strict ordering, the ADR is right there in the repo explaining that the assumption was never true.

Keep ADRs as numbered files in the repo and, when a later decision reverses an earlier one, have Claude write a new ADR that supersedes the old one by number rather than editing history. The chain of superseded records becomes a readable story of how the architecture evolved.

• Writing the ADR after the code, as an afterthought — it then rationalises the decision instead of informing it.
• Omitting the rejected alternatives, which are the most valuable part: they stop people re-litigating settled questions.
• Letting the Consequences section list only benefits; an ADR that admits no downside isn't recording a real trade-off.