Skip to content
mif-docs

Skill reference: arc42-arch-doc

Skill reference: arc42-arch-doc

Section titled “Skill reference: arc42-arch-doc”

The arc42-arch-doc skill authors one document genre: an arc42 architecture document — the twelve-section template that captures a system’s architecture as durable, declarative knowledge. This reference describes what that document type is, how the skill produces one, when it earns its place, and the provenance and sources behind it.

PropertyValue
AuthorsA full arc42 software architecture document (SAD)
Purpose groupArchitecture design
MIF conceptTypesemantic
Target MIF level3
Primary sourcearc42

What this document type is

Section titled “What this document type is”

arc42 is an open template for describing and communicating software and system architectures. Its defining property is a fixed twelve-section structure that gives every system the same drawer for every kind of architectural knowledge: introduction and goals, constraints, context and scope, solution strategy, building-block view, runtime view, deployment view, cross-cutting concepts, architecture decisions, quality requirements, risks and technical debt, and a glossary. The sections move from the abstract — what the system must achieve and under what constraints — down to concrete structure, behaviour, and the decisions that shaped them. The template is deliberately notation- and tool-agnostic: it prescribes what to record, not how to draw it.

An arc42 document is therefore not a single decision record — one consequential choice belongs in an adr — and not a step-by-step procedure, which is a runbook or how-to. It is the durable, whole-system reference an architect maintains over the life of the system. Because it is descriptive knowledge rather than performed steps, it projects to MIF as semantic content at Level 3.

How the skill produces one

Section titled “How the skill produces one”

arc42-arch-doc is a genre skill: it carries the arc42 template as durable instructions plus exemplars, and writes the artifact over a MIF floor so the result is at once a human-readable SAD and a machine-conformant unit.

  • Pattern, made operational. The skill encodes the twelve sections and their intent — goals before structure, building blocks before runtime, decisions recorded with their forces — and refuses anti-triggered work (a lone decision belongs in an ADR; operational steps belong in a runbook).
  • Exemplars set the bar. Like every genre in the suite it ships good-l1.md (the MIF Level-1 floor), good.md (the Level-3 target), bad.md (a counter-example), and evals/evals.json. The check-exemplars gate proves good-l1.md validates at L1 and good.md at Level 3, so the pattern the skill teaches is itself continuously verified.
  • MIF projection. The document is authored with MIF frontmatter (via the shared mif-frontmatter substrate) and a conceptType of semantic, reflecting that an architecture description is structural knowledge rather than a sequence of steps. mif-validate proves the Markdown ↔ JSON-LD round-trip is lossless before the document is considered done.

When it is beneficial

Section titled “When it is beneficial”

Reach for arc42-arch-doc when you need the whole picture of a system in one durable place: onboarding new engineers, surviving team turnover, passing an architecture review, or giving a coding agent a complete structural map. The fixed sections make gaps visible — an empty “quality requirements” or “risks” drawer is itself a finding — and give every reader a predictable place to look.

Do not use it to capture a single decision and its trade-offs; that is an adr, which is smaller and immutable once accepted. Do not use it when the deliverable is diagrams at varying zoom levels for a mixed audience — that is the c4-model-diagram genre, which arc42’s building-block and context views happily embed. And for a machine-first spec a coding agent consumes — arc42 structure plus testable NFRs and a decision log in one artifact — prefer ai-architecture-doc. The cost of arc42 is breadth: a full SAD is a substantial document to write and to keep current, so use it where the whole-system view repays the upkeep.

Example

Section titled “Example”

An arc42 document titled “MIF conversion service — architecture” opens with the quality goals (lossless round-trip, deterministic validation) and the stakeholders who care about them, states the constraints (Node runtime, JSON Schema 2020-12), sketches the system context, then descends through the building-block view of the converter and validator down to the runtime and deployment views. A cross-cutting-concepts section records how provenance and versioning are handled uniformly, a decisions section links the ADRs behind each major choice, and the quality-requirements section lists scenarios a reviewer can test against.

Provenance & citations

Section titled “Provenance & citations”