陌讯skills聚合平台

specs

📁 tyler-r-kendrick/agent-skills 📅 10 days ago
4
总安装量
4
周安装量
#49336
全站排名
安装命令
npx skills add https://github.com/tyler-r-kendrick/agent-skills --skill specs

Agent 安装分布

amp 4
gemini-cli 4
github-copilot 4
codex 4
kimi-cli 4
opencode 4

Skill 文档

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.
GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台
本页面由 陌讯 Skills 聚合平台 收录整理，数据定期更新。