A No-Bullshit ADR Framework for Teams That Actually Ship

TL;DR

Architecture Decision Records (ADRs): short markdown files in git. One per decision. Fixed template with context, decision, alternatives, consequences. Write when you decide. Stops rehashing, aligns everyone, speeds onboarding.

Why ADRs beat random notes or Slack threads

Decisions vanish in chats, tickets, or memory. ADRs live with code: versioned, searchable, permanent. No more "why the fuck did we choose this?"

Setup: folder and naming

• /docs/adr/ or root /adr/
• Files: 0001-use-postgresql.md, 0002-auth-with-jwt.md
• Zero-padded numbers for easy sorting.

Template (just copy this)

# ADR {NNNN}: Short clear title

**Status:** Proposed | Accepted | Deprecated | Superseded (by ADR XXXX)

**Date:** YYYY-MM-DD

**Deciders:** @github-names or roles

## Context

Problem, constraints, goals. What forces are at play?

## Decision

What we picked and one-sentence why.

## Alternatives considered

- Option 1: pros/cons, why rejected
- Option 2: same

## Consequences

- Good stuff: what improves
- Risks/down sides: what we live with or mitigate
- Next actions: if any

Real workflow

1. Need architecture choice → create draft ADR, status "Proposed".
2. Open PR for the ADR file.
3. Discuss async in PR comments (better than meetings).
4. Consensus → merge, change status to "Accepted".
5. Want to reverse? New ADR that supersedes the old one.

Keep it light

• Only for meaningful decisions (stack, patterns, trade-offs).
• Skip trivial crap (minor library bumps).
• Max 1 page. Longer = overthinking.
• Plain English, no buzzword soup.
• Link code changes to the ADR when possible.

Wins you'll see

• New hires: "Read the ADRs" actually works.
• Fewer surprise "let's switch again" debates.
• Clear rationale forever.
• Easy audit trail if regs ever knock.

How it dies

• Writing ADRs after the fact as paperwork.
• Walls of text nobody reads.
• Storing outside git.
• No numbering → find-nothing hell.

Start now

Make the folder, drop in 0000-template.md, write your first real ADR this week. Future you (and everyone else) will thank you.

References

• Documenting Architecture Decisions (Michael Nygard) - The original post that popularized the concept of lightweight decision records.
• Architecture Decision Records (adr.github.io) - A comprehensive collection of resources, templates, and tools for ADRs.
• Decision Log (Atlassian) - A team-focused playbook for tracking broader product and management decisions.