8.4 KiB
SDD Markdown 项目分类与需求参考
以下是一批采用Spec-Driven Development (SDD) 且在项目中直接存放业务相关需求/规范Markdown文件的AI开源项目,按工具/框架、实践示例分类,附核心需求文档位置与内容特点,方便你参考需求文档的写法与粒度。
一、官方/主流SDD工具与框架(含完整需求模板)
1. GitHub Spec-Kit(官方SDD工具集)
-
GitHub地址:https://github.com/github/spec-kit
-
核心需求文件:
-
specs/目录下的*.spec.md(功能规范主文件) -
templates/目录:spec-template.md(标准需求模板)、requirements-template.md
-
-
文档特点:
-
强制结构化:项目概述、用户故事、验收标准、非功能需求、边界条件、接口定义、测试用例
-
支持AI直接解析,用于Copilot生成代码与任务拆解
-
示例:
specs/feature-example.spec.md含完整功能需求+用例+验证点
-
2. liatrio-labs/spec-driven-workflow(SDD工作流模板)
-
GitHub地址:https://github.com/liatrio-labs/spec-driven-workflow
-
核心需求文件:
-
prompts/目录:define-intent.prompt.md(需求定义)、generate-spec.prompt.md(规范生成) -
examples/目录:完整SDD项目示例(含spec.md、plan.md、tasks.md)
-
-
文档特点:
-
需求聚焦可演示标准(Demo Criteria),明确“完成即验收”
-
含上下文校验标记(SDD1️⃣-SDD4️⃣),确保AI理解核心约束
-
3. gotalab/cc-sdd(多AI代理兼容的SDD框架)
-
GitHub地址:https://github.com/gotalab/cc-sdd
-
核心需求文件:
-
templates/目录:requirements.md、design.md、tasks.md全套模板 -
examples/目录:真实项目需求文档(如todo-app/requirements.md)
-
-
文档特点:
-
需求→设计→任务全链路Markdown,适配Claude、Cursor、Copilot等
-
需求含业务价值、用户场景、异常处理、性能指标,无冗余配置文件
-
4. Ataden/SDD_Flow(AI编码SDD框架)
-
GitHub地址:https://github.com/Ataden/SDD_Flow
-
核心需求文件:
-
templates/目录:requirements-document.md(完整需求模板) -
docs/目录:sdd-workflow.md(流程规范)、example-project/(含需求示例)
-
-
文档特点:
-
需求分业务需求、功能需求、非功能需求、数据需求、接口需求五大模块
-
附Mermaid图、API定义、测试计划,形成可执行规范
-
二、SDD实践示例项目(含真实业务需求文档)
1. amaynez/kiro-style-sdd(Kiro IDE风格SDD实践)
-
核心需求文件:
-
examples/目录:requirements.md、design.md、tasks.md(完整项目示例) -
templates/目录:极简需求模板(聚焦“做什么”而非“怎么做”)
-
-
文档特点:
-
需求文档无技术实现细节,仅定义功能行为与验收条件
-
示例:
todo-app/requirements.md含用户故事、边界场景、数据模型、验证步骤
-
2. claude-code-spec-workflow(Claude Code SDD实战)
-
GitHub地址:https://github.com/anthropics/claude-code-spec-workflow
-
核心需求文件:
-
src/markdown/templates/requirements-template.md(需求模板) -
examples/目录:feature-requirements.md(真实功能需求)
-
-
文档特点:
-
需求含功能概述、用户故事、验收标准、非功能需求、依赖项、风险点
-
适配Claude Code自动生成代码与测试,文档即“代码契约”
-
3. OpenSpec(轻量级SDD框架,面向AI编码助手)
-
核心需求文件:
-
specs/目录:*.spec.md(项目规范主文件) -
templates/目录:project-spec.md、feature-spec.md(项目/功能需求模板)
-
-
文档特点:
-
需求文档可验证,含自动检查点与验收规则
-
示例:
blog-app/specs/core-features.spec.md含功能列表、用例、接口、数据 schema
-
4. GitHub Brain MCP Server(SDD驱动的Go项目)
-
核心需求文件:
-
main.md(项目核心规范,驱动所有代码生成) -
specs/目录:database.spec.md、api.spec.md(模块级需求)
-
-
文档特点:
-
开发者不直接编辑代码,仅维护Markdown规范,AI自动编译为Go代码
-
需求含技术约束、数据存储、API行为、错误处理、性能指标,粒度极细
-
三、其他优质SDD AI项目(含需求文档参考)
-
sdd-ai-coding-examples:https://github.com/ainoya/sdd-ai-coding-examples
-
含多个AI项目的
spec.md示例,覆盖Web应用、API、CLI工具 -
需求文档含用例(Given/When/Then)、领域模型、序列图、数据库 schema
-
-
ai-spec-driven-development:https://github.com/leandroms/ai-spec-driven-development
- 提供SDD需求文档编写指南与模板,含需求检查清单(完整性、清晰度、可验证性)
-
spec-driven-ai-agents:https://github.com/huggingface/spec-driven-ai-agents
- 面向AI Agent的SDD框架,
specs/agent-behavior.spec.md定义Agent能力与交互规则
- 面向AI Agent的SDD框架,
四、SDD需求Markdown文档核心写法与粒度参考(从上述项目提炼)
1. 标准结构(必选模块)
# 功能/项目需求规范(v1.0)
## 1. 项目/功能概述
- 业务价值:解决什么问题、为谁服务
- 范围:包含/不包含的功能
- 目标:可量化的成功指标
## 2. 用户故事(User Stories)
- As a [用户角色], I want [功能], so that [价值]
- 示例:As a user, I want to create a todo item, so that I can track my tasks
## 3. 功能需求(Functional Requirements)
### 3.1 核心功能
- 功能1:详细行为描述(输入、输出、流程)
- 功能2:边界条件(如空输入、重复数据)
### 3.2 非功能需求(Non-Functional Requirements)
- 性能:响应时间、吞吐量
- 安全:权限、数据加密
- 可用性:兼容性、错误处理
- 可维护性:代码规范、文档要求
## 4. 接口与数据定义
- API:请求/响应格式、状态码
- 数据模型:字段、类型、约束
- 外部依赖:第三方服务、库版本
## 5. 验收标准(Acceptance Criteria)
- 场景1:Given [前提], When [操作], Then [结果]
- 场景2:异常场景验证(如网络失败、权限不足)
## 6. 测试计划
- 测试类型:单元测试、集成测试、E2E测试
- 测试用例:关键场景覆盖
- 验证方式:自动/手动测试
## 7. 修订历史
- 版本、日期、修改内容、作者
2. 粒度原则(从项目实践总结)
-
最小粒度:每个需求点可独立验证,无模糊描述(避免“优化性能”等笼统表述)
-
业务聚焦:仅写“做什么”,不写“怎么做”(技术实现由AI/开发者决定)
-
AI友好:使用结构化标题、列表、代码块,避免长段落;关键约束用加粗标注
-
可执行:验收标准可转化为测试用例,确保“文档即契约”
五、快速参考清单(按项目类型)
| 项目类型 | 核心需求文件 | 推荐参考项目 |
|---|---|---|
| AI编码工具 | spec.md、requirements.md |
GitHub Spec-Kit、cc-sdd |
| Web应用/API | api.spec.md、features.spec.md |
Brain MCP Server、OpenSpec |
| AI Agent | agent-behavior.spec.md |
spec-driven-ai-agents |
| 轻量级项目 | simple-spec.md(聚焦核心功能) |
kiro-style-sdd |
| 需要我从这些项目里挑1-2个最典型的,把它们的需求Markdown文档完整提取并标注关键写法要点吗? |
(注:文档部分内容可能由 AI 生成)