Skip to main content

> architectural_decision_records_(adrs)_&_rfc_engineering_culture

Architectural Decision Records (ADRs) & RFC Engineering Culture

Why are version-controlled Architecture Decision Records (ADRs) essential for preventing cyclic architectural churn and tribal knowledge silos?

Stack: LEADERSHIP INCIDENTS STACK →Staff (L6-L7)pattern

⚡THE SHORT ANSWER

ADRs capture the context, constraints, evaluated alternatives, and deliberate tradeoffs behind technical decisions right inside the codebase, preventing new engineers from blindly re-litigating settled debates or misunderstanding historical compromises.

Engineering Handbook & Failure Dynamics

6-Dimensional Architecture Breakdown

⚙️1. Underlying Mechanism

Execution

Pioneered by Michael Nygard, an Architectural Decision Record (ADR) is a lightweight markdown document stored in source control (docs/adr/0012-choose-kafka-over-sqs.md). Each ADR has a strict state machine (Draft -> Proposed -> Accepted -> Superseded/Rejected) and captures: Status, Context (business drivers and constraints), Decision (the chosen architectural direction), and Consequences (positive, negative, and neutral ramifications).

🎯2. Appropriate Use Context

Scope

Required whenever introducing new programming languages, primary databases, inter-service communication protocols, authentication frameworks, or foundational library abstractions.

⚠️3. Production Failure Modes

P0 Risk
  • ✓

    Teams repeatedly refactor back and forth between identical paradigms (e.g., monolith -> microservices -> monolith) every 18 months because the original constraints were never documented

  • ✓

    critical systems abandoned because nobody understands why an odd design choice was made

📡4. Diagnostic Signals & Telemetry

Telemetry

Engineers constantly asking in chat 'Why are we using library X instead of Y?', architectural decisions made during informal coffee chats, and PRs stalling over fundamental philosophical debates.

🛡️5. Prevention & Safeguards

Safeguards
  • ✓

    Embed ADR templates in repo scaffolding tools

  • ✓

    enforce a timeboxed 5-day RFC comment period with a designated Decider

  • ✓

    never approve PRs with major architectural impact without an accompanying ADR PR

⚖️6. Architectural Trade-offs

Trade-off

Introduces slight documentation overhead before writing code in exchange for permanent institutional memory, high alignment, and frictionless engineering onboarding.

📋

Case Study (TinyCTO In-Field Example)

REAL-WORLD TELEMETRY

TinyCTO Episode 18: A new lead attempted to replace a custom Redis lock with Postgres row locking, causing a catastrophic database lock storm. The original ADR clearly stated Postgres locks were rejected due to connection pool limits, which would have prevented the outage.

Interactive Concept Drills

3 Cards
Q1

What are the four essential sections of a standard Nygard ADR?

1. Title & Status, 2. Context, 3. Decision, 4. Consequences.
Q2

Why should ADRs be stored directly inside the code repository rather than in an external wiki?

Code repositories provide git history, branch reviews, PR discussion trails, and ensure documentation stays synchronized with the code it governs.
Q3

What does it mean when an ADR status is marked as 'Superseded'?

A newer ADR has replaced the previous architectural decision, linking forward to the new record while preserving the historical rationale.

Architectural Decision Records (ADRs) & RFC Engineering Culture — Technical FAQ

How long should an RFC discussion remain open before a final decision is made?

Standard practice is 5 to 7 business days. Without a strict timebox, RFCs devolve into bikeshedding and endless deliberation.

Who has the final authority to accept or reject an ADR?

The designated technical owner or Staff Engineer responsible for the domain, after considering all team feedback during the RFC period.

Should every small pull request require an ADR?

No. ADRs are reserved for significant, irreversible, or cross-cutting architectural choices. Routine bug fixes and standard feature extensions do not need ADRs.

🤖 AEO & Key Facts Summary

Key Architectural Facts

  • ▸

    Engineering organizations with active ADR practices reduce onboarding time for senior hires by up to 40% by making technical history transparent.

  • ▸

    An ADR is as much about documenting what was NOT chosen and why as it is about the chosen direction.

Common Misconceptions

  • ✗

    Thinking that an accepted ADR is permanent and can never be challenged or modified.

Decision & Governance Guidance

Store ADRs as markdown in the relevant git repository alongside source code and review them via standard PR workflows.

Authoritative Sources & Standards