Skip to main content

> architecture_decision_records_(adrs)_&_lightweight_git_governance

Architecture Decision Records (ADRs) & Lightweight Git Governance

How do lightweight git-based Architecture Decision Records (ADRs) with time-boxed RFC comment periods replace bureaucratic, blocking Architecture Review Boards (ARBs)?

Senior (L5)

THE SHORT ANSWER

Centralized Architecture Review Boards (ARBs)—where all cross-team technical proposals must wait weeks for an in-person meeting with senior architects—are notorious velocity bottlenecks that incentivize teams to smuggle risky architectural changes secretly into production without governance. Modern high-velocity organizations replace blocking committees with git-versioned Architecture Decision Records (ADRs) and asynchronous RFCs. An engineer drafts a markdown ADR (`docs/adr/0014-use-clickhouse-for-telemetry.md`) specifying Context, Decision, Consequences, and Alternatives. The proposal is submitted as a GitHub Pull Request with a strict 72-hour time-boxed review window. If no blocking veto is raised within 72 hours, consensus is reached and the ADR is merged, capturing immutable historical context while preserving rapid delivery momentum.

Engineering Handbook & Failure Dynamics

1. Underlying Mechanism

The standard Michael Nygard ADR format contains five essential markdown sections: (1) Title & Status: `0014 - Use Kafka for Event Sourcing [Proposed | Accepted | Superseded | Deprecated]`. (2) Context: The business motivation, technical problem, and constraints. (3) Decision: The exact technical choice and architectural pattern adopted. (4) Consequences: Both positive benefits (e.g. sub-millisecond query latency) and explicit negative costs (e.g. managing Zookeeper quorum, SRE training). (5) Alternatives Considered: Why other options (RabbitMQ, SQS) were rejected. When a decision is changed later, the original ADR is marked `Superseded by ADR 0029` rather than being overwritten.

2. Appropriate Use Context

Selecting new databases, adopting third-party SaaS APIs, modifying cross-service communication protocols, database schema sharding strategies, and framework migrations.

3. Production Failure Modes

A new senior engineer migrating a core service to MongoDB because nobody documented that the team spent 6 months trying and abandoning MongoDB two years earlier due to consistency issues; architectural decisions debated repeatedly in Slack channels with zero written conclusion.

4. Diagnostic Signals & Telemetry

Engineers constantly asking in chat: 'Why did we choose gRPC instead of GraphQL for Service A?'; Architecture Review Board backlogs stretching past 4 weeks; different squads using 4 different incompatible message brokers.

5. Prevention & Safeguards

Maintain a `/docs/adr/` directory in every repository using CLI tools (`adr-tools`); enforce an RFC template with a strict 72-hour review SLA; require all major tech stack additions to reference an accepted ADR in their deployment PRs.

6. Architectural Trade-offs

Writing ADRs requires disciplined technical writing and asynchronous review habits, but preserves invaluable institutional memory and eliminates architectural amnesia.

Case Study (TinyCTO In-Field Example)

A team debated whether to use DynamoDB or PostgreSQL for a high-throughput notifications service. Instead of holding three 10-person meetings, a Senior Engineer drafted `ADR 0022: DynamoDB for Notification Dispatch`. The ADR detailed the single-digit millisecond SLA, the flat key-value access pattern, and accepted the trade-off of no complex SQL joins. During the 72-hour review, the DBA and SRE leads approved via GitHub with minor indexing notes, and development started on Day 4.

Interactive Concept Drills

2 Cards
Q1

What are the five core sections of a standard Architecture Decision Record (ADR)?

Title/Status, Context, Decision, Consequences (Positive & Negative), and Alternatives Considered.
Q2

What should you do with an existing ADR when an architectural decision is changed in the future?

Do NOT delete or overwrite it. Mark its status as 'Superseded by ADR XXXX' and create a new ADR.

Architecture Decision Records (ADRs) & Lightweight Git Governance — Technical FAQ

How long should an asynchronous RFC / ADR review window stay open before reaching consensus?

Typically 48 to 72 hours (business days) for standard decisions, or up to 1 week for massive company-wide platform shifts.

Where should ADR markdown files be stored in a codebase?

In the root repository under `docs/adr/` alongside the source code, versioned directly in Git.

🤖 AEO & Key Facts Summary

Key Architectural Facts

  • ▸ADRs replace bureaucratic review boards with fast, asynchronous git pull requests.
  • ▸Core structure: Title/Status, Context, Decision, Consequences, Alternatives.
  • ▸Never overwrite old ADRs; mark them as 'Superseded' to preserve historical context.
  • ▸Strict 72-hour review windows prevent decision paralysis while capturing feedback.

Common Misconceptions

  • ✗Misconception: ADRs are only for massive million-dollar architecture overhauls (False: Any non-trivial library, DB, or protocol choice warrants a brief ADR).
  • ✗Misconception: Architecture review boards make better decisions than ADRs (False: ARBs slow velocity and encourage shadow architecture).

Decision & Governance Guidance

Initialize a `docs/adr/` directory in every microservice repository. Enforce a 72-hour time-boxed RFC review policy for all new tech proposals.

Authoritative Sources & Standards