ADR discipline

How bassclef records architecture decisions — one-shape ADRs with Context, Decision, Consequences, Rejected alternatives, and Exit cost.

Ships with bassclef execution

Architecture Decision Records are not a skill you invoke by hand. The discipline ships with bassclef and fires automatically on architecturally- relevant paths — schema changes, middleware, deployment topology, dependency manifests. The framework records ADRs on your behalf and those ADRs then inform SDLC work as adopters run it.

Read this page to understand how the discipline works. Most ADR bodies stay operator-private by default; only curated ones land as pages here.

Use this when

You are picking whether to adopt bassclef and want to see how it handles architectural decisions. Or you are writing a rule or hook that touches architectural surface and want to know when the ADR gate fires.

Skip this when

You are trying to run bassclef or install it. Head to Get started. ADR discipline is background — the framework runs it on your behalf.

What ADRs are

An Architecture Decision Record is a Markdown file that captures one significant architectural decision — the context, the choice, and the consequences. bassclef adds two sections beyond Michael Nygard's original 3-part template — Rejected alternatives and Exit cost — for a 5-part shape total.

Every ADR follows the same shape so a reader knows exactly where to look for each concern.

Why bassclef writes them

Before the discipline, architectural decisions lived only in commit messages and code review threads. Two months later nobody could reconstruct why a specific choice landed the way it did. New architectural decisions could not be measured against the original rationale. Deprecation required re-deriving decision context from scratch.

bassclef fixes this by capturing every significant decision as a record — while the context is fresh, in the same PR that ships the change.

When the discipline fires

The adr-discipline-check.sh hook fires on Edit and Write against architecturally-relevant paths:

Schema files (prisma/schema.prisma, per-ORM equivalents)
Deployment topology (docker-compose*.yml)
Middleware (src/middleware.ts, per-stack equivalents)
Schema migrations (*/alembic/versions/*.py, */db/migrate/*.rb)
Dependency manifests on Write only (package.json, pyproject.toml)

When the hook fires it checks for an ADR marker at state/markers/adr/<decision-slug>-*.md. If missing, it BLOCKs with a template and asks you to record the decision before proceeding.

Template shape

Michael Nygard's original 3 sections (Context, Decision, Consequences) plus bassclef's 2 additions (Rejected alternatives, Exit cost):

Context — what motivated the decision
Decision — the choice + rationale
Consequences — what becomes easier, what becomes harder, what the decision enables or blocks
Rejected alternatives — what we considered and did not pick, and why. Prevents the "did anyone think about X?" review question by putting the answer inline.
Exit cost — what it would take to reverse the decision. Forces the author to think about lock-in at the moment of the decision, not months later when the cost lands.

How ADRs inform SDLC

bassclef ADRs are essential input at multiple SDLC surfaces:

Iteration goal docs reference pinned ADRs — the goal cannot deviate without a 2-luminary challenge per the adr-deviation-luminary-challenge rule
The adr-deviation-challenge.sh hook fires on substantive architectural work and surfaces the deviation as a marker
Architect-review sessions cite ADRs when evaluating new changes

Adopters inherit both the discipline and the mechanical enforcement — even sequential-mode sessions (no Architect agent) get the gate.

Enforcement

Rule — .claude/rules/adr-discipline.md auto-loads into every session
Hook — .claude/hooks/adr-discipline-check.sh fires on PreToolUse Edit and Write on architectural paths
Deviation gate — .claude/hooks/adr-deviation-challenge.sh surfaces attempted deviation from a pinned ADR

Substrate telemetry

bassclef has authored 45 ADRs to date across the substrate. The lite tier ships 6 adopter-facing ADRs; the rest stay operator-private by default.

Counts refresh from data/substrate-counts.json (currently v1.14.3).

Curated public excerpts

Individual ADR bodies default to operator-private. Many carry strategic reasoning and internal-state references that are not for public consumption. The operator picks specific ADRs to publish as needed. None ship in this iteration.

When operator-picked ADRs land, they show up as pages under this section. Until then, the discipline itself is the trust signal — the count above.

.claude/rules/adr-discipline.md .claude/rules/adr-deviation-luminary-challenge.md

Rules catalog — every rule bassclef auto-loads
Hooks catalog — every mechanical gate
State spine — how ADR markers live in the state layer
Chronicle — session record that references ADR authorship

ADR discipline

On this page