specs

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.