夜雨聆风
用AI写代码，你真的需要OpenSpec
你有没有这样的经历：让AI帮你写个功能，它在聊天框里一通猛操作，代码是写完了，但你回头一看——它理解错了你的意思，或者干脆写了一套你根本不想要的东西。更惨的是，你花了半小时调试才发现，问题出在一开始就没对齐需求上。
这就是AI编码的"阿喀琉斯之踵"：需求不清晰，AI再聪明也白搭。
今天想聊聊一个正在解决这个问题的新工具——OpenSpec。它不是又一个AI编码助手，而是一套让"人"和"AI"在写代码之前先达成共识的方法论和工具链。GitHub上已经超过5万Star，社区热度很高。
一、问题出在哪
先说说为什么需要这么个东西。
现在用AI写代码大致有两种风格。一种是"vibe coding"——直接跟AI说"帮我做个xxx"，然后祈祷结果是对的。另一种是仔细写prompt，把需求掰开了揉碎了喂给AI。
两种方式都有问题。前者太随意，产出质量完全看运气；后者看似严谨，但所有上下文都存在聊天记录里——关掉会话就没了，换个AI工具就全丢了，新同事来了更是一头雾水。
这就好比让一个建筑师在脑子里记住所有的设计图纸，然后直接动手盖房子。没有蓝图、没有施工图、没有验收标准，全凭记忆和感觉。
OpenSpec想做的事很简单：给AI编码也加上"蓝图"。
二、OpenSpec是什么
OpenSpec由Fission-AI团队开发，全称是Spec-Driven Development（规范驱动开发）框架。
一句话概括：在写任何一行代码之前，先和AI就"要做什么"达成明确共识，并把这份共识记录成结构化的活文档，作为整个开发过程的唯一事实来源。
它有四个核心理念：
流动而非僵化——没有死板的阶段门槛，你可以随时回头改前面的设计。
迭代而非瀑布——需求会变，理解会加深，这很正常。改规范就好，不用推倒重来。
简单而非复杂——几秒钟就能初始化，立刻开始工作，不需要学习一套重量级的流程。
为存量项目而生——大多数开发工作是在已有代码上改东西，不是从零开始。OpenSpec的"增量规范"设计就是为此优化的。
关键的一点：OpenSpec不依赖任何AI服务商，不需要API Key，所有规范都存在你的代码仓库里，跟着代码一起版本管理。
三、核心概念拆解
理解OpenSpec需要掌握几个关键概念，我用大白话解释一下。
3.1 Spec（规范）
Spec是OpenSpec的核心，它描述的是系统应该怎么表现，而不是怎么实现。
每个Spec包含两部分：需求（Requirement） 和场景（Scenario）。
需求描述"系统必须做什么"，用RFC 2119关键词（SHALL、MUST、SHOULD）来表述强度。场景是需求的具体例子，用经典的"Given-When-Then"格式。
举个例子，一个"用户登录"的Spec可能长这样：
需求：会话过期
系统SHALL在用户不活动24小时后使会话失效。
场景：默认超时
·GIVEN 用户已认证登录
·WHEN 24小时内没有任何活动
·THEN 使会话token失效
·AND 要求重新认证
注意：这是行为契约，不是实现方案。它不关心你用JWT还是Session，只关心"24小时不活动就要重新登录"这个行为。
3.2 Change（变更）
Change是你想对系统做的修改。每个变更都有自己的文件夹，里面包含理解这个变更所需的所有材料。
openspec/changes/add-remember-me/ ├── proposal.md← 变更提案（为什么做、做什么） ├── design.md← 技术设计（怎么做） ├── tasks.md← 任务清单（具体步骤） └── specs/← 增量规范（哪些需求变了） └── auth-session/ └── spec.md
这个设计很巧妙——每个变更都是自包含的。你不需要翻遍整个项目才能理解"这次改了什么"，打开变更文件夹就全清楚了。
3.3 Delta Spec（增量规范）
这是OpenSpec最亮眼的设计，也是它能优雅处理存量项目的关键。
Delta Spec不重写整个规范，而是用标记描述变化的部分：
·ADDED：新增了哪些需求
·MODIFIED：修改了哪些需求（以及从什么改成了什么）
·REMOVED：删除了哪些需求
举个例子，你想给登录加上"记住我"功能，Delta Spec是这样的：
## ADDED Requirements ### Requirement: Extended Session with Remember Me 用户勾选"记住我"后，系统SHALL将会话有效期延长至30天。 #### Scenario: Extended session with remember me - GIVEN 用户在登录时勾选了"记住我" - WHEN 30天过去 - THEN 使会话token失效 - AND 清除持久化cookie ## MODIFIED Requirements ### Requirement: Session expiration - 系统SHALL支持可配置的会话过期时间。 （之前：系统SHALl在配置时间后过期会话）
这个设计为什么重要？因为在真实项目中，大多数变更都是"改一点点"而不是"重写全部"。用Delta描述变更，既精确又轻量，还能在归档时自动合并回主规范。
3.4 Artifact（制品）
制品是变更文件夹里的各种文档：
制品 | 用途 | 回答的问题 |
proposal.md | 变更提案 | 为什么做？做什么？ |
specs/ | 增量规范 | 哪些行为变了？ |
design.md | 技术设计 | 怎么实现？ |
tasks.md | 任务清单 | 具体步骤是什么？ |
它们之间的关系是递进的：提案定了方向 → 规范定了行为 → 设计定了方案 → 任务定了步骤。但你可以随时跳回去修改任何一个，没有死板的顺序要求。
四、工作流：四步闭环
OpenSpec的核心工作流非常简单，就四步：
第一步：Propose（提案）
告诉AI你想做什么：
/opsx:propose add-dark-mode
AI会自动创建变更文件夹，生成proposal.md、Delta Specs、design.md和tasks.md。它会扫描已有的规范和代码，理解当前系统，然后生成结构化的变更提案。
第二步：Apply（实施）
/opsx:apply
AI按照tasks.md里的清单逐步实现代码。因为有明确的任务列表和验收标准，AI不会跑偏。
第三步：Sync（同步）
/opsx:sync
实施过程中如果发现了新问题、需要调整设计，可以同步更新各个制品，保持文档和代码的一致性。
第四步：Archive（归档）
/opsx:archive
变更完成后，归档操作会：
·把Delta Specs自动合并回主规范
·将变更文件夹移到archive目录，保留审计记录
·确保openspec/specs/始终代表系统的当前状态
一个闭环下来，你不仅得到了代码，还得到了一份完整的、和代码同步的行为规范。
五、实战演示：给应用加暗黑模式
假设我们要给一个Web应用添加暗黑模式。看看用OpenSpec怎么走。
启动提案：
你: /opsx:propose add-dark-mode AI: Created openspec/changes/add-dark-mode/ ✓ proposal.md — 用户要求暗黑模式，减少夜间使用的眼部疲劳 ✓ specs/— 新增"主题切换"需求，含手动切换和系统偏好检测场景 ✓ design.md— 使用CSS自定义属性 + React Context方案 ✓ tasks.md— 8个具体实现步骤 Ready for implementation!
AI生成的proposal.md：
意图：用户反馈夜间使用时白色背景太刺眼，需要暗黑模式。
范围：添加主题切换设置、支持系统偏好检测、localStorage持久化。
AI生成的Delta Specs（specs/ui/spec.md）：
新增需求"主题选择"：系统SHALL允许用户在浅色和暗黑主题之间切换。
场景一：手动切换——点击切换按钮，主题立即改变，偏好跨会话保持。
场景二：系统偏好——没有保存偏好时，自动跟随系统配色方案。
AI生成的tasks.md：
1.主题基础设施：创建ThemeContext、添加CSS变量、实现localStorage
2.UI组件：创建ThemeToggle组件、添加到设置页面
3.样式：定义暗黑色板、更新组件使用CSS变量
执行实施：
你: /opsx:apply AI: Working through tasks... ✓ 1.1 Created ThemeContext with light/dark state ✓ 1.2 Added CSS custom properties to globals.css ✓ 1.3 Implemented localStorage persistence ✓ 2.1 Created ThemeToggle component ✓ 2.2 Added toggle to settings page ✓ 2.3 Updated Header with quick toggle ✓ 3.1 Defined dark theme color palette ✓ 3.2 Updated all components to use CSS variables All tasks complete!
归档：
你: /opsx:archive AI: Archiving add-dark-mode... ✓ Merged specs into openspec/specs/ui/spec.md ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/ Done! Ready for the next feature.
整个过程，需求始终清晰、过程始终可追溯、文档始终和代码同步。
六、和同类工具对比
市面上类似思路的工具还有几个，做个横向对比。
vs GitHub Spec Kit：Spec Kit很全面但偏重量级，有严格的阶段门控，大量Markdown文档，还需要Python环境。OpenSpec更轻量，让你自由迭代，不想写design.md就可以跳过。
vs AWS Kiro：Kiro功能强大，但你被锁定在它的IDE里，模型选择也受限。OpenSpec和你已有的工具配合，Claude Code、Cursor、Windsurf、Copilot……二十多个AI助手都支持。
vs 什么都不用：没有规范的AI编码，本质上就是在用"模糊的提示"碰运气。OpenSpec在不增加太多仪式感的前提下，带来了可预测性。
vs 传统需求文档：传统需求文档写完就放那儿落灰了。OpenSpec的规范是活的——它跟着代码一起变，通过Delta Specs精确追踪每一次变化，永远是系统当前行为的准确描述。
还有一个容易被忽视的优势：工具无关性。今天你用Claude Code，明天可能换Cursor，后天可能又换别的。规范存在你的仓库里，不绑定任何特定AI工具。
七、谁适合用、怎么开始
适合的场景
个人项目：即使是一个人开发，有规范也能让AI更准确、减少返工。10分钟梳理需求，可能省下几小时的调试时间。
团队协作：规范跟着代码走，通过Git PR来审查变更。新成员看规范就能理解系统怎么运作，不用翻聊天记录或者问老员工。
存量项目：OpenSpec为存量项目优化。你不需要一开始就把所有模块都写好规范，用到哪里写到哪里，渐进式引入。
多AI工具混用：团队成员各用各的AI工具，但共享同一套规范。规范就是人机之间、机器之间、人人之间的"公共语言"。
可能不适合的场景
如果你只是写个一次性脚本，或者项目的寿命就是几个小时，那确实没必要上规范。
如果你期待的是一个"全自动"的工具——不需要你读规范、不需要你思考、AI自己搞定一切——OpenSpec不是干这个的。它的前提是你愿意花几分钟想想"到底要做什么"。
快速上手
三步就能开始用：
安装：
[bash]
npm install -g @fission-ai/openspec@latest
初始化：
[bash]
cd your-project openspec init
开始第一个变更：
在你的AI工具里输入：
/opsx:propose 你的功能描述
就这样。不需要配置API Key，不需要注册账号，不需要学习复杂的概念。先用起来，遇到需要深入理解的地方再回头看文档。
八、我的看法
OpenSpec解决的核心问题不是技术问题，而是协作问题——人和AI之间的协作。
过去几年，AI编码工具的能力突飞猛进，但我们使用它们的方式还停留在"聊天"层面。把需求放在聊天记录里，就像把建筑图纸放在餐巾纸上——能用，但不靠谱。
OpenSpec提出了一种更好的方式：把需求从"聊天"升级为"文档"，从"临时"升级为"持久"，从"模糊"升级为"结构化"。
它不会让AI变得更聪明，但能让AI的使用变得更可控。就像项目管理方法论不会让程序员写代码更快，但能让整个团队产出更可预测。
5万Star说明了一件事：很多开发者遇到了同样的问题，也认可这个解决思路。
如果你经常和AI写代码，而且经常遇到"AI理解错需求"或者"改来改去效率低"的问题，花10分钟试试OpenSpec，可能会有意想不到的收获。
参考资料：
·OpenSpec官网：https://openspec.dev/
·GitHub仓库：https://github.com/Fission-AI/OpenSpec
·OpenSpec概念文档：https://lzw.me/docs/openspec/en/concepts.html
·OpenSpec入门指南：https://lzw.me/docs/openspec/en/getting-started.html
·Jimmy Song：OpenSpec与SpecKit——AI时代的规范驱动开发新实践
