OpenSpec 深度剖析：规约驱动开发的终极形态

公众号名称：James的成长日记

作者名称：Jameszyh

发布时间：2026-06-20 12:50

大家好，我是 James。

上一篇我们拆了任务原子化——把一个大任务拆成可以独立执行的最小单元，每个单元有明确的输入、输出和验收标准，AI 在有限的上下文窗口里也能稳定输出高质量结果。

这一篇我们聊一个专为「改现有代码库」设计的框架：OpenSpec。

先说一个很多人都有过的体验：从零开始做一个新项目，和在一个已有几十万行代码的存量系统上加一个功能，难度根本不是一个量级。新项目可以从白纸画起，规范随你定；存量系统里有历史包袱、有约定俗成、有不能动的「禁区」——AI 不了解这些，动一下就可能踩地雷。

OpenSpec 就是专门解决这个问题的。它不是一个新建项目的脚手架，是一个叠加在现有代码库上的规约层：告诉 AI 这个项目是什么、能改什么、不能改什么、改完了怎么验收。

01 | 为什么选 OpenSpec 作为 SDD 类的代表？

规范驱动开发（SDD）类 Harness 框架有多个：Spec-Kit、Kiro、OpenSpec。选择 OpenSpec 作为代表的原因有四：

设计最纯粹：OpenSpec 把「规范驱动」的核心理念——Delta Spec（增量规范）——做到了极致。别的框架还在纠结「全量规范怎么写」，OpenSpec 直接说「只写这次变了什么」。

棕地友好：现实世界绝大多数项目是棕地（已有代码），不是从零开始的绿地。OpenSpec 比 Spec-Kit 更贴合实际——它不需要你一次性把整个系统的规范都写出来，而是允许你渐进式接入。

工具无关：不绑定特定 IDE 或 AI 模型，方法论价值最高。你可以在 Claude Code 里用，在 Cursor 里用，甚至在纯命令行里用。

设计可迁移：理解 OpenSpec 的设计哲学后，反推 Spec-Kit、Kiro 等都很容易。它代表了一类框架的共性设计原则。

02 | 设计哲学：规范是契约，不是文档

哲学 1：规范是契约，不是文档

传统观念里，规范是写给人看的文档，可有可无。OpenSpec 的观念截然不同：规范是 AI 和人类共同遵守的契约，是强制性的。

具体体现：主规范（specs/）描述当前系统的真实行为；任何变更必须先修改规范，再改代码；AI 在 Apply 阶段必须严格按规范执行，不能「自由发挥」。这就像 TypeScript 的类型系统——规范不是事后注释，而是事前约束。

哲学 2：变更是一等公民

传统观念里，变更是 commit message 里的一句话。OpenSpec 的观念：变更是独立、可审计、可回滚的实体。

具体体现：每个变更有完整产物（proposal + specs + design + tasks）；每个变更在 changes/ 目录中独立存储；归档后保留完整审计历史。这就像 Git 把「提交」变成一等公民改变了软件协作；OpenSpec 把「变更」变成一等公民改变了规范协作。

哲学 3：增量优于全量

传统观念里，每次都重新描述完整系统。OpenSpec 的观念：只描述这次变了什么。

具体体现：Delta Spec 只用 ## ADDED、## MODIFIED、## REMOVED 三种段落；主规范由历次 delta 累积合成；系统的「完整画像」是涌现的，不是预先定义的。这就像数据库的 WAL（Write-Ahead Log）——通过增量日志能恢复任意时间点的状态。

03 | 架构剖析：四个关键概念

概念 1：主规范（Main Specs）

描述系统当前的真实行为，作为权威真相源。按领域组织（auth/、payments/、api/），内容是「完整描述」，不含变更标记，由多次变更归档累积形成。AI 在做新变更时，先读主规范了解现状。

示例（specs/auth/user-login.md）：

# 用户登录规范

## 功能描述
用户通过邮箱+密码登录系统。

## 行为契约
- 登录成功：返回 JWT token，有效期 24 小时
- 密码错误：返回 401，第 5 次失败锁定账号 30 分钟
- 邮箱不存在：返回 401（不暴露具体原因）

概念 2：变更（Changes）

描述一次具体的变更意图、设计和任务。每个变更目录包含 4 个核心文件：

文件	职责
proposal.md	为什么要这次变更（动机、影响、风险）
specs/*.md	这次变更的 Delta Spec（增量规范）
design.md	技术设计（架构、数据流、容错）
tasks.md	原子化的任务清单

概念 3：Delta Spec（增量规范）

这是 OpenSpec 最核心的创新。三种操作：

## ADDED Requirements
### 暗色模式开关
- 用户在设置页面可切换暗色模式
- 偏好保存在 localStorage

## MODIFIED Requirements
### 颜色变量定义 [MODIFIED]
- 旧：硬编码 #FFFFFF, #000000
- 新：使用 CSS 变量 --bg-primary, --text-primary

## REMOVED Requirements
### 强制白色主题
（移除，由暗色模式开关替代）

合并规则：ADDED → 追加到主规范对应章节，MODIFIED → 替换主规范的对应内容，REMOVED → 从主规范中删除。

概念 4：配置（config.yaml）

告诉 AI 项目的全局上下文：技术栈、编码规范、AI 指令等。相当于项目的元数据，比 Spec-Kit 的 constitution.md 更轻量。

04 | 工作流深度解析

OpenSpec 有两套 Profile。

Profile 1：Quick（快速模式，默认）

适合简单变更，3 个核心命令：

/opsx:propose ：创建变更提案
/opsx:apply：执行任务实现
/opsx:archive：归档变更

Profile 2：Expanded（扩展模式）

适合复杂变更，提供更细的步骤：

/opsx:explore：探索现有代码，生成初始规范
/opsx:new ：脚手架创建变更目录
/opsx:continue：逐步生成 proposal → specs → design → tasks
/opsx:verify：校验实现与规范一致性
/opsx:apply：执行实现
/opsx:archive：归档

完整工作流详解（Quick 模式）：

Step 1：/opsx:propose 内部发生了什么？读取 config.yaml 获取项目上下文 → 读取 specs/ 了解系统现状 → 分析现有代码库 → 生成 changes/ 目录 → 创建 proposal.md、Delta 规范、design.md、tasks.md。关键点：AI 不是凭空想象，而是先理解现状再设计变更。

Step 2：人类审阅与迭代。这是最关键但常被忽略的环节。人类需要审查 proposal.md（变更动机是否合理）、specs/*.md（Delta 是否完整）、design.md（技术方案是否可行）、tasks.md（任务粒度是否合适）。任何一项不满意，可以直接编辑文件或让 AI 补充。

Step 3：/opsx:apply 内部发生了什么？读取 changes/ 全部产物 → 按 tasks.md 顺序逐个执行任务 → 每个任务完成后在 tasks.md 中标记、提交一个 atomic git commit → 全部完成后标记变更可归档。关键点：任务原子化执行，严格按 spec 实现，不「自由发挥」。

Step 4：/opsx:archive 内部发生了什么？验证所有任务都已完成 → 运行测试 → 合并 Delta Specs 到主规范 → 把变更目录移动到 changes/archived/ → 生成归档摘要。关键点：归档不是简单的目录移动，而是真相源更新。归档后，系统的「当前真实行为」就包含了这次变更。

05 | 精妙设计：五个值得学习的点

设计 1：变更隔离

每个变更在自己的目录中独立存在，互不干扰。好处：多个变更可以并行开发（多个分支同时进行），任何变更可以独立放弃（删除目录即可），变更间的冲突在合并时显式暴露。

设计 2：归档保留历史

归档后的变更不是删除，而是移到 changes/archived/。好处：完整的审计历史（谁、什么时候、改了什么、为什么），可以回溯任何决策的原始动机，替代了一部分 ADR（架构决策记录）的作用。

设计 3：Delta 比 Diff 更高层

Git diff 是字符级的差异，难以理解语义。OpenSpec Delta 是需求级的差异，直接表达意图。比如「超时时间从 60 分钟改为 30 分钟，原因：响应安全合规要求」——人和 AI 都能理解。

设计 4：先理解后设计

/opsx:propose 强制 AI 先读取现有 specs 和代码，再生成变更。这避免了 AI 的两个常见错误：凭空设计（不考虑现有架构）和重复造轮子（已存在的功能再实现一遍）。

设计 5：渐进式接入

不需要一次性把整个系统的规范都写出来。典型接入路径：第 1 个月只为新功能写规范，第 2 个月修改 Bug 时顺便补上相关模块的规范，第 6 个月核心模块的规范已基本完整。主规范是涌现的，不是预先定义的。这是 OpenSpec 比 Spec-Kit 更友好的根本原因。

06 | 在三大原理上的体现

决策外化为文件

决策类型	外化文件
全局约定	config.yaml
系统现状	specs/*
变更动机	changes/*/proposal.md
技术决策	changes/*/design.md
执行进度	changes/*/tasks.md
历史记录	changes/archived/*

评价：决策外化做得全面且分层。每个决策都有明确的归属文件。

流程结构化为阶段

Quick 模式：Propose → Apply → Archive（三阶段）。Expanded 模式：Explore → New → Continue → Verify → Apply → Archive（六阶段）。评价：阶段化做得清晰但灵活。Quick 模式的三阶段是 SDD 类框架中最少的，但通过 Expanded 模式提供了细粒度选项。

任务原子化为单元

OpenSpec 在 tasks.md 中拆分原子任务，但不强制子代理隔离执行。评价：任务原子化做得到位但执行隔离不强。这是 OpenSpec 的弱点——它假设你用 Claude Code 等工具的子代理能力配合。

07 | 局限、适用场景与对比

局限 1：规范维护成本

虽然 Delta 模式降低了启动成本，但长期维护规范仍需投入。如果团队不严格执行「先改规范再改代码」，主规范会逐渐与代码脱节。对策：把「更新规范」作为 PR 合并的硬性要求。

局限 2：对小变更过重

修复一个简单 typo，也要走 propose → apply → archive？对策：定义「豁免范围」——纯 bug 修复、文档调整等可不走流程。

局限 3：跨服务协调能力有限

虽然天然支持跨服务变更（一个 change 可含多服务的 specs），但没有内置的服务依赖编排。对策：在 design.md 中明确部署顺序，或与 OMC、GSD 等编排框架组合使用。

局限 4：依赖团队的工程文化

OpenSpec 的价值依赖于团队愿意写规范、读规范、维护规范。如果团队仍然「只看代码不看 spec」，OpenSpec 会沦为形式。对策：把规范评审纳入代码评审流程。

适用场景判断：

场景特征	推荐度
已有项目（棕地）	★★★★★
频繁迭代（每周多次变更）	★★★★★
重构频繁（架构经常调整）	★★★★★
需要变更审计	★★★★★
新项目（绿地）	★★★
强调快速 prototype	★★

与 Spec-Kit 的最终对比：

维度	OpenSpec	Spec-Kit
核心数据模型	Delta Spec（增量）	Full Spec（全量）
类比	Git（快照+增量）	Word 文档（直接编辑）
启动成本	低（直接 propose）	高（先写宪法）
棕地友好度	★★★★★	★★★
变更审计	★★★★★	★★★
适合「修一个 bug」	重	重
适合「加大功能」	★★★★	★★★★★

常见坑

规范与代码脱节：不严格执行「先改规范再改代码」，主规范逐渐变成摆设。对策：把规范更新纳入 PR 检查清单。
Delta 写得太粗：ADDED 段落里塞了太多内容，失去了「增量」的意义。对策：一个变更只做一件事，Delta 只描述这件事的变化。
跳过人类审阅：AI 生成的 proposal 和 design 直接 apply，没有人工把关。对策：propose 阶段必须有人类 review。
归档后不再维护：主规范累积了多次变更后变得臃肿。对策：定期重构主规范，合并同类项，删除过时内容。
过度使用 Expanded 模式：简单 typo 修复也走六步流程，团队很快会厌倦。对策：定义豁免范围，小变更走 Quick 模式。

总结

OpenSpec 是面向 AI 编程时代的变更管理基础设施，不是 IDE 插件，不是 AI 工具，而是一种规范代码变更的工程化方法
三大设计哲学：规范是契约不是文档、变更是一等公民、增量优于全量
Delta Spec 是最核心的创新：用 ADDED/MODIFIED/REMOVED 三种操作表达变更意图，比 Git diff 更高层
渐进式接入：不需要一次性写完所有规范，主规范是涌现的
棕地友好：专为改现有代码库设计，比 Spec-Kit 更贴合实际
局限明确：规范维护成本高、对小变更过重、依赖团队工程文化

关注我，James 的成长日记，持续分享干货，帮你在 AI 时代少走弯路。

内容效果不满意？点此反馈