Architecture Decision Records for SA interviews

Why interviewers ask about ADRs

You are forty minutes into a system design round at Stripe or Linear. The interviewer has watched you sketch a queue, pick Postgres over DynamoDB, and reach for an event bus. Then they lean in and ask the question every senior systems analyst dreads: "Six months from now a new engineer joins and asks why you chose this. What do you hand them?"

The answer they want is Architecture Decision Records. ADRs are the standard way mature engineering orgs document non-trivial architectural decisions so future humans understand the context, the alternatives, and the trade-offs — not just the conclusion. The interviewer is not testing memorization; they are checking whether you treat architecture as a versioned conversation or as a verbal handshake that evaporates in six months.

Strong candidates can describe the Nygard template, name the five lifecycle states, and tell a concrete story of an ADR they wrote or reviewed. Weak candidates say "we documented things in Confluence" and pivot. The difference is roughly one tier on the levelling ladder.

What an ADR actually is

An Architecture Decision Record is a short, immutable markdown document that captures one significant architectural choice. One decision, one file, numbered sequentially: ADR-001-use-postgres-as-primary-store.md, ADR-002-adopt-cqrs-for-orders.md, and so on.

The point is not the document — the point is the discipline of writing down why. A year later, when someone asks "why are we not on DynamoDB?", the answer lives in ADR-001 with the original context, the rejected alternatives, and the consequences you signed up for. No tribal knowledge. No Slack archaeology.

Three properties make ADRs different from generic design docs. They are scoped to one decision (not a sprawling design), immutable once accepted (you write a new ADR to override, never edit history), and lightweight (200–800 words, not a 12-page RFC). That immutability is the part juniors usually miss on interviews.

The Michael Nygard template

The canonical template comes from Michael Nygard's 2011 essay. Most teams at Google, Spotify, ThoughtWorks, and Shopify use a variant of it. Here is the minimum viable shape:

# ADR-001: Use Postgres as the primary OLTP store

## Status
Accepted — 2026-04-12

## Context
We need an OLTP store for the new billing service. Expected load:
- 5k writes/sec peak, 20k reads/sec peak
- Strong consistency required for invoice state
- Team of 6, already operating two Postgres clusters
- Budget caps managed cloud spend at $4k/month

## Decision
We will use Postgres 16 on RDS as the primary store, with logical
replication into Snowflake for analytics.

## Consequences

### Positive
- Strong ACID guarantees match the invoice domain.
- Team already owns Postgres tooling and runbooks.
- Rich JSONB support covers the semi-structured metadata fields.
- Mature ecosystem (pgBouncer, pg_partman, logical replication).

### Negative
- Horizontal write scaling is non-trivial; we accept vertical scaling
  for the next 18 months.
- Higher operational overhead than DynamoDB on-demand.

## Alternatives considered

### DynamoDB
- Excellent horizontal scaling, predictable latency.
- Rejected: weak secondary index story for our access patterns,
  team has no operational experience, and transactional writes
  across items are expensive.

### MongoDB Atlas
- Flexible schema, decent transactions since 4.x.
- Rejected: weaker SQL story for finance reconciliation queries,
  and the team would carry two query languages.

Notice what is not in the template: implementation details, code samples, deployment diagrams, or sprint plans. Those belong in design docs and runbooks. An ADR answers "why" — everything else answers "how".

Status lifecycle

Every ADR moves through one of five states. Memorize this for the interview — interviewers love the lifecycle question because it separates people who have written ADRs from people who have read about them.

The immutability rule matters here. If the team later moves from Postgres to CockroachDB, you do not edit ADR-001. You write ADR-047: Migrate billing store from Postgres to CockroachDB, mark ADR-001 as Superseded by ADR-047, and leave the original context intact. The history is a chain, not a diff.

When to write one (and when not to)

The number-one mistake teams make with ADRs is writing too many. Bumping a library minor version is not an architectural decision. Picking a logging format probably is not either. Use this rough filter:

The heuristic from Spotify's engineering culture deck is useful: if reversing this decision in a year would cost more than two engineer-weeks, write an ADR. If reversing costs an afternoon, do not bother.

Who writes them depends on org shape. At product-led companies, the tech lead or staff engineer owns ADRs for their service. At platform-heavy orgs, an architect or principal drives cross-cutting ADRs. As a systems analyst, you write ADRs for cross-team interface decisions — API contracts, shared event schemas, integration patterns — where no single engineering team owns the choice end-to-end.

How to talk about ADRs in the loop

Interviewers rarely ask "define ADR" directly. The question shows up disguised. Watch for these openings and have a one-liner ready:

The first opening is "how do you document architectural decisions?". Do not say "Confluence". Say: "We use ADRs in the Nygard format, committed alongside the code in docs/adr/. Each significant decision gets a numbered markdown file with context, decision, alternatives, and consequences." That single sentence signals seniority.

The second opening is "tell me about a decision you reversed". This is the Superseded question. Pick a real one — a queue choice, a database, an auth model — and walk through ADR-N (original), what changed (new constraint, new scale, regulatory shift), and ADR-M (the reversal). The interviewer is testing whether you can hold both states in your head without rewriting history.

The third opening is "how do you keep documentation in sync with code?". Answer: ADRs are co-located with the code in git, reviewed in PRs, and immutable once merged. You do not keep them in sync — you append. Drift is impossible because the history is the document.

A good ADR story takes ninety seconds. Practice yours before the loop.

Common pitfalls

The first pitfall is editing an accepted ADR. Junior engineers see a typo or a stale claim and "fix" it in place. This breaks the entire model — the value of an ADR is that it freezes the team's thinking at decision time. The fix is to add a new ADR that supersedes the old one and links back. If you only need to correct a factual typo, add a dated note at the bottom; never rewrite the decision itself.

The second pitfall is writing ADRs for trivial choices. A repository with 400 ADRs, 380 of which document library bumps, is worse than no ADRs at all because the signal-to-noise ratio collapses. The fix is the two-engineer-week reversal heuristic above. Aim for 10–50 ADRs on a medium project, 100+ on a large platform, and treat anything beyond that as a smell.

The third pitfall is skipping the alternatives section. An ADR with only "Decision" and "Context" reads like a fait accompli — the reader cannot tell whether the team actually considered other options or just picked the first thing that came to mind. The fix is to document at least two rejected alternatives, with one sentence on why each was wrong for this context. Even bad alternatives in the doc are better than no alternatives.

The fourth pitfall is treating ADRs as approvals rather than records. Some teams gate every architectural change behind a multi-week ADR review board, which kills momentum. The fix is to treat the ADR as the output of the discussion, not the discussion itself. Decide in a 30-minute working session; write the ADR in the next hour; PR it for a 24-hour review window. Anything longer and the process eats the work.

The fifth pitfall is burying ADRs in Confluence. Once they live in a wiki, they rot — no PR review, no git history, no link from the code. The fix is docs/adr/ in the same repo as the service. If the org demands a wiki copy for non-engineering readers, automate the sync with a CI job, but make git the source of truth.

Related reading

• C4 model for systems analyst interviews
• CAP theorem for systems analyst interviews
• Case interview for systems analyst
• API contract testing for systems analysts

If you want to drill SA system design questions like this every day, NAILDD ships with hundreds of architecture and decision-rationale problems tuned to exactly this format.

FAQ

How long should an ADR be?

Between 200 and 800 words in the body, not counting code blocks. Shorter than 200 usually means context or alternatives are missing. Longer than 800 usually means you are mixing two decisions and should split into ADR-N and ADR-N+1. A senior reviewer will push back on either extreme, and an interviewer will read tightness as a proxy for clarity of thought.

Do I write ADRs as a systems analyst or is that the architect's job?

Both, but for different scopes. Engineering ADRs (datastore, framework, deployment topology) are typically owned by the tech lead or architect. Cross-team and integration ADRs — API contracts, shared event schemas, authentication boundaries between domains — are exactly where a systems analyst adds value, because nobody else holds the full picture. On the interview, lean into that distinction: it shows you understand where the SA role earns its keep.

Where do ADRs live — git, Confluence, or somewhere else?

Git, in the same repo as the code, under docs/adr/. This is the answer interviewers want. ADRs in Confluence drift because they are not part of the PR review surface. If compliance forces a wiki copy, automate the export from git and label the wiki version as read-only. The chain of custody is what makes ADRs trustworthy a year later.

What is the difference between an ADR and a design doc?

A design doc describes how a system will be built — components, sequence diagrams, deployment topology, API shapes. It is often 5–20 pages and lives for the duration of a project. An ADR captures why one specific choice inside that design was made and persists forever. A medium-sized design doc usually spawns three to seven ADRs. Conflating the two is the most common interview red flag — candidates who say "we wrote one big doc" signal they have never operated a decision log at scale.

Are ADRs only for greenfield projects?

No, and arguably they are more valuable on brownfield work. On a legacy system, the first batch of ADRs is usually retroactive — you sit with the original team, reconstruct the context, and write ADR-001 through ADR-010 to capture decisions already made. This is sometimes called "ADR archaeology" and it pays for itself the first time a new hire asks "why is this queue here". Interviewers at companies with large legacy estates (Microsoft, Oracle, big banks moving off mainframes) ask about this scenario specifically.

How do ADRs interact with regulated environments?

In regulated domains — payments, healthcare, anything with auditors — ADRs become part of the audit trail. The immutability rule that feels nerdy in a startup is mandatory in a SOC 2 or HIPAA shop because reviewers need to see the original risk reasoning, not a tidied-up retrospective. If your interview is at a fintech or healthtech, name-drop the audit angle: it signals you understand why the discipline exists beyond engineering hygiene.