CW-301f · Module 1

Architecture Decision Records

3 min read

An Architecture Decision Record (ADR) captures why a technical decision was made — not just what was decided. Six months later, when someone asks "why did we use PostgreSQL instead of MongoDB?" the ADR answers the question without requiring the original architect to be in the room. Claude can draft ADRs from meeting notes, Slack conversations, or verbal descriptions of the decision context.

The ADR prompt: "Draft an Architecture Decision Record from this context: [paste meeting notes or decision description]. Use this structure: Title (ADR-NNN: short decision name), Status (proposed/accepted/deprecated), Context (the problem or requirement that triggered the decision), Decision (what we decided), Alternatives Considered (what we rejected and why), Consequences (positive and negative implications of the decision)." The Alternatives Considered section is the most valuable — it prevents future engineers from revisiting options that were already evaluated and rejected.

Do This

  • Write ADRs at decision time, not retroactively — context fades fast
  • Include rejected alternatives with the reason for rejection — this prevents re-evaluation
  • Link ADRs to each other when decisions are related — "see ADR-012 for the authentication decision"

Avoid This

  • Document only the decision without the context — "we chose PostgreSQL" without "because our team has 5 years of PostgreSQL experience and zero MongoDB experience"
  • Write ADRs as justifications after the fact — they should capture the real decision process, including uncertainty
  • Skip the consequences section — every decision has tradeoffs, and documenting them builds trust