OpenSpec应用与实践：AI 时代的规范驱动开发(SDD)

引言：从 Prompt Engineering 到 Spec-driven Development

在 AI 辅助编程快速普及的今天，开发者们正在经历从“手写代码”到“对话编程”的范式转移。作为开发者，我们不怕写代码，怕的是反复修改那些因为理解偏差而产生的“垃圾代码”。

为了解决这一痛点，OpenSpec 应运而生。它倡导一种全新的开发模式——Spec-driven Development (SDD，规范驱动开发)。其本质是把我们脑子里的架构图，翻译成 AI 能听懂的“说明书”，让 AI 编码助手能够像资深工程师一样，严格遵循项目规约执行任务。

一、什么是 OpenSpec？

1.1 定义

OpenSpec 是由 Fission AI 发起的一个开源项目，旨在为 AI 编码助手（如 Cursor、Windsurf 等）提供一套通用的规范定义标准。如果说 OpenAPI 定义了机器之间如何通信，那么 OpenSpec 就定义了人类开发者如何与 AI 助手深度协同。

1.2 核心理念：SDD

SDD 的核心思想是将开发意图转化为结构化的“规范（Spec）”，而非零散的“提示词（Prompt）”。

OpenSpec 的设计哲学强调：

• Fluid not rigid：流程流畅而非僵化
• Iterative not waterfall：敏捷迭代而非瀑布式
• Easy not complex：简单易用而非过度设计
• Built for brownfield：不仅适用于新项目，也能无缝接入存量项目

二、为什么需要 OpenSpec？

维度	传统 Prompt 模式	OpenSpec (SDD) 模式
表达方式	零散、即兴的自然语言	结构化、持久化的规范文档
复用性	差，每次对话需重复描述	强，一次编写，全局生效
准确度	波动较大，易受上下文干扰	高，严格遵循规则，减少幻觉
新人接入	需口传心授大量规范	读取 Spec 即可快速上手

三、新版核心：Artifact-Guided Workflow

OpenSpec 最新版引入了**“制品驱动工作流” (Artifact-Guided Workflow)**，不再仅仅依赖静态的配置文件，而是将开发过程拆解为四个动态维护的关键制品：

1. proposal.md (Why & What)：变更提案。明确为什么要做这个变更，以及变更的核心目标范围。
2. specs/ (Requirements)：详细规范。包含具体的业务规则、上下文约束、数据字典等（即原有的 Instructions/Rules/Context 体系）。
3. design.md (How)：技术设计。定义技术实现路径、架构决策与依赖关系。
4. tasks.md (Checklist)：任务清单。颗粒度极细的可执行步骤，用于指导 AI 逐步实施。

这种结构让 AI 从“一次性生成”转变为“分步骤思考”，大幅提升了复杂任务的成功率。

---

四、实战演练：CLI 交互式开发

假设你要为一个现有的前端项目添加“暗黑模式 (Dark Mode)”，OpenSpec 的 CLI 工作流能让你体验到“结对编程”的快感。

4.1 安装与初始化

首先，在全局安装 OpenSpec CLI 并初始化项目：

# 需要 Node.js 20.19.0+
npm install -g @fission-ai/openspec@latest

cd your-project
openspec init

4.2 交互式开发全流程

Step 1: 提出变更 (/opsx:propose)

在 IDE 的终端或 AI 助手中输入指令：

/opsx:propose add-dark-mode

AI 会自动在 openspec/changes/add-dark-mode/ 目录下生成四个核心制品。你可以打开 proposal.md 或 design.md 进行审查，确保 AI 理解了你的意图（例如：是否跟随系统主题？使用 CSS 变量还是 Tailwind？）。

Step 2: 执行实现 (/opsx:apply)

确认设计无误后，下达执行指令：

/opsx:apply

AI 会读取 tasks.md，逐条执行编码任务，并实时反馈进度：

• ✓ 1.1 Add theme context provider
• ✓ 1.2 Create toggle component
• ✓ 2.1 Add CSS variables
• ✓ …

Step 3: 归档变更 (/opsx:archive)

功能验收通过后，将本次变更归档：

/opsx:archive

系统会将当前的变更记录移入 archive 目录，并更新全局 Specs，为下一次迭代做好准备。

4.3 传统 .spec 文件怎么写？

虽然有了 CLI，但在 specs/ 目录下，我们依然可以使用 .spec (YAML) 文件来定义持久化的业务规则。例如前文提到的 Java Web 规范：

name: JavaEnterpriseWebSpec
description: 约束 Spring Boot 项目的 Controller 与 Service 层开发规范

rules:
  - name: ResponseWrapper
    pattern: "所有 REST 接口必须使用 Result<T> 类包装返回"
    details: "禁止直接返回 DTO 或 List，必须使用 Result.success(data)"

  - name: Validation
    pattern: "入参必须使用 @Validated 校验"
    details: "DTO 字段需包含 @NotBlank, @Min 等注解"

  - name: DynamicMapping
    pattern: "报备模板需动态映射数据字典"
    details: "禁止在代码中硬编码状态码，需通过 DictionaryService 动态获取"

context:
  - type: class_definition
    name: Result
    content: |
      public class Result<T> {
          private int code;
          private String msg;
          private T data;
      }

examples:
  - input: "创建一个实名报备的保存接口"
    output: |
      @PostMapping("/save")
      public Result<Long> save(@Validated @RequestBody ReportDTO dto) {
          log.info("开始报备: {}", dto.getIdCard());
          return Result.success(reportService.save(dto));
      }

4.4 工具链集成

• Cursor: 目前 OpenSpec 官方提供工具将规范转换并应用到 .cursorrules 中。
• Windsurf: 在项目的 IDE 策略配置中引用 .spec 目录。
• CI/CD: 在代码合并前，利用 OpenSpec CLI 检查生成的代码是否偏离了规范。

---

五、如何编写高质量的 OpenSpec？

1. 原子化规则：每条规则只讲一件事（如：只管日志，或只管异常）。
2. 示例驱动 (Few-shot)：提供 1-2 个正例和负例，AI 的理解准确率能提升 80% 以上。
3. 动态迭代：Spec 不是死文档，应随着架构演进而版本化（Version Control）。
4. 避开“僵尸文档”：结合项目中的数据字典，让 Spec 具备动态业务上下文，而非陈旧的描述。

六、结语：迈向 AI 原生开发

OpenSpec 不仅仅是一个工具，更代表了一种 AI 原生 (AI-Native) 的开发思维。在未来，编写高质量的 Spec 将成为开发工程师的核心竞争力，它让我们从繁琐的重复劳动中解脱，真正回归到业务设计的本质。

---

参考资源：

• OpenSpec GitHub 仓库
• OpenSpec 官方文档