OpenSpec 爆火是内卷信号:当"让 AI 写代码"变成"给 AI 写文档",我们是不是绕远了?

原创2026-10-10 11:02:041,711 阅读
文章标签:开发工具CLIAI 技能代码智能体需求管理

OpenSpec 爆火是内卷信号:当"让 AI 写代码"变成"给 AI 写文档",我们是不是绕远了?

2025 年下半年以来,一个叫 OpenSpec 的规范驱动开发(SDD)框架在中文开发者社区持续刷屏:GitHub 星标数一路冲到数万,掘金上相关教程动辄数万阅读,从"Claude + DeepSeek + OpenSpec 自动化生成代码"到"企业级 API 开发实战案例",教程与案例以周为单位涌现。它的卖点非常戳人——AI 编码助手"自信但不可靠",需求只存在聊天记录里,模型脑补需求、几轮对话后忘了初衷、一改就是整个文件,于是 OpenSpec 提出:先写规范,再写代码,让 AI 有据可依。

听起来是正解。但热潮之下值得冷静一问:规范驱动开发,是不是把"AI 帮你写代码"悄悄变成了"你帮 AI 写文档"?当写 specs、写 proposal、维护 config 的时间成本压回人身上,我们到底是在驯服 AI,还是在给 AI 当秘书?

规范驱动是否把负担悄悄转回人

先看 OpenSpec 到底要求人做什么。初始化一个项目后,你会得到 openspec/specs/(当前系统行为的唯一真相源)与 openspec/changes/(每个变更一个文件夹)的双目录结构,每次改动要走 proposal → specs → design → tasks 的产物流(见 docs/concepts.md)。这套机制的核心假设是:AI 负责起草,人负责审阅与拍板。

但打开 openspec/config.yaml 就会发现,人的工作量比想象中更大。这个文件承载着 context: 字段——技术栈、包管理器、跨平台约定、产品语言要求,逐条手工维护,并且会被注入到每一次规划请求里。换句话说,团队的技术债、架构约定、编码纪律,全要靠人先写成结构化文本喂给 AI。社区教程里大量出现"openspec/config.yaml 不生效怎么排查""context 字段 50KB 大小限制"这类问题(docs/opsx.md 专门有 Troubleshooting 一节),说明这份"给 AI 的背景说明书"本身已经成了新的维护负担。

更隐蔽的负担在变更生命周期里。每个 change 文件夹下的 delta spec 需要人审阅、修订、在实现过程中回填——文档明确写道:"at archive time, your specs become the truth of record. So before you archive, make the specs honest about what the code does"(见 docs/editing-changes.md)。也就是说,代码写完不算完,你还得回头核对 spec 是否与代码一致,不一致就手动回填。OpenSpec 甚至为这个痛点专门做了一个提案,openspec/changes/spec-diffs/proposal.md 里白纸黑字承认:MODIFIED 需求必须把整个 requirement 块(含全部场景)复制进 delta,导致审阅者难以分辨"到底改了什么",审阅摩擦与出错风险随之上升。它的解法是给 openspec show 加 --diff 参数实时算 diff——注意,它没有解决"复制粘贴"本身,只是让看的人省点眼力。

这还没算工具适配的长尾。仓库里同时在跑的变更列表很能说明问题:add-amp-support 为 Amp 加一个工具入口、rename-bob-to-ibm-bob 把 bob 改名成 "IBM Bob"、fix-cli-local-date-semantics 修一个本地时区边界 bug。当社区的注意力从"如何把需求讲清楚"滑向"如何给第 30 个 AI 工具装技能文件、如何改一个显示名字"时,一个信号已经出现:工具链的维护成本,正在悄悄把开发者从写代码拽向伺候工具。

文档成本 vs 返工成本的账怎么算

OpenSpec 并非没算过这笔账。恰恰相反,它自己在文档里算得很诚实。在 docs/overview.md 的"Why this is worth the small overhead"一节,项目方原话是:"Plain truth: OpenSpec adds a step. You write a short plan before building."(直白地说,OpenSpec 增加了一个步骤。)它给出的理由是:在一段话的 proposal 里修正误解是免费的,等 AI 写完 400 行再改不是。

这个逻辑在"大改动 + 高歧义"的场景下完全成立。社区里被引用最多的成功案例——得物技术、洞窝技术、网易智企的落地实践——无一例外是跨团队、跨仓库、接口契约型的中大型变更。这类场景里,规范是谈判桌,需求是合同,返工成本极高,写文档的边际成本几乎可以忽略。而对 API 生成类场景(社区教程里最常见的"Claude + DeepSeek + OpenSpec 生成 API 客户端/服务端代码"),一份结构化的接口规格确实能显著降低模型的幻觉率。

但账的另一面很少被讨论。OpenSpec 自己也承认:"for a truly trivial one-line fix, the ceremony may not pay off"(见 docs/overview.md)——一行字符的修复不值得走完整套仪式。问题在于,真实工作里"小改动"的比例远高于任何人的预期:改个文案、调个阈值、修个字段名。这类改动在传统流程里是分钟级的事,在 SDD 里却要先写 proposal、再写 delta spec、走验证、最后归档回填。归档还不是终点——docs/concepts.md 的 Archive 一节说明,变更归档后 delta 会合并进主 specs,也就是说你每一次修 bug 都在为"真相源"添砖加瓦,而这部分文档维护的劳动密度,是纯代码时代没有的。

更值得警惕的是成本叠加。SDD 的文档不是写一次就完:需求演化要改 spec,实现偏离要回填 spec,工具升级要跑 openspec update 刷新技能文件,新增 AI 工具要重新初始化。每个环节都在文档维护的存量上继续叠加。当"返工成本"被规范大幅压低时,"文档成本"这条曲线却在稳定爬升——这笔账在项目初期几乎必然亏损,只有在项目足够大、改动足够频繁时才能抹平。这不是 OpenSpec 的缺陷,而是所有 SDD 框架的固有税:规范是资产,但资产也有持有成本。

SDD 的正确打开姿势:灵活而非教条

如果 OpenSpec 只是一个"先写文档再写代码"的教条框架,它不会火到这个程度。恰恰相反,它最值得借鉴的地方,是它用一整套机制主动对抗规范驱动开发的最大原罪——流程僵化。

第一层机制是"依赖是使能器,不是门禁"。在 docs/opsx.md 里,OPSX 工作流的核心表述是 "Dependencies are enablers, not gates":proposal → specs → design → tasks 的顺序表示"接下来可以做什么",而不是"必须做什么"。实现到一半发现设计错了?改 design.md 继续;范围要收缩?改 proposal。产物依赖只服务于"AI 需要有上下文才能写好下一个产物"这一目的,而不是把人锁进阶段流水线。相比之下,GitHub Spec Kit 被官方 README 明确对比为"Thorough but heavyweight. Rigid phase gates"(README.md),OpenSpec 的差异化恰恰是反过来的轻量。

第二层机制是"渐进式严谨"(Progressive Rigor)。docs/concepts.md 明确给出分级:默认的 Lite spec 只要"简短的行为优先需求 + 清晰的范围与非目标 + 几条具体验收标准",只有跨团队、跨仓库、API 契约、迁移、安全隐私这类高歧义高成本变更才升级到 Full spec。文档原话是"Most changes should stay in Lite mode"(大多数变更应保持在 Lite 模式)——这正是对"文档成本 vs 返工成本"账本的正确回应:不是一刀切地给所有改动上强度,而是按风险定价文档深度。

第三层是 delta 机制对存量系统的友好度。OpenSpec 自称 brownfield-first:你不必先把整个 5 万行应用文档化,只需为每个变更写它触碰的那一小块 delta(ADDED/MODIFIED/REMOVED),specs 随着归档自然生长(见 docs/concepts.md 与 docs/overview.md)。这让"给 AI 写文档"从一次性的大工程,降格为跟日常开发同步进行的碎片化动作。

最后也是最容易被忽略的一层:OpenSpec 把"人机对齐"的颗粒度切到了变更级,而不是对话级。一个活生生的例子在仓库里:openspec/changes/graceful-status-no-changes/proposal.md 记录了一个真实 bug——AI agent 在 onboarding 时调用 openspec status,因为还没有任何 change 而直接抛致命错误,导致 agent 卡死。修复方式是让 status 在空状态下优雅退出并输出 {"changes":<a href="https://link.gitcode.com/i/ef3f4a6005ac2d6518570788101fd3b6" target="_blank">],"message":"No active changes."}。这个案例说明 SDD 真正的价值不在"文档本身",而在把 AI 的工作流从不可复现的聊天随机性,变成可检查、可续跑、可审计的确定性流程——[docs/faq.md 里那句"上下文窗口烧没了?清空重开一个会话,/opsx:apply 会从第一个未勾选的任务继续",才是这套框架对"内卷"最有力的回应:它防止的是"重来一次"这种最贵的内卷。

结语:别让工具链本身成为新的内卷源头

回到最初的问题:我们是不是绕远了?答案是"看怎么用"。OpenSpec 的爆火本质上反映了行业的一个共识转变——纯靠提示词工程压不住大模型的幻觉,规范层是 AI 编码从"玩具"走向"工程"的必经之路,这也是为什么从 GitHub Spec Kit 到 Superpowers、再到 OpenSpec,SDD 家族在 2025–2026 年集体爆发。社区 3.6 万阅读的三剑客对比、企业团队的落地复盘,都在验证同一个方向。

但方向正确不等于姿势可以偷懒。OpenSpec 官方文档里埋着最清醒的一句话:"OpenSpec is designed to be lightweight, but it isn't free."(它被设计得很轻,但它不是免费的。)这套工具的诚实之处在于:它知道自己增加了步骤,于是用 enablers-not-gates 消除门禁、用 Lite spec 控制文档深度、用 delta 适配存量代码、用变更级工作流对抗上下文丢失——这些设计都是在为"文档成本"这条曲线踩刹车。

而对使用者来说,真正的护城河在于拒绝教条:别给一行修复写四份文档,别让 config.yaml 变成第二个需要重构的遗产,别把"规范驱动"异化成"流程驱动"。SDD 的正确打开姿势从来不是"先写文档再写代码",而是只给值得的变更写文档,让文档服务于人机对齐,而不是服务于流程本身的仪式感。OpenSpec 提供了一整套对抗内卷的机制,但如果你的团队把工具用成了新的内卷——每天在 spec 上花的时间比写代码还多——那问题不在工具,而在打开方式。

OpenSpec 仪表盘界面预览

上图是 OpenSpec 自带的终端仪表盘(openspec view),它把 specs 与 changes 的状态可视化,让规范层成为可浏览、可审计的项目资产——这也是判断你的 SDD 实践是否健康的试金石:如果规范是团队共同维护、随时可查的资产,它是杠杆;如果规范是某个人默默维护的负担,它就是内卷。

登录后查看全文
OpenSpec