藏经阁

我为什么开始用 OpenSpec 做 SDD：把 AI coding 从“聊天驱动”拉回可验证交付

2k
2025-11-10 23:53
4 个月前

我为什么开始用 OpenSpec 做 SDD：把 AI coding 从“聊天驱动”拉回可验证交付

我最近越来越明确一件事：AI 写代码这件事，最贵的成本已经不是“写”，而是返工。 真正让我疲惫的，从来不是 AI 一次写不出来，而是它明明写了很多，却总是离我要的东西差半步： 有时是范围变大了，有时是把重点做偏了，有时是代码已经改完，但回头看我自己都说不清这次改动到底想解决什么。

以前我会把这个问题归结为 prompt 不够准，或者上下文喂得还不够多。 但我后来发现，很多问题根本不是“提示词技巧”能解决的，而是我一直在用一种天然会漂移的方式和 AI 协作： 需求在聊天里，边界在脑子里，设计在临时判断里，任务靠临场拆解。 这种用法在小任务里还能扛，一旦事情稍微复杂一点，AI 和人就会一起失焦。

也正是因为这个原因，我开始认真研究 OpenSpec。我关注它，不是因为它是一个“新工具”，而是因为它提供了一种我现在非常需要的东西： 把 AI coding 从聊天驱动，重新拉回到规格驱动。换句话说，我不是想让 AI 更敢写，而是想让它更少写偏。

TL;DR（30 秒讲清楚）

  • 我的结论：OpenSpec 最有价值的地方，不是生成文档，而是帮我把 AI coding 里的意图、边界、设计和任务固定下来。
  • 我的痛点：以前很多返工都来自“聊天里说过，但没有沉淀成稳定工件”，导致 AI 越写越偏，我也越改越累。
  • 我的新做法：先让 AI 产出 proposal、specs、design、tasks，我确认边界后再进入实现。
  • 我的判断：这更像是一种适合 AI 时代的 SDD（Spec Driven Development），尤其适合存量项目和容易反复迭代的需求。
  • 我的底线：不是所有事情都要重流程，但越是高风险、多人协作、容易漂移的改动，越值得先走规格层。

适用读者与前置知识

  • 适合：已经在用 Codex、Claude Code、Cursor 或其他 AI 助手写代码，但明显感觉到返工成本越来越高的人。
  • 适合：在存量项目里和 AI 协作，希望把“它会写”升级成“它写得更稳”的团队或个人。
  • 前置：知道需求、设计、任务拆解这些工程概念即可，不需要先掌握完整的软件过程学。

问题定义（Problem Statement）

我想为自己的 AI coding 建立一层轻量但稳定的规格闭环：在实现之前先固定这次改动的目标、边界与任务，在实现之后还能回看“为什么这么改、改了什么、是否真的达成了预期”。

目标与非目标（Goals / Non-goals）

目标

  • 把原本只存在于聊天窗口里的需求和判断，沉淀成仓库内可追踪的工件。
  • 让 AI 在进入代码之前，先和我就范围、行为和任务达成一致。
  • 让一次变更结束后能被归档、复盘，并成为系统新的可追溯真相。

非目标

  • 不把 OpenSpec 当成必须套在所有事情上的流程外壳；极小变更依然可以轻量处理。
  • 不神化规格工具；好的工件能减少误解，但不能替代真正的判断和取舍。

我为什么开始重新定义自己的 AI 使用方式

过去我用 AI，更多是“把任务描述清楚，然后让它开工”。这种方式的好处是快，尤其在我已经知道大概要怎么做的时候， AI 能迅速给出一个还不错的初版。问题也恰恰出在这里：它太容易让我误以为自己已经对齐了。

但很多时候，我和 AI 只是“表面上在说同一件事”。我脑子里想的是“先做最小闭环，别动边界”， 它理解成了“顺手把附近相关的结构一起重构”；我想解决一个局部问题，它却热情地帮我补全了一整片并不需要现在落地的功能。

以前我会觉得这是模型能力问题。现在我更倾向于认为，这是协作协议的问题。 如果人与 AI 之间没有一层稳定的中间工件，双方都只能依赖聊天上下文和即时推断；而上下文越长、任务越复杂，这种协作方式就越容易失真。

所以我现在开始刻意调整：不再把 prompt 当成唯一入口，而是把规格工件当成真正的协作入口。 OpenSpec 之所以吸引我，是因为它刚好把这件事产品化了。

OpenSpec 吸引我的地方：它不是在加文档，而是在补“协作协议”

我读完 OpenSpec 的公开资料后，最认同它的一点，是它并不强调大而重的过程，而是在强调一套轻量、可迭代、适合存量项目的工件流。 它的核心不是“让你多写几份文档”，而是让你把一次变更里最容易丢失的几件事固定下来。

  • proposal：这次为什么要做，打算改什么，不改什么。
  • specs：系统行为应该变成什么样，用 requirement 和 scenario 来定义边界。
  • design：技术上怎么落，为什么这么落，有什么约束和权衡。
  • tasks：最终到底要做哪些执行项，方便 AI 按项推进，也方便我回看。

这就是我愿意把它理解成 SDD 的原因。这里的“规格”，不是传统那种厚重文档，而是一套能在 AI 协作里真正起作用的中间层。

我最看重的一个设计：把“当前真相”和“本次变更”分开

伪代码：OpenSpec 的目录模型（概念化表达）

openspec/
├── specs/
│   ├── auth/spec.md
│   ├── billing/spec.md
│   └── ui/spec.md
└── changes/
    └── add-dark-mode/
        ├── proposal.md
        ├── design.md
        ├── tasks.md
        └── specs/
            └── ui/spec.md

这个模型对我非常重要，因为它天然回答了两个我在 AI 协作里经常遇到的问题：

  • 现在系统到底是什么状态？ 这个由 specs/ 负责，表示当前真相。
  • 我这次准备改什么？ 这个由 changes/ 负责，表示这次变更的增量。

以前我和 AI 讨论一个改动，很多内容其实都混在一起：旧规则、新判断、临时方案、最终实现，最后很难回看。 现在如果把“真相”和“增量”拆开，整个协作关系会清楚很多。AI 不再只是盯着当前代码瞎猜，它有机会沿着变更工件来理解意图。

为什么 Requirement + Scenario 对 AI 特别重要

伪代码：规格片段示意

### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.

#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard

这类写法对我来说最大的意义，是它把“模糊目标”压缩成了“可验证行为”。 以前我跟 AI 说“把登录流程补完整”，这句话对人类当然能大致理解，但对 AI 来说，仍然有太多可发挥空间。

一旦进入 Requirement + Scenario 的表达，它就不再只是“帮我写一个功能”，而是“在这些条件下，系统必须表现出这些行为”。 我越来越觉得，这才是 AI 最需要的边界形式：不是更长的 prompt，而是更稳的行为定义。

我现在会怎么用 OpenSpec：先固定边界，再允许 AI 发挥

截至 2026-03-10 我读到的公开资料，OpenSpec 已经有一条很清晰的 quick path： 先初始化，然后通过 /opsx:propose 生成 proposal、specs、design、tasks，再进入实现与归档。

伪代码：我会采用的最小工作流

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init

# 在 AI 工具里
/opsx:propose add-billing-export

# 我先审工件，再让 AI 继续
/opsx:apply
/opsx:archive

这里最关键的一步，不是命令本身，而是我会先停下来审 proposal / specs / design / tasks。 以前我总是急着让 AI 往后走，现在我更愿意把时间花在“先把边界钉住”。因为一旦这几份工件钉住了，后面很多返工其实就提前消失了。

我为什么觉得它特别适合存量项目

如果只是做一个一次性的 demo，很多时候直接和 AI 对话就够了。但我真正有需求的场景，几乎都发生在存量系统里： 补功能、修线上问题、做迁移、拆边界、压返工。这些事情最大的难点，从来不是“从零写出来”，而是别误伤旧系统，同时别把 scope 弄散。

OpenSpec 公开资料里强调 brownfield-first，我很认同。因为它不是要求你先完整建模整个世界，而是允许你围绕某次 change 去定义增量。 这点很现实，也很适合今天的 AI 工作流。

我接下来会怎么把它融进自己的日常 AI 使用

  • 需求模糊时：先探索，不急着让 AI 动代码；必要时先让它帮我收敛 proposal。
  • 需求明确时：先产出 proposal、specs、design、tasks，我先确认这次到底做到哪。
  • 实现阶段：优先按 tasks 推进，尽量减少“顺手多做一点”的范围外动作。
  • 插入紧急修复时：单开 change，不把临时问题混进原计划里，避免工件失真。
  • 收尾时：重视 archive，因为它决定这次变更是否真的沉淀成新的系统真相。

我现在越来越不想把 AI 当成一个“只要 prompt 写好就会自动变聪明”的黑箱。 我更愿意把它当成一个执行力很强、但边界必须由我来定义的协作者。

我预期中的边界和坑

  • 坑 1：把 OpenSpec 用成文档制造机，结果文件很多，但真正起边界作用的内容很少。
  • 坑 2：proposal 和 design 写得很漂亮，specs 却没有把行为定义清楚，最后还是会回到模糊协作。
  • 坑 3：tasks 不跟着实现同步更新，AI 显示“完成了”，但工件和代码实际已经脱节。
  • 坑 4：忘记 archive，导致变更停留在半空中，后续协作还是找不到稳定真相。
  • 坑 5：对所有任务一刀切；明明是一个小修复，却也要硬套完整流程，最后流程成本高于收益。

我的最终判断：我不是想更会“提示”AI，而是想更会“约束”AI

这应该是我最近关于 AI 使用方式最大的转变。 以前我更关注怎么把 prompt 说得更像一个高手；现在我更关注，怎么让 AI 在一套稳定边界里工作。

所以我会继续关注 OpenSpec，不是因为它名字新、命令酷，而是因为它切中的问题非常真实： 当 AI 具备越来越强的实现能力时，人真正应该补的，是规格、边界和可追溯交付能力。

对我来说，这不是一套“更正式的文档方法”，而是一次协作方式的升级。 我希望以后我和 AI 的关系，不再是“我说一点，你猜一点”，而是“我们先把这次变更讲清楚，再一起把它做对”。

FAQ

OpenSpec 和 PRD、Issue、Todo List 有什么区别？

在我的理解里，PRD 更偏产品表达，Issue/Todo 更偏任务管理，而 OpenSpec 更像是把“变更意图、行为边界、技术设计、执行清单”收束到同一个 change 里。 它不是替代这些东西，而是给 AI 协作补上一层更稳定的中间工件。

是不是以后每个需求都要走这套？

我不会这么做。极小的改动、一次性脚本、纯试验性质的东西，直接和 AI 对话就够了。 但只要问题开始涉及范围控制、多人协作、历史包袱或后续复盘，我就更愿意先走规格层。

这套方法最适合什么类型的人？

最适合已经明显感受到 AI 带来“高产出 + 高返工”双重特征的人。你越依赖 AI 参与复杂任务，越会意识到规格层的重要性。