Architecture Decision Records: Documenting Why You Built Things That Way

You inherit a codebase. The authentication uses a custom JWT implementation instead of a standard library. You ask: "Why was this built custom?" Nobody remembers. The developer who made the decision left. The commit messages say "implement auth" — not why custom was chosen over standard.

Now you face a choice: rewrite to use a standard library (risk breaking something the custom solution handled specifically) or keep the custom code (maintain something you do not understand). Both options are risky because you lack context.

Architecture Decision Records (ADRs) solve this. They document the WHY behind significant technical decisions — so future developers (including future you) have the context to make informed choices about changing or maintaining the system.

What an ADR Contains

An ADR is a short document (typically 1-2 pages) that captures:

Title: what decision was made. "Use Prisma ORM for database access" or "Implement custom rate limiting instead of using a third-party service."

Status: proposed, accepted, deprecated, or superseded.

Context: what situation prompted this decision? What constraints existed? What problem were we solving?

Decision: what we decided and why. The actual choice AND the reasoning.

Consequences: what follows from this decision? Trade-offs accepted. Risks acknowledged. Benefits expected.

Alternatives considered: what other options were evaluated and why they were rejected.

Why Context Matters More Than the Decision

The decision itself is visible in the code. If you chose Prisma: the code has Prisma imports. You can see WHAT was decided.

What you cannot see in the code: why Prisma was chosen over Drizzle or TypeORM, what constraints influenced the choice (team familiarity, performance requirements, type safety priority), what trade-offs were accepted (Prisma's abstraction over raw SQL performance), and under what circumstances the decision should be revisited.

This context is what gets lost. Six months later: the team composition changes, requirements evolve, and alternatives mature. Without the original context: you cannot evaluate whether the decision still makes sense.

When to Write an ADR

Write an ADR for decisions that: are difficult to reverse (database choice, ORM, framework), affect the entire system (architecture patterns, deployment model), have non-obvious trade-offs (reasonable people could disagree), or will be questioned by future team members ("why did they do it THIS way?").

Do NOT write ADRs for: trivial decisions (which ESLint rule to enable), easily reversible choices (variable naming in one file), or standard practices (using HTTPS — this does not need justification).

The rule of thumb: if you spent more than 30 minutes discussing or researching the decision, it deserves an ADR.

ADR Template

We use a simple template:

Title: [short descriptive name]

Date: [when the decision was made]

Status: [accepted/deprecated/superseded]

Context: [1-3 paragraphs explaining the situation, constraints, and problem]

Decision: [1-2 paragraphs explaining what was decided and the primary reasoning]

Alternatives Considered:

[Alternative 1]: [why rejected]

[Alternative 2]: [why rejected]

Consequences:

[Positive consequence 1]

[Positive consequence 2]

[Negative consequence / trade-off 1]

[Risk or concern]

Example ADR: Database Choice

Title: Use SQLite for local development and MySQL for production

Date: 2024-11-15

Status: Accepted

Context: Our application needs a relational database. The team is 3 developers working on macOS. We deploy to a serverless platform (Vercel). We need fast local development iteration. Production needs managed scaling and reliability.

Decision: Use SQLite locally (zero setup, instant startup, file-based simplicity) and MySQL via Planetscale in production (managed, serverless-compatible, branching workflow). Prisma ORM abstracts the dialect differences for standard operations.

Alternatives Considered:

Docker Postgres locally + Postgres in production: rejected because Docker adds setup friction for new team members and slows dev iteration (container startup time).

Planetscale for both: rejected because cloud database for local dev requires internet and adds latency to development queries.

SQLite everywhere: rejected because SQLite lacks features needed in production (concurrent writes, managed backups, horizontal scaling).

Consequences:

Positive: local development is instant (no Docker, no server process)

Positive: production has managed scaling and automatic backups

Negative: some SQL dialect differences between SQLite and MySQL may cause bugs caught only in staging

Risk: Prisma's abstraction may not cover edge cases where dialects differ

Mitigation: CI runs tests against both SQLite and MySQL

Where to Store ADRs

In the repository: a docs/decisions/ or docs/adr/ directory. Each ADR is a numbered markdown file: 001-use-prisma-orm.md, 002-sqlite-local-mysql-production.md.

Benefits of in-repo storage: version controlled (history of changes), searchable (grep finds relevant decisions), co-located with code (developers find them naturally), and part of code review (new ADRs reviewed alongside code changes).

ADR Lifecycle

New decision: write ADR with status "Accepted."

Decision revisited: if the context has changed and the decision no longer makes sense: write a new ADR that supersedes the old one. Update the old ADR's status to "Superseded by ADR-017."

Decision deprecated: if the system evolves away from the decision (migrating from Prisma to Drizzle): update the original ADR to "Deprecated" and reference the new ADR explaining the migration.

This lifecycle means: you can trace the evolution of architectural thinking over time. Why did we choose Prisma? (ADR-003). Why did we later switch to Drizzle? (ADR-017 references ADR-003).

Making ADRs Part of Your Process

ADRs only work if the team writes them consistently. Integration points:

PR reviews: if a PR introduces a significant architectural choice: "This needs an ADR. Can you add one explaining why you chose this approach?"

Sprint planning: when planning work that involves architectural decisions: allocate time for ADR writing as part of the task.

Onboarding: point new team members to the ADR directory. "Read these 10 decisions to understand why our system is structured this way."

The Lightweight Approach

ADRs should not be burdensome. A good ADR: takes 15-30 minutes to write, is 1-2 pages (not a thesis), captures the essential reasoning (not every detail), and is written immediately after the decision (while context is fresh).

If writing ADRs feels heavy: you are writing too much. Capture the minimum context that would help a future developer understand and evaluate the decision. Nothing more.

The Return on Investment

The cost: 15-30 minutes per significant decision.

The return: every time a future developer does NOT spend 2 hours wondering "why was this done this way?" — the ADR paid for itself. Every time a team avoids re-debating a settled decision because the ADR documents the reasoning — the ADR paid for itself. Every time a new team member onboards faster because they can read the architectural context — the ADR paid for itself.

ADRs are one of the highest-ROI documentation practices in software engineering. Write them.