arch-adr

One-line summary

A short, structured document capturing one architectural decision: what was decided, why, what alternatives were rejected, and what consequences follow. Written at the moment of decision, lives in the repo forever.

When to use this skill

• Any architectural choice that future maintainers will second-guess if they don't know the reasoning. Examples: picking a database, picking a messaging system, choosing hexagonal vs layered, picking microservices over monolith.
• A decision whose alternatives were genuinely considered and rejected — capturing why is most valuable.
• Onboarding: new joiners can read the ADR set to understand how the architecture got to its current state.

When NOT to use this skill

• Tactical code-level decisions (using data class vs class, file organization) — these are too granular; the cost-of-writing exceeds the benefit.
• Decisions that have no real alternatives (Java vs Python on a Python-only team is not a decision).
• After-the-fact "let me write an ADR for this decision we made two years ago and don't remember the reasoning for" — the value is in the timestamp; back-dating is worth less.

Core content

Standard ADR structure (Michael Nygard's original template):

• Title. A short noun phrase. "Use PostgreSQL as the primary store" or "Adopt hexagonal architecture for the order service".
• Status. proposed / accepted / deprecated / superseded by ADR-NNN.
• Context. What's the situation, the forces, the constraints? Why is this decision needed now?
• Decision. What did we decide. Stated as a positive assertion ("We will…"), not as discussion ("We're thinking about…").
• Consequences. What follows from this decision — good and bad. Forces it commits us to. New problems it creates.
• (Optional) Alternatives considered. What else was on the table; why each was rejected.

File layout.

docs/adr/
├── 0001-use-postgresql.md
├── 0002-adopt-hexagonal-architecture.md
├── 0003-event-bus-via-rabbitmq.md
├── 0004-replace-rabbitmq-with-kafka.md  (supersedes 0003)
└── README.md      ← index of ADRs

Numbering is sequential and never reused. When an ADR is replaced, the new ADR references the old one and the old one's status becomes superseded by ADR-NNN. The old ADR stays in the tree — the history is the point.

Length. A single page. If an ADR is two pages, it's probably making two decisions and should be split.

Tooling. adr-tools (shell), adr-manager, MADR template, Log4brains — all generate / index ADRs. Useful at scale; markdown by hand works fine for small teams.

Living document vs decision log. ADRs are decision logs — immutable once accepted. The "living document" is something else (the README, the architecture diagram). Don't update an ADR's decision text; supersede it with a new ADR.

Decision heuristics

• Write the ADR before implementing the decision. Forces clarity.
• Write the ADR even if the decision feels obvious — "obvious" often means "I'm not thinking carefully about it".
• Keep alternatives short but specific. "We considered Kafka but rejected it because we don't have streaming use cases yet."
• Numbers are sequential and immutable. Don't re-number. Don't reuse a deleted number.
• ADRs live in the repo, not a wiki. They're versioned, reviewed, and travel with the code.

Anti-patterns

• Architecture wiki page. Drifts immediately. Doesn't survive team turnover. Reviewers don't read it.
• ADRs written after the fact, for decisions nobody remembers. Time-stamps matter. Backfilling has limited value.
• ADRs that hide the alternatives section. Most of the value is in why we rejected X. Without it, the ADR is just a declaration.
• Updating an old ADR's decision text. Breaks the historical record. Supersede instead.
• Hundreds of ADRs for tactical decisions. ADRs are architectural; not every file-organization choice deserves one. Keep the bar high enough that the set stays readable.

See also

• arch-fitness-functions — fitness functions enforce what; ADRs document why. Pair them.
• All other arch-* skills — most architectural decisions deserve an ADR.

References

• Michael Nygard, "Documenting Architecture Decisions" (2011 essay) — original ADR articulation.
• MADR template — modern markdown ADR template.
• adr-tools — Joel Parker Henderson's shell tool.
• Richards & Ford, Fundamentals of Software Architecture, Ch. 19 (Architecture Decisions).