用AI写代码,你真的需要OpenSpec

用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（制品）

制品是变更文件夹里的各种文档：

它们之间的关系是递进的：提案定了方向 → 规范定了行为 → 设计定了方案 → 任务定了步骤。但你可以随时跳回去修改任何一个，没有死板的顺序要求。

四、工作流：四步闭环

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时代的规范驱动开发新实践