Topic: adr vs design decision record

ADR vs Design Decision Record: What's the Difference?

You've seen both acronyms. ADR is the common one; DDR comes up in enterprise and some FAANG-adjacent practices. They overlap, but the boundary is useful — and most of the "we need a new type of decision doc" proposals are just one or the other mislabeled.

TL;DR

ADR = Architecture Decision Record. Captures durable, cross-cutting architecture choices (stack, pattern, data model, deployment topology). Lives for the life of the system. DDR = Design Decision Record. Captures specific, local design calls (API shape, schema detail, interface contract, internal class structure). Lives for the life of that component. Rule of thumb: if a new team adopting the code base would need to understand it on day one, it's ADR; if only a developer touching that specific file would need it, it's DDR.

When to use which

Example decision	Use	Why
Postgres vs MongoDB for primary store	ADR	Affects every feature; survives a rewrite of individual services.
Monorepo vs multirepo	ADR	Structural, cross-cutting, expensive to reverse.
REST field names: `userId` vs `user_id`	DDR	Local to the API contract; matters inside that service boundary.
Event schema v2: add `idempotency_key`	DDR	Design-level change to one interface; doesn't reshape the system.
Move auth from Clerk to Auth0	ADR	Vendor swap with system-wide coupling; new hire will ask.
Cache TTL: 60s vs 300s for pricing API	DDR	Tunable parameter inside one subsystem.
Adopt OpenTelemetry across services	ADR	Cross-service, long-lived, hard to reverse.
Use `zod` for request validation in this service	DDR	Local lib choice in one service; other services may differ.

Format-wise, they're almost identical

Both use the Nygard 5-section template: Title, Status, Context, Decision, Consequences. The difference is scope and storage location, not format:

ADRs live in a repo-level doc/decisions/ folder. Anyone can read them; anyone on the team might propose one.
DDRs live alongside the code they describe — services/billing/doc/ddrs/, for example — and are co-owned with that service. Cross-service reviewers don't need to read them.

This keeps the ADR folder readable (new hires can skim 30 files and understand the system) and the DDR folders relevant (only the team in that service reads theirs).

Common mistakes

Writing a DDR when you mean ADR. "Which JSON field name" gets a DDR; but "We'll use snake_case for all APIs company-wide" is ADR-level — it's a standard, not a local call.
Writing an ADR when you mean RFC. ADRs record decisions already made; RFCs propose decisions for review. If the outcome is uncertain, you're writing an RFC.
Inventing a third acronym. We've seen teams invent TDR (technical decision record), PDR (platform decision record), CDR (component decision record). These are almost always DDRs with a local naming preference. Resist the acronym sprawl.

How WhyChose helps

WhyChose extracts both kinds from your AI chat history. The extractor tags each record with a scope field based on heuristics — cross-cutting keywords ("database", "framework", "monorepo", "auth provider") land as ADR-scoped; narrower keywords ("API response", "schema field", "cache TTL") land as DDR-scoped. You can filter by scope in the decision log and route ADRs to the repo root while DDRs stay with their services. Same extraction runs locally via the open-source CLI.

Get early access