229 lines
8.4 KiB
Markdown
229 lines
8.4 KiB
Markdown
# SDD Markdown 项目分类与需求参考
|
||
|
||
以下是一批采用**Spec-Driven Development (SDD)** 且在项目中直接存放**业务相关需求/规范Markdown文件**的AI开源项目,按工具/框架、实践示例分类,附核心需求文档位置与内容特点,方便你参考需求文档的写法与粒度。
|
||
|
||
---
|
||
|
||
### 一、官方/主流SDD工具与框架(含完整需求模板)
|
||
|
||
#### 1. GitHub Spec-Kit(官方SDD工具集)
|
||
|
||
- **GitHub地址**:[https://github.com/github/spec-kit](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](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](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](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实践)
|
||
|
||
- **GitHub地址**:[https://github.com/amaynez/kiro-style-sdd](https://github.com/amaynez/kiro-style-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](https://github.com/anthropics/claude-code-spec-workflow)
|
||
|
||
- **核心需求文件**:
|
||
|
||
- `src/markdown/templates/requirements-template.md`(需求模板)
|
||
|
||
- `examples/` 目录:`feature-requirements.md`(真实功能需求)
|
||
|
||
- **文档特点**:
|
||
|
||
- 需求含**功能概述、用户故事、验收标准、非功能需求、依赖项、风险点**
|
||
|
||
- 适配Claude Code自动生成代码与测试,文档即“代码契约”
|
||
|
||
#### 3. OpenSpec(轻量级SDD框架,面向AI编码助手)
|
||
|
||
- **GitHub地址**:[https://github.com/openspec-dev/openspec](https://github.com/openspec-dev/openspec)
|
||
|
||
- **核心需求文件**:
|
||
|
||
- `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项目)
|
||
|
||
- **GitHub地址**:[https://github.com/github/brain-mcp-server](https://github.com/github/brain-mcp-server)
|
||
|
||
- **核心需求文件**:
|
||
|
||
- `main.md`(项目核心规范,驱动所有代码生成)
|
||
|
||
- `specs/` 目录:`database.spec.md`、`api.spec.md`(模块级需求)
|
||
|
||
- **文档特点**:
|
||
|
||
- 开发者**不直接编辑代码**,仅维护Markdown规范,AI自动编译为Go代码
|
||
|
||
- 需求含**技术约束、数据存储、API行为、错误处理、性能指标**,粒度极细
|
||
|
||
---
|
||
|
||
### 三、其他优质SDD AI项目(含需求文档参考)
|
||
|
||
1. **sdd-ai-coding-examples**:[https://github.com/ainoya/sdd-ai-coding-examples](https://github.com/ainoya/sdd-ai-coding-examples)
|
||
|
||
- 含多个AI项目的 `spec.md` 示例,覆盖Web应用、API、CLI工具
|
||
|
||
- 需求文档含**用例(Given/When/Then)、领域模型、序列图、数据库 schema**
|
||
|
||
2. **ai-spec-driven-development**:[https://github.com/leandroms/ai-spec-driven-development](https://github.com/leandroms/ai-spec-driven-development)
|
||
|
||
- 提供SDD需求文档编写指南与模板,含**需求检查清单**(完整性、清晰度、可验证性)
|
||
|
||
3. **spec-driven-ai-agents**:[https://github.com/huggingface/spec-driven-ai-agents](https://github.com/huggingface/spec-driven-ai-agents)
|
||
|
||
- 面向AI Agent的SDD框架,`specs/agent-behavior.spec.md` 定义Agent能力与交互规则
|
||
|
||
---
|
||
|
||
### 四、SDD需求Markdown文档核心写法与粒度参考(从上述项目提炼)
|
||
|
||
#### 1. 标准结构(必选模块)
|
||
|
||
```Markdown
|
||
|
||
# 功能/项目需求规范(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 生成) |