"我跟 AI 说加个暗黑模式，它给我重构了半个项目。" "明明上次讲好了的需求，新开一个对话它全忘了。" "任务做到一半，AI 开始幻觉，凭空发明了一个不存在的接口。" ——每一个深夜盯着 AI 生成代码却越看越不对劲的开发者

AI 编码的"薛定谔状态"

AI 编码助手已经成为了很多开发者的标配工具。你给它一个模糊的需求，它唰唰唰几秒钟生成几十行代码，感觉效率拉满。

但等等——这段代码真的是你想要的吗？

问题不在于 AI 不够聪明，而在于 AI 的记忆是会话级别的。你今天在 Cursor 里讲好的架构决策，明天新开一个对话它全不记得了。你在聊天框里给 AI 讲了二十分钟的上下文，它在第 21 条消息时就开始"忘事"。

更要命的是：当你的需求稍微复杂一点——比如同时涉及数据库 Schema 变更、接口改动和前端组件重构——AI 在没有明确规格约束的情况下，很可能：

这就是开发者们熟悉的"AI 乱猜"状态。

传统解法的局限

当然，有经验的开发者会说：把需求写清楚嘛！在 prompt 里把上下文交代清楚！

确实，这能缓解问题，但不能根治。因为：

一句话：把需求放在聊天框里，就像把合同写在沙子上——只要潮水来了（新会话开始了），什么都没了。

SDD：把合同刻在石头上

这就是 规格驱动开发（Spec-Driven Development，SDD） 的核心思想——

把"我们要做什么、为什么做、怎么做"写成结构化的 Markdown 文件，和代码一起存进 Git 仓库。

AI 助手不再依赖你在聊天框里的临时描述，而是从仓库里读取持久化的规格文档，然后照单执行。

而 OpenSpec，就是把 SDD 落地的那把利器。

一句话定义

OpenSpec 是一个轻量级、开源的规格驱动开发框架，通过结构化的 Markdown 文件帮助人类和 AI 编码助手在写代码之前就达成一致。

它本质上是一套工作流规范 + CLI 工具，让你的 AI 助手能够：

整套文档住在你的项目仓库里，持久存在，永不遗忘。

核心概念速览

在深入使用方法之前，先认识几个关键词，别让它们在后面绊倒你：

OpenSpec 的文件夹结构

初始化后，你的项目会多出这样的目录：

sql 体验AI代码助手 代码解读复制代码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 的核心工作流分为三个阶段：

 体验AI代码助手 代码解读复制代码阶段一：规划（Propose） 

为什么分三阶段？

因为这三个阶段对应着三种不同的思维模式：

把这三件事混在一起（比如边想边做），就是需求漂移和 AI 乱发挥的根源。

支持 20+ AI 助手

OpenSpec 不绑定任何特定的 AI 工具，支持市面上几乎所有主流 AI 编码助手：

Cursor、Claude Code、GitHub Copilot、Windsurf、RooCode、Cline、Amazon Q、Codex、Gemini CLI……

无论你用哪个，通过统一的斜杠命令（/opsx:*）就能触发相同的工作流。团队里有人用 Cursor、有人用 Claude Code？没关系，大家共享同一套规格文档，协作照样顺畅。

3.1 安装：两种方式，选一种

方式一：使用 Vercel Skills 工具安装（推荐给 AI 驱动的工作流）

是 2026 年 1 月发布的开放式 Agent 技能生态工具，专门用来给各种 AI 助手安装和管理"技能包"。OpenSpec 已经发布了官方技能包，可以直接通过 Skills 工具安装：

第一步：安装 OpenSpec 技能包

bash 体验AI代码助手 代码解读复制代码npx skills add partme-ai/openspec-skills

这条命令会把 OpenSpec 的全套技能（包括 openspec-new、openspec-ff、openspec-apply、openspec-archive 等）安装到你当前 AI 助手的技能目录下。

如果你想指定安装到特定的 AI 工具：

bash 体验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:* 系列命令了。

还可以单独安装某个技能

如果你只想用某个特定功能，也可以单独安装：

bash 体验AI代码助手 代码解读复制代码# 只安装 fast-forward 技能 npx skills install partme-ai-openspec-skills-openspec-ff –agent cursor

Skills 工具小贴士：用 npx skills list 查看已安装的技能，用 npx skills update 更新技能，用 npx skills remove 卸载。

方式二：直接安装 CLI 工具（全功能版）

如果你想要完整的命令行功能（包括 openspec validate、openspec schema 等高级操作），可以直接安装 CLI：

bash 体验AI代码助手 代码解读复制代码# 需要 Node.js 20.19.0 或更高版本 npm install -g @fission-ai/openspec@latest 
验证安装
 
openspec –version

3.2 初始化项目

安装完成后，在你的项目根目录执行：

bash 体验AI代码助手 代码解读复制代码cd your-project openspec init

这条命令会：

• 创建 openspec/ 目录结构
• 生成 AGENTS.md（AI 助手的项目级说明书）
• 生成初始配置文件

关键提示：openspec init 不会 动你现有的代码，对存量项目完全友好。这不是从零新建项目的工具，而是给任何项目添加规格层的工具。

3.3 核心工作流实战演示

我们用一个真实场景串起来：给一个 React 应用添加深色模式。

Step 1：创建变更（/opsx:new）

在你的 AI 助手里输入：

csharp 体验AI代码助手 代码解读复制代码/opsx:new add-dark-mode

AI 会创建 openspec/changes/add-dark-mode/ 目录，并开始引导你填写 proposal.md。

此时的 proposal.md 大概长这样：

markdown 体验AI代码助手 代码解读复制代码# 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）

如果你已经想清楚了这个功能的大致方向，直接：

bash 体验AI代码助手 代码解读复制代码/opsx:ff

AI 会依次生成所有规划文档：

生成好的 specs/theme.md 可能长这样：

markdown 体验AI代码助手 代码解读复制代码# Specs: Theme System 
Scenario: 用户切换到深色模式
 
Given 用户在浅色模式下 When 用户点击主题切换按钮 Then 页面立即切换为深色配色方案 And 用户的选择被保存到 localStorage
 
Scenario: 用户重新打开页面
 
Given 用户之前选择了深色模式 When 用户重新打开应用 Then 应用直接以深色模式启动，无闪烁

生成好的 tasks.md 可能长这样：

markdown 体验AI代码助手 代码解读复制代码# 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）

文档确认无误后：

bash 体验AI代码助手 代码解读复制代码/opsx:apply

AI 会逐步执行 tasks.md 里的每一项，完成一项打一个勾：

scss 体验AI代码助手 代码解读复制代码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）

功能测试通过、代码合并之后：

bash 体验AI代码助手 代码解读复制代码/opsx:archive

这条命令会：

1. 把 openspec/changes/add-dark-mode/ 整个移入 openspec/changes/archive/2026-03-30-add-dark-mode/
2. 把这次变更涉及的规格变更自动合并进 openspec/specs/ 主文档

这样，openspec/specs/ 永远反映系统当前的真实状态。下次新人进来，读读 specs/ 就知道系统现在能做什么、不能做什么，不用费力扒 Git 记录。

3.4 高级用法

分步生成（精细控制）

不想一次性 ff 全部文档？也可以分步来：

bash 体验AI代码助手 代码解读复制代码/opsx:new add-payment # 创建变更 /opsx:continue # 生成下一个文档（循环触发）

每次 /opsx:continue 会生成下一个待生成的文档（proposal → specs → design → tasks），让你有机会在每个环节介入调整。

验证规格完整性

bash 体验AI代码助手 代码解读复制代码openspec validate

检查当前变更的文档结构是否完整，有没有漏掉必要的字段。用 CI 跑它，确保每次提交的规格都是合格的。

自定义工作流 Schema

OpenSpec 支持自定义工作流模板，如果你的团队有特殊的规范文档格式：

bash 体验AI代码助手 代码解读复制代码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 写场景，不写感觉

markdown 体验AI代码助手 代码解读复制代码❌ 差：主题切换应该流畅、好用 ✅ 好： Given 用户在浅色模式下 When 用户点击切换按钮 Then 页面在 200ms 内完成主题切换，无明显闪烁

场景是 AI 实现时的验收标准。"流畅好用"这种描述，AI 会凭自己的理解发挥，结果可能五花八门。

✅ 任务要小，小到可以独立验证

markdown 体验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"，那你正在用反了。

OpenSpec 的甜蜜点是：够轻，够灵活，够通用。它不要求你换工具，不要求你学新语言，5 分钟上手，然后渐进式地融入你现有的工作流。

回到文章开头的那些抱怨——AI 发挥过头、忘记上下文、需求漂移——这些不是 AI 的问题，而是缺乏规格约束的问题。

OpenSpec 提供的，是一套对人类友好、对 AI 友好、对团队友好的工作框架：

如果你已经在用 AI 编码助手做开发，OpenSpec 是让它从"聪明的随机数生成器"变成"可靠的工程师"的关键一步。

五分钟安装，一个功能实践，你就会明白为什么它叫"Spec-Driven"——带着规格上路，比漫无目的地催 AI 要快得多、稳得多。

核心命令

Skills 工具安装命令

bash 体验AI代码助手 代码解读复制代码# 安装全套 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

文档结构速查

perl 体验AI代码助手 代码解读复制代码openspec/ ├── changes/ ← 进行中（你的"待办队列"） │ └── 
    
      
      
        / │ ├── proposal.md ← 为什么做，做什么 │ ├── specs/ ← 需求场景（验收标准） │ ├── design.md ← 技术方案 │ └── tasks.md ← AI 执行步骤 ├── archive/ ← 已完成 └── specs/ ← 主规格文档（系统现状的活文档） 
      

有用的链接

让 AI 助手成为靠谱的队友，而不是让人哭笑不得的艺术家。