xmlns="http://www.w3.org/2000/svg"

style="display:

/>

在当前复杂业务系统研发中，我们常陷入诸多困境：需求反复变更导致开发返工，AI辅助编程易出现幻觉生成无效代码，多人协作时重复开**费精力，上线后频繁出现回归bug，文档与代码脱节成为“无效资产”。

这些问题的核心，是缺乏一套统一可落地的研发范式，让需求、设计、开发、测试全流程形成闭环，而规格驱动开发（SDD，Spec-Driven

Development），正是解决这一痛点的关键。

很多开发者对SDD的认知停留在“先写文档再写代码”的表面，甚至觉得它是“额外负担”，尤其在工期紧张的复杂项目中，更倾向于跳过规格设计直接编码。

但事实上，SDD并非传统意义上的“文档绑架”，而是结合AI时代研发特点，形成的一套高效可落地的工程化方法。

本文结合OpenSpec这一主流SDD工具，从实操层面拆解SDD在复杂业务系统中的落地全流程，解答工具使用、流程设计、痛点解决等关键问题，帮助每一位开发者真正用好SDD，提升复杂系统研发效率与质量。

核心概念明确

SDD中的Spec（Specification，规格），本质是对业务需求、技术设计、实现细节的标准化描述，是整个研发流程的“唯一真理来源”。

与传统系统分析文档不同，SDD的规格文档是“活文档”——与代码同步迭代、可执行、可验证。

OpenSpec作为目前社区最热门的SDD工具之一，以轻量、敏捷、贴合AI辅助编程的特点，成为复杂业务系统落地SDD的首选。

接下来从工具实操入手，逐步深入SDD落地逻辑。

一、OpenSpec基础实操：从CLI命令到初始化OpenSpec，搭建基础（无本质区别），生成两个核心文件：

• project.md：记录项目上下文（技术栈、移动到changes/archive/的长期文档中。

• 核心参数：–yes

  -y（自动确认归档，适合AI执行；开发者手动归档可省略，避免误操作）。

• 适用场景：变更完成开发、测试、验证后执行。

  复杂项目建议每个迭代周期结束后，统一归档该迭代内的变更。

补充说明：OpenSpec还提供openspec

version（查看版本）、openspec

view（终端可视化进度条）、openspec

help（帮助文档）三个辅助命令，日常使用频率较低，需用时执行openspec

树”，才算真正理解SDD

很多开发者使用OpenSpec时，只记命令不看结构清晰，核心围绕“当前真理（specs）”和“变更提案（changes）”两大核心，以下拆解各结构（以openspec/结构约定、业务核心规则、OpenSpec使用规范等。

与GitHub

Spec

Kit的constitution.md（强调不可违背的原则）不同，project.md更务实、灵活，适合复杂业务系统的迭代需求。

使用建议：由技术负责人牵头编写，随项目迭代更新；新人加入先阅读project.md和openspec

list

--specs，快速了解项目规范和已实现功能；AI生成代码/规格时，会读取该文件确保符合项目约定。

（2）specs/（如artifact-notification：产物通知模块），每个模块包含两个核心文件：

• spec.md：核心规格文件，记录模块的需求（Requirement）和场景（Scenario），每个需求对应至少一个场景，场景需包含“前置条件（GIVEN）、触发动作（WHEN）、预期结果（THEN）”，确保需求可验证、可落地。

• design.md：可选文件，记录模块技术方案（技术选型、架构设计、数据流转等），复杂核心模块建议编写，方便后续维护迭代。

核心原则：specs/发起变更，归档后同步更新，确保历史可追溯。

（3）changes/（如feature-mobile-notification：移动端通知功能），每个变更（变更内）：记录增量规格，仅包含新增（ADDED）、修改（MODIFIED）、删除（REMOVED）的内容，减少冗余，便于归档时合并到主specs/（变更内）：存放已归档的变更（历史档案），建议按季度清理，避免结构的核心是“分离当前真理与变更提案”，通过specs/保障系统稳定性，changes/管控迭代需求，project.md规范项目约定，形成完整的规格管理体系，有效解决复杂项目的规格混乱、协作低效问题。

二、SDD落地的核心逻辑：为什么传统SDD失败，AI时代能成功？

很多开发者曾尝试SDD但最终流于形式，核心原因是传统SDD不符合研发实际，成为开发者负担；而AI辅助编程普及的今天，SDD迎来真正落地契机——核心是生产关系的改变：从“人写规格、人写代码”变为“AI写规格、人审规格、AI写代码”，彻底解决传统SDD痛点。

2.1

传统SDD失败的3个核心痛点

AI普及前，传统SDD的执行模式是“开发者写规格→写代码→测试维护”，在复杂业务系统中易陷入以下痛点：

（1）工期紧张下，规格文档无法考虑周全

复杂项目需求复杂、工期紧张，编写详细规格文档被视为“额外负担”，开发者往往潦草编写或跳过，导致规格与实际开发脱节，无法起到指导作用。

示例：某复杂系统支付模块开发，工期仅2周，需完成接口对接、订单生成、退款逻辑等功能，开发者无时间编写详细规格，凭经验开发导致上线后出现退款漏洞、状态同步异常等问题。

（2）需求变更频繁，规格文档快速过时

复杂项目需求不确定性强，开发过程中产品经理可能调整需求，导致原有规格文档快速过时；而传统SDD中，规格更新需手动修改并同步全员，耗时耗力，最终导致规格与代码脱节，成为无效资产。

示例：某电商系统商品列表功能，初始需求是显示名称、价格、图片，开发者编写规格后，产品经理要求新增销量、好评率显示，手动修改同步不及时，导致测试用例与需求不符、测试遗漏。

（3）规格文档成为负担，违背开发者心智

开发者的核心诉求是“快速实现功能、解决业务问题”，而传统SDD对规格文档的格式、描述要求严格，需编写大量样板内容，与开发者“务实”心智相悖，抵触情绪严重，最终敷衍了事。

2.2

AI时代SDD落地的核心逻辑：生产关系的颠覆

AI辅助编程（Cursor、Copilot、Claude等）普及后，研发生产关系发生根本性变化，SDD落地逻辑分为3步，贴合复杂项目实际，兼顾效率与质量：

第一步：AI起草规格文档，解放开发者精力

开发者无需手动编写繁琐规格，只需向AI输入简单需求描述（如“移动端支持PPT大纲生成完成通知，底部Snackbar样式，与PC端内容一致”），AI即可基于OpenSpec规范，自动生成proposal.md、tasks.md、spec.md等所有相关文档，格式规范、内容完整。

核心价值：解决规格编写耗时的痛点，开发者专注于需求审核和技术决策，繁琐文档工作交给AI，大幅提升效率。

第二步：人审核规格文档，把控核心质量

AI生成规格后，开发者的核心工作是“审核”，重点关注3点：需求场景是否完整（尤其是边缘场景）、任务拆分是否合理（可独立完成、可验证）、影响范围是否清晰（避免影响核心功能、出现回归bug）。

核心价值：人不可替代的决策环节，避免AI因上下文窗口限制出现幻觉，确保规格符合业务需求和项目规范。

第三步：AI生成代码，人审核代码，同步迭代规格

规格审核通过后，AI基于规格自动生成代码，开发者只需审核代码的合理性、规范性，无需从零编写；若需求变更，只需修改规格文档，AI即可重新生成代码，确保规格与代码同步迭代，解决规格过时痛点。

核心总结：AI做繁琐执行工作（写文档、写代码），人做核心决策工作（审规格、审代码），既解决传统SDD的负担问题，又保障研发质量，完美适配复杂项目“需求复杂、迭代频繁、工期紧张”的特点。

三、SDD落地实操：从需求提出到归档，完整流程拆解

掌握OpenSpec基础用法和SDD核心逻辑后，结合复杂业务系统实际研发场景，以“移动端支持PPT大纲生成完成通知”为例，拆解SDD从“需求提出”到“变更归档”的完整落地流程，确保每一步可落地、可复用。

3.1

需求提出：明确变更目的，发起变更提案

复杂项目中，任何需求变更（新增、修改、bug修复），需先明确目的，再通过OpenSpec发起变更提案，避免盲目开发。

核心是编写清晰的proposal.md，明确“为什么做、做什么、影响什么”。

具体步骤：

1. 需求梳理：产品提出“移动端支持PPT大纲生成完成通知”，梳理细节：PC端已实现，移动端目前禁用，需新增底部Snackbar样式，内容、交互与PC端一致，点击“去查看”切换到对应产物面板。

2. 发起变更：打开Cursor，输入指令“/openspec-proposal

   移动端支持PPT大纲生成完成通知，底部Snackbar样式，与PC端内容和交互一致”，AI自动在openspec/changes/，并生成proposal.md、tasks.md、spec.md等文件。

3. 审核提案：重点确认3点：

   • Why：变更原因清晰（PC端已实现，移动端缺失，用户体验不一致）；

   • What

     Changes：变更内容完整（移除移动端禁用、新增Snackbar组件等）；

   • Impact：影响范围清晰（受影响Specs：artifact-notification；受影响代码：src/xxx/Chat.tsx、新增MobileSnackbar组件）。

3.2

规格细化：完善spec.md，明确需求场景

提案审核通过后，细化spec.md，明确变更的需求和具体场景，为AI生成代码、后续测试提供标准。

核心是“每个需求对应至少一个场景，场景包含GIVEN-WHEN-THEN逻辑”。

具体步骤：

1. 完善需求描述：在变更移至archive，spec内容合并到主specs）。

2. 归档验证：执行openspec

   list

   --specs，确认变更内容同步到主specs；执行openspec

   list，确认变更已移除“进行中”状态。

3. 团队同步：将归档结果同步给产品、测试等成员，更新project.md（若有规范调整）。

总结：SDD落地流程本质是“需求提案→规格细化→任务拆分→开发实现→质量验证→归档闭环”的六步循环，每一步有明确目标和规范，借助AI提升效率，让人专注核心决策，确保需求落地的效率和质量。

四、SDD落地常见痛点与解决方案，避坑指南

复杂业务系统落地SDD时，即使掌握基础用法和流程，也可能遇到重复开发、归档报错、规格被覆盖等问题，若不及时解决，会影响落地效果甚至导致团队放弃SDD。

以下梳理5个常见痛点，分析原因并给出可落地解决方案：

4.1

痛点1：重复需求未被检测，多人协作时重复开发

• 场景：新人加入或多人协作时，开发已实现的功能，导致重复编写代码和规格。

• 原因：AI未正确读取已归档Specs，依赖终端命令（如openspec

  list

  --specs）执行，若命令失败，AI误以为需求未实现。

• 解决方案：修改OpenSpec提示词，强制AI先读取openspec/specs/的spec.md中无对应标题，归档时无法找到修改对象。

• 解决方案：

  • 临时解法：检查变更是否误归档，若已归档则移回changes/；手动在主specs/中添加对应需求标题（与变更中完全一致）；重新执行validate和归档命令。

  • 长期解法：修改提示词，让AI归档前检查MODIFIED需求在主specs中是否存在，不存在则停止归档并提示。

4.4

痛点4：变更需求后，归档的Spec被覆盖

• 场景：修改已归档需求（如PC端通知bug修复），标注MODIFIED，归档后原有Spec内容被覆盖，历史逻辑无法追溯。

• 原因：OpenSpec中MODIFIED本质是“覆盖操作”，与开发者“增量修改”心智不符。

• 解决方案：明确变更类型使用场景，避免滥用MODIFIED：

  • ADDED：新增需求/场景，不修改原有内容（如新增通知自动关闭场景）；

  • MODIFIED：替换原有场景全部内容，仅用于业务规则变更、bug修复（确认原有逻辑无需保留）；

  • REMOVED：删除需求/场景（如功能下线）。

• 补充建议：需保留历史逻辑时，采用“ADDED+REMOVED”组合：先删除原有场景，再新增修改后场景。

4.5

痛点5：AI生成的规格文档与项目规范不符

• 场景：AI生成的spec.md、proposal.md不符合项目规范（场景格式错误、任务拆分过粗等），需反复修改。

• 原因：AI未正确读取project.md规范，或提示词中规则不明确。

• 解决方案：

  • 优化project.md，明确规格编写规范（如场景需含GIVEN-WHEN-THEN）；

  • 优化提示词，强制AI遵循project.md规范，不符合则停止生成；

  • AI生成后，先执行validate命令检测格式，再手动审核规范符合性。

五、SDD工具选型：OpenSpec

GitHub

Kit，该怎么选？

复杂业务系统落地SDD，工具选型至关重要。

目前社区主流SDD工具为OpenSpec（Fission-AI）和GitHub

Spec

Kit（GitHub官方），两者目标一致（先写文档再写代码），但设计哲学和适用场景截然不同，选择错误会导致落地受阻。

以下从核心维度拆解对比，结合复杂业务场景给出选型建议：

5.1

核心维度对比（表格更清晰）

5.2

选型建议：结合复杂业务系统的核心诉求

复杂业务系统的核心研发诉求是“高效迭代、灵活适配、质量可控”，结合上述对比，给出以下选型建议：

优先选OpenSpec的情况（大部分复杂业务系统）

• 团队已使用AI辅助编程（如Cursor、Copilot），希望借助AI提升规格编写、代码生成效率；

• 项目迭代频繁，需求变更多，需要灵活适配的SDD工具，无需繁琐的流程约束；

• 现有项目结构复杂，希望SDD工具无侵入，快速集成，不影响现有开发节奏；

• 团队追求“效率与质量兼顾”，希望减少开发者的文档负担，专注核心业务实现。

可考虑GitHub

Spec

Kit的情况（少数特殊场景）

• 项目标准化要求极高（如大型开源项目、金融级核心系统），需要严格的流程约束，避免随意变更；

• 团队规模大，流程严谨，需要“宪法式”的规范文档，统一所有成员的研发行为；

• 不依赖AI辅助编程，更注重文档的规范性和严肃性，愿意投入更多人力编写和维护规格文档。

补充提醒

工具本身无优劣，核心是适配项目需求和团队研发模式。

对于大部分复杂业务系统而言，OpenSpec的“轻量、敏捷、AI友好”更贴合实际研发场景，能快速落地SDD，真正解决研发痛点；若项目对规范和约束的要求远超效率，可考虑GitHub

Spec

Kit。

六、总结：SDD落地的核心关键

SDD在复杂业务系统中落地，核心不是“写文档”，而是“建立一套以规格为核心的研发闭环”，借助AI的力量，让规格成为需求、设计、开发、测试全流程的“唯一真理来源”，解决返工、重复开发、文档脱节等痛点。

结合本文内容，SDD落地的3个核心关键的：

1. 选对工具：优先选择OpenSpec这类轻量、AI友好的工具，降低落地门槛，提升效率；

2. 理顺流程：严格遵循“需求提案→规格细化→任务拆分→开发实现→质量验证→归档闭环”的六步流程，确保每一步可落地、可追溯；

3. 用好AI：让AI做繁琐的执行工作（写文档、写代码），人做核心的决策工作（审规格、审代码），颠覆传统研发生产关系，彻底解决SDD的负担问题。

复杂业务系统的研发难度高、痛点多，SDD并非“万能药”，但它能为研发工作提供一套统一的、可落地的范式，帮助团队提升研发效率、降低质量风险。

希望本文能帮助每一位开发者真正用好SDD，让复杂业务系统的研发更高效、更可控。