# 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 生成)