"我跟 AI 说加个暗黑模式，它给我重构了半个项目。" "明明上次讲好了的需求，新开一个对话它全忘了。" "任务做到一半，AI 开始幻觉，凭空发明了一个不存在的接口。" ——每一个深夜盯着 AI 生成代码却越看越不对劲的开发者
一、为什么需要 OpenSpec？（WHY）
AI 编码的"薛定谔状态"
AI 编码助手已经成为了很多开发者的标配工具。你给它一个模糊的需求，它唰唰唰几秒钟生成几十行代码，感觉效率拉满。
但等等——这段代码真的是你想要的吗？
问题不在于 AI 不够聪明，而在于 AI 的记忆是会话级别的。你今天在 Cursor 里讲好的架构决策，明天新开一个对话它全不记得了。你在聊天框里给 AI 讲了二十分钟的上下文，它在第 21 条消息时就开始"忘事"。
更要命的是：当你的需求稍微复杂一点——比如同时涉及数据库 Schema 变更、接口改动和前端组件重构——AI 在没有明确规格约束的情况下，很可能：
- 过度实现：你要的是加个按钮，它给你重构了整个状态管理
- 欠拟合：你要的是完整功能，它给你实现了一半然后说"其余你自己补吧"
- 需求漂移：做到第三步发现已经偏离原始设计十万八千里
这就是开发者们熟悉的"AI 乱猜"状态。
传统解法的局限
当然，有经验的开发者会说：把需求写清楚嘛！在 prompt 里把上下文交代清楚！
确实，这能缓解问题，但不能根治。因为：
- Context 是一次性的：写在聊天框里的需求，换个会话就消失了
- 同步成本高：团队协作时，每个人告诉 AI 的上下文不一致
- 不可追溯：代码里看不出当初做这个决策的理由是什么
- 难以复查：没有结构化的"变更说明"，代码评审只能靠猜
一句话：把需求放在聊天框里，就像把合同写在沙子上——只要潮水来了（新会话开始了），什么都没了。
SDD：把合同刻在石头上
这就是 规格驱动开发（Spec-Driven Development，SDD） 的核心思想——
把"我们要做什么、为什么做、怎么做"写成结构化的 Markdown 文件，和代码一起存进 Git 仓库。
AI 助手不再依赖你在聊天框里的临时描述，而是从仓库里读取持久化的规格文档，然后照单执行。
而 OpenSpec，就是把 SDD 落地的那把利器。
二、OpenSpec 是什么？（WHAT）
一句话定义
OpenSpec 是一个轻量级、开源的规格驱动开发框架，通过结构化的 Markdown 文件帮助人类和 AI 编码助手在写代码之前就达成一致。
它本质上是一套工作流规范 + CLI 工具，让你的 AI 助手能够：
- 读懂你真正想要什么（proposal.md）
- 理解具体的需求约束（specs/）
- 知道技术怎么实现（design.md）
- 按步骤系统地执行（tasks.md）
整套文档住在你的项目仓库里，持久存在，永不遗忘。
核心概念速览
在深入使用方法之前，先认识几个关键词，别让它们在后面绊倒你：
| 术语 | 你可以理解为 |
|---|---|
| Change（变更） | 一个独立的功能开发或修改任务，是 OpenSpec 的最小工作单元 |
| proposal.md | "我们为什么要做这件事，做什么，不做什么"的说明书 |
| specs/ | 具体需求场景，用 Given/When/Then 格式写清楚验收条件 |
| design.md | 技术方案文档，怎么做，用什么技术，关键决策是什么 |
| tasks.md | AI 实现时的步骤清单，打勾制度，做一步标一步 |
| AGENTS.md | 给 AI 助手看的项目级说明书，告诉它这个项目怎么运转 |
| Fast-Forward（ff） | 一键生成全套规划文档的快捷操作，懒人必备 |
| Archive（归档） | 变更完成后，将变更文件夹归档，并将规格合并到主文档 |
OpenSpec 的文件夹结构
初始化后，你的项目会多出这样的目录：
your-project/
├── AGENTS.md ← AI 助手的项目说明书
└── openspec/
├── changes/ ← 进行中的变更（你的"待办队列"）
│ └── add-dark-mode/ ← 一个变更对应一个文件夹
│ ├── proposal.md ← 变更说明（为什么做，做什么）
│ ├── specs/ ← 需求规格（Given/When/Then 场景）
│ ├── design.md ← 技术设计（怎么做）
│ └── tasks.md ← 任务清单（AI 执行步骤）
├── archive/ ← 已完成的变更归档
└── specs/ ← 主规格文档（持续更新的"活文档"）
这个结构设计得非常讲究：changes/ 就是你的进行中队列，一目了然看到有哪些功能在开发；archive/ 是历史记录；specs/ 是反映当前系统真实状态的活文档——每次 archive 操作都会自动把变更同步进来。
三阶段工作流
OpenSpec 的核心工作流分为三个阶段：
阶段一：规划（Propose）
└─ 定义变更 → 写提案 → 梳理规格 → 技术设计 → 任务拆分
阶段二：实现（Apply）
└─ AI 读取规格文档 → 按 tasks.md 逐步实现 → 打勾确认
阶段三：归档（Archive）
└─ 变更文件夹移入 archive/ → 规格合并到主 specs/ → 开启下一个变更
为什么分三阶段？
因为这三个阶段对应着三种不同的思维模式：
- 规划阶段是"发散思维"——想清楚要做什么，允许反复推敲
- 实现阶段是"收敛执行"——严格按照规格，不做规格之外的事
- 归档阶段是"沉淀知识"——让完成的工作成为持久的项目知识
把这三件事混在一起（比如边想边做），就是需求漂移和 AI 乱发挥的根源。
支持 20+ AI 助手
OpenSpec 不绑定任何特定的 AI 工具，支持市面上几乎所有主流 AI 编码助手：
Cursor、Claude Code、GitHub Copilot、Windsurf、RooCode、Cline、Amazon Q、Codex、Gemini CLI……
无论你用哪个，通过统一的斜杠命令（/opsx:*）就能触发相同的工作流。团队里有人用 Cursor、有人用 Claude Code？没关系，大家共享同一套规格文档，协作照样顺畅。
三、怎么使用 OpenSpec？（HOW）
3.1 安装：两种方式，选一种
方式一：使用 Vercel Skills 工具安装（推荐给 AI 驱动的工作流）
Vercel Skills 是 2026 年 1 月发布的开放式 Agent 技能生态工具，专门用来给各种 AI 助手安装和管理"技能包"。OpenSpec 已经发布了官方技能包，可以直接通过 Skills 工具安装：
第一步：安装 OpenSpec 技能包
npx skills add partme-ai/openspec-skills
这条命令会把 OpenSpec 的全套技能（包括 openspec-new、openspec-ff、openspec-apply、openspec-archive 等）安装到你当前 AI 助手的技能目录下。
如果你想指定安装到特定的 AI 工具：
# 安装到 Cursor
npx skills add partme-ai/openspec-skills --agent cursor
# 安装到 Claude Code
npx skills add partme-ai/openspec-skills --agent claude-code
# 安装到 Codex
npx skills add partme-ai/openspec-skills --agent codex
安装后，AI 助手会自动加载这些技能，你就可以直接在编辑器里使用 /opsx:* 系列命令了。
还可以单独安装某个技能
如果你只想用某个特定功能，也可以单独安装：
# 只安装 fast-forward 技能
npx skills install partme-ai-openspec-skills-openspec-ff --agent cursor
Skills 工具小贴士：用
npx skills list查看已安装的技能，用npx skills update更新技能，用npx skills remove <name>卸载。
方式二：直接安装 CLI 工具（全功能版）
如果你想要完整的命令行功能（包括 openspec validate、openspec schema 等高级操作），可以直接安装 CLI：
# 需要 Node.js 20.19.0 或更高版本
npm install -g @fission-ai/openspec@latest
# 验证安装
openspec --version
3.2 初始化项目
安装完成后，在你的项目根目录执行：
cd your-project
openspec init
这条命令会：
- 创建
openspec/目录结构 - 生成
AGENTS.md（AI 助手的项目级说明书） - 生成初始配置文件
关键提示：openspec init 不会 动你现有的代码，对存量项目完全友好。这不是从零新建项目的工具，而是给任何项目添加规格层的工具。
3.3 核心工作流实战演示
我们用一个真实场景串起来：给一个 React 应用添加深色模式。
Step 1：创建变更（/opsx:new）
在你的 AI 助手里输入：
/opsx:new add-dark-mode
AI 会创建 openspec/changes/add-dark-mode/ 目录，并开始引导你填写 proposal.md。
此时的 proposal.md 大概长这样：
# Proposal: add-dark-mode
## Problem
用户反馈在夜间使用时眼睛疲劳，需要深色模式支持。
## Proposed Solution
添加深色/浅色主题切换功能，使用 CSS 变量 + Context 实现，
支持用户偏好持久化（localStorage）。
## In Scope
- 主题 Context Provider
- 主题切换按钮组件
- 核心页面的深色样式
- localStorage 持久化
## Out of Scope
- 系统级深色模式自动检测（v2 再做）
- 邮件模板深色适配（不影响核心功能）
## Risks
- 需要审查现有 CSS 是否有硬编码颜色值
注意 Out of Scope 这一栏——这是防止需求范围蔓延的关键。明确写出"不做什么"，AI 就不会自作主张地多做。
Step 2：快进生成全部规划文档（/opsx:ff）
如果你已经想清楚了这个功能的大致方向，直接：
/opsx:ff
AI 会依次生成所有规划文档：
- proposal.md → 变更说明
- specs/theme.md → 需求规格（Given/When/Then 场景）
- design.md → 技术方案
- tasks.md → 实现步骤清单
生成好的 specs/theme.md 可能长这样：
# Specs: Theme System
## Scenario: 用户切换到深色模式
Given 用户在浅色模式下
When 用户点击主题切换按钮
Then 页面立即切换为深色配色方案
And 用户的选择被保存到 localStorage
## Scenario: 用户重新打开页面
Given 用户之前选择了深色模式
When 用户重新打开应用
Then 应用直接以深色模式启动，无闪烁
生成好的 tasks.md 可能长这样：
# Tasks: add-dark-mode
## Phase 1: Theme Infrastructure
- [ ] 1.1 创建 ThemeContext 和 ThemeProvider
- [ ] 1.2 创建 useTheme() Hook
- [ ] 1.3 添加 localStorage 持久化逻辑
## Phase 2: UI Components
- [ ] 2.1 创建 ThemeToggle 组件
- [ ] 2.2 在 Header 中集成 ThemeToggle
## Phase 3: Styles
- [ ] 3.1 定义 CSS 变量（light/dark tokens）
- [ ] 3.2 更新 globals.css 支持 data-theme 属性
- [ ] 3.3 审查并替换硬编码颜色值
在跑 /opsx:apply 之前，花 5 分钟看一眼这些文档。 调整不合理的地方比修改一堆生成代码要省事 100 倍。
Step 3：实现（/opsx:apply）
文档确认无误后：
/opsx:apply
AI 会逐步执行 tasks.md 里的每一项，完成一项打一个勾：
Implementing tasks...
✓ 1.1 创建 ThemeContext 和 ThemeProvider
✓ 1.2 创建 useTheme() Hook
✓ 1.3 添加 localStorage 持久化逻辑
✓ 2.1 创建 ThemeToggle 组件
✓ 2.2 在 Header 中集成 ThemeToggle
...
All tasks complete!
注意这里的重大变化：AI 不再是从你的 prompt 中猜测要做什么，而是从 tasks.md 中读取明确的指令执行。你能清楚看到它在做什么，做到哪里了。
如果实现过程中断了（比如 token 用完、会话中断），下次新开对话，AI 读取 tasks.md 就能看到哪些做完了（[x]），哪些没做（[ ]），从断点继续，没有任何上下文丢失。
Step 4：归档（/opsx:archive）
功能测试通过、代码合并之后：
/opsx:archive
这条命令会：
- 把
openspec/changes/add-dark-mode/整个移入openspec/changes/archive/2026-03-30-add-dark-mode/ - 把这次变更涉及的规格变更自动合并进
openspec/specs/主文档
这样，openspec/specs/ 永远反映系统当前的真实状态。下次新人进来，读读 specs/ 就知道系统现在能做什么、不能做什么，不用费力扒 Git 记录。
3.4 高级用法
分步生成（精细控制）
不想一次性 ff 全部文档？也可以分步来：
/opsx:new add-payment # 创建变更
/opsx:continue # 生成下一个文档（循环触发）
每次 /opsx:continue 会生成下一个待生成的文档（proposal → specs → design → tasks），让你有机会在每个环节介入调整。
验证规格完整性
openspec validate
检查当前变更的文档结构是否完整，有没有漏掉必要的字段。用 CI 跑它，确保每次提交的规格都是合格的。
自定义工作流 Schema
OpenSpec 支持自定义工作流模板，如果你的团队有特殊的规范文档格式：
openspec schema init # 初始化 schema 配置
openspec schema fork # 基于现有 schema 创建自定义版本
openspec schema validate # 验证 schema 是否合法
四、最佳实践
✅ 变更名称要小而精确
用 add-oauth-token-refresh 而不是 auth-improvements。
为什么？因为变更名会成为文件夹名，出现在 git status 和 code review 里。一个好的名字让团队成员一眼就知道这个 PR 在做什么。
好的命名：fix-login-redirect-loop、add-user-avatar-upload、migrate-db-to-postgresql
差的命名：stuff、updates、fix-issues、wip
✅ 提案要能在 2 分钟内读完
proposal.md 的核心价值是快速对齐。如果你的 reviewer 需要花 20 分钟才能看懂这个提案，那说明要么范围太大，要么描述不清。
好的提案回答四个问题：问题是什么？解决方案是什么？做什么/不做什么？风险是什么？
✅ specs 写场景，不写感觉
❌ 差：主题切换应该流畅、好用
✅ 好：
Given 用户在浅色模式下
When 用户点击切换按钮
Then 页面在 200ms 内完成主题切换，无明显闪烁
场景是 AI 实现时的验收标准。"流畅好用"这种描述，AI 会凭自己的理解发挥，结果可能五花八门。
✅ 任务要小，小到可以独立验证
❌ 差：实现主题系统
✅ 好：
- [ ] 1.1 创建 ThemeContext（含 light/dark 类型定义）
- [ ] 1.2 创建 useTheme() Hook（读取/更新 context）
- [ ] 1.3 创建 ThemeProvider 并包裹 App 根节点
细粒度的任务让 AI 的每一步都可验证，出问题了也更容易定位到哪一步。
✅ 规划稳定后再开始实现
/opsx:ff 生成的文档是起点，不是终点。在执行 /opsx:apply 之前，读一遍，改掉不对的地方。改一行 design.md 比修复 AI 生成的三十行错误代码省时多了。
✅ 规划和实现分开对话
长对话会积累噪音。规划阶段的讨论完成后，新开一个对话，把相关的规格文件附上（或者 AI 自动从仓库读），再开始实现。上下文更干净，AI 的注意力更集中。
✅ 做完就归档，保持队列整洁
openspec/changes/ 应该是你的进行中队列，不是历史博物馆。功能合并后，尽快 /opsx:archive，让 changes/ 目录只有当前正在做的工作。
五、常见误区
❌ 误区一：OpenSpec 只适合新项目
真相：OpenSpec 是专门为存量（brownfield）项目设计的。openspec init 不会碰你现有的任何代码。从今天起，下一个 feature 就可以用 OpenSpec 来做，已有代码不受任何影响。
❌ 误区二：有了 OpenSpec 就不用思考了
真相：OpenSpec 把"思考"前置了，不是消除了。/opsx:ff 能帮你生成文档框架，但 你必须审核。它不了解你的业务约束、团队规范、性能要求——这些还是要靠人来把关。
把 ff 的输出当成"草稿"而不是"定稿"，你就用对了。
❌ 误区三：一个变更做所有事
把"重构整个后端"放进一个变更，tasks.md 会变成一本书，AI 做到一半就失控了。
正确做法：单次变更控制在 1-3 天 的工作量内。"重构后端"拆成"迁移用户服务"、"迁移订单服务"、"统一错误处理"……一个个来。
❌ 误区四：归档前不用测试
/opsx:archive 会把规格合并进主文档，这意味着如果你的实现是错的，错误的规格就永久进入了 specs/。
正确做法：先测试、先合并代码，确认没问题再归档。Archive 是"宣布这件事完成了"，不是"宣布这件事结束了"。
❌ 误区五：把 OpenSpec 当成文档工具
OpenSpec 文件是活的执行规格，不是事后补的文档。它的价值在于引导 AI 实现，而不是给人类看的文档。如果你的用法是"先写代码，再补 spec"，那你正在用反了。
六、与其他工具对比
| 工具 | 定位 | 复杂度 | 是否锁定特定 IDE |
|---|---|---|---|
| OpenSpec | 轻量 SDD 框架 | ⭐⭐ | 否，20+ 工具通用 |
| BMAD | 多 Agent 协作系统 | ⭐⭐⭐⭐⭐ | 否 |
| Spec Kit | 重型规格管理 | ⭐⭐⭐⭐ | 否 |
| Kiro (AWS) | AI IDE 原生 SDD | ⭐⭐⭐ | 是（绑定 Kiro IDE 和 Claude） |
| 只写 Prompt | 无框架 | ⭐ | 否 |
OpenSpec 的甜蜜点是：够轻，够灵活，够通用。它不要求你换工具，不要求你学新语言，5 分钟上手，然后渐进式地融入你现有的工作流。
七、总结：从"乱猜"到"照单执行"
回到文章开头的那些抱怨——AI 发挥过头、忘记上下文、需求漂移——这些不是 AI 的问题，而是缺乏规格约束的问题。
OpenSpec 提供的，是一套对人类友好、对 AI 友好、对团队友好的工作框架：
- 对人类：规格即文档，一目了然知道在做什么、做了什么
- 对AI：有明确的输入（spec）和输出（tasks），照单执行而不是自由发挥
- 对团队：规格活在仓库里，人人可见，协作摩擦大幅降低
如果你已经在用 AI 编码助手做开发，OpenSpec 是让它从"聪明的随机数生成器"变成"可靠的工程师"的关键一步。
五分钟安装，一个功能实践，你就会明白为什么它叫"Spec-Driven"——带着规格上路，比漫无目的地催 AI 要快得多、稳得多。
附录：快速参考卡
核心命令
| 命令 | 作用 |
|---|---|
openspec init | 在当前项目初始化 OpenSpec |
/opsx:new <name> | 创建新变更 |
/opsx:ff | 快进：一键生成所有规划文档 |
/opsx:continue | 生成下一个规划文档（分步模式） |
/opsx:apply | 执行 tasks.md 中的所有任务 |
/opsx:archive | 归档已完成的变更 |
/opsx:verify | 验证实现是否符合规格 |
openspec validate | 校验规格文档完整性 |
Skills 工具安装命令
# 安装全套 OpenSpec 技能
npx skills add partme-ai/openspec-skills
# 指定安装到 Cursor
npx skills add partme-ai/openspec-skills --agent cursor
# 查看已安装技能
npx skills list
# 更新技能
npx skills update partme-ai/openspec-skills
文档结构速查
openspec/
├── changes/ ← 进行中（你的"待办队列"）
│ └── <change-name>/
│ ├── proposal.md ← 为什么做，做什么
│ ├── specs/ ← 需求场景（验收标准）
│ ├── design.md ← 技术方案
│ └── tasks.md ← AI 执行步骤
├── archive/ ← 已完成
└── specs/ ← 主规格文档（系统现状的活文档）
有用的链接
- 官网：openspec.pro
- GitHub：github.com/Fission-AI/…
- Skills 生态：skills.sh
- Discord 社区：discord.gg/openspec
让 AI 助手成为靠谱的队友，而不是让人哭笑不得的艺术家。
