Question and context
This question tests whether you can turn an important technical trade-off into searchable, reviewable, and evolvable team memory. Cover when an ADR is warranted, how to record rejected options, how the record supports code review and troubleshooting, and how to handle a decision that is superseded by a new one.
It fits backend, platform, SRE, staff engineer, and cross-functional roles. Assume the team has a repository and review process but no shared decision-record convention; the choice may involve reliability, security, interfaces, dependencies, or an irreversible cost trade-off.
What the interviewer is evaluating
First, can you identify an architecturally significant decision instead of documenting every implementation detail? Second, can you explain the choice with neutral context, constraints, options, and consequences? Third, can you place the ADR in a proposed, reviewed, accepted, and superseded lifecycle? Fourth, can you make the record useful in code review, onboarding, and incident response?
Clarifying questions to ask
- Does the decision affect system structure, key quality attributes, a public interface, or only local implementation?
- What hard constraints apply: latency, availability, compliance, skills, migration window, or cost?
- Is the option already deployed, or is the ADR still Proposed? Who can accept or reject it?
- Will ADRs live in the repository, a documentation system, or both? How will affected teams find updates?
- What signals would trigger reevaluation: traffic, failure rate, cost, or regulatory change?
A 30-second answer framework
“I first check whether the choice changes system structure, key quality attributes, or a hard-to-reverse interface. If so, I create a concise ADR. It records context, constraints, options considered, rejected alternatives, the decision, trade-offs, risks, and status, then affected teams review it while Proposed. After acceptance I treat it as immutable history; when requirements change, I create a superseding ADR, link the old record, and update the index. I keep the record in an accessible versioned repository and reference it in design reviews, code reviews, onboarding, and troubleshooting.”
Step-by-step answer
Step 1: Set the recording threshold
Create an ADR when a choice affects system structure, key quality attributes, public interfaces, important dependencies, or hard-to-reverse cost. Naming, a one-off refactor detail, or a choice already governed by a clear standard usually does not need its own record. The threshold preserves decisions that will change future reasoning without creating documentation noise.
Step 2: Describe the problem neutrally
State the problem, user or business impact, functional and non-functional requirements, deadline, and non-negotiable constraints. Do not smuggle a preferred option into the context or replace facts with “team X insisted.” A new contributor should understand why a decision is required now.
Step 3: Compare options and trade-offs
List the options actually considered, including rejected choices and why they were rejected. Compare latency, availability, blast radius, security, migration cost, operational load, and team capability; where values are uncertain, state assumptions and confidence. Keep the ADR focused on the decision and link detailed spikes or designs separately.
Step 4: State the decision and consequences
Write a decision that stands alone, such as “We will use a regional queue and accept manual approval for cross-region failover.” Then record expected benefits, costs, risks, required controls, and affected components. “Choose option A” is not enough because future reviewers cannot see the reason or the price paid.
Step 5: Set status, ownership, and review
Use states such as Proposed, Accepted, Rejected, Deprecated, and Superseded. Assign an owner and invite affected teams to read and comment while Proposed; on acceptance add date, stakeholders, and version. Review verifies that facts, constraints, options, and consequences are clear, not that everyone will agree forever.
Step 6: Put the ADR in the engineering workflow
Version ADRs with the repository or documentation system and maintain a searchable index. When a design or code review finds a change that conflicts with an accepted decision, link the ADR and require an explicit change record. Onboarding, handoffs, and incident response should also use the ADR to answer “why this way,” reducing repeated debate.
Step 7: Add a new record when the decision changes
Keep an accepted or rejected ADR immutable. If new evidence, scale, cost, or regulation changes the conclusion, write a new ADR describing the new context, the old limitation, and the new trade-off. Once accepted, mark the old record Superseded and link both records. This preserves history while making the current decision easy to find.
Example of a strong answer
“I first check whether this affects system structure, key quality attributes, an interface, or an irreversible cost; if it is only local implementation, I would not add an ADR. Once it meets the threshold, I write a Proposed record with the problem context, user and non-functional requirements, constraints, options, rejected alternatives, decision, trade-offs, risks, and confidence.
I invite affected teams to read before a review discussion, and record status, owner, date, and stakeholders. After acceptance, I keep the ADR in a searchable versioned repository and reference it in design reviews, code reviews, onboarding, and troubleshooting. It stays concise and factual rather than replacing a full design document.
If requirements or evidence change, I do not edit the accepted record. I create a new ADR explaining why the old decision no longer fits, the new options, and their consequences. After acceptance I mark the old record Superseded and link the two, so the team sees the current choice without losing the reasoning history.”
Common mistakes
- Writing a full design guide → the decision is hard to find → keep context, options, decision, and consequences; link details.
- Recording only the winner → the debate repeats later → include rejected options and the constraints at the time.
- Replacing constraints with preference → the record cannot be reviewed → use neutral, observable facts and assumptions.
- Editing an accepted record in place → history disappears → add a new record and mark the old one Superseded.
- Omitting status and owner → nobody knows whether it applies → track lifecycle, owner, and acceptance date.
- Never citing the ADR → documentation has no operational value → connect it to design review, code review, onboarding, and incident response.
Follow-up questions and answers
Follow-up 1: Can a team accept an ADR while people disagree?
Yes. Record unresolved objections, risks, and who can accept the decision. Review makes the choice and its cost visible; it does not manufacture permanent consensus. If evidence is missing, keep the ADR Proposed and schedule a validation task.
Follow-up 2: When should you backfill an ADR?
Backfill when an existing structure, interface, or quality trade-off is important but nobody can explain it. Use commits, incident data, and maintainer interviews, and label the result as a retrospective record so inference is not presented as contemporaneous fact.
Follow-up 3: Repository or wiki?
Prefer the versioned repository near the affected code so the record is reviewed with implementation. If business or security stakeholders need broader access, mirror an index or summary while keeping one authoritative source to prevent drift.
Follow-up 4: How do you show ADR value?
Track time for new members to understand key choices, repeated debates, accepted-decision violations found in review, and how quickly incident responders find context. Metrics reveal gaps; document count is not the goal.