Skip to content
mif-docs

Skill reference: ai-architecture-doc

Skill reference: ai-architecture-doc

Section titled “Skill reference: ai-architecture-doc”

The ai-architecture-doc skill authors one document genre: a composite AI-spec architecture document — one spec-channel artifact that embeds an arc42/C4-style structure plus testable non-functional requirements and an ADR-style decision log. 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 composite AI-spec architecture document
Purpose groupArchitecture design
MIF conceptTypesemantic
Target MIF level3
Primary sourcearc42

What this document type is

Section titled “What this document type is”

An AI-architecture doc is a composite, machine-first architecture spec: it combines, in a single artifact, the three things a coding agent needs to build correctly. From arc42 and C4 it takes structure — context, building blocks, and the relationships between them — so the agent knows the shape of the system. From EARS it takes testable non-functional requirements — latency, availability, security, and the like, each written so a human and an agent grade it identically rather than as vague prose. From MADR it takes an ADR-style decision log — the constraints already decided, with their rationale, so the agent does not relitigate settled choices. The result is one spec-channel document optimised to be consumed, not just read: unambiguous structure, gradeable requirements, and pinned decisions.

It is therefore not a pure human narrative — for that, write an arc42-arch-doc — and not a set of diagrams alone, which is c4-model-diagram. It is the deliberately composite form, and it projects to MIF as semantic content at Level 3, where the structure, requirements, and decisions all become addressable.

How the skill produces one

Section titled “How the skill produces one”

ai-architecture-doc is a genre skill: it carries the composite pattern as durable instructions plus exemplars, and writes the artifact over a MIF floor so the result is at once human-readable and agent-consumable.

  • Pattern, made operational. The skill encodes the three embedded layers — arc42/C4 structure, EARS non-functional requirements, an ADR-style decision log — and refuses anti-triggered work (a pure narrative belongs in arc42-arch-doc; diagrams alone belong in c4-model-diagram).
  • 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, keeping the taught pattern continuously verified.
  • MIF projection. The document is authored with MIF frontmatter (via the shared mif-frontmatter substrate) and a conceptType of semantic; the EARS criteria draw on the ears-acceptance-criteria substrate so each requirement is gradeable. 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 ai-architecture-doc when the primary consumer of the architecture is a coding agent and you want it to build to spec without inventing structure, guessing at quality targets, or reopening decided trade-offs. It is the right genre when structure, testable NFRs, and pinned decisions all need to travel together as one authoritative artifact — for example, the architecture handed to an agent at the start of an implementation task.

Do not use it when the audience is human and the goal is understanding or review; a arc42-arch-doc narrative or a google-design-doc is friendlier for that. Do not use it when you only need diagrams at varying zoom — that is c4-model-diagram. The cost of the composite form is that it carries three concerns at once: it is denser to write and to keep coherent, so use it where the machine-first payoff justifies maintaining structure, requirements, and decisions in lockstep.

Example

Section titled “Example”

An AI-architecture doc titled “MIF conversion service — agent spec” opens with a C4-style context and building-block view of the parser, projector, and round-trip checker, then lists EARS non-functional requirements (“WHEN a document is converted, the service SHALL reproduce the source byte-for-byte on round-trip”), then an ADR-style log pinning the settled constraints (JSON Schema 2020-12, the stable unversioned $id). A coding agent reads it and implements the converter without re-deriving the structure or re-deciding the schema dialect.

Provenance & citations

Section titled “Provenance & citations”