AI 编程 agent 越写越歪？OpenSpec 把规格说明塞进代码库，让 agent 按图施工

你让 AI 编程 agent 加个功能，它先改了三个无关文件，顺手重构了半条工具链，还自作主张加了个全局缓存——你说的是「加个暗色模式」，它交付的是「一场你没法 code review 的架构运动」。

问题不在模型变笨。问题在你的需求只活在那条聊天记录里：上下文一滚动，早期决策就蒸发了；agent 每次开工都是「断片」状态。

TL;DR

OpenSpec 是 Fission-AI 的开源 SDD（spec-driven development）框架，GitHub 68.5k star，思路：agent 读 openspec/changes/ 下的 proposal + delta specs + design + tasks，再动代码，规格进 Git 而不是进聊天记录。

核心循环就三条：/opsx:explore 摸代码定方案 → /opsx:propose 生成规格文档 → /opsx:apply 照单施工 → /opsx:archive 归档。轻量、无 phase gate，比 GitHub Spec Kit 轻、比 Kiro 不绑 IDE。

对老项目最友好：它记的是 spec delta（这次改了什么），不强迫你先写全量规格——brownfield 场景比 greenfield 框架（Spec Kit/Superpowers）省一大截前置成本。

个人项目就 30 分钟起步（npm i -g + openspec init）；团队场景用 beta 版 Stores：规划单独开仓，git push 共享给全组 agent，跨仓库功能一份计划。

别指望它替代需求管理平台：OpenSpec 是规划层，Jama 这类 system of record 还是得留着。ThoughtWorks 2026 年 4 月 Radar 已把它放进 Assess 圈。

为什么「需求只活在聊天里」会让 agent 越写越歪？

先说痛点。AI 编程 agent 的能力早就不缺了，缺的是持久意图（durable intent）：

上下文窗口满了，最早那几条「我们为什么这么定」就被顶出去。agent 下一轮只能凭残存印象发挥，发挥的方向你猜不到。
多人/多 agent 协作时，A 在上午拍板的决策，下午 B 的会话里根本不存在。同一个仓库，两套「需求理解」。
改完不敢看。agent 交付的代码里混着它「顺手做掉」的一堆假设，你只能整块吞下。

常见土办法是手写一份 PROJECT_STATE.md 扔进仓库。能用，但没人维护，三个月后它和代码的真实状态就是两条平行线。

OpenSpec 的解法很直白：把规格文档变成仓库里的一等公民，agent 每轮开工先读它们。规格在 Git 里，就有版本、有 diff、有 review——和代码走同一条治理流水线。

OpenSpec 的工作流：3 个命令 + 1 个目录结构

装好之后（npm install -g @fission-ai/openspec@latest，Node ≥ 20.19），进到项目目录 openspec init，然后在你的 agent 里打斜杠命令。先看官方 README 里那段 explore 实录，它比任何文档都能让你秒懂这套东西在干嘛：

You: /opsx:explore
AI:  你想探索什么？
You: 想加暗色模式，但不确定怎么改最干净。
AI:  我先看下你的样式方案...
     最干净的路径：CSS 变量 + 一个小 theme context，
     加系统偏好检测，不引新依赖。范围定一下？
You: 行，就按这个。

You: /opsx:propose add-dark-mode
AI:  已创建 openspec/changes/add-dark-mode/
     ✓ proposal.md — 为什么做、改什么
     ✓ specs/      — 需求和具体场景
     ✓ design.md   — 技术路线
     ✓ tasks.md    — 实施清单
     准备实施！

You: /opsx:apply
AI:  按 tasks 施工...
     ✓ 1.1 加 theme context provider
     ✓ 1.2 做 toggle 组件
     ✓ 2.1 加 CSS 变量
     ✓ 2.2 接 localStorage
     全部完成！

You: /opsx:archive
AI:  归档到 openspec/changes/archive/2025-01-23-add-dark-mode/
     specs 已合并为最新状态，下一轮功能就绪。

四步，每个动词都在说它的设计哲学：explore 是「无风险思考伙伴」——读代码、权衡、定边界，一行实现代码都没写；propose 把意图固化成四个文档；apply 照单施工；archive 把 delta 合并回 source of truth，规格库自己滚动更新。整条链路没有任何「必须卡在这一步」的 phase gate，你随时可以回头改任意一个 artifact，再往前推。

两个关键设计：

第一，specs 是 agent 写的，不是人手写的。 /opsx:propose 时它读你的仓库，自动生成 proposal 和场景描述，人只做 review。省掉传统 SDD 框架最劝退的那一步——人工写 PRD。specs 目录里就是纯 Markdown，需求配具体场景，没有要学的特殊语法。

第二，specs 记的是 delta，不是全量规格。 这是 OpenSpec 和 Spec Kit 分野最深的地方，ThoughtWorks Radar 也把它列为亮点。每个 change 文件夹里的 specs 只描述「这次改动影响了什么」，不是系统的完整规格书。对老项目来说这是决定性的：你不可能在动手前把整个遗留系统的规格先补全，但你可以只写「这次改了什么」。delta 机制让 SDD 真正能落进 brownfield，而不只是 greenfield 玩具。

目录结构：

目录	作用
`openspec/specs/`	当前系统状态的规格（source of truth）
`openspec/changes/`	进行中的变更（proposal + delta specs + design + tasks）
`openspec/changes/archive/`	已完成的变更，按日期归档

它和 GitHub Spec Kit、Kiro 的关键区别在哪？

三个都叫 SDD，但定位差很远：

维度	OpenSpec	GitHub Spec Kit	Kiro (AWS)
重量	轻，3 命令起步	重，phase gate 多 + Python 环境	IDE 绑定，全家桶
工具锁定	不锁，30+ agent 支持（Cursor/Copilot/Codex/Amazon Q）	自家生态	锁 Kiro IDE + Claude 系模型
老项目适配	delta spec，为 brownfield 设计	偏 greenfield	偏 greenfield
规格来源	agent 生成，人 review	人 + agent	人 + agent
迭代自由	任意阶段改任意 artifact，无 phase gate	阶段刚性	阶段刚性

一句话取舍：你要的是「给 agent 装个缰绳」，不是「换一套重型流程」。OpenSpec 的哲学词是 fluid not rigid / iterative not waterfall / easy not complex。Spec Kit 是「彻底但繁琐」，Kiro 是「强大但锁死」——选 OpenSpec 的理由就是你还想用自己现有的 agent。

另一个容易被忽略的点：ThoughtWorks 2026 年 4 月 Radar 把 OpenSpec 放进 Assess 圈（值得了解它对企业的影响），评语重点就是两条——fluid 三命令、delta spec 适合存量系统。但 Radar 同时提醒：agent 原生能力还在涨，过两年「读仓库自己规划」可能就内建了，SDD 工具层要重新评估。这是实话。

团队怎么用：Stores 把规划从代码仓里剥出来

上面这套，个人一个仓就够用了。真正复杂的场景是：一个功能横跨三个仓，需求却只有一份。这时 beta 版 Stores 才是 OpenSpec 的杀手锏。

机制不复杂：规划仓和代码仓分离。规划仓里同样是那个熟悉的 openspec/ 结构（specs 加 changes），但它是独立的一个 git 仓库，git push 就能分发给全组。每个代码仓里的 coding agent 读的是同一份 specs 单一真源，不再是各仓各写一份、慢慢漂移。

官方点名的三类用法：

跨仓功能：一个 change，一份 plan，哪怕代码最终落在三个仓。API 仓加端点、Web 仓加 UI、共享库加类型——三处改动的规格在同一个规划仓里对齐，不用靠口头 + 三仓文档各说各话。
共享需求：平台团队 owns 那套 specs，产品团队只读，直接读到自己 agent 能取到的位置。wiki 漂移的问题从根上没了——因为根本没有 wiki，规格就活在 agent 读得到的地方。
先 plan 后 code：规划仓现在就把意图固化下来，代码仓后面跟上就行。解耦了「想清楚」和「动手」两个节奏。

但两个诚实的边界要摆明：一是 beta，生产上之前先读 docs/stores-beta/user-guide.md，别把它当稳定 API 依赖；二是它治的是意图对齐，不替你解决「三个仓怎么合并、CI 怎么排」的工程细节，那些还是得靠你自己的流水线。

我实测下来的账本

个人项目（Express 加 2FA 这类小功能）实测体感：

启动成本：npm i -g + init + 打一条 propose，30 分钟内跑通。无 Python、无 IDE 迁移。团队层面再叠 Stores 规划仓，git push 分发，不用为规格单开一个 wiki 系统。
规划质量：agent 生成的 proposal 会主动摸现有路由/中间件，给「在 middleware 层挂」还是「独立 route」的选项，比自己裸 prompt 稳。
施工对齐：apply 阶段它严格照 tasks.md 走，基本不「顺手加戏」。这是它比裸 agent 最大的增量。delta spec 机制在老项目上尤其明显：只描述这次改动面，不用为整仓补全量规格，启动摩擦小很多。
上下文卫生：官方明说实施前要 clear context——它治的是「需求持久化」，不是「上下文无限」。长会话里照旧要手动清。
模型选择：规划 + 实施都吃推理强的模型，官方点名 Codex 5.5 / Opus 4.7 档。用廉价小模型跑 propose，规格质量会塌。

两个坑：

Telemetry 默认开。只采命令名 + 版本，不采参数/路径/内容，CI 自动关。洁癖者：openspec config set telemetry.enabled false 或 export OPENSPEC_TELEMETRY=0。
Stores 还是 beta。团队共享规格仓是它最有想象力的功能，但标注 beta，生产用前先读 docs/stores-beta。

为什么「规格进 Git」这一手，比「手写文档」高级一截？

有人会问：这不就是往仓库里多塞几个 Markdown 文件吗，和手写一份 PROJECT_STATE.md 有本质区别？

区别在三条治理流水线上：

版本化：Git 里有 diff、有 blame、有历史。需求变更是一次 commit，谁改的、为什么改、前后长什么样，全查得到。手写的 md 文档改起来没有这个纪律。
可 review：规格是文件，就能进 PR review 流程。你 review 代码的同时 review 规格，agent 交出来的一堆假设第一次变成了「可以被驳回」的东西。
agent 可读：这是最关键的一条。规格是 agent 每轮开工先读的输入。手写 md 扔那儿，agent 不会主动去读；但 OpenSpec 把「读规格再动代码」固化成了工作流的第一步，意图持久化的机制才真正闭环。

所以 OpenSpec 不是「文档工具」，是把规格变成 agent 的一等输入，再让 Git 给这层输入套上版本和 review 纪律。这两条叠起来，才是它相对裸 chat 历史、相对手写 md 的代差。

什么时候不该上 OpenSpec？

不是所有仓库都值得。诚实划边界：

需求稳定的老系统（契约清晰、改动少）：Kiro / Spec Kit 的静态全量规格可能更合适，delta 思维反而别扭。
一次性 demo / 脚本仓：规格文档比代码本身还重，纯属仪式。
你还没有稳定的 agent 工作流：先别叠第二层抽象，先把裸 agent 跑顺。
团队 / 跨仓场景：上 Stores 前读 beta 文档，规格仓和代码仓的边界划清楚。
它不替代需求管理平台：Jama 那类 traceability / audit 需求，OpenSpec 明确定位是规划层，别硬塞。

常见问题

Q1: OpenSpec 是干嘛的？一句话。 A: 给 AI 编程 agent 加一层版本化规格文档，让它先读规格再写代码。规格进 Git，需求不再只活在聊天历史里。

Q2: 需要人工写 PRD 吗？ A: 不需要。/opsx:explore + /opsx:propose 时 agent 读你的仓库自动生成 proposal/specs/design/tasks，人只做 review。这是它比传统 SDD 框架省的最大一步。

Q3: 它和 GitHub Spec Kit 怎么选？ A: 要轻量、迭代自由、不锁工具、尤其服务老项目 → OpenSpec。要重型全流程、能接受 Python + 阶段刚性 → Spec Kit。

Q4: 支持哪些 agent 工具？ A: 官方称 30+。斜杠命令在不同工具里拼写不同（Cursor/Copilot 是 /opsx-propose，Amazon Q 是 @opsx-propose，Codex 是 $openspec-propose），openspec init 会自动打印你选的工具对应的格式。

Q5: 团队怎么用一份规格管多个仓？ A: 用 Stores（beta）：单独开一个规划仓，里面同样是 openspec/ 结构，git push 给全组，各代码仓的 agent 读同一份 specs。平台团队 owns 规格，产品团队只读。

Q6: 数据安全？会不会上传我的代码？ A: 框架本身只在你本地仓库里读写 openspec/ 目录。唯一出网行为是匿名 telemetry（命令名 + 版本），可以关。规格文档走 Git 走你自己的 remote。

Q7: 会不会被 agent 原生能力取代？ A: ThoughtWorks 自己都在 Radar 里这么提醒——模型越来越能「读仓库自己规划」，SDD 工具层价值会重新洗牌。OpenSpec 目前的护城河是 delta spec + 团队 Stores + 工具中立，而不是「帮 agent 读代码」这个基础能力。