bahadirkisbet ADR — Architecture Decision Records
A significant decision that isn't written down gets re-litigated, half-remembered, or silently reversed. An ADR is a short, immutable record of one decision: what was decided, why, what was rejected, and what it costs. Cheap to write; priceless six months later when someone asks "why is it like this?"
Announce at start: "Recording this as an ADR." / "Searching existing ADRs first."
When to Use
- A decision that is expensive to reverse: a framework, a data model, a service boundary, a protocol, a build-vs-buy.
- A decision people will ask "why?" about later.
- Before re-deciding something — search existing ADRs first; the question may already be answered (and rejected for a reason).
- Not for: reversible, local, or obvious choices.
- Not for deliberating a decision still in flight — that is
bardak:less-is-more. Reach for an ADR once the choice is settled and worth recording.
Search First
Before writing a new ADR, look through the existing ones (default location: docs/adr/). If the decision was already made, read it — don't silently contradict or duplicate it. If you are reversing a past ADR, the new one supersedes it explicitly (reference its number).
Write the ADR
One file per decision: docs/adr/NNNN-short-title.md (zero-padded sequential number). Keep it short — a screen, not an essay.
# NNNN. <short decision title>
- Status: proposed | accepted | superseded by ADR-XXXX
- Date: YYYY-MM-DD
## Context
What forces are at play — the problem, constraints, and assumptions that make this a real decision. Pull from project business context where relevant.
## Decision
What we are doing. State it as a fact: "We will …"
## Options Considered
- Option A — what it is, why chosen/rejected.
- Option B — …
## Consequences
What becomes easier, what becomes harder, what we now have to live with. The costs, not just the wins.
Rules
- Immutable. An accepted ADR is not edited to change the decision. To change course, write a NEW ADR that supersedes it and flip the old one's status to "superseded by ADR-XXXX."
- Numbered sequentially, never reused.
- Honest consequences — record the costs and the things that got harder, not only the upside. A consequences section with only wins is a sales pitch, not a record.
Common Mistakes
- Editing an old ADR to reverse it instead of superseding it — destroys the history of why.
- Writing ADRs for trivial or reversible choices — noise that buries the real ones.
- Skipping the search and re-deciding something already settled.
- A consequences section that lists only benefits.
- Novel-length ADRs nobody will read — keep it to one screen.
Pairs with: bardak:less-is-more — its path analysis and .claude/business-context.md feed this ADR's Context and Options sections.