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

Choosing the Right Document

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.