Software architecture, decided and enforced
Documenting an architecture is a solved problem. Deciding one, keeping it true after the code moves on, and making it legible to the agents writing that code is not. The Spine is an open, versioned spec for the part that is still open.
128 articles · 10 pathways · 6 reference documents · 3 tools · 63 glossary terms
Four doors
The artefact, the loop you run it with, the files you take away, and the depth everything else points at.
The Spine
An open, versioned architecture spec that lives in your repo. Twelve concerns in Markdown, one spine.yaml your CI and your coding agents read. Crosswalked to arc42's twelve sections so adopting one does not mean abandoning the other.
12 concerns · 1 spine.yaml · arc42 crosswalk
Read the specDecide → Record → Enforce → Review
Four steps, one loop, tool-agnostic. What each step produces, what it costs to skip, and the situations where running this loop is the wrong call.
4 steps · one loop · tool-agnostic
Read the methodTemplate, schema, agent bundle
The whole arch/ directory as a zip, a single-file variant for small systems, the JSON Schema for editor validation, and a paste-ready AGENTS.md fragment.
4 formats · nothing behind an email
Get the templateReference, tools, glossary
Latency numbers, failure modes, consistency models, sixty fitness functions, three calculators and sixty-odd definitions. The lookup layer the spec points at.
6 references · 3 tools · 63 terms
Browse the referenceStart here
The right first move depends on which of these you actually are.
You are designing something new
Start with quality goals, not boxes. Three attributes, ranked, each written as a measurable scenario.
System Design MasteryYou have a system nobody can explain
Start with decisions. Record the six choices the current design rests on, then bind the two that matter to a check.
ADR GeneratorAgents are writing a real share of your code
Start with the machine layer. Constraints and guardrails an agent reads beat a wiki nobody opens.
The agent bundleThe loop
Four steps. Skipping any one of them has a specific, predictable cost — the method page prices each.
- Step 01
Decide
A decision with an owner and a date.
Skip itThe choice still gets made — by whoever writes the code first, without the context to make it well.
- Step 02
Record
arch/decisions/ADR-NNNN.md plus one line in spine.yaml.
Skip itSix months on, the rationale exists only in the head of whoever has since changed teams.
- Step 03
Enforce
A guardrail id in CI that fails the build when the goal is violated.
Skip itThe architecture drifts and nobody finds out until the incident review.
- Step 04
Review
An updated review block, and superseded decisions that still read as history.
Skip itThe spec becomes confidently wrong — worse than absent, because people trust it.
Review feeds straight back into Decide — that is what makes it a loop
Twelve concerns
What the spec covers, in decision-first order. Each concern already has depth on this site; the dedicated pages are being written one at a time.
Has its own pageBeing writtenNew = no arc42 section covers it
Decisions
arc42 §9
The spine itself. Every consequential choice recorded once, with its alternatives and its expiry — not reconstructed from a diagram two years later.
Quality goals
arc42 §1.2, 10
The three to five attributes this system is allowed to be good at, each written as a measurable scenario rather than an adjective.
Guardrails
New · no arc42 section
Every quality goal bound to a check that fails a build, a deploy or an eval. Unenforced architecture is a preference, not an architecture.
Constraints
arc42 §2
What you were not free to choose — technical, organisational, regulatory — each with the reason and, where it exists, the date it stops being true.
Context & scope
arc42 §3
The systems on the other side of your boundary, what each exchange costs you, and which of them you cannot afford to trust.
Solution strategy
arc42 §4
The handful of moves that shape everything downstream, and the ones you consciously deferred. Short on purpose — a long strategy is a missing decision.
Structure
arc42 §5
Building blocks and the coupling between them — derived from the decisions, not a substitute for them. This is where most documentation starts and most of it dies.
Behaviour
arc42 §6
The four or five flows that decide whether the design holds — including the failure paths, retries and idempotency that never make it onto a happy-path diagram.
Deployment & operations
arc42 §7
Where it runs, how it is released, and what an operator does at 3am. Operability is an architectural property, not a hand-off.
Cross-cutting concepts
arc42 §8
The decisions that apply everywhere and therefore belong nowhere in particular — identity, error handling, persistence, logging, cost attribution.
Risks & debt
arc42 §11
The parts you know are wrong, priced. A risk register nobody reviews is theatre; this one is bound to a review date and an owner.
Vocabulary
arc42 §12
The terms this system uses and refuses to use. Cheap to write, and the single highest-leverage file when agents are generating names.
Frequently asked
The five questions this gets asked before anybody downloads anything.
Is this an alternative to arc42?
No — it sits on top of it. arc42 answers how to document an architecture, and answers it well. The Spine answers three questions it deliberately leaves open: how you decide, how you keep the decision true once the code moves on, and how anything other than a human reads it. The Spine page publishes a full crosswalk to arc42's twelve sections, so a team already using arc42 keeps everything they have written.
What makes it different from an ADR folder plus a C4 diagram?
Two things. Every quality goal is bound to a guardrail — a build rule, a test, an SLO or an eval threshold that fails when the goal is violated, which is what stops the spec drifting from the system. And the whole thing has a machine layer, spine.yaml, validated against a published JSON Schema, so a coding agent reads your constraints as rules rather than as prose it may or may not have been shown.
Do I need all twelve concerns?
No, and starting with twelve is the most common way this fails. Fill quality goals and decisions, bind two goals to real guardrails, and stop. Add a concern file when the same question has been answered twice in a pull request. A four-file arch/ directory that people update beats twelve files that were written once.
Why does architecture documentation need to change for AI agents?
Because the reader changed. A human engineer infers intent from the surrounding code and asks in a channel when it is unclear; an agent generating a change does neither. It needs the boundary stated, the term defined and the decision addressable by id — otherwise it produces code that is locally plausible and architecturally wrong, at a rate no review process was sized for.
Is any of this free?
All of it. The template, the schema and the agent bundle are open and downloadable, the tools run entirely in your browser with no sign-up, and there is no account to create anywhere on this site.
Version 0.2
The Spine is versioned in public
The schema, the template and the agent bundle change as the practice does. The newsletter is where breaking changes and new concern pages get announced.
No spam, and nothing about this artefact is behind an email address.