software-specification
Spec-driven development workflow — requirements elicitation, SWEBOK-structured specs, template migration, spec validation against codebase.
- License 许可
- Unlicense
- 最近更新
- 2026-11-03
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- software-specification
- tags
- [ "specification", "requirements", "swebok", "ba", "grilling", "template-migration" ]
- description
- Spec-driven development workflow — requirements elicitation, SWEBOK-structured specs, template migration, spec validation against codebase.
02 资源文件 1
- 参考文档references/swebok-template-structure.md3.4 KB
03 SKILL.md 正文
Software Specification
Spec-driven development: write requirements before code, validate specs against implementation.
When to Use
- User wants to define requirements for a new project
- User has old specs that need restructuring into a standard template
- User wants to validate specs against actual codebase
- User mentions "spec-driven development" or "requirements first"
Workflow
Phase 1: Requirements Elicitation (Grilling)
Run structured interview rounds to extract requirements. Use grill-me skill methodology:
Round 1 — Core Problem:
- What does "done" look like? (3-5 core actions)
- Who is the user/persona?
- Why not existing solutions?
- What's the MVP line?
Round 2 — Stress-Test Design:
- Find contradictions in answers
- Challenge naming/semantics
- Identify gaps between vision and MVP
Round 3 — Architecture:
- API contract / interface design
- Data ownership / isolation
- Where it fits in existing stack
- Why this architecture vs alternatives
Round 4 — Data Model:
- Review for redundancy (can fields be derived/computed?)
- Naming consistency
- Enum vs string trade-offs
Round 5 — API Contract:
- Propose endpoints
- Pagination / filtering
- Response format
- Error handling
Round 6 — Decisions:
- Consolidate all decisions
- Set development order: spec → test → code
Phase 2: Spec Document Creation
Create structured spec documents using SWEBOK template format:
project-specs/
├── 01_requirement/
│ ├── 011_business_objective.md — SMART objectives
│ ├── 012_user_stories.md — User stories with ACs
│ ├── 013_acceptance_criteria.md — Given/When/Then format
│ └── 014_stakeholder_analysis.md — Stakeholder matrix
├── 02_design/
│ ├── 021_architecture_decision_records.md — ADRs
│ ├── 022_API_specification.md — REST endpoints
│ ├── 023_database_schema_DDL.md — PostgreSQL DDL
│ ├── 024_ERD.md — Mermaid ERD
│ └── 025_software_architecture_document.md — Architecture
├── 03_construction/
│ ├── 031_README_developer_guide.md — Setup instructions
│ ├── 033_dependency_manifest.md — Package versions
│ ├── 034_commit_messages_changelog.md — PR/commit log
│ └── 035_coding_standards_development.md — Code style
├── 04_testing/
│ ├── 041_test_plan.md — Strategy + scope
│ └── 042_test_cases.md — Test cases from ACs
├── 05_devops/
│ └── 053_release_notes.md — Release notes
└── 07_pm/
├── 071_risk_register.md — Risk log
└── 072_meeting_minutes.md — Daily logs
Key format rules:
- YAML frontmatter with document_type, version, status, tags, standard_ref
- Tables for structured data (not prose)
- Wikilinks for cross-references
- Mermaid for diagrams (ERD, architecture, flowcharts)
Phase 3: Template Migration
When user has old specs in non-standard format:
- Read old specs to understand content
- Read new template to understand structure
- Map old content to new structure
- Transform with proper frontmatter and formatting
- Create placeholder sections for TODO items
Mapping strategy:
| Old Content | New Location |
|---|---|
| Project overview | 011_business_objective + 021_ADR |
| Data model | 023_database_schema_DDL + 024_ERD |
| API spec | 022_API_specification |
| Business logic | 013_acceptance_criteria |
| Daily logs | 072_meeting_minutes |
Phase 4: Spec Validation
After implementation exists, validate specs against actual codebase:
- Read GitHub repo structure (mcp__github__get_file_contents)
- Check actual dependencies (go.mod, package.json)
- Verify data model matches code structs
- Confirm API endpoints match handler code
- Update specs with actual versions and findings
What to check:
- Dependency versions (go.mod, package.json)
- Data model structs (model/.go, types/.ts)
- Handler implementations (handler/.go, pages/.tsx)
- Test coverage (test files)
- Configuration (ports, env vars)
Pitfalls
- Don't over-spec for MVP — placeholder files are fine for future work
- Don't assume tech stack — read actual code before updating specs
- Don't skip validation — specs that don't match code are worse than no specs
- Use tables, not prose — structured data is easier to maintain and reference
- Frontmatter matters — consistent YAML enables tooling and filtering
Related Skills
grill-me— Requirements elicitation methodologyplan— Planning mode for implementationtest-driven-development— Test-first development
04 同仓库更多 Skills
project-spec-docs
Fill/update project_spec docs (templates, MM handoffs).
penpot-mcp
Penpot MCP: connect, verify, and fix streaming via nginx.
nginx-streaming-proxy
Configure nginx for streaming endpoints (SSE, MCP, WS).
branding-ci
Use for brand/CI identity, style guides, and brand docs.
yuanbao
Yuanbao (元宝) groups: @mention users, query info/members.
slidev
Create and present web-based slidedecks for developers using Slidev with Markdown, Vue components, code highlighting, animations, and interactive features. Use when building technical presentations, conference talks, code walkthroughs, teaching materials, or developer decks.