Skip to main content

ADR Writing Workshop

Kata: Write an ADR for a real recent technology choice. Pick a decision made in the last 90 days that qualifies as architectural (see Concept 1). Produce a full ADR, not a stub.

Retrieval Prompts​

  1. State from memory the three required sections of an ADR and what fails when each is missing.
  2. Name the three templates covered in this module. For each, state the one thing it emphasizes.
  3. What is the difference between a two-way-door decision and a one-way-door decision? What does each change about how you write the ADR?
  4. What does "decisions without consequences" indicate about an ADR?
  5. When is in-place amendment appropriate, and when must you supersede instead?

Compare and Distinguish​

Separate these pairs clearly:

  • Context vs history. What goes in Context that does not belong in a timeline?
  • Consequences vs followups. Which stays in the ADR permanently? Which belongs in a tracker?
  • Rejected vs Superseded vs Deprecated. When is each the correct status?
  • Nygard vs MADR. What does MADR force the author to name that Nygard permits hiding?

Common Mistake Check​

Identify the error in each ADR excerpt:

  1. "Decision: We will improve system reliability." (no concrete decision named)
  2. "Context: The team met last Thursday and discussed caching." (history, not context)
  3. "Consequences: Improved performance. Better maintainability. Cleaner code." (all positive; no negative or risk)
  4. "Status: Accepted. Updated 2026-01-02 to reflect new database choice." (in-place override of an Accepted ADR; should supersede)
  5. "Alternatives considered: None." (on a decision with clearly available alternatives - red flag)

Mini Application​

Write a full ADR for each of the following, using the stated template. Each should take ~30 minutes.

  1. Nygard. A recent decision your team made about a third-party service (auth, payments, analytics).
  2. MADR. A decision with 3+ live alternatives - e.g., an internal framework, an ORM, a queue system.
  3. Y-statement. A one-sentence Y-statement summarizing one of the above.

Self-checks for each ADR:

  • Context: names at least two constraints, at least two alternatives, and why those alternatives were not chosen
  • Decision: one or two declarative sentences; no passive voice
  • Consequences: at least one positive, one negative, one risk; labeled one-way or two-way
  • Status: present and correct
  • Template: named at the top ("Nygard" / "MADR" / "Y-statement")

Critique and Rewrite​

Pick one ADR from a public repository (the Joel Parker Henderson corpus or any team ADR repo on GitHub). For that ADR:

  • score each of Context, Decision, Consequences on 1-3 (weak / present / load-bearing)
  • identify one sentence that should be added, removed, or rewritten
  • rewrite the Consequences section with at least one negative and one risk you can infer

Evidence Check​

This page is complete only when you can:

  • produce a full Nygard ADR in under 30 minutes for any decision you have recently lived through
  • produce a full MADR ADR in under 45 minutes for a decision with 3+ live alternatives
  • write a Y-statement without losing the tradeoff
  • critique an ADR for missing consequences or in-place amendment abuse
  • defend the template you picked in one sentence

Integrated ADR Packet​

Write three ADRs for the restaurant-management case:

  1. starting architecture style
  2. boundary between reservation/table assignment and order/kitchen workflows
  3. synchronous API versus event publication for kitchen status updates

Each ADR must include:

  • context
  • decision
  • alternatives considered
  • positive consequences
  • negative consequences
  • risks and follow-up decisions

Review packet addition: include a one-page risk list and a decision log showing which ADRs may need revisiting after load, team size, or reporting requirements change.