The Spine
An open, versioned architecture spec that lives in your repo at arch/. Human-readable Markdown, a machine-readable spine.yaml, and decisions treated as the load-bearing artefact rather than a section near the back.
Version 0.2 · Free, no attribution required · Crosswalked to all twelve arc42 sections
Why another architecture artefact
Architecture documentation is a solved problem. arc42 solved it, and a team that adopts it ends up with something genuinely useful. What no template solves is the part that actually fails in production: the document and the system stop agreeing, and nothing tells you when.
The rationale lives in a channel that has since been archived. The quality goal says “highly available” and nothing fails when it is not. And now a large share of the code is written by an agent that has read your prompt, your open files and none of your architecture.
So the question this artefact answers is not how do I document an architecture. It is how do I decide one, keep it true, and make it legible to whatever writes the code next.
Three properties, and what each one costs you
Decision-first
Decisions are the spine; structure, views and diagrams are derived from them. Most templates put the drawing first, which is why the drawing is the part that goes stale — it records what was built without recording why, so nobody can tell whether a change contradicts an intention or just a picture.
Accepted decisions are never edited. They are superseded, and the old one stands as history.
Enforced
Every quality goal names a guardrail: a build rule, a test, a runtime SLO, or an eval threshold for anything LLM-shaped. A goal with no guardrail is a wish, and the spec says so out loud rather than letting it sit in a table looking like a commitment.
Sixty ready-made checks in the fitness functions catalog, mapped by quality attribute.
Machine-readable
arch/spine.yaml carries the constraints, quality goals, guardrails and agent rules in a schema-validated form. A coding agent reads them as rules. A human reads the Markdown beside them. Neither reader is served a compromise.
Version 0.2 of the schema is published and stable; editors validate against the URL.
What lands in the repo
One directory, committed alongside the code it describes. Numbered in decision-first order, so the file you open first is the one that decides the rest.
arch/
spine.yaml machine layer — read by CI and by agents
01-decisions.md the index; one file per decision below
02-quality-goals.md ranked, measurable, no ties
03-guardrails.md what fails when a goal is violated
04-constraints.md what you were not free to choose
05-context.md what crosses your boundary, and what it costs
06-strategy.md the five moves that shape everything
07-structure.md building blocks, derived from decisions
08-behaviour.md the flows where the goals are won or lost
09-deployment.md where it runs, and the 3am section
10-cross-cutting.md answered once, applies everywhere
11-risks.md what you know is wrong, priced
12-vocabulary.md the terms, and the terms you refuse
decisions/
ADR-0001-record-architecture-decisions.mdThe machine layer
spine.yaml holds only what something other than a human has to act on: the ranked quality goals, the constraints and their expiry dates, the decision index, the guardrails, and the rules an agent must not break.
It validates against a published schema, so your editor completes it and CI can fail when it stops parsing. Ids are the point: QG-1 is addressable from a guardrail, a pull request, a dashboard and a prompt.
spine.schema.json — JSON Schema draft 2020-12, version 0.2.
Add this line at the top of the file and most editors validate it as you type:# yaml-language-server: $schema=https://ruchitsuthar.com/architecture/spine.schema.json
spine: "0.2"
system:
name: checkout
purpose: Take money reliably enough that nobody talks about it.
lifecycle: growing
quality_goals:
- id: QG-1
attribute: availability
scenario: >-
During a single-AZ failure, checkout completes for 99.9% of
requests within 2s p99, without operator intervention.
priority: 1
guardrails: [G-1]
decisions:
- id: ADR-0007
title: Idempotency keys on every payment mutation
status: accepted
date: "2026-03-04"
serves: [QG-1]
file: decisions/ADR-0007-idempotency-keys.md
guardrails:
- id: G-1
checks: [QG-1]
kind: runtime
rule: Checkout availability SLO, multi-window burn-rate alert.
threshold: "99.9% over 30d; page at 14.4x burn over 1h"
enforced_by: prometheus/alerts/checkout.yaml
on_breach: fail
agent_rules:
must_not:
- Contradict an accepted decision. Propose a superseding ADR.
- Weaken a guardrail to make a build pass.
review:
last: "2026-08-01"
cadence: quarterlyCrosswalk to arc42
Every arc42 section, and where its content goes in a Spine. Adopting one does not mean abandoning the other — the last row is the only place The Spine adds something arc42 has no slot for.
| arc42 § | arc42 section | Spine concern | What differs |
|---|---|---|---|
| 1 | Introduction and Goals | Quality goals | Split: purpose sits in spine.yaml, the goals become measurable scenarios. |
| 2 | Architecture Constraints | Constraints | Same content, same purpose. |
| 3 | Context and Scope | Context & scope | Same content, same purpose. |
| 4 | Solution Strategy | Solution strategy | Same content, same purpose. |
| 5 | Building Block View | Structure | Derived from decisions, not authored first. |
| 6 | Runtime View | Behaviour | Same content, same purpose. |
| 7 | Deployment View | Deployment & operations | Same content, same purpose. |
| 8 | Cross-cutting Concepts | Cross-cutting concepts | Same content, same purpose. |
| 9 | Architecture Decisions | Decisions | Promoted to the spine. Everything else references it. |
| 10 | Quality Requirements | Quality goals | Merged with §1.2 — one list, each entry bound to a guardrail. |
| 11 | Risks and Technical Debt | Risks & debt | Same content, same purpose. |
| 12 | Glossary | Vocabulary | Same content, same purpose. |
| — | No arc42 equivalent | Guardrails | Enforcement. The layer arc42 leaves to you entirely. |
The twelve concerns
In decision-first order. The links under each one are the depth that already exists on this site; dedicated pages per concern are being written one at a time.
The spine itself. Every consequential choice recorded once, with its alternatives and its expiry — not reconstructed from a diagram two years later.
The three to five attributes this system is allowed to be good at, each written as a measurable scenario rather than an adjective.
Every quality goal bound to a check that fails a build, a deploy or an eval. Unenforced architecture is a preference, not an architecture.
What you were not free to choose — technical, organisational, regulatory — each with the reason and, where it exists, the date it stops being true.
The systems on the other side of your boundary, what each exchange costs you, and which of them you cannot afford to trust.
The handful of moves that shape everything downstream, and the ones you consciously deferred. Short on purpose — a long strategy is a missing decision.
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.
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 §7Where 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 §8The decisions that apply everywhere and therefore belong nowhere in particular — identity, error handling, persistence, logging, cost attribution.
Risks & debt
arc42 §11The 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 §12The terms this system uses and refuses to use. Cheap to write, and the single highest-leverage file when agents are generating names.
Adopt it this afternoon
In this order. Steps four and five are the ones teams skip, and they are the two that decide whether the directory is still accurate in six months.
- Step 1
Copy arch/ into the repo
Delete the concern files your system has not earned. Four files you maintain beat twelve you wrote once.
- Step 2
Fill quality goals first
Three attributes, ranked, no ties. Each one a scenario with a number in it. This is the only section that is not optional.
- Step 3
Bind two goals to real checks
Two guardrails that fail a build are worth more than twelve that describe an intention. Add the rest when they stop being aspirational.
- Step 4
Record the decisions you already made
Not all of them — the six the current design rests on. Backfilling history is a trap; backfilling the load-bearing six is an afternoon.
- Step 5
Paste the agent bundle
Into AGENTS.md or CLAUDE.md, so the next agent-written change reads the spec before it writes.
When not to use this
- A prototype you expect to throw away. Recording decisions you intend to discard is theatre. Write down the two constraints that would make you keep it, and nothing else.
- A system with one maintainer and no agents. The value here is transfer — between people, teams and tools. With no transfer, an ADR folder is enough.
- As a compliance exercise. A Spine filled in to satisfy an audit will be filled in once and then be wrong, which is worse than empty because people will trust it.
Frequently asked
How is The Spine different from arc42?
arc42 is a documentation template: twelve sections that describe an architecture, with the building block view as the centre of gravity. The Spine is a decision spec: decisions are the centre, views are derived, every quality goal is bound to an automated check, and a machine layer in spine.yaml makes the whole thing readable by a coding agent. The crosswalk table on this page maps all twelve arc42 sections onto Spine concerns, so a team already using arc42 keeps everything they have written and adds the enforcement and agent layers.
Can I use The Spine alongside arc42, C4 and ADRs?
Yes, and that is the intended path. Keep arc42 as your prose structure and C4 as your diagram notation; The Spine tells you which decisions those artefacts are derived from and binds your quality goals to checks. If you already keep ADRs, you are most of the way there — add spine.yaml, index the decisions you have, and bind two quality goals to guardrails.
What is in spine.yaml and why is it separate from the Markdown?
It holds quality goals, constraints, the decision index, guardrails, agent rules and the review stamp — the entries that something other than a human needs to act on. It is separate because the two readers want different things: a human wants context and prose, and a build check or a coding agent wants an addressable id and an unambiguous rule. Mixing them produces a file that serves neither, which is the failure mode of documenting architecture in a wiki.
Do I have to fill in all twelve concern files?
No. Fill quality goals and decisions, bind two goals to guardrails, and stop. Add a concern file the second time a pull request has to re-answer a question that belongs in it. Twelve files written in one sitting is the most reliable way to end up with twelve files nobody reads.
Is there a schema I can validate against?
Yes — version 0.2 of the JSON Schema is published at https://ruchitsuthar.com/architecture/spine.schema.json. Point your editor's YAML language server at it for completion and inline validation, and add a schema check to CI so the spec cannot silently rot into something that no longer parses.
Is it free to use commercially?
Yes. The template, the schema and the agent bundle are free to copy, fork, modify and use commercially, with no attribution requirement and no account to create.
Version 0.2
Take the directory, not the idea
The zip, the single-file variant, the schema and the agent bundle. Nothing behind an email address.
Free to fork, modify and use commercially. No attribution required.