告别 AI 乱改代码：OpenSpec 规范驱动开发完全指南

告别 AI 乱改代码：OpenSpec 规范驱动开发完全指南

简介

OpenSpec 是由 Fission-AI 团队开发的 开源规范驱动开发（Spec-Driven Development, SDD）框架，专为 AI 编程助手（如 Cursor、Claude、GitHub Copilot）设计。

其核心目标是解决 AI 编码时需求模糊、理解偏差、代码不可控的问题，通过 “先定规范，再写代码” 的流程，让人与 AI 在开发前达成共识

核心定位与价值

• 核心理念：Spec First, Code Later（规范优先，代码后置）

  • Spec (规范)：人与 AI 的 “契约”，明确定义需求、设计、任务清单。
  • Code (代码)：AI 严格按规范生成，杜绝 “自由发挥” 和 “幻觉”。

• 主要价值

  1. AI 开发可控：AI 必须遵循文档规范，输出可预测、高质量代码。
  2. 全链路可追溯：从需求提案到代码归档，每一步变更都有文档记录。
  3. 团队协作高效：统一规范消除沟通歧义，新成员可快速通过文档理解项目。
  4. 兼容主流工具：原生支持 20+ AI 编辑器（Cursor、Claude、Copilot、Windsurf 等）。
  5. 零侵入、轻量级：一键初始化，不破坏现有项目结构。

安装

环境要求

• Node.js ≥ 20.19.0

包管理器安装

# npm (最常见)
npm install -g @fission-ai/openspec@latest

# pnpm
pnpm add -g @fission-ai/openspec@latest

# yarn
yarn global add @fission-ai/openspec@latest

# bun
bun add -g @fission-ai/openspec@latest

初始化

使用 openspec init 命令来初始化

⚠️ 重要：请在你的项目根目录中执行此命令

openspec init 做了什么？

创建的文件

1. openspec 文件夹：内部包含核心配置文件 config.yaml、specs 文件夹、changes 文件夹
2. Claude Code：8 个文件（4 commands + 4 skills）
3. Cursor：8 个文件（4 commands + 4 skills）

commands：用于手动触发的斜线命令（/opsx:apply、/opsx:archive、/opsx:explore、/opsx:propose），skill：与 commands 对应的 AI 可以主动调取的技能模块

核心功能

• propose：创建变更提案
• apply：实施任务
• explore：探索思考
• archive：归档变更

目录结构

初始化后，OpenSpec 会在项目中创建以下结构：

openspec/
├── specs/              # 系统行为规范（真实来源）
│   └── <domain>/
│       └── spec.md
├── changes/            # 提议的变更（init 时为空，创建变更后才有）
│   ├── <change-name>/  # 进行中的变更（使用 /opsx:new 创建）
│   │   ├── proposal.md
│   │   ├── design.md
│   │   ├── tasks.md
│   │   └── specs/      # 增量规范（变更内容）
│   │       └── <domain>/
│   │           └── spec.md
│   └── archive/        # 已归档的变更（YYYY-MM-DD-<name>）
└── config.yaml         # 项目配置（可选）

两个核心目录：

目录	作用	说明
specs/	系统行为规范	描述系统当前如何工作，按功能模块组织（如 specs/auth/、specs/payments/）
changes/	提议的变更	每个变更一个文件夹，包含所有相关工件。完成后，specs 合并到主 specs/ 目录

各流程文件作用

1. proposal.md：“为什么？”、“是什么？”，体现一个需求最开始的意图、范围
2. specs/：需求的新增、修改、移除，体现出需求的变更
3. design.md：如何实现需求，描述的是技术方案架构、实现方法
4. tasks.md：具体的实施步骤，可以看作一个 todo list 清单

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
    可在实现过程之中，根据实际情况回头细化任意一个流程

工作流程

基础核心

1. 使用 /opsx:propose 创建一个变更提案，AI 会依次生成 proposal.md、design.md、tasks.md、specs/ 文件夹
2. 使用 /opsx:apply 开始实现变更，AI 会按照 tasks.md 中的步骤执行
3. 使用 /opsx:archive 归档变更，将完成的变更移动到 /change/archive/ 文件夹

扩展模式

通过执行 openspec config update、openspec update 命令，可以更新配置文件，并扩展出更多命令（command，skills）：

完整命令包括：

名称	命令	作用
Propose change	/opsx:propose	根据需求生成提案（proposal.md）、设计方案（design.md）和 任务清单（tasks.md）、需要达成的规范（spec/*）
Explore ideas	/opsx:explore	动手实现前先深入调研问题
New change	/opsx:new	执行之后 AI 会先在 openspce/change 目录中生成一个新的需求空目录
Continue change	/opsx:continue	继续处理某个未完成的变更，当你想每一步都手动控制触发时，使用这个命令
Apply tasks	/opsx:apply	按照任务清单实施当前变更
Fast-forward	/opsx:ff	一般在 /opsx new 之后执行，执行后会生成提案（proposal.md）、设计方案（design.md） 和任务清单（tasks.md）、需要达成的规范（spec/*）
Sync specs	/opsx:sync	把变更的规范（openspec/change/xxx/spec/*）同步到 主规范库（openspec/spec/*）
Archive change	/opsx:archive	将已完成的变更归档，会将/openspec/change/xxx 移动 到 /openspec/archive/YYYY-MM-DD-xxx
Bulk archive	/opsx:bulk-archive	一次性归档多个已完成变更
Verify change	/opsx:verify	从完整性、正确性、一致性三个方面检查变更是否正确完成
Onboard	/opsx:onboard	模拟跑一遍 openspec 完整工作流程

快速执行

当明确自己想要做什么，只需要快速执行时： /opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

例：

你：/opsx:new add-logout-button

AI：已创建 openspec/changes/add-logout-button/
    准备创建提案（proposal.md）

你：/opsx:ff

AI：正在创建所有规划工件...
    ✓ proposal.md
    ✓ specs/
    ✓ design.md
    ✓ tasks.md
    准备实施！

你：/opsx:apply

AI：正在执行任务...
    ✓ 已在头部添加退出登录按钮
    ✓ 已实现会话清除功能
    ✓ 已添加确认对话框
    所有任务完成！

你：/opsx:archive

AI：✓ 规范已合并
    ✓ 变更已归档

最佳用途： 小到中型功能，修复漏洞，简单易懂的改动。

探索模式

当要求不明确或需要先调查时： /opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

例：

你：/opsx:explore

AI：您想要探索什么？

你：我想提升页面加载性能，但不确定
    瓶颈在哪里。

AI：让我帮您调查一下...
    [分析打包体积、识别慢查询、审查组件渲染模式]

    我发现了三个主要瓶颈：
    1. 大量未优化的图片
    2. ProductList 中的同步数据获取
    3. 上下文变化导致的重渲染

    您想先解决哪一个？

你：我们先解决数据获取问题。

你：/opsx:new 解决ProductList 中的同步数据获取

AI：已创建变更。准备创建：proposal.md

你：/opsx:continue

AI：基于我们的探索创建proposal.md...
    [编写包含调查洞察的proposal.md]

    准备创建：specs/、design.md
    接下来想要哪个？

你：/opsx:continue

AI：正在创建规范...

最佳用途： 性能优化、调试、架构决策、不明确的需求。

多个变更之间切换

同时进行多项调整：

Change A: /opsx:new ──► /opsx:ff 或 /opsx:continue ──► /opsx:apply (in progress)
                                                         │
                                                    context switch
                                                         │
Change B: /opsx:new ──► /opsx:ff 或 /opsx:continue ────► /opsx:apply

例： 使用 /opsx:ff 快速生成所有工件

你：我正在做 add-dark-mode，但被叫去修复一个 bug

你：/opsx:new fix-login-redirect

AI：已创建 openspec/changes/fix-login-redirect/
    准备创建提案（proposal.md）

你：/opsx:ff

AI：正在创建所有规划工件...
    ✓ proposal.md
    ✓ specs/
    ✓ design.md
    ✓ tasks.md
    准备实施！

你：/opsx:apply

AI：正在实施 fix-login-redirect...
    [实施修复]
    所有任务完成！

你：/opsx:archive

AI：✓ fix-login-redirect 已归档

你：让我们回到暗黑模式

你：/opsx:apply add-dark-mode

AI：正在恢复 add-dark-mode...
    从任务 2.3 继续：更新 Header...

💡 提示：也可以使用 /opsx:continue 逐步生成工件，每执行一次创建一个（proposal → specs → design → tasks），适合需要逐步确认的场景。

最佳用途： 并行工作流程、紧急中断。

批量归档

当你有多个已完成的变更时，使用 /opsx:bulk-archive 一次性归档：

例：

你：/opsx:bulk-archive

AI：发现 3 个已完成的变更：
     - add-dark-mode（所有任务完成）
     - fix-login-redirect（所有任务完成）
     - update-footer（所有任务完成）

     正在检查规范冲突...
     ⚠ add-dark-mode 和 update-footer 都涉及 specs/ui/

     正在检查代码库以解决...
     两个变更都已实现。将按时间顺序应用。

     归档所有 3 个变更？

你：Yes

AI：✓ add-dark-mode 已归档
     ✓ fix-login-redirect 已归档
     ✓ update-footer 已归档
     规范按顺序合并：add-dark-mode → update-footer

💡 特性：批量归档会检测多个变更是否涉及相同的规范，并通过检查实际实现的内容来解决冲突。

最佳用途： 完成多个并行变更后统一归档、团队协作合并。

完成变更

推荐的完成流程：

/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              验证实现            提示同步规范
              （如需要）

核实：检查你的作品

/opsx:verify 从三个维度验证你的工件实现：

例：

你：/opsx:verify

AI：正在验证 add-auth...

     完备性
     ✓ tasks.md 中所有 12 个任务已完成
     ✓ specs 中的所有需求都有对应代码
     ⚠ 场景"会话超时"未测试

     正确性
     ✓ 实现符合规范意图
     ✓ 场景中的边界情况已处理
     ✓ 错误状态符合规范定义

     连贯性
     ✓ 设计决策体现在代码结构中
     ✓ 命名约定与 design.md 一致
     ⚠ design.md 提到"事件驱动"但实现使用轮询

     总结
     ─────────────────────────────
     严重问题：0
     警告：2
     可以归档：是（有警告）

     建议：
     1. 添加会话超时场景的测试
     2. 考虑重构为事件驱动（按设计），或更新 design.md

验证内容：

维度	验证内容
完备性	所有任务完成、所有需求已实现、场景覆盖
正确性	实现符合规范意图、边界情况已处理
连贯性	设计决策反映在代码中、模式一致

💡 提示：验证不会阻止归档，但会帮助你发现可能需要先解决的问题。

归档：完成变更

/opsx:archive 完成变更并将其移动到归档：

例：

你：/opsx:archive

AI：正在归档 add-auth...

     工件状态：
     ✓ proposal.md 存在
     ✓ specs/ 存在
     ✓ design.md 存在
     ✓ tasks.md 存在（12/12 任务完成）

     增量规范：尚未同步到主规范
     → 是否现在同步？

你：Yes

AI：✓ 已将规范同步到 openspec/specs/auth/spec.md
     ✓ 已移动到 openspec/changes/archive/2025-01-24-add-auth/

     变更归档成功。

💡 提示：如果规范未同步，归档会提示你同步。它不会阻止未完成的任务，但会提醒你。

使用心得、思考与最佳实践

AI 时代的开发模式转变

AI 编码工具的出现，不只是让我们"写代码更快"，而是在重塑我们思考问题的方式：

• 从"怎么写"到"写什么"：AI 可以承担大量实现细节，我们的精力应该更多放在需求的准确表达、方案的合理性判断上
• 从"个人经验"到"可传递的规范"：以前很多决策藏在开发者脑子里，现在通过规范文档沉淀下来，团队成员和 AI 都能理解
• 从"结果导向"到"过程可控"：不只关心代码跑不跑，更关心每一步变更是否有据可查、可回溯

OpenSpec 的价值不只是提效

OpenSpec 的价值可以从三个层面来看：

1. 规范沉淀：specs/ 目录是项目的"活文档"，随着每次变更不断更新，始终反映系统当前的真实行为，而不是某个时间点的快照
2. 需求记录：每个 changes/ 下的变更都完整保留了"为什么做、做什么、怎么做"，是比 git commit 更高层次的上下文
3. 快速上手：新成员或 AI 在接手项目时，可以通过规范文档快速建立对系统的理解，而不是靠读代码反推逻辑

解决了工作中使用 AI 最核心的顾虑

很多人在学习项目中用 AI 很顺手，但一到真实工作项目就变得保守——核心原因是：不敢让 AI 批量改代码，改完之后不知道怎么自测，出了问题也不知道从哪里排查。

OpenSpec 正是针对这个痛点设计的：

• AI 执行的每一步都来自我们事先确认过的 tasks.md，不会"自由发挥"
• 变更范围在 proposal.md 和 specs/ 中已经明确，AI 不会越界
• /opsx:verify 在归档前做三维度验证，让你对"改了什么、改对了没有"心里有数

本质上，OpenSpec 把 AI 的不可控变成了可控：不是限制 AI 的能力，而是把人的判断前置到规范制定阶段，让 AI 在一个清晰的边界内工作。

工作流命令如何选择

• 官方说明:

/opsx:ff vs /opsx:continue 选择指南：

场景	推荐命令
需求明确，准备开始构建	/opsx:ff
探索中，想逐步审查每一步	/opsx:continue
想在生成规范前先迭代提案	/opsx:continue
时间紧迫，需要快速推进	/opsx:ff
复杂变更，想要更多控制	/opsx:continue

💡 经验法则：如果你能一开始就描述完整范围，用 /opsx:ff。如果你边做边摸索，用 /opsx:continue。

• 我的建议:

不建议直接使用 /opsx:propose 命令或者使用 /opsx:new + /opsx:ff 来一次性生成 proposal.md 、specs/* 、design.md 、tasks.md，推荐使用 /opsx:new 创建变更，然后使用 /opsx:continue 来一步步创建其他工件。在这个过程中需要我们对 AI 生成的内容进行审阅和即时的纠正，保证最终生成的文档是 AI 在完整理解了我们的需求后生成的，要完全符合我们的要求的，将 AI 的产出视为我们自己的产出，对这些内容的正确性以及完整性负责。

🤔 什么时候更新现有的变更，什么时候新建变更？

何时更新 vs 新建变更

其实就好像我们的需求一样，当一个需求过来时，我们有判断它是属于之前需求的变更，还是一个完全的新需求

在以下情况更新现有的变更：

• 根本意图相同，执行过程更精细，比如最终结果相同，但增加一些优化用户体验的小功能
• 范围缩小，先实现基础功能，比如功能上线时间节点突然提前，要先实现核心基础功能
• 边学习边修正，比如任务列表已经完成，自测时发现实际效果与你期望的不一致，可能是之前某一步设计不合理或者有遗漏，此时需要在当前变更中更新需求设计等

在以下情况新建变更：

• 根本意图改变，最终目标功能完全不一致
• 需求范围扩大到跟以前完全不同的工作领域
• 原有的变更此时已经可以标记为 “已完成”
• 继续补充内容不仅不会起到澄清需求的作用，反而会让人感到困惑

🔍 在创建变更前有自己不清楚的，无法决定的内容，包括但不限于实现方式、技术栈选型、解决方案等时，要善于先使用/opsx:explore来探索思路

✅ 在归档之前先使用/opsx:verify命令进行验证

自定义

config.yaml 配置文件

通过 openspec/config.yaml 可以自定义 OpenSpec 的工作流行为。

基本结构

# 工作流模式（必填）
schema: spec-driven

# 项目上下文（可选）
context: |
  技术栈、编码规范、业务领域等

# 流程规则（可选）
rules:
  proposal:
    - 规则列表
  design:
    - 规则列表
  tasks:
    - 规则列表
  specs:
    - 规则列表

三个配置项

配置项	必填	作用	何时使用
schema	✅	定义工作流模式	始终需要
context	❌	给 AI 的项目背景	团队协作、特定技术栈
rules	❌	流程生成规则	需要统一格式和风格

1. schema - 工作流模式

定义 OpenSpec 使用的工作流（如 spec-driven），决定创建哪些流程及其依赖关系。

2. context - 项目上下文

告诉 AI 你的项目情况，帮助生成更合适的流程。

可包含内容：

• 技术栈（框架、语言、组件库）
• 编码规范（命名约定、风格指南）
• 业务领域（平台类型、目标用户）
• 特殊要求（SEO、性能、安全合规）

3. rules - 流程规则

对不同流程的自定义约束，控制 AI 生成内容的格式和风格。

支持流程：proposal、design、tasks、specs

示例：

rules:
  proposal:
    - 使用中文编写
    - 字数控制在 500 字以内
  design:
    - 必须包含架构图
    - 技术选型需要说明理由
  tasks:
    - 每个任务 1-2 小时完成
    - 标注优先级：[P0] [P1] [P2]
  specs:
    - 遵循 BDD 风格（GIVEN-WHEN-THEN）
    - 明确边界条件和异常处理

完全自定义

openspec也支持完全自定义工作流程，甚至可以自定义自己的的工件文档，具体可以参考：github.com/Fission-AI/…

⚠️ 使用建议

• 如果你决定了使用了 openspec 来进行规范驱动开发，那么最好所有要对代码进行更改的操作都通过其来进行，避免 有需求 ——》 直接改，而是始终 有需求 ——》 /opsx/propose 或 /opsx:new，避免在 openspec 中，出现 spec规范和实际代码逻辑不一致的情况

总结

OpenSpec 的核心不是工具本身，而是它背后的工作方式：把人的判断前置，让 AI 在清晰的边界内执行。规范文档不是额外的负担，而是需求、设计、实现之间的共识载体——它让 AI 可控、让变更可追溯、让团队协作更顺畅。

如果你正在寻找一种在真实项目中放心使用 AI 编程的方式，OpenSpec 值得一试。

总结

OpenSpec 解决的不只是"怎么用 AI 写代码"的问题，而是"怎么在真实项目中放心地用 AI"的问题。规范先行、逐步确认、全程可追溯，让 AI 从一个不可控的变量变成一个可以信赖的协作者。

如果你也在工作项目中对 AI 编码工具又爱又怕，不妨试试 OpenSpec 这套工作流——它的核心不是约束 AI，而是把你自己的判断提前落到纸面上。

GitHub：github.com/Fission-AI/…