在当前复杂业务系统研发中，我们常陷入诸多困境：需求反复变更导致开发返工，AI 辅助编程易出现幻觉生成无效代码，多人协作时重复开发浪费精力，上线后频繁出现回归 bug，文档与代码脱节成为'无效资产'。这些问题的核心，是缺乏一套统一可落地的研发范式，让需求、设计、开发、测试全流程形成闭环。规格驱动开发（SDD，Spec-Driven Development）正是解决这一痛点的关键。
很多开发者对 SDD 的认知停留在'先写文档再写代码'的表面，甚至觉得它是'额外负担'，尤其在工期紧张的复杂项目中，更倾向于跳过规格设计直接编码。但事实上，SDD 并非传统意义上的'文档绑架'，而是结合 AI 时代研发特点，形成的一套高效可落地的工程化方法。
本文结合 OpenSpec 这一主流 SDD 工具，从实操层面拆解 SDD 在复杂业务系统中的落地全流程，解答工具使用、流程设计、痛点解决等关键问题，帮助每一位开发者真正用好 SDD，提升复杂系统研发效率与质量。
核心概念明确
SDD 中的 Spec（Specification，规格），本质是对业务需求、技术设计、实现细节的标准化描述，是整个研发流程的'唯一真理来源'。与传统系统分析文档不同，SDD 的规格文档是'活文档'——与代码同步迭代、可执行、可验证。
OpenSpec 作为目前社区最热门的 SDD 工具之一，以轻量、敏捷、贴合 AI 辅助编程的特点，成为复杂业务系统落地 SDD 的首选。接下来从工具实操入手，逐步深入 SDD 落地逻辑。
一、OpenSpec 基础实操：从 CLI 命令到目录结构，快速上手不踩坑
复杂业务系统落地 SDD 的第一步，是选择合适工具并掌握其基础用法。OpenSpec 的核心优势是'轻量无侵入'，无需改造现有项目结构，通过简单 CLI 命令即可快速集成，且完美适配 AI IDE（如 Cursor），让 AI 成为撰写规格、生成代码的辅助，而非负担。
1.1 CLI 命令实操：6 个核心命令，覆盖全研发流程
OpenSpec 的 CLI 命令设计简洁，核心逻辑与 Git 类似，分为'初始化、日常开发、质量控制、归档'四大场景，日常常用命令不超过 3 个，其余可由 AI 代劳。
关键区分：AI 负责'创造'（写规格文档、生成代码）；CLI 负责'管理'（初始化工具、查看进度、验证格式、归档变更），分工明确、互不冲突。
以下逐一拆解核心 CLI 命令的用法、行为及适用场景，结合复杂业务场景给出使用建议：
（1）项目初始化：openspec init
- 作用：在当前项目目录初始化 OpenSpec，搭建基础目录结构（引入 OpenSpec 的第一步，唯一需手动执行的初始化操作）。
- 具体行为：自动创建
.openspec/或openspec/目录（无本质区别），生成两个核心文件：project.md：记录项目上下文（技术栈、目录约定、业务核心规则等），相当于项目'备忘录'，方便新人上手和 AI 理解项目规范；AGENTS.md：AI 说明书，配置 AI 工具（Cursor、Copilot 等）的提示词规则，确保 AI 生成内容符合项目规范。
- 适用场景：引入 OpenSpec 到现有复杂项目、新建项目启用 SDD 模式时。建议项目初始化阶段执行，避免后续规格文档混乱。
（2）配置更新：openspec update
- 作用：更新 OpenSpec 配置文件和 AGENTS.md 文档，确保 AI 提示词始终最新。
- 具体行为：升级 OpenSpec 的 npm 包、修改项目规范需同步 AI 提示词时，自动检测配置差异，更新 AGENTS.md 提示词规则及项目基础配置。
- 适用场景：升级 OpenSpec 版本后、AI 生成内容不符合项目规范时（大概率提示词过时）。复杂项目建议每 1-2 个迭代周期执行一次，确保 AI 与项目规范同步。
（3）日常开发核心：openspec list
- 作用：列出当前所有'进行中'的变更（Active Changes），日常开发使用频率最高。
- 具体行为：显示未归档的变更 ID、变更状态，以及每个变更对应 tasks.md 的任务完成进度（如 [2/5]），便于了解需求开发进度、避免重复开发/任务遗漏。
- 核心参数：
--specs，列出已归档的 Specs（项目当前'真理来源'），快速查看已实现功能规格，避免重复开发。 - 适用场景：日常查看任务进度、未完成需求，建议每天开工前、下班前各执行一次。
（4）变更详情查看：openspec show
- 作用：输出某个具体变更的详细信息（通常为 JSON 格式）。
- 具体行为：主要供 AI 使用（生成代码时参考规格细节，后台自动执行），开发者手动使用场景较少（仅排查变更细节时）。
- 核心参数：
--json（强制 JSON 格式，方便 AI 解析）；--deltas-only（仅显示变更部分，忽略未变更内容）。
（5）质量控制：openspec validate
- 作用：检查某个变更的 Spec 文档格式是否标准、符合 OpenSpec 规范，是保障规格文档质量的核心命令。
- 具体行为：从三个维度检查：Markdown 的 Frontmatter 正确性、tasks.md 未完成任务、proposal.md 结构完整性。
- 核心参数：
--strict（严格模式，任何小格式错误都报错，推荐 AI 使用；开发者可按需关闭，建议尽量遵循）。 - 适用场景：每个变更开发完成后、归档前必须执行；AI 生成规格文档后建议执行，排查格式错误。
（6）结束与归档：openspec archive
- 作用：将已完成的变更'合并'到主 Specs 库，标志需求正式落地，是 SDD 流程闭环的最后一步。
- 具体行为：将 changes/目录移动到 changes/archive/目录，同时将变更中 spec.md 的内容合并更新到 openspec/specs/目录的长期文档中。
- 核心参数：
--yes / -y（自动确认归档，适合 AI 执行；开发者手动归档可省略，避免误操作）。 - 适用场景：变更完成开发、测试、验证后执行。复杂项目建议每个迭代周期结束后，统一归档该迭代内的变更。
补充说明：OpenSpec 还提供 openspec version（查看版本）、openspec view（终端可视化进度条）、openspec help（帮助文档）三个辅助命令，日常使用频率较低，需用时执行 openspec help 即可。
1.2 目录结构解析：看懂'目录树'，才算真正理解 SDD
很多开发者使用 OpenSpec 时，只记命令不看目录结构，导致后续规格混乱、归档出错。OpenSpec 目录结构清晰，核心围绕'当前真理（specs）'和'变更提案（changes）'两大核心，以下拆解各目录、文件的作用及规范使用方法：
OpenSpec 标准目录结构（以 openspec/目录为例）
openspec/
├── project.md # Project conventions（项目约定）
├── specs/ # Current truth - what IS built（当前真理：已实现的功能）
│ └── [capability]/ # Single focused capability（单一核心能力/模块）
│ ├── spec.md # Requirements and scenarios（需求和场景）
│ └── design.md # Technical patterns（技术方案）
├── changes/ # Proposals - what SHOULD change（变更提案：待实现/正在实现的变更）
│ ├── [change-name]/ # 具体变更（以变更名称/ID 命名，如 feature-mobile-notification）
│ │ ├── proposal.md # Why, what, impact（变更原因、内容、影响范围）
│ │ ├── tasks.md # Implementation checklist（实现任务清单）
│ │ ├── design.md # Technical decisions(optional)（技术决策，可选）
│ │ └── specs/ # Delta changes（增量变更，仅记录变更部分）
│ │ └── [capability]/
│ │ └── spec.md # ADDED/MODIFIED/REMOVED（新增/修改/删除的规格）
│ └── archive/ # Completed changes（已完成归档的变更）
（1）project.md：项目的'说明书'，不可或缺
记录项目核心约定，包括技术栈、目录结构约定、业务核心规则、OpenSpec 使用规范等。与 GitHub Spec Kit 的 constitution.md（强调不可违背的原则）不同，project.md 更务实、灵活，适合复杂业务系统的迭代需求。
使用建议：由技术负责人牵头编写，随项目迭代更新；新人加入先阅读 project.md 和 openspec list --specs，快速了解项目规范和已实现功能；AI 生成代码/规格时，会读取该文件确保符合项目约定。
（2）specs/目录：项目的'唯一真理来源'，核心中的核心
存放项目当前已实现的所有功能规格，是研发流程的'真理基准'，以'capability（核心能力/模块）'为单位划分子目录（如 artifact-notification：产物通知模块），每个模块包含两个核心文件：
spec.md：核心规格文件，记录模块的需求（Requirement）和场景（Scenario），每个需求对应至少一个场景，场景需包含'前置条件（GIVEN）、触发动作（WHEN）、预期结果（THEN）'，确保需求可验证、可落地。design.md：可选文件，记录模块技术方案（技术选型、架构设计、数据流转等），复杂核心模块建议编写，方便后续维护迭代。
核心原则：specs/目录内容不可随意修改，任何已实现功能的修改，需通过 changes/目录发起变更，归档后同步更新，确保历史可追溯。
（3）changes/目录：变更的'工作区'，管控所有迭代需求
存放所有待实现、正在实现的变更提案，以'change-name（变更名称/ID）'为单位划分子目录（如 feature-mobile-notification：移动端通知功能），每个变更目录包含 4 个核心文件（design.md 可选）：
proposal.md：变更'申请书'，说明变更的原因（Why）、内容（What）、影响范围（Impact），帮助团队快速理解变更目的，避免盲目开发。tasks.md：实现任务清单，将变更拆分为'小而具体、可验证'的子任务，标注进度（[x]已完成、[]未完成），复杂项目建议拆分颗粒度细一些，便于把控进度。design.md：可选文件，记录变更的技术决策（新选型、复杂逻辑等）。specs/目录（变更内）：记录增量规格，仅包含新增（ADDED）、修改（MODIFIED）、删除（REMOVED）的内容，减少冗余，便于归档时合并到主 specs/目录。
archive/目录（变更内）：存放已归档的变更（历史档案），建议按季度清理，避免目录过大影响查询效率。
总结：OpenSpec 目录结构的核心是'分离当前真理与变更提案'，通过 specs/保障系统稳定性，changes/管控迭代需求，project.md 规范项目约定，形成完整的规格管理体系，有效解决复杂项目的规格混乱、协作低效问题。
二、SDD 落地的核心逻辑：为什么传统 SDD 失败，AI 时代能成功？
很多开发者曾尝试 SDD 但最终流于形式，核心原因是传统 SDD 不符合研发实际，成为开发者负担；而 AI 辅助编程普及的今天，SDD 迎来真正落地契机——核心是生产关系的改变：从'人写规格、人写代码'变为