5 exercises — ADR status lifecycle, context sections, decision rationale, honest consequences, and managing historical ADRs. Capture the "why" behind technical decisions.
0 / 5 completed
ADR template sections
Title: ADR-NNN: [Short decision description] — e.g. "ADR-007: Use PostgreSQL for primary data store"
Status: Proposed → Accepted → Deprecated / Superseded by ADR-NNN
Context: What situation, constraints, and requirements force this decision?
Decision: What was decided and WHY — not just what
Alternatives considered: What else was evaluated and why rejected
Consequences: Both positive outcomes AND accepted trade-offs
1 / 5
A team starts writing ADRs. An ADR's Status field currently says "Proposed." What does this mean for the team?
ADR status values track the lifecycle of a decision. The most commonly used statuses are:
Proposed — written, shared, open for review and discussion Accepted — the team has agreed to this decision and will implement it Deprecated — this decision was once accepted but is no longer in effect Superseded by ADR-NNN — this decision was replaced by a newer one (link provided) Rejected — the proposal was discussed and not adopted
Why status matters: ADRs accumulate over time. Without clear status, a future engineer reading ADR-007 can't tell if it reflects current practice or a 3-year-old decision that was replaced. "Superseded by ADR-023" creates a navigable chain of reasoning.
ADR status vocabulary examples: "Status: Proposed" → "Status: Accepted (2026-04-07, agreed by backend team)" "Status: Superseded by ADR-023 (2026-03-15) — we moved from PostgreSQL to CockroachDB for global distribution" "Status: Deprecated — this pattern was abandoned when we moved to microservices"
2 / 5
An ADR's "Context" section reads: "We need to choose a database." A principal engineer rejects this as insufficient. What does a strong context section contain?
The ADR Context section answers: "Why was this decision even necessary? What situation forced us here?"
Weak context: "We need to choose a database."
Strong context: "Our current single-node PostgreSQL instance serves 3 read-heavy microservices. As of Q1 2026, peak read load exceeds the connection limit (500 connections). The services compete for connections, causing intermittent 503 errors. We need a solution that: • Handles at least 2,000 concurrent read connections • Requires no changes to the existing SQL query patterns • Can be deployed within the current infrastructure (AWS RDS or self-managed on EKS) • Fits within the team's existing Postgres expertise"
What context should establish: • The current state (what exists today) • The problem or constraint (why the current state is insufficient) • Specific requirements or constraints (non-negotiables) • Team context (skills, existing tools, budget) • Timing or urgency
ADR context vocabulary: "At the time of this decision, …" "The current approach has the following limitations: …" "The following constraints drive this decision: …" "We require a solution that: …"
3 / 5
An ADR's "Decision" section reads: "We will use PostgreSQL with read replicas." A tech lead says the decision statement is correct but incomplete. What is the most important thing to add?
The Decision section must state both what was decided AND why — otherwise the ADR is just a record of what was done, not a record of the reasoning.
Weak decision statement: "We will use PostgreSQL with read replicas."
Strong decision statement: "We will add 2 read replicas to our existing PostgreSQL instance. This approach was chosen because: • It requires no changes to existing SQL queries (unlike moving to a different database engine) • It is within the team's current operational expertise • It addresses the connection limit issue without a disruptive migration • Estimated cost increase: ~$340/month, within approved infrastructure budget The alternative (migrating to PgBouncer connection pooler) was rejected for now due to query compatibility unknowns (see ADR-Alternatives)."
Why the "why" matters: In 2 years, a new engineer will read this ADR and ask "but why not use connection pooling?" Without the reasoning, they will either repeat the analysis wastefully or make a change that undoes the original decision without understanding its context.
Decision vocabulary: "We will adopt X because: …" "We chose X over Y based on: …" "This decision is driven by: …" "We accept the trade-off of [X] in exchange for [Y]."
4 / 5
An ADR includes a "Consequences" section. An engineer asks: "This section says the decision creates both positive and negative consequences. Should we hide the negative ones?" What is the correct answer?
The Consequences section is what separates a genuine ADR from a post-hoc justification document.
What Consequences should list:
Positive consequences: "This eliminates connection limit errors immediately." "The team can implement this within 1 sprint using existing skills."
Negative consequences / trade-offs accepted: "Read replicas add replication lag — reads from replicas may return data up to 100ms old." "The team must now manage replica health monitoring and failover testing." "This is a temporary solution — at 10x current load, we will need to revisit sharding or a different database."
Why honesty is essential: • Future engineers who encounter the replication lag problem can look back and see: "yes, the team knew about this and accepted it" • It prevents the "but who decided this?" blame game • It enables smarter future decisions: "ADR-012 said this would need revisiting at 10x load — we're there now"
Consequences vocabulary: "The positive effect is: …" "The accepted trade-off is: …" "This introduces risk of: …" "Future teams should be aware that: …" "This decision will need to be revisited when: …"
5 / 5
A team has 47 ADRs. An engineer proposes deleting ADR-003 because "we don't use that technology anymore." The tech lead says this is wrong. What should be done instead?
ADRs are a historical record of decision-making, not a current state documentation system. Deleting or hiding decisions destroys the organisational memory that ADRs are designed to preserve.
Why "Superseded by ADR-031" is the right approach: • It preserves the original reasoning — future engineers can see what was decided AND what replaced it • It creates a chain of decisions — ADR-003 links to ADR-031 which may link to ADR-047 • It shows the evolution of thinking: "we tried approach A, it had problem X, so we moved to approach B" • It prevents re-litigating old decisions — "we already considered this in 2023"
The ADR amendment pattern: 1. Write a new ADR explaining what changed and why 2. Mark the old ADR as "Superseded by ADR-[new number]" 3. Add "Supersedes ADR-[old number]" to the new ADR 4. Add a brief note to the old ADR: "This approach was replaced in 2026 when [reason]."
What to preserve in a supersession note: "Status: Superseded by ADR-031 (2026-04-07). We replaced this approach because the chosen library was abandoned and we moved to [alternative]. See ADR-031 for the current decision."