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

8.4 KiB
Raw Permalink Blame History

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实践)

  • GitHub地址: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

  • 核心需求文件:

    • src/markdown/templates/requirements-template.md(需求模板)

    • examples/ 目录:feature-requirements.md(真实功能需求)

  • 文档特点:

    • 需求含功能概述、用户故事、验收标准、非功能需求、依赖项、风险点

    • 适配Claude Code自动生成代码与测试,文档即“代码契约”

3. OpenSpec(轻量级SDD框架,面向AI编码助手)

  • GitHub地址: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

  • 核心需求文件:

    • 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

    • 含多个AI项目的 spec.md 示例,覆盖Web应用、API、CLI工具

    • 需求文档含用例(Given/When/Then)、领域模型、序列图、数据库 schema

  2. 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

    • 面向AI Agent的SDD框架,specs/agent-behavior.spec.md 定义Agent能力与交互规则

四、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 生成)