Specifications & Architecture Documentation
Overview
Good architecture starts with good specs. This skill covers the full spectrum of specification-driven development — from visual diagrams that communicate system structure, to requirements documents that capture intent, to tools that automate the spec-to-code pipeline.
Specification Landscape
┌─────────────────────────────────────────────────────┐
│ Diagramming │
│ Visual representations of architecture & behavior │
│ C4, Mermaid, UML, TOGAF, ArchiMate, D2, ERD, ... │
├─────────────────────────────────────────────────────┤
│ Documentation │
│ Written specifications capturing intent & design │
│ PRD, TRD, BRD, ADR, RFC, Gherkin, Gauge │
├─────────────────────────────────────────────────────┤
│ Tools │
│ Automation for spec-driven workflows │
│ GitHub Spec Kit │
└─────────────────────────────────────────────────────┘
Choosing the Right Diagram
| Need |
Diagram Type |
Tool |
| System context and containers |
C4 diagrams |
Structurizr DSL, Mermaid |
| Interaction sequences |
Sequence diagrams |
Mermaid, PlantUML |
| Object-oriented structure |
Class / component diagrams |
UML, Mermaid |
| State machines |
State diagrams |
Mermaid, PlantUML, UML |
| Data models |
Entity-Relationship diagrams |
Mermaid, ERD tools |
| Enterprise architecture |
TOGAF / ArchiMate |
Archi, Sparx EA |
| Data flow and processing |
Functional diagrams |
DFD, Mermaid |
| General architecture |
Declarative diagrams |
D2, Mermaid |
| Timelines and scheduling |
Gantt charts |
Mermaid |
Choosing the Right Document
| Need |
Document Type |
| What to build and why (product view) |
PRD |
| How to build it (engineering view) |
TRD |
| Business justification and ROI |
BRD |
| Recording an architecture decision |
ADR |
| Proposing a significant change |
RFC |
| Executable acceptance criteria |
Gherkin feature files |
| Markdown-based test specifications |
Gauge specs |
Spec-Driven Development Workflow
1. Requirements → PRD / BRD (what + why)
2. Architecture → C4 / TOGAF diagrams (how it fits)
3. Design → TRD + ADRs (how to build + decisions)
4. Acceptance → Gherkin / Gauge (verifiable criteria)
5. Implementation → Code (guided by specs)
6. Validation → Automated tests from specs
Best Practices
- Start with a C4 Context diagram before diving into implementation — it forces you to define system boundaries and external dependencies.
- Use ADRs to record every significant architecture decision so future developers understand the "why" behind the "what."
- Write Gherkin scenarios alongside PRDs so acceptance criteria are executable from day one.
- Use Mermaid for diagrams embedded in Markdown docs (PRs, ADRs, RFCs) — it renders natively on GitHub.
- Use spec-driven tools like GitHub Spec Kit to automate the spec → plan → tasks → implementation pipeline.
- Keep diagrams as code (Mermaid, D2, PlantUML, Structurizr DSL) and version them in Git alongside the source code they describe.
1---2name: specs-23description: Use when working with software specifications, architecture documentation, and diagramming. Covers the full spectrum of spec-driven development — from architectural diagrams to requirements documents to specification tooling. USE FOR: specification-driven development, architecture documentation strategy, choosing diagram types, choosing requirements formats, spec-to-implementation workflows DO NOT USE FOR: specific diagram syntax (use diagramming sub-skills), specific document templates (use documentation sub-skills), specific tooling (use tools sub-skills)4license: MIT5---6
7# Specifications & Architecture Documentation
8
9## Overview
10Good architecture starts with good specs. This skill covers the full spectrum of specification-driven development — from visual diagrams that communicate system structure, to requirements documents that capture intent, to tools that automate the spec-to-code pipeline.
11
12## Specification Landscape
13
14```
15┌─────────────────────────────────────────────────────┐
16│ Diagramming │
17│ Visual representations of architecture & behavior │
18│ C4, Mermaid, UML, TOGAF, ArchiMate, D2, ERD, ... │
19├─────────────────────────────────────────────────────┤
20│ Documentation │
21│ Written specifications capturing intent & design │
22│ PRD, TRD, BRD, ADR, RFC, Gherkin, Gauge │
23├─────────────────────────────────────────────────────┤
24│ Tools │
25│ Automation for spec-driven workflows │
26│ GitHub Spec Kit │
27└─────────────────────────────────────────────────────┘
28```
29
30## Choosing the Right Diagram
31
32| Need | Diagram Type | Tool |
33|------|-------------|------|
34| System context and containers | C4 diagrams | Structurizr DSL, Mermaid |
35| Interaction sequences | Sequence diagrams | Mermaid, PlantUML |
36| Object-oriented structure | Class / component diagrams | UML, Mermaid |
37| State machines | State diagrams | Mermaid, PlantUML, UML |
38| Data models | Entity-Relationship diagrams | Mermaid, ERD tools |
39| Enterprise architecture | TOGAF / ArchiMate | Archi, Sparx EA |
40| Data flow and processing | Functional diagrams | DFD, Mermaid |
41| General architecture | Declarative diagrams | D2, Mermaid |
42| Timelines and scheduling | Gantt charts | Mermaid |
43
44## Choosing the Right Document
45
46| Need | Document Type |
47|------|--------------|
48| What to build and why (product view) | PRD |
49| How to build it (engineering view) | TRD |
50| Business justification and ROI | BRD |
51| Recording an architecture decision | ADR |
52| Proposing a significant change | RFC |
53| Executable acceptance criteria | Gherkin feature files |
54| Markdown-based test specifications | Gauge specs |
55
56## Spec-Driven Development Workflow
57
58```
591. Requirements → PRD / BRD (what + why)
602. Architecture → C4 / TOGAF diagrams (how it fits)
613. Design → TRD + ADRs (how to build + decisions)
624. Acceptance → Gherkin / Gauge (verifiable criteria)
635. Implementation → Code (guided by specs)
646. Validation → Automated tests from specs
65```
66
67## Best Practices
68- Start with a C4 Context diagram before diving into implementation — it forces you to define system boundaries and external dependencies.
69- Use ADRs to record every significant architecture decision so future developers understand the "why" behind the "what."
70- Write Gherkin scenarios alongside PRDs so acceptance criteria are executable from day one.
71- Use Mermaid for diagrams embedded in Markdown docs (PRs, ADRs, RFCs) — it renders natively on GitHub.
72- Use spec-driven tools like GitHub Spec Kit to automate the spec → plan → tasks → implementation pipeline.
73- Keep diagrams as code (Mermaid, D2, PlantUML, Structurizr DSL) and version them in Git alongside the source code they describe.
majiayu000