一、「感觉流」编程的尽头

你有没有过这种经历——

打开 Claude Code 或 Cursor，把需求用两句话丢进去，AI 噼里啪啦写了一堆代码。乍一看还不错，跑起来才发现漏了三个边界条件、两个关键参数，还有一个功能你明明在聊天记录里提过但它完全没理会。于是你继续对话、反复修正、越改越乱，最后干脆 /clear 重来。

这个问题的根因不是模型不够聪明，而是需求没有被结构化。

聊天记录是线性的、散落的、随时被压缩截断的。当你在对话里说"然后把这个也加上""哦对了还有那个"，AI 看不到优先级、看不到依赖关系、看不到全局。它只是在一次一次地猜你的意思。

这就是 Fission-AI 团队提出的诊断：AI 编码的瓶颈不是模型能力，而是 欠规范化（underspecification）。

他们的答案是 OpenSpec——一个开源、轻量的规范驱动开发（Spec-Driven Development, SDD）框架，在写任何代码之前，先在代码库里铺一层 Markdown 规范。

二、OpenSpec 是什么

OpenSpec 由 Fission-AI（创始人 Tabish）于 2025 年底发布，不到半年在 GitHub 上获得 27,000+ 颗星，入选 Y Combinator，目前已有 v1.0.0 稳定版。

一句话概括它的核心思想：

把规范文件变成 AI 编码 Agent 的「机器可读合同」——人类意图和 AI 执行之间的结构化桥梁。

它不是另一个 AI 编码工具，而是一个叠加在现有工具之上的规范层。你继续用 Claude Code、Cursor、Copilot——OpenSpec 在背后提供一套结构化的 spec 文件，让 AI 每次执行前都能读取完整的需求、设计和任务拆解。

openspec/
├── specs/              # "真相源" —— 当前系统的规范描述
│   └── [capability]/
│       └── spec.md
└── changes/            # 变更区 —— 进行中和已归档的变更
    └── [change-name]/
        ├── proposal.md   # 为什么要做、做什么
        ├── design.md     # 怎么做、技术决策
        ├── tasks.md      # AI 可执行的任务清单
        └── specs/        # Delta 规范 (ADDED/MODIFIED 标记)

这四个文件构成了每次变更的完整上下文。AI 不是靠"回忆"你几分钟前说了什么，而是直接读取这套结构化的规范文件。

三、核心概念拆解

3.1 proposal.md —— 为什么和做什么

在动手之前，先把动机和目标写清楚：

这不是摆设。一份好的 proposal 让 AI 能从意图层面理解任务，而不是机械地匹配关键词。

3.2 design.md —— 怎么做

技术决策写在这里：

对团队来说，design.md 的价值甚至超过代码本身——代码审查被前置到了设计审查。reviewer 不再盯着几百行的 diff 去反推开发者的思路，而是直接在 design.md 里看决策逻辑。

3.3 tasks.md —— AI 的执行清单

这是整套系统里最精妙的设计。tasks.md 不是给人类看的 TODO，而是给 AI 编码 Agent 的可执行指令：

## 1. 数据模型变更
- [ ] 1.1 在 `models.py` 中新增 `UserRole` 枚举
- [ ] 1.2 在 `User` 模型中添加 `role` 字段和迁移脚本
- [ ] 1.3 更新 `schemas.py` 中的 Pydantic 模型

## 2. API 层实现
- [ ] 2.1 在 `auth.py` 中新增 `require_role` 依赖注入
- [ ] 2.2 修改 `/users` 端点的权限校验逻辑
- [ ] 2.3 添加 `tests/test_auth.py` 中的角色验证用例

每一条任务都是可验证、可追踪的。AI 逐条执行，人类逐条确认。这种确定性正是「感觉流」所不具备的。

3.4 specs/ —— 真相源

specs/ 目录存储的是当前系统已经实现的能力规范。它不是设计文档，而是系统行为的"快照"。当一次变更完成并归档后，delta spec 中的 ADDED / MODIFIED 内容会合并回主 spec 库，保持真相源与实际代码同步。

四、OPSX 工作流

OpenSpec v1.0 引入了 OPSX（OpenSpec eXperience）——一套动作驱动的命令系统，取代了早期版本中僵硬的阶段门控。

命令 做什么 什么时候用
/opsx:explore 只读探索代码库，不创建文件 想法还不成熟，先看看现状
/opsx:propose <name> 一键生成 proposal + design + tasks + delta specs 需求明确了，开始规划
/opsx:apply AI 逐条执行 tasks.md，按锁定计划实现 计划已审批，动手写代码
/opsx:archive 将完成的 delta specs 合并回主 spec 库 变更完成，归档收尾
/opsx:verify 验证实现是否符合规范 apply 之后的交叉检查
/opsx:sync 同步 delta specs 到主 specs 多人协作时的同步操作

这套流程的设计哲学是：

"Fluid not rigid, iterative not waterfall"

你不会被锁在一个僵硬的瀑布模型里。propose 完了觉得设计不对，可以重新 propose。apply 到一半发现漏了东西，可以补充 tasks 继续。每个动作都是独立的、可重复的、可跳过的。

五、动态指令机制

OpenSpec 最被低估的设计是它的动态指令系统。

传统的 AI 编码方式是"静态 prompt"——你在 .claude/instructions.md 或 .cursorrules 里写一堆规则，AI 在需要的时候（可能）会读到。但这些文件不会根据项目状态变化而自动更新。

OpenSpec 的做法不同：AI 通过 CLI 命令实时查询项目状态。

openspec status --json
# 返回：当前有哪些活跃的变更、哪些待归档、哪些 specs 已过期

openspec instructions --json
# 返回：根据当前项目状态动态生成 AI 应该遵循的指令

这意味着 AI 不是靠"记忆"来了解项目状态，而是每次执行前都从命令行获取最新信息。项目状态变了，指令自动跟着变——不用手动维护 prompt 文件。

这也是为什么 OpenSpec 能支持 21+ 种 AI 编码工具：它为每个平台生成原生的 slash command 或 skill，底层统一通过 CLI 获取项目上下文。

六、Delta Specs 与语义合并

Brownfield 项目（已有代码库的 1→n 开发）是 SDD 最难处理的场景。Greenfield 可以尽情定义完整 spec，但往已有系统加功能时，你不可能为整个系统重写 spec。

OpenSpec 的解决方案是 Delta Specs——只描述变更的增量：

## ADDED Requirements
### Requirement: 用户角色管理
系统必须支持 `admin`、`editor`、`viewer` 三种角色。
admin 拥有全部权限，editor 可编辑内容，viewer 只读。

## MODIFIED Requirements
### Requirement: 用户认证流程
认证成功后，系统必须检查用户角色并附加到请求上下文中的
`request.role` 字段。

归档时，openspec archive 命令会做语义合并——将 ADDED 内容追加到主 spec，将 MODIFIED 内容替换原有章节。整个过程有版本控制（Git），可以回溯、可以回滚。

这种增量机制让 SDD 在已有代码库中也能落地，不需要一次性补齐全部 spec。

七、方案对比

7.1 OpenSpec vs. 纯 Prompt 工程

维度 纯 Prompt 工程 OpenSpec
需求存储 聊天记录中散落 结构化的 Markdown 文件，可版本控制
AI 上下文 依赖对话历史和压缩算法 AI 主动查询 CLI 获取结构化状态
可审查性 审查代码 diff 反推意图 先审查 design.md，再对照 tasks.md 逐条验证
可复用性 每次重新描述 spec 文件可继承、可迁移到同类项目
团队协作 各自维护 prompt 文件 统一的 spec 目录，提交到 Git

7.2 OpenSpec vs. Superpowers

这两个项目经常被放在一起比较，因为它们在同一个生态位上——都试图让 AI 编码更结构化。但核心思路不同：

实际使用中两者可以互补。你可以用 OpenSpec 管理需求和设计规范，用 Superpowers 里的 TDD 和 code review 技能来执行实现和验证。

7.3 OpenSpec vs. 手工维护 Spec 文件

维度 手工 Spec OpenSpec
格式一致性 每个人写法不同 统一的 proposal/design/tasks 模板
AI 集成深度 AI 不会主动读取 CLI 动态查询 + 原生 slash command
归档与合并 手动管理 archive 命令自动语义合并
学习曲线 零 15 分钟上手（/opsx:onboard）

八、实践建议

什么时候值得用

什么时候可能太重

最小化上手路径

# 1. 全局安装
npm install -g @fission-ai/openspec@latest

# 2. 在项目根目录初始化
cd your-project
openspec init

# 3. 跟 AI 说一句话
/opsx:propose "你要做的东西"

然后 AI 会自动创建 proposal.md、design.md、tasks.md 和 delta specs。你审查完后说 /opsx:apply，它就按清单逐条实现。

九、总结

OpenSpec 本质上是在回答一个问题：在 AI 大规模参与编码的时代，人类如何保持对软件的控制力？

它的答案是让规范成为"一等公民"——不是写完了就丢的 PRD，而是和代码一起存在于仓库中、可被 AI 实时读取和执行的机器可读合同。

核心要点：

从「感觉流」到工程纪律，OpenSpec 提供了一条可落地、可扩展的路径。

参考资料