Files
Obsidian/MyArticles/SDD Markdown 项目分类与需求参考.md
coco 8b94d76799 a
2026-07-21 13:57:15 +08:00

229 lines
8.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 生成)