AI 辅助开发中的 SDD 与 OpenSpec 实战指南

1 问题背景：AI 写代码很快，对齐意图却很慢

AI 编程助手已经能在一轮对话里生成数百行可用代码。真正拖慢交付的，往往不是生成速度，而是意图对齐：需求只存在于聊天窗口里，改着改着就偏离了最初目标；换一个人、换一个 Agent、开一个新会话，上下文随之消失；PR 里 reviewer 只能对着 diff 猜"这段逻辑到底想解决什么问题"。

用 AI 辅助编程一段时间后，上述问题会以几种典型形态反复出现：

• 花了两段话描述功能，AI 听起来像是懂了，写出来的代码却跑偏了。纠偏几轮后，上下文窗口已被消耗大半。
• 好不容易和 AI 对齐了设计思路，实现完一个功能。过两天开新对话继续下一个功能，之前的讨论、决策、设计全部蒸发。
• 功能做到一半被打断——开会、下班、切去修 Bug。回来打开新对话，AI 完全不知道之前做到哪了。

这些痛点的根源相同：AI 的"记忆"只存在于当前对话中。对话关了，一切归零。

Spec-Driven Development（SDD，规格驱动开发）针对的正是这一缺口。它的核心判断是：在 AI 时代，规格（Specification）应重新成为软件开发的权威来源，代码则是规格的实现产物或验证对象——而不是反过来从代码里反推意图。

OpenSpec 是目前 SDD 工具链里关注度较高的一款开源框架（GitHub 上已有 5 万+ star）。它把 SDD 落到仓库里的 Markdown 规格、变更提案和 slash 命令工作流上，目标是在不引入重型流程的前提下，让"先对齐、再编码"成为日常习惯。思路很朴素：既然对话会消失，那就把重要的东西写成文件——需求是什么、技术方案怎么设计、实现步骤有哪些，全部以 Markdown 持久化在项目里。

2 核心结论

SDD 不是"多写几份文档"，而是把意图 → 规格 → 实现串成一条可追溯的链路。OpenSpec 在这条链路上扮演的是轻量级规格层：规格与代码同仓存放，每次变更产生可 review 的 spec delta，Agent 通过 slash 命令读写这些工件，而不是只在对话里"口头约定"。

如果你已经在用 Cursor、Claude Code、Copilot 等工具，OpenSpec 的价值在于：把跨会话、跨 Agent 的上下文沉淀到 Git 里，而不是绑定某一家 IDE 或某一种模型。AI 每次开工，不是从你的口头描述出发，而是从这份"共识文档"出发。

3 SDD 是什么：三种成熟度

学术界和工程实践通常把 SDD 分成三个层次（参见 arXiv 论文 Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants）。理解这三层，有助于判断自己需要多"重"的规格纪律。

OpenSpec 主要服务 Spec-Anchored 这一档：规格不是写完就扔的 PRD，而是随变更演进、可 diff、可归档的 living documentation。它并不强迫你走到 Spec-as-Source 那种"代码完全不可手改"的极端。

与"提示词工程"的区别也在这里：提示词是单次对话的战术输入；SDD 是跨会话的方法论——规格是可版本化、可 review、可继承的工程工件。

4 通用 SDD 工作流

无论用 OpenSpec、GitHub Spec Kit 还是 Agent 原生能力，SDD 通常都收敛到四个阶段。每个阶段产出一个工件，约束下一阶段，形成从意图到实现的 accountability chain。

flowchart LR
    A[Specify<br/>定义做什么] --> B[Plan<br/>决定怎么做]
    B --> C[Tasks<br/>拆成可验证单元]
    C --> D[Implement<br/>实现并对照规格]
    D --> E{通过?}
    E -->|否| A
    E -->|是| F[Archive / Sync<br/>合并规格变更]

Specify：捕获用户故事、验收标准、边界条件。重点写"做什么"和"不做什么"，而不是过早绑定实现细节。

Plan：在规格约束下确定技术方案——数据结构、模块边界、依赖关系、风险点。

Tasks：把工作拆成可独立验证的小任务。对大模型而言，原子化任务能显著降低"一次生成太多、漏掉边界"的概率。

Implement：按任务实现，并对照规格做验证。若实现过程中发现规格有误，应先回改规格，而不是让代码悄悄偏离文档。

OpenSpec 把这四个阶段映射为 proposal → specs → design → tasks → apply，但 OPSX 工作流刻意不做"阶段锁"——实现过程中发现设计有误，可以随时回改 specs 或 design，再继续 apply。

5 OpenSpec 的定位与设计哲学

OpenSpec 由 Fission-AI 维护，MIT 开源。官方自述的设计取向可以概括为五条：

• fluid not rigid — 灵动而非僵化
• iterative not waterfall — 迭代优先，拒绝瀑布流程
• easy not complex — 分钟级上手，而非天级流程搭建
• built for brownfield — 面向已有代码库，而非只服务 greenfield
• scalable — 从个人项目到团队 PR review 均可扩展

与 Agent 内置的 Plan Mode 相比，OpenSpec 解决的是跨会话、跨人、跨 Agent 的持久化规划层——Plan Mode 擅长单次对话内的拆解，OpenSpec 则把规划结果写进仓库，成为团队共享上下文。

OpenSpec 官方推荐渐进式严格：日常变更写 Lite Spec 即可；涉及跨团队协作、API 变更、数据迁移等高风险场景，再写完整的 Given/When/Then 场景和边界分析。判断标准：如果这个变更搞砸了的返工成本很高，就多花点时间写规格；如果改错了 5 分钟就能修好，写个大概就够了。

6 安装与初始化

6.1 前置要求与安装

• Node.js 20.19.0+

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init

初始化时 CLI 会询问使用哪些 AI 工具（Claude Code、Cursor、Copilot 等），然后自动往对应目录写入 Skill 和斜杠命令文件。完成后项目里多出一个 openspec/ 目录：

openspec/
├── specs/        # 系统当前行为的"源真相"（Source of Truth）
├── changes/      # 每个变更的独立工作目录
└── config.yaml   # 项目配置

6.2 配置项目上下文

这一步经常被跳过，但它对工件质量影响巨大。openspec/config.yaml 可向所有工件注入项目上下文和 per-artifact 规则：

schema: spec-driven

context: |
  Tech stack: TypeScript, React 18, Node.js, PostgreSQL
  API 风格：RESTful，文档在 docs/api.md
  Testing: Vitest + Playwright
  代码规范：参考 .eslintrc.js

rules:
  proposal:
    - Include rollback plan
    - 标注影响的模块范围
  specs:
    - Use Given/When/Then format for scenarios

context 会 prepend 到每次 Agent 生成工件的指令里，相当于一次配置，以后不必在对话开头反复交代技术栈。rules 则是针对特定工件类型的额外要求。

可以让 AI 协助填写：

Please read openspec/config.yaml and help me fill it out with details about my project, tech stack, and conventions，请使用中文，后续所有的 spec 都使用中文编写。

注意：openspec/project.md 已废弃。代理读取它的可靠性不一致，应把有用信息迁移到 config.yaml。迁移说明见 migration-guide。

6.3 启用扩展命令

默认安装 4 个核心命令（propose、explore、apply、archive）。如需更精细的控制：

openspec config profile
openspec update

选择 Expanded Profile 后，new、continue、ff、verify、sync、bulk-archive、onboard 等高级命令可用。

7 仓库结构与核心概念

7.1 Specs 与 Changes

OpenSpec 的整个体系建立在一个简单的二分法上：

openspec/
├── specs/          ← "系统现在是什么样的"
│   ├── auth/
│   ├── payments/
│   └── ...
└── changes/        ← "我们打算改什么"
    ├── add-dark-mode/
    └── fix-login-bug/

Specs（主规格） 是系统当前行为的权威描述——“源真相”，回答"系统现在是怎么运作的"。

Changes（变更） 是正在进行的修改——每个功能、每个 Bug 修复独立一个文件夹。变更完成后归档，delta 合并进 specs，变更目录移入带时间戳的归档目录。这个分离设计的好处是：多个变更可以并行推进，各自在自己的文件夹里工作，互不干扰。

7.2 变更目录结构

openspec/changes/add-remember-me/
├── proposal.md      # 为什么要做、范围边界
├── design.md        # 技术决策
├── tasks.md         # 实现清单
└── specs/           # 对主规格的 delta（增量修改）
    └── auth-session/
        └── spec.md

四个工件之间有明确的依赖关系，但这是**“使能"而不是"门禁”**：

proposal.md  →  specs/  →  design.md  →  tasks.md
 为什么做？     做什么？     怎么做？       具体步骤

有了 proposal 才方便写 specs，有了 specs 才方便写 design——但不禁止你在 apply 过程中回改 design.md。你完全可以先写 design 再补 specs，或者直接跳到 tasks。

• proposal.md：动机、范围（做什么和不做什么）、预期收益
• specs/：系统行为将如何改变，用 Delta Specs 描述
• design.md：架构决策、组件设计、技术选型的理由
• tasks.md：带复选框的实现清单，AI 在 /opsx:apply 时逐条执行

7.3 Specs 写法

OpenSpec 的 specs 很轻量，核心就两个部分：需求（Requirements） 和场景（Scenarios）。

需求用 RFC 2119 关键字表达意图强度：

## Purpose
用户认证模块，管理登录、登出和会话维护。

### Requirement: Login Authentication
系统 MUST 在用户提供有效凭证时签发 JWT token。
系统 MUST 在凭证无效时返回 401 错误，且不泄露是用户名还是密码错误。
系统 SHOULD 在连续 5 次失败后触发临时锁定。
系统 MAY 支持"记住我"功能以延长 token 有效期。

MUST = 必须实现，不实现就是 Bug；SHOULD = 强烈建议；MAY = 可选增强。

场景用 Given/When/Then 格式描述：

#### Scenario: Successful Login
Given 用户名 "alice" 存在且密码正确
When 用户提交登录请求
Then 系统返回 200 和有效的 JWT token
And token 有效期为 24 小时

specs 只描述外部可观察的行为，不描述内部实现。 “用 bcrypt 加密密码"不该出现在 specs 里（那是 design 的事），但"密码不得以明文存储"可以——这是可验证的外部约束。判断标准：如果把底层实现换了（比如从 bcrypt 换成 argon2），但系统对外的行为没有任何变化，那它就不该出现在 specs 里。

7.4 Delta Specs：增量规格

变更不直接覆盖主规格，而是在 change 目录里用 diff 风格描述"需求将如何变化”。每个变更的 specs/ 子目录里存放三类变化：

## ADDED Requirements

### Requirement: Theme Switching
系统 MUST 提供深色/浅色主题切换功能。

#### Scenario: Manual Theme Switch
Given 用户当前使用浅色主题
When 用户点击主题切换开关
Then 界面切换为深色主题
And 选择结果持久化到 localStorage

## MODIFIED Requirements

### Requirement: Page Background (MODIFIED)
- 原：系统 MUST 使用固定白色背景（#FFFFFF）
- 新：系统 MUST 根据当前主题设置显示对应的背景色

## REMOVED Requirements

### Requirement: Fixed Color Scheme (REMOVED)
- 原：系统 MUST 使用预设的固定配色方案
- 原因：被新的主题系统取代

也可以用 diff 风格描述单个需求的变化：

### Requirement: Session expiration
- The system SHALL expire sessions after a configured duration.
+ The system SHALL support configurable session expiration periods.

#### Scenario: Default session timeout
- WHEN 24 hours pass without activity
+ WHEN 24 hours pass without "Remember me"

+ #### Scenario: Extended session with remember me
+ - GIVEN user checks "Remember me" at login
+ - WHEN 30 days have passed
+ - THEN invalidate the session token

Reviewer 不必通读全部实现代码，先看 delta 就能回答：系统契约变了什么、验收场景新增了哪些。归档时，ADDED 追加、MODIFIED 替换、REMOVED 移除，合并回 openspec/specs/。

这个设计有三个实际好处：

1. 看变更一目了然——审查时不需要对比两个大文件找差异
2. 并行开发不冲突——两个变更可以同时修改同一模块，各自描述"我改了什么"
3. 存量项目友好——不需要先给整个系统写完整规格，直接从第一个变更开始，specs 随归档逐渐积累

7.5 自定义 Schema

默认使用 spec-driven schema。如需在 proposal 前加 research.md 等自定义工件：

openspec schema fork spec-driven research-first

通过 schema.yaml 和 templates/*.md 自定义工件类型与 AI 指令模板。对大多数人来说，默认 schema 完全够用。

8 OPSX 工作流与命令

2026 年初，OpenSpec 把标准工作流升级为 OPSX（OpenSpec eXtended workflow）。它要解决的问题是：旧版 /openspec:proposal 一次性生成全部工件，指令硬编码在 npm 包里，难以定制；线性阶段与真实开发节奏不符。

OPSX 的核心转变是：从 Phase 到 Action。

flowchart LR
    subgraph actions [随时可执行的动作]
        E[/opsx:explore/]
        P[/opsx:propose/]
        A[/opsx:apply/]
        S[/opsx:sync/]
        V[/opsx:verify/]
        AR[/opsx:archive/]
    end

    E --> P
    P --> A
    A --> V
    V --> AR
    A --> S
    A -.->|发现设计偏差| P

依赖关系是 enabler，不是 gate。 这正是 Brownfield 开发里高频发生的场景——写到一半发现 specs 不对，回去改就是了。

8.1 核心命令（Core Profile）

/opsx:propose — 需求清晰时，一步到位

You: /opsx:propose 用户可以通过 GitHub OAuth 登录，
     登录后自动创建账号，支持关联已有邮箱账号

AI:  ✓ Created openspec/changes/add-github-oauth/
     ✓ proposal.md — scope & intent
     ✓ specs/auth.md — delta specs
     ✓ design.md — OAuth flow, token handling
     ✓ tasks.md — 8 implementation tasks
     Ready for review!

生成完后，花几分钟扫一遍工件——尤其是 tasks.md 的拆分是否合理、specs/ 有没有遗漏边界条件。在规格层面改一行字，可能省下代码层面改一百行。

/opsx:explore — 不确定的时候，先探索

还没想清楚要做什么，或在几个方案之间纠结？explore 让 AI 先帮你搞清楚情况，不会创建任何文件，零副作用：

You: /opsx:explore 我们应该用 WebSocket 还是 SSE 来实现实时通知？

AI:  Found: Express server, nginx reverse proxy, no WebSocket infrastructure.
     Recommendation: SSE for your use case — notifications are all server-initiated.

You: 好的，就用 SSE。
You: /opsx:propose implement-sse-notifications

/opsx:apply — 按清单执行实现

You: /opsx:apply add-github-oauth

AI:  Reading tasks.md... Found 8 tasks, 0 completed.
     Working on task 1: Install passport-github2 dependency
     ✓ Added to package.json
     ...
     All 8 tasks complete!

每完成一项，AI 会在 tasks.md 里打勾。中途被打断后，重新执行 /opsx:apply，它会从未完成的任务接着来——这是 OpenSpec 最实用的价值之一。

/opsx:archive — 收尾归档

You: /opsx:archive add-github-oauth

AI:  ✓ All 8 tasks completed
     ✓ Synced delta specs → openspec/specs/auth.md
     ✓ Archived to openspec/archive/2026-02-27_add-github-oauth/

归档做了三件事：合并 Delta Specs 到主规格、移动变更目录到归档目录、关闭变更生命周期。归档前建议先跑 /opsx:verify。

8.2 扩展命令（Expanded Profile）

ff 和 propose 的区别：ff 可以在已有部分工件的情况下快进补全；propose 是从零开始一步到位。需求清晰 → ff 或 propose；需求还在打磨 → continue。

verify 从三个维度报告问题：

8.3 CLI 工具命令

openspec list                    # 查看所有活跃变更
openspec view                    # 交互式仪表盘
openspec show add-dark-mode      # 查看某个变更的详情
openspec status add-dark-mode    # 查看工件完成进度
openspec validate --all --strict # 检查所有变更和规格的格式
openspec archive add-dark-mode   # 从终端归档
openspec config profile          # 切换 Profile

8.4 两种 Profile 怎么选

建议从 Core 开始。当你发现自己频繁需要"先看看 proposal 再继续"时，再切到 Expanded。

9 实战场景指南

9.1 需求清晰，直接开干

路径：/opsx:propose → 审查 → /opsx:apply → /opsx:verify → /opsx:archive

You: /opsx:propose 在用户设置页面添加深色模式开关，
     支持跟随系统主题，选择结果持久化到 localStorage

AI:  ✓ Created openspec/changes/add-dark-mode/
     ✓ proposal.md / specs/ / design.md / tasks.md (6 tasks)

You: /opsx:apply add-dark-mode
AI:  ✓ All 6 tasks complete!

You: /opsx:verify add-dark-mode
AI:  No issues found.

You: /opsx:archive add-dark-mode
AI:  ✓ Merged specs, archived change.

9.2 需求模糊，边探索边明确

路径：/opsx:explore → /opsx:new → /opsx:continue → … → /opsx:apply → /opsx:archive

需求本身不清晰时，用 continue 而不是 ff——每一步生成的工件都可能需要手动修正，避免 AI 在错误方向上一路狂奔。

9.3 做到一半被打断，怎么继续

路径：（新对话）→ /opsx:apply <change-name>

所有规格和任务清单以文件形式存在项目里，AI 直接读 tasks.md，看哪些任务已打勾、哪些还没完成，从断点继续。想调整方案，先用 openspec status <change-name> 看进度，编辑 tasks.md 后再 apply。

9.4 apply 完发现需求遗漏或实现有问题

tasks.md 随时可以编辑，apply 每次都会检查未完成任务，从那里接着跑。漏掉大需求时，先更新 specs/ 里的 Delta Specs，再 /opsx:continue 重新生成 tasks。实现有问题时，先 /opsx:verify 让 AI 对照规格扫描，或直接描述问题让 AI 修复。

如果新增的需求跟原变更强相关，直接往 specs/ 和 tasks.md 里加；如果是独立新功能，另开变更。判断标准：如果这个新需求拿掉了，原来的变更还是完整的，就单开一个变更。

9.5 纯技术调研，不急着动手

路径：/opsx:explore → （多轮对话）→ 方向确定后再 /opsx:propose

explore 全程不产生任何文件，对项目零副作用。

9.6 并行开发多个功能

路径：多个 /opsx:propose + /opsx:apply 自由切换 → /opsx:bulk-archive

$ openspec list

CHANGES
  add-dark-mode       ████████░░ 6/8 tasks
  fix-login-timeout   ██████████ 3/3 tasks ✓
  add-user-profile    ████░░░░░░ 2/7 tasks

切换上下文只需要在 apply 时指定不同的变更名。全部完成后 bulk-archive 一次性归档，自动检测 Delta Specs 之间的冲突。

9.7 存量项目引入 OpenSpec

不必一次性补齐所有规格，按"用到哪补到哪"渐进推进：

1. openspec init 初始化
2. /opsx:explore 让 AI 分析现有代码，按模块梳理当前行为
3. 基于探索结果，逐步往 openspec/specs/ 里写规格
4. 后续新功能按正常流程走——每次归档都会让主规格更完整

几个变更归档之后，openspec/specs/ 会自然积累一份相当可用的系统行为文档。

10 与 GitHub Spec Kit 等的对比

OpenSpec 官方的定位是：相对 Spec Kit 更轻；相对 Kiro 等 IDE 内置方案 不锁厂商；相对"什么都不做" 多一层可预测性，但不搞仪式化流程。

实践中的体感差异（参见 Hashrocket 的对比实验）：OpenSpec 从 proposal 到 apply 的路径更短，规格文件更紧凑；Spec Kit 在任务拆分和验证步骤上更细致，适合需要强流程约束的团队。

11 适用边界与常见误区

11.1 SDD 不是银弹

以下场景不必强行上完整 SDD：

• 单行 bugfix、变量重命名等机械性改动
• 探索性 spike，目标本身尚不明确
• 规格维护成本高于收益的一次性脚本

SDD 的收益在行为复杂、协作人多、生命周期长的变更上最明显。

11.2 “这是不是瀑布？”

瀑布失败在于数月 upfront planning + rigid 计划。SDD 要的是花 10 分钟把意图写清楚，而不是花两周写完美 PRD。发现偏差时更新规格继续走，比假装规格不存在更务实。

11.3 规格质量决定上限

OpenSpec 不会替你想清楚需求。规格若含糊（“优化性能”、“改进 UX”），Agent 照样会猜。Given/When/Then 场景、明确的 in/out scope、边界条件，才是 SDD 真正产生价值的输入。

官方建议配合高推理能力模型（如 Codex 5.5、Opus 4.7），并在 /opsx:apply 前清理上下文窗口——规格工件本身就会占用 token，杂乱的对话历史会稀释关键约束。

11.4 Brownfield 不必一次补全全部规格

OpenSpec 明确反对"先给整个老项目生成全套规格"——那通常是时间浪费。正确做法是：随变更按需创建规格，每次 /opsx:propose 触达哪个模块，就为哪个模块沉淀 spec。

11.5 何时更新现有 change，何时开新 change

变更名称应该能一句话说清楚：add-user-avatar、fix-login-timeout。如果写不出简洁的名字，说明变更可能包含了太多不相关的内容，考虑拆分。

12 最佳实践

1. 归档前先 verify——apply 完了别直接 archive，先跑 verify 抓遗漏的边界条件和不一致的实现。
2. 审查工件，别急着 apply——尤其关注 tasks.md 的颗粒度和 specs/ 的边界覆盖。
3. 用 config.yaml 的 context 减少重复——技术栈、代码规范写进 context，一次配置，所有变更自动继承。
4. apply 前开一个新对话——让 AI 从干净状态读取工件文件去实现，避免探索阶段的对话噪音影响代码质量。
5. 选择高推理能力的模型——propose、ff、continue 环节用高推理模型；apply（纯执行）对模型要求相对低。
6. 把 spec delta 纳入 PR review 习惯——先 review 意图变更，再 review 代码 diff。

13 命令速查表

14 总结

SDD 重新回答了一个老问题：在 AI 能批量生成代码的今天，什么才是软件开发的"源真相"？ 答案倾向于规格——代码描述的是"现在怎样"，规格描述的是"应当怎样"。

OpenSpec 把这一倾向落实为仓库里的 Markdown 规格、变更 delta 和 OPSX 动作式工作流。它不试图取代你的 Agent 或 IDE，而是在它们之上加一层持久、可 diff、可 review 的规划上下文。对 Brownfield 项目、多 Agent 协作、以及需要 async review 的团队，这一层的边际收益通常高于再调一轮 prompt。

若你已经在用 AI 写代码，但经常遇到"生成很快、对齐很慢、换会话就失忆"的困境，值得用一个小需求跑通 /opsx:propose → /opsx:apply → /opsx:archive 全流程——SDD 是否适合你的团队，用一次完整变更比读十篇文章更有说服力。

参考链接

• OpenSpec 官网：https://openspec.dev/
• OpenSpec GitHub：https://github.com/Fission-AI/OpenSpec
• Getting Started：https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md
• OPSX 工作流文档：https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md
• Commands Reference：https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md
• GitHub Spec Kit：https://github.com/github/spec-kit
• SDD 综述论文：https://arxiv.org/pdf/2602.00180