Topic: adr template arc42
arc42 Architecture Decision Record Template
arc42 reserves section 9 for architecture decisions. Here's a template for that section that reads cleanly on its own and cross-references the other arc42 sections the decision actually touches.
TL;DR
In arc42, ADRs live in section 9 — Architecture Decisions. Keep each decision short (Nygard's five sections, 250-word cap) and cross-reference the arc42 sections it affects: §3 context & scope, §4 solution strategy, §5 building block view, §6 runtime view, §7 deployment view, §10 quality requirements, §11 risks & technical debt, §12 glossary. Cross-references are what make arc42 ADRs different from freestanding Markdown ADRs — they anchor each decision in the architecture document.
Why this matters
arc42 is the de-facto architecture-documentation template across European enterprise — banks, insurance, automotive, public sector. If your organisation has standardised on arc42, the ADR format isn't a free choice: section 9 exists, your audit team expects it populated, and the value comes from decisions that link forward into sections 5–7 (the views) and backward into sections 3–4 (context and strategy). A freestanding Nygard ADR that doesn't reference the arc42 building blocks it affects is half-documented.
The arc42 section 9 ADR block
One sub-section per decision, numbered within section 9. The template extends Nygard's five sections with an explicit Cross-References block so the decision is stitched into the rest of the arc42 document.
### 9.1 Use Postgres over MongoDB for the v1 datastore
**Status:** Accepted · **Date:** 2026-04-24 · **Deciders:** @alice (CTO), @bob (Staff Eng)
#### Context
From §3.1 (Business Context), the system serves transactional workloads with
strict consistency requirements (payments, account state). §10.2 requires
point-in-time recovery of 35 days for compliance. Team operational experience
is in relational databases.
#### Decision
Adopt PostgreSQL 16 as the system of record for all transactional data.
Document-store needs (if any emerge) will use Postgres' JSONB columns rather
than a separate database, until the volume justifies a dedicated store.
#### Consequences
Positive: schemas are enforced, existing SRE playbooks apply, point-in-time
recovery is well-understood. Negative: schema migrations are a constraint on
fast product iteration; we'll invest in migration tooling (§4.3). Neutral:
vertical scale ceiling is not a near-term concern given §3.4 capacity model.
#### Alternatives Considered
- **MongoDB** — rejected; schema flexibility does not offset the operational
learning curve in the v1 timeframe (§11.2, risk register).
- **DynamoDB** — rejected; vendor lock-in flagged as a board-level concern
(§11.3); secondary index limitations conflict with §6 runtime query patterns.
#### Cross-References
- Context: §3.1 Business Context, §3.2 Technical Context
- Solution strategy: §4.1 Data & Persistence
- Building blocks: §5.2 Persistence Layer
- Runtime: §6.3 Payment Processing Flow
- Deployment: §7.2 Database Cluster Topology
- Quality goals: §10.2 Recoverability, §10.4 Consistency
- Risks: §11.2 Operational Learning Curve
- Glossary: §12 "System of Record"
#### Links
- PR: #341
- Original discussion: <ChatGPT / Claude conversation URL>
- Supersedes: —
Which arc42 sections each ADR typically references
Not every ADR touches every section. In practice, well-written arc42 ADRs follow a predictable pattern depending on what kind of decision they record.
| Decision type | Always cross-references | Often cross-references |
|---|---|---|
| Technology choice (DB, framework, language) | §3 Context, §4 Solution Strategy, §5 Building Blocks, §10 Quality | §7 Deployment, §11 Risks |
| Integration pattern (sync vs async, REST vs event) | §5 Building Blocks, §6 Runtime | §3 Context, §10 Quality (latency, throughput) |
| Deployment topology (single region vs multi, k8s vs VM) | §7 Deployment, §10 Quality | §11 Risks, §4 Solution Strategy |
| Quality trade-off (consistency vs availability) | §10 Quality, §4 Solution Strategy | §6 Runtime, §11 Risks |
| Debt acknowledgement (we will pay this later) | §11 Technical Debt | §5 Building Blocks, §4 Solution Strategy |
A good rule: every ADR should reference at least §4 Solution Strategy (why this fits the strategic shape) and at least one view section (§5, §6, or §7 — where the decision is visible). If it touches neither, it's probably not an architecture decision.
File layout & tooling
arc42 doesn't prescribe storage. Two workable layouts:
- Everything in one file. Good for ≤20 decisions.
docs/architecture.adocwith section 9 growing as you decide things. Easy for reviewers to read linearly. - One file per ADR, transcluded. Section 9 becomes
docs/architecture/09-decisions/, each ADR isNNNN-slug.adocorNNNN-slug.md, and section 9 of the main doc includes them in order. This scales past 20 decisions and keeps git-blame meaningful. arc42 templates for AsciiDoc and Markdown both work — the Markdown variant is what most teams reach for, especially if they also publish the doc through a static site generator.
For CI linting, the same Action described in the GitHub ADR template page works here with a tweak to the path glob.
How WhyChose helps
WhyChose can emit arc42-shaped ADR blocks directly — the Nygard-style body is identical to arc42's expected shape, and the cross-reference block is populated with placeholders you fill in with your specific section numbers. The open-source extractor takes your ChatGPT or Claude export and outputs one record per decision; an --arc42 flag renders the output in the block shape above rather than plain Nygard. Run it locally if your arc42 document is in a regulated repository that can't phone home.
Related questions
Does arc42 mandate a specific ADR format?
No. Section 9 is defined as "the place for decisions" but the template for each decision is left to the team. Nygard's five-section format is the default most teams adopt; MADR's YAML-frontmatter variant is a reasonable alternative when the arc42 document is being consumed by tooling. The cross-reference block in the template above is the arc42-specific addition either way.
Should we number ADRs within section 9 or globally?
Globally. 9.1, 9.2, etc. within section 9 but with a stable ADR number that doesn't get renumbered when you reorganise. The convention is §9.1 — ADR-0001: ..., so both numbering schemes are visible. Reorganising section 9 without breaking PR links requires the stable ID.
How do we handle superseded decisions?
Mark the old entry Status: Superseded by ADR-NNNN and leave it in section 9 — never delete. The historical record is the point. The superseding ADR references the old ID in its Cross-References block under a "Supersedes" line. Readers who follow a link from §5 to the old ADR will see the status and click through to the current one.
Further reading
- The Nygard ADR template — the five-section body arc42 ADRs build on.
- MADR template explained — the structured-frontmatter alternative, compatible with arc42 section 9.
- How to document architecture decisions (without your team revolting) — the practice, not the format.
- ADR status template — format, fields, and the lifecycle beyond Accepted — arc42 ships Status as a section heading inside §9 by default; this page covers the migration path to YAML frontmatter for tooling-friendly directories, the five companion fields that earn their place, and the optional Trial-Period state for decisions teams adopt provisionally.
- ADR storage format comparison — AsciiDoc as one of five storage layers compared head-to-head; the transclusion benefit (
include::adr/0042.adoc[]) is what justifies the smaller-ecosystem cost when ADRs are sub-sections of a larger arc42 architecture document, and the page argues against picking AsciiDoc for ADRs alone. - TOGAF ADR template — the heavier enterprise framework that maps ADRs to Phase H change requests, the Architecture Repository, and a seven-field frontmatter; the comparison table at the bottom of that page argues arc42 is the right pick for single-product teams and TOGAF is the right pick when audit surface and cross-segment decisions matter.