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.
