Decision Records

An Architecture Decision Record (ADR) captures the why and what we gave up behind a design decision — the parts code and docs cannot carry. This skill covers where records live, when to write one, and the in-file structure. It applies to any project that wants its rationale to outlive the change.

The defining constraint: an ADR records a decision — the alternatives it beat and the consequences it accepted — not a transcript of how the decision was reached. A decision without its rejected alternatives invites re-litigation.

Layout and lifecycle

Every record has two axes:

• Lifecycle — its status, which changes over time:
  • proposed — not yet built (or only partly); the plan and open questions live here.
  • accepted / implemented — the decision shipped; the file describes shipped reality in the present tense and is kept current with what actually shipped (facts — paths, names, structure — not the decision itself).
  • rejected — considered and declined; keep it only while its rationale prevents a tempting, meaningful mistake.
• Class — the kind of decision (feature, bug-fix, simplification, architecture, process, testing). Pick the class folder that matches.

A record moves between lifecycle folders as its status changes; the move updates the status line and the body's form in the same change.

When to write one