4 minute read

  • Status: Accepted

  • Date: 2026-02-28

  • Authors: Claude, Vadim Kuhay

Summary

Record architectural decisions in the Rust RFC style, adapted for a project whose decisions are earned across generations of experimentation and production.

Governing Dynamic

Architecture is a story! Architects are storytellers. A story well told is retold by everybody.

Motivation

Total Recall is Generation 3, Take 2 of synthetic memory. Generations 1 and 2 paid real costs for architectural knowledge. Gen 3v1 rediscovered constraints that earlier generations had already navigated. The reason: the WHY behind decisions was not captured. Only the WHAT survived.

Architecture pages on the site describe the current design. README documents the lineage. Neither captures the reasoning process — what was considered, what was rejected, and what evidence drove the choice. Without that, the next contributor (human or synthetic) sees the structure but not the forces that shaped it.

Guide-Level Explanation

An ADR is a short document that captures one architectural decision. It explains the decision as if teaching it to someone who wasn’t in the room. It lives in site/_adr/ alongside the site it publishes to, with a symlink at docs/adr/ for repository-level access.

Each ADR has a number that never changes and is never reused. If a decision is reversed, the old ADR stays and a new one supersedes it. The history is the point.

When you need to understand why something is the way it is, you read the ADR. When you want to change it, you write a new one.

Reference-Level Explanation

Template

Every ADR in this project follows this structure:

= ADR-NNNN: Title as Short Noun Phrase

* *Status:* Proposed | Accepted | Deprecated | Superseded by ADR-NNNN
* *Date:* YYYY-MM-DD
* *Authors:* who wrote it

== Summary

One paragraph. What was decided and why it matters.

== Governing Dynamic

One sentence. The principle that makes this decision inevitable.

== Motivation

Why this decision needed to be made. What problem exists.
What happens if we do nothing.

== Guide-Level Explanation

Explain the decision as if teaching it. No jargon without context.
Someone reading this at 2am, three years from now, with no memory
of the discussion, should understand.

== Reference-Level Explanation

Technical details. How it interacts with other decisions.
Implementation specifics where relevant.

== Prior Art

What came before. What other projects do. What we tried in
previous generations and what happened. This is where the
generational lessons live.

== Rationale and Alternatives

Why this choice and not the others. What was considered.
What was rejected and why. Be specific.

== Consequences

Everything that follows from this decision -- positive, negative,
and neutral. Do not hide the costs.

Sections That May Be Omitted

  • Governing Dynamic — if no single principle drives the decision.

  • Prior Art — if there is no relevant history or precedent.

  • Reference-Level Explanation — if the guide-level explanation is sufficient.

All other sections are required.

File Naming

NNNN-title-with-dashes.adoc — four-digit zero-padded, lowercase, dashes for spaces.

Directory

Source files live in site/_adr/. A symlink at docs/adr/ provides repository-level access for contributors who don’t use the site.

Status Lifecycle

Proposed --> Accepted
                 \--> Deprecated
                 \--> Superseded by ADR-NNNN

ADRs are immutable after acceptance. If circumstances change, write a new ADR that supersedes the old one. The old ADR’s status is updated to point to the new one. Nothing else changes.

Index

docs/adr/README.md tracks all ADRs with number, title, status, and date.

Prior Art

Michael Nygard (2011)

The original ADR format. Four sections: Status, Context, Decision, Consequences. Adopted by adr-tools, UK GDS, US 18F. Clean and minimal. But four sections cannot carry the teaching weight our decisions need. "Context" is a single section for both the problem and the history — too compressed for generational lessons.

MADR (Markdown Any Decision Records)

Nygard plus structured options comparison. Decision Drivers as bullet lists. Considered Options with Good, because…​ / Bad, because…​ pros and cons. Well-organized but clinical. The structured format flattens narrative into checklists. Our decisions have stories — Tillie’s three-week shutdown proving decoupled backends, SSE failing in production during Gen 3v1. Bullet points do not carry that.

Rust RFCs

Guide-level and Reference-level explanation split. Motivation, Prior Art, Rationale and Alternatives. Designed for decisions that need to teach, not just record. The best decision-record format in open source. We adapt it by dropping language-feature sections (Unresolved Questions, Future Possibilities) and adding Consequences from Nygard.

Kubernetes KEP, Go Proposals

Governance documents for massive distributed projects. Production readiness questionnaires, graduation criteria, SIG ownership. Overkill for a team of four.

Rationale and Alternatives

Why Rust RFC adapted, not pure Nygard: Our ADRs carry generational lessons. The Guide-level explanation forces us to teach, not just state. Prior Art is where generations 1-3v1 live. Nygard’s four sections are too compressed for this.

Why Rust RFC adapted, not MADR: MADR is clinical. Structured pros/cons lists flatten reasoning into checklists. We want narrative, not bullet points.

Why Rust RFC adapted, not pure Rust RFC: Rust RFCs are designed for language feature proposals, not post-hoc architectural documentation. We drop sections that assume a proposal process (Unresolved Questions, Future Possibilities) and add Consequences from Nygard because every decision has costs that should be stated.

Why not tooling (adr-tools, log4brains): We have six ADRs to write. The tooling overhead is not justified. If the ADR count grows significantly, revisit.

Consequences

  • Every architectural decision gets a permanent, numbered record.

  • Future contributors (including future Claude instances) can understand WHY, not just WHAT.

  • The template is longer than Nygard’s four sections. Each ADR takes more effort to write. This is deliberate — the effort produces better documentation.

  • ADRs live in site/_adr/ and are published on the site under /decisions/. A symlink at docs/adr/ provides repository-level access. One source of truth, two audiences. Architecture pages link to relevant ADRs so readers can switch between WHAT and WHY.

  • No tooling dependency. Plain AsciiDoc files in a directory.

Updated: