# Specs

> 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)

- Skill: `majiayu000/specs-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/specs-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/specs-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/specs-2

---


# 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.