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):