AI飞行客

掠过技术的云层，落地在工程的原野

近期文章

近期评论

您尚未收到任何评论。

归档

分类

OpenSpec：AI 编码时代的「规范驱动开发」，49K Stars 不是吹的

一句话总结：OpenSpec 不是又一个文档框架，而是 AI 编码助手的「工作流操作系统」——让人和 AI 在敲代码之前先对齐需求，用轻量级的规范层把模糊的想法变成可执行的工程计划。

一、先交代背景：为什么需要这个？

用过 Claude Code、Cursor、Windsurf 这类 AI 编码助手的都知道一个痛点：

你说了半天需求，AI 噼里啪啦写了几百行代码，结果发现方向错了。

问题出在哪？需求只存在于聊天历史里，没有一份被双方认可的「规范」作为基准。每次对话都是从零开始，AI 的记忆窗口又有限，改着改着就偏离了最初的目标。

这就是 OpenSpec 要解决的问题。

GitHub 上这个项目已经有 49,302 颗星，月下载量持续增长，社区 Discord 也很活跃。它的全称是「Spec-driven development (SDD) for AI coding assistants」，翻译过来就是：给 AI 编码助手用的规范驱动开发框架。

二、核心设计：两个目录，一套流

OpenSpec 的核心极其简洁，就两件事：

1. specs/ —— 系统的「唯一真值」

这个目录放的是你的系统当前长什么样。按领域组织：

openspec/specs/
├── auth/
│   └── spec.md      ← 认证模块的行为规范
├── payments/
│   └── spec.md      ← 支付模块的行为规范
└── ui/
    └── spec.md      ← UI 层的行为规范

每份 spec 用标准格式写，包含：

  • Requirements：系统必须做什么（用 SHALL/MUST，不用 should/may）
  • Scenarios：每个需求至少配一个 WHEN/THEN 场景
  • Invariants：不变量，改什么都不该碰的底线

2. changes/ —— 每个变更一个文件夹

这是 OpenSpec 最聪明的设计。每个 feature、bug fix、重构，都创建一个独立文件夹：

openspec/changes/add-dark-mode/
├── proposal.md      ← 为什么要做、做什么
├── specs/           ← 变更的 delta spec
│   └── ui/
│       └── spec.md  ← ADDED/MODIFIED/REMOVED
├── design.md        ← 技术方案
├── tasks.md         ← 实现 checklist
└── notes.md         ← 过程中的思考（可选）

变更完成后，用 sync 把 delta 合并进主 specs，然后 archive 归档。整个过程就像 Git 的 branch-merge 一样自然。

Delta Spec 格式

OpenSpec 用三种标记来描述变更，非常直观：

## ADDED Requirements
### Requirement: User can toggle dark mode
The system SHALL support a dark theme toggle.
#### Scenario: Toggle from light to dark
- **WHEN** user clicks the theme toggle
- **THEN** the UI switches to dark mode

## MODIFIED Requirements
### Requirement: Theme persistence
The system SHALL persist the user's theme preference...
（完整重写变更后的需求）

## REMOVED Requirements
### Requirement: Legacy theme switcher
**Reason**: Replaced by unified toggle component
**Migration**: Remove old `theme-switcher.js`, use new component

这个设计对 legacy 代码库特别友好——不需要重写整个系统的文档，只需要描述「这次改什么」。

三、OPSX 工作流：不是阶段，是动作

传统的工作流把开发切成阶段：先规划，再实现，再验收。但真实的工作是流动的——你写了一半发现设计有问题，需要回过去改 spec，再继续实现。

OpenSpec 的新 OPSX 工作流放弃了「阶段」概念，改用动作（Actions）：

proposal ──► specs ──► design ──► tasks ──► implement
    ▲          ▲          ▲              │
    └──────────┴──────────┴──────────────┘
              随时回去改

核心命令（slash commands）

在 AI 助手的聊天界面里直接输入：

命令 作用
/opsx:propose "你的需求" 一键创建 proposal + specs + design + tasks
/opsx:explore 先探索、调研，不急着立项
/opsx:apply 按照 tasks.md 开始实现
/opsx:sync 把 delta spec 合并到主 specs
/opsx:archive 归档已完成的变更

如果你想更精细地控制流程，可以用扩展模式：

  • /opsx:new → /opsx:continue（逐个 artifact 创建）
  • /opsx:ff（fast-forward，一次性生成所有 artifact）
  • /opsx:verify（验证实现是否匹配 spec）

一个完整的工作流示例

You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — 为什么要做深色模式
     ✓ specs/       — 新增的需求和场景
     ✓ design.md    — 技术方案：CSS变量 + React Context
     ✓ tasks.md     — 实现 checklist
     Ready for implementation!

You: /opsx:apply

AI:  Implementing tasks...
     ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 2.1 Add CSS variables
     ✓ 2.2 Wire up localStorage
     All tasks complete!

You: /opsx:sync

AI:  ✓ Merged delta specs into openspec/specs/ui/spec.md

You: /opsx:archive

AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

整个过程在 AI 助手里完成，不需要切来切去。

四、实战场景：五个真实案例

光讲设计太虚，下面用五个真实场景告诉你 OpenSpec 到底怎么用。

场景一：新项目从零启动

你刚接了个新项目——一个电商后台管理系统。团队就你一个人，AI 助手是你唯一的「队友」。

传统做法：打开编辑器，新建文件，边想边写，写了一周发现数据库模型设计错了。

OpenSpec 做法：

You: /opsx:propose ecommerce-admin-dashboard

AI:  Created openspec/changes/ecommerce-admin-dashboard/
     ✓ proposal.md — MVP 范围：商品管理 + 订单管理 + 用户管理
     ✓ specs/
        ├── product/spec.md    ← 商品的增删改查、库存校验
        ├── order/spec.md      ← 订单状态机、支付回调
        └── user/spec.md       ← 角色权限、JWT 认证
     ✓ design.md — 技术选型：Next.js + Prisma + PostgreSQL
     ✓ tasks.md — 48 个 task，分 6 个迭代
     Ready for implementation!

You: /opsx:apply

AI:  Implementing tasks...
     ✓ 1.1 Initialize Next.js project with TypeScript
     ✓ 1.2 Setup Prisma schema for Product
     ✓ 1.3 Implement Product CRUD API
     ...

关键收益：在你写第一行代码之前，AI 已经帮你把模块划分、数据模型、API 设计都想清楚了。一旦实现过程中发现某个设计有问题，你可以随时回过去改 design.md，然后继续 apply。方向不会偏。

场景二：老项目接入 OpenSpec（Brownfield）

这是最常见的场景——你手里已经有一个跑了三年的 Node.js 项目，代码 5 万行，没有文档，接手的人换了三拨。

你不需要「先把所有代码写成 spec」——那是不可能的。你只需要从现在开始，每次变更带一份 delta spec。

# 第一步：初始化
$ openspec init
$ openspec update

# 第二步：开始第一个变更——加一个导出报表功能
You: /opsx:propose add-order-export-csv

AI:  Created openspec/changes/add-order-export-csv/
     ✓ proposal.md — 运营团队需要导出订单数据到 Excel
     ✓ specs/order/spec.md — ADDED: 订单导出 Requirements
     ✓ design.md — 流式导出 + 内存控制（老项目内存吃紧）
     ✓ tasks.md — 6 个 task

# 实现完成后
You: /opsx:sync

AI:  ✓ Merged delta into openspec/specs/order/spec.md
     你的主 specs 现在包含了「订单导出」的规范

关键收益：legacy 项目不需要一次性「还债」，而是每次变更时「顺带存一份档」。三个月后，你的 specs 可能已经覆盖了 60% 的核心功能，新接手的同事再也不需要读源码猜行为了。

场景三：做到一半，需求变了

这是所有工程师的噩梦。你按 spec 实现了 80%，产品经理过来说：「导出功能能不能加个筛选？只要已付款的订单。」

传统做法：在脑子里记一下，改代码的时候容易漏。或者重新口述一遍需求给 AI，AI 可能理解成另一个意思。

OpenSpec 做法——Fluid 工作流的优势就在这里：

You: 我现在要修改当前的 change，加一个新需求

AI:  当前 change: add-order-export-csv
     你可以直接告诉我需要改什么，我会更新对应的 artifact。

You: 导出功能需要增加筛选条件：只导出 status='paid' 的订单

AI:  ✓ Updated specs/order/spec.md
     ADDED: Requirement — 导出 MUST 支持按订单状态筛选
     ✓ Updated design.md
     技术方案调整：查询增加 WHERE status='paid'
     ✓ Updated tasks.md
     ADDED: 2.3 实现状态筛选参数

You: /opsx:apply

AI:  ✓ 2.3 Implement status filter in export query
     All tasks complete!

关键收益：需求变了不用「从头来」，回去改对应的 artifact 就行。AI 知道当前 change 的全部上下文，不会把旧需求和新需求搞混。所有变更都有记录，三个月后你翻回来还能看「当时为什么加了筛选」。

场景四：线上出了 Bug

凌晨 2 点，监控报警：用户支付成功后订单状态没变成「已支付」。你顶着困意开干。

传统做法：直接改代码，越改越乱，第二天发现引入了新的 bug。

OpenSpec 做法——把 bug fix 当成一个 change 来管理：

You: /opsx:propose fix-payment-callback-status

AI:  Created openspec/changes/fix-payment-callback-status/
     ✓ proposal.md
       Why: 支付回调后订单状态未更新为 paid
       Root Cause: 回调 handler 中事务未正确提交
       Impact: 影响所有微信支付订单
     ✓ specs/order/spec.md
       MODIFIED: 支付回调处理 Requirements
       ADDED: 回调处理 MUST 在事务内完成状态更新
       ADDED Scenario: 支付成功后 5 秒内订单状态变为 paid
     ✓ design.md
       修复方案：将状态更新移入同一个 Prisma transaction
     ✓ tasks.md
       ☐ 1.1 复现 bug（构造支付回调测试数据）
       ☐ 1.2 修复 transaction 范围
       ☐ 1.3 添加单元测试：验证回调后状态正确
       ☐ 1.4 回归测试：确保其他支付方式不受影响

You: /opsx:apply

AI:  Implementing tasks...
     ✓ 1.1 复现成功：构造了微信支付回调，确认状态未更新
     ✓ 1.2 修复：将 $transaction.order.update 纳入同一事务
     ✓ 1.3 新增测试：payment-callback.test.ts
     ✓ 1.4 回归通过：支付宝、Stripe 回调均正常
     All tasks complete!

You: /opsx:verify

AI:  ✓ 验证通过：spec 中所有 scenario 均已实现
     ✓ 订单状态在回调后正确变为 paid

关键收益：bug fix 不再是一次「手快脑慢」的应急操作，而是一个有记录、有根因分析、有回归验证的变更。三个月后复盘，你能在 archive 里找到完整的事故处理记录，包括根因、方案、测试覆盖——这就是技术债务管理。

场景五：多人并行开发，怎么不打架

你和同事小明同时在开发：你在做「订单导出」，小明在做「订单退款」。两个功能都改 orders 表。

传统做法：口头沟通「你改哪几个字段？」「我先合还是你先合？」容易踩坑。

OpenSpec 做法：

# 你的 change
openspec/changes/add-order-export-csv/
└── specs/order/spec.md  ← 只描述「导出」相关需求

# 小明的 change
openspec/changes/add-order-refund/
└── specs/order/spec.md  ← 只描述「退款」相关需求

两个人各自在自己的 change 文件夹里工作，互不干扰。等要 sync 的时候，OpenSpec 会提示你们两个 change 都改了 specs/order/spec.md，需要人工 review 合并。

You: /opsx:sync

AI:  ⚠️ Conflict detected in specs/order/spec.md
     Your change: ADDED export requirements
     Other change (add-order-refund): ADDED refund state requirements
     Both changes are compatible. Merging...
     ✓ Merged successfully.

关键收益：每个 change 是一个独立的「变更包」，多人并行时不会互相覆盖。冲突在 sync 阶段被发现和解决，而不是在代码合并时才发现「你改了我改的同一个接口」。

看完这五个场景，你应该能感觉到：OpenSpec 不是「又多了一个写文档的累赘」，而是把「规划、实现、验证、归档」串成了一条流水线。每个场景都有对应的命令和 artifact，不空喊口号。

五、兼容性：不挑食

这是 OpenSpec 最让我佩服的一点——它不绑任何工具。

它支持 25+ 个 AI 编码助手，包括：Claude Code、Cursor、GitHub Copilot、Cline、Windsurf、Amazon Q Developer、Continue、Gemini CLI、Kimi CLI，以及更多…

关键是，openspec init 在项目根目录创建 openspec/ 文件夹（specs、changes、config），这个规范层跟工具无关——不管你换 Cursor、Claude Code 还是 Windsurf，openspec/ 始终在根目录，所有工具读的是同一份规范。

与此同时，它还会在你选择的 AI 助手目录里安装 skill 文件，告诉 AI 怎么调用这套工作流。比如在 Cursor 里生成 .cursor/skills/openspec-*/SKILL.md，在 Claude Code 里生成 .claude/skills/openspec-*/SKILL.md。

这意味着：工具可以换，规范层不动。不像某些方案把你锁死在特定的 IDE 或模型上。

六、与其他方案的对比

vs GitHub Spec Kit

GitHub 也出了个 Spec Kit，设计得很 thorough，但太重了：有 rigid phase gates，必须先规划再实现；大量 Markdown 格式要求；需要 Python 环境。OpenSpec 的定位是「lighter and lets you iterate freely」——轻量、灵活、随时改。

vs Kiro (AWS)

Kiro 很强，但有两个硬伤：锁死在自家的 IDE 里，只支持 Claude 模型。OpenSpec 不挑 IDE、不挑模型，「works with the tools you already use」。

vs Nothing

不设规范直接用 AI 编码？可以，但结果不可预测。同一个需求，每次给 AI 的上下文不同，产出也不同。OpenSpec 带来的不是「更多文档」，而是「可预测性」——你和 AI 先对齐 spec，再动手写代码，返工率大幅下降。

七、技术实现：可定制、可扩展

OpenSpec 本身是一个 TypeScript 的 npm 包：@fission-ai/openspec。安装后通过 CLI 初始化项目：

npm install -g @fission-ai/openspec@latest
openspec init

Schema 驱动的可定制性

OPSX 工作流的核心是一个 schema.yaml 文件，定义了 artifact 的序列和依赖关系。你可以改 schema、改 template、改 instruction，改完立即生效，不需要等新版本发布。

社区 Schema

OpenSpec 还搞了个社区 schema 目录，类似于插件生态。你可以引入别人设计好的工作流模板，比如「微服务变更工作流」、「前端组件开发工作流」等。

八、我的评价：它解决了一个真问题

在 AI 编码助手横行的今天，我见过太多「AI 写了一堆代码但方向错了」的惨案。OpenSpec 的思路是对的：不要把 AI 当成一个「打字更快的工程师」，而是把它当成一个「需要明确需求的协作者」。

它的几个设计决策我非常认同：

  1. Brownfield-first：大多数项目不是从零开始，而是改现有系统。Delta spec 的设计完美匹配这个现实。
  2. Fluid not rigid：不强制阶段门，允许随时回退。真实的工程就是这样的。
  3. Tool-agnostic：不锁任何 IDE 或模型。在当前这个 AI 工具百花齐放的时代，这个决策非常明智。
  4. Lightweight：初始化只要 openspec init，没有繁重的 setup 过程。

当然它也不是完美的。几个需要注意的点：

  • 模型门槛：官方推荐用高推理能力的模型（Opus 4.5、GPT 5.2），低能力模型可能无法很好地理解和执行 spec
  • 上下文管理：需要在干净的上下文窗口里工作，聊天历史不能太长
  • 学习成本：虽然比 Spec Kit 轻，但仍有规范格式需要学习（尤其是 delta spec 的格式要求）

九、最后一句

OpenSpec 的 slogan 很到位：

Agree before you build.

在 AI 能写代码但不一定写对的今天，「先对齐再动手」可能是比「更快写代码」更有价值的能力。

如果你还没试过，建议花十分钟跑一遍 openspec init + /opsx:propose 的流程。至少我的体验是：这 10 分钟的规划，能省掉后面几小时的返工。

参考链接

  • GitHub: https://github.com/Fission-AI/OpenSpec
  • npm: https://www.npmjs.com/package/@fission-ai/openspec
  • Discord: https://discord.gg/YctCnvvshC

—— END ——

Previous Article
Next Article

发表回复

Your email address will not be published. Required fields are marked *.

*
*