Decision Logs and ADRs: The Memory of a Project

The decision a project makes today gets forgotten by the people who made it within 6 months. The team that joins in a year has no idea why the design looks the way it does. ADRs and decision logs are the artifacts that stop this memory loss. This chapter shows the template for both and the discipline that keeps them useful.

When does decision documentation pay back?

Three signals.

Project longer than 6 months. Below that, memory carries the context. Above it, the team has rotated, sponsors have changed, and "why did we do this" loses its origin.

Architecture choices with reversible-but-costly options. Database, API style, auth approach. The kind of choices the System Design series covers. Each is an ADR.

Multiple teams will inherit the system. Onboarding a new team is much faster with a folder of ADRs than with "ask Bob, he was there".

If the project is small, short, and you'll own it forever, documentation is overhead. Most production projects are not.

What is the cost of skipping decision documentation?

Three failure modes.

Endless relitigation. Every new engineer questions the architecture. The team spends hours re-explaining; some choices get reversed and re-reversed.

Cargo-cult engineering. New work copies old patterns without understanding why. The original choice was for reason X; the copy applies it where reason X doesn't hold.

Lost context at handover. Team A built the system; Team B inherits it; the decisions that made sense at the time look arbitrary now. Team B rewrites because they cannot tell what was deliberate vs accidental.

What is the minimal ADR template?

# ADR-001: Use Postgres for primary data store

Date: 2026-06-19
Status: Accepted
Deciders: Tech Lead, EM, Sponsor

## Context

We need a primary data store for the new billing service. The
service writes 100-500 transactions/sec and reads 5-10x that.
Data is relational (orders, line items, payments). Team is
familiar with Postgres; alternatives considered include MongoDB,
DynamoDB.

## Decision

We will use PostgreSQL 16 hosted on Azure Database for
PostgreSQL Flexible Server, with one read replica.

## Consequences

### Positive
- Team familiarity reduces onboarding time
- Strong consistency by default; transactions are simple
- EF Core support is mature
- Read replica handles dashboard queries

### Negative
- Single-region by default; multi-region needs work later
- Vertical scaling ceiling at ~5K writes/sec; will need
  partitioning if volume grows 10x

## Alternatives considered

- **DynamoDB**: rejected - team unfamiliar, eventual consistency
  complicates billing logic
- **MongoDB**: rejected - flexible schema not needed; relational
  model fits domain

## Revisit conditions

If write QPS approaches 3K/sec, evaluate sharding via Citus or
moving to a different store. Track via
[observability metrics](/system-design/observability-otel-dotnet).

Three details. The status (Accepted, Superseded, Deprecated) lets you see if the decision still holds. The "revisit conditions" is a built-in trigger to revisit; without it, ADRs go stale silently. Numbered sequentially in a folder (docs/adr/).

What does the lighter decision log look like?

For non-architecture decisions, a single markdown file per project:

# Decision Log — {{ Project Name }}

## 2026-06-19: Use Mailgun for transactional email
Decided by: PM + TL. Context: needed reliable email delivery
for refund notifications. Considered SendGrid, Postmark.
Picked Mailgun for existing account and lower volume tier.
Rationale: cheaper at our volume; team already has dashboard
access.

## 2026-06-15: Defer subscription billing to Q4
Decided by: Sponsor. Context: scope creep on initial release.
Scope-tradeoff framework applied; subscription moved from Must
to Won't this quarter.

## 2026-06-10: Outsource customer-support runbook to vendor
Decided by: PM. Context: in-house writer at capacity. Vendor
chosen: AcmeWriting based on prior project. Cost: $5K. Owner:
PM signs off final.

The lighter format catches process and procurement decisions that ADRs don't cover. Both formats coexist - ADRs in the repo for engineers, decision log in the project wiki for everyone.

How does decision documentation scale to multi-team?

flowchart TB
    OrgADRs[Org-level ADRs<br/>cross-team standards] --> TeamADRs[Team ADRs<br/>local choices]
    TeamADRs --> Project[Project decision log<br/>operational choices]
    OrgADRs -.referenced by.-> Project
    Project --> Onboarding[New hire reads on day 2]

Org-level ADRs cover the choices everyone follows ('we use PostgreSQL by default'); team-level ADRs cover the choices the team makes within those defaults; project decision logs cover the operational calls. New engineers read all three on the onboarding plan from chapter 16 day 2. The scope chapter and stakeholder chapter feed content into both formats.

What failure modes does this introduce?

• ADR theatre. Every PR comes with an ADR; the folder has 500 entries; nobody reads. Mitigation: ADRs are for non-obvious, expensive-to-reverse choices. Most decisions don't need them.
• ADR superseded silently. A new ADR contradicts an old one without marking the old one Superseded. Mitigation: when writing a new ADR that changes course, update the old one's status and link forward.
• Decision log without decisions. Log lists everything that happened; no rationale. Mitigation: each entry needs the "why" sentence; if you cannot articulate it, the entry doesn't belong.
• No revisit triggers. ADR documents past decision but doesn't say when to revisit. Mitigation: every architecture ADR has a revisit condition (volume, time, dependency).

When is full ADR overkill?

Two cases.

Solo engineer, small scope. You're the only one who will ever read it. A short README explaining "I picked X because Y" is enough.

Quick experiment / spike. Two-week throwaway code doesn't need ADRs. Document the result of the spike; the scaffolding disappears.

The discipline earns its overhead at team size 3+ and project duration 3+ months.

Where should you go from here?

You have completed the artifact group. The next four chapters are case studies that put every artifact you've learned into real project shapes. Start with rescue a failing project - the playbook for the hardest situation a tech lead can inherit.