AgentSkillsCN

specs

适用于处理软件规格、架构文档与图表绘制。涵盖从架构图到需求文档，再到规格化工具的全链条规范驱动开发。 适用场景：规范驱动开发、架构文档编写策略、图表类型的选择、需求格式的确定、从规格到实现的工作流程。 不适用场景：特定的图表语法（应使用绘图子技能）、特定的文档模板（应使用文档子技能）、特定的工具（应使用工具子技能）。

SKILL.md
--- frontmatter
name: specs
description: |
    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)
license: MIT
metadata:
  displayName: "Specifications & Architecture Documentation"
  author: "Tyler-R-Kendrick"
compatibility: claude, copilot, cursor

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

code
┌─────────────────────────────────────────────────────┐
│  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

NeedDiagram TypeTool
System context and containersC4 diagramsStructurizr DSL, Mermaid
Interaction sequencesSequence diagramsMermaid, PlantUML
Object-oriented structureClass / component diagramsUML, Mermaid
State machinesState diagramsMermaid, PlantUML, UML
Data modelsEntity-Relationship diagramsMermaid, ERD tools
Enterprise architectureTOGAF / ArchiMateArchi, Sparx EA
Data flow and processingFunctional diagramsDFD, Mermaid
General architectureDeclarative diagramsD2, Mermaid
Timelines and schedulingGantt chartsMermaid

Choosing the Right Document

NeedDocument Type
What to build and why (product view)PRD
How to build it (engineering view)TRD
Business justification and ROIBRD
Recording an architecture decisionADR
Proposing a significant changeRFC
Executable acceptance criteriaGherkin feature files
Markdown-based test specificationsGauge specs

Spec-Driven Development Workflow

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