openSpec 管变更，让需求、边界、规则、经验被清楚表达

openSpec 管变更，让需求、边界、规则、经验被清楚表达

• • 三步工作流
  • 使用方法

痛点：你想要的和 AI 做出来的不是一回事。

• 没有经验导致需求不清：你没有完整做过类似功能，所以很难一次性描述清楚边界、流程、异常情况和验收标准。
• 上下文缺失：AI 不知道项目历史、业务规则、代码风格、哪些地方不能动，只能根据当前提示猜。
• 改动失控：项目变大后，AI 容易顺手重构、改命名、调整结构，导致修改范围超过预期。
• 返工频繁：结果不符合预期时，需要反复补充说明、撤回、重改，沟通成本很高。
• 验收困难：AI 写完代码后，用户不一定能快速判断是否正确，尤其是涉及架构、性能、安全、边界条件时。
• 隐性假设多：AI 会默认很多东西，比如技术选型、交互方式、数据结构、错误处理策略，但这些默认值未必符合你的真实需求。
• 局部正确，整体不对：单个函数可能能跑，但和现有系统、业务流程、权限模型、数据状态结合后不一定正确。
• 维护成本增加：AI 可能写出“看起来能用”的代码，但结构不利于后续扩展、调试和团队维护。

根本原因：

• 用户的问题：还没想清楚“要什么”，就让 AI 开始“怎么做”。
• AI 的问题：AI 擅长补全和执行，但不擅长主动确认真实业务意图。
• 项目的问题：缺少规范文档、接口说明、测试用例、不可修改边界。
• 流程的问题：直接让 AI 写代码，没有先做需求拆解、方案确认、范围约束和验收定义。

特别是你没有做过这种项目，你没有经验，就不知道该约束什么，不知道出问题从哪里改，AI 就容易跑偏。

OpenSpec 把需求经验、工程经验、项目约束前置，让 AI 在写代码之前先理解 “什么是正确的变更”。

解决的是 AI 编程里最关键的一层问题：不是代码不会写，而是需求、边界、规则、经验没有被清楚表达。

核心定位

• OpenSpec 是 AI 编程前的“需求经验层”：它补的是用户经验不足的问题，而不是单纯补代码能力。
• OpenSpec 是文档驱动开发框架：把业务规则、技术规则、变更规则、验收规则写成结构化文件。
• OpenSpec 是 AI 的约束系统：让 AI 不只是“自由发挥”，而是在明确规则、边界和流程中完成变更。
• OpenSpec 重点解决“变更”：不是从 0 写一个 demo，而是在现有项目里安全、可控地增加、修改、删除功能。

它解决的问题

• 用户不知道怎么提需求：OpenSpec 帮用户把模糊想法拆成目标、范围、约束、边界和验收条件。
• 用户不知道技术方案：OpenSpec 可以沉淀技术栈规则、架构规则、已有模块规则，让 AI 根据项目上下文选择合适方案。
• 用户不知道有哪些坑：OpenSpec 把有经验开发者才会考虑的异常情况、兼容性、权限、状态流转、数据一致性提前写出来。
• AI 容易乱改代码：OpenSpec 通过变更范围、禁止事项、实现步骤、验收标准约束 AI 的行为。
• 项目越大越难改：OpenSpec 让每次变更都先形成规格，再编码，避免 AI 一次性大面积改动。

关键概念：重变更
OpenSpec 的核心不是“写新功能”，而是“管理变更”。

因为真实项目里最难的不是从零开始，而是：

• 这个功能应该接入哪个模块？
• 会不会影响已有功能？
• 数据结构要不要改？
• 权限、状态、异常怎么处理？
• 哪些文件能改，哪些不能改？
• 新功能完成后怎么验收？
• 如果需求变了，怎么追踪影响？

所以 OpenSpec 更像是：

每次功能变更前，先生成一份“变更规格”，再让 AI 按规格执行，让 AI 始终知道 做什么、不做什么、怎么验收。

三步工作流

OpenSpec 的“三步工作流”可以概括为：

Propose → Apply → Archive
先定义变更 → 再实现变更 → 最后沉淀规则

官方工作流页面把它展开成 4 个阶段：Proposal、Planning、Implementation、Archiving；

但在实际使用里，通常可以压缩理解成三步：propose → apply → arch
ive。

1. Propose：先把需求说清楚

• 目的：不要直接让 AI 写代码，而是先生成一份“变更提案”。
• 解决的问题：用户没经验、需求模糊、边界没说清。
• 产物通常包括：proposal.md、规格变更、设计说明、任务列表。
• 这一阶段 AI 要帮你回答：为什么做、做什么、不做什么、影响哪里、怎么验收。

简单说：

Propose 是把 “我想要一个功能” 变成 “AI 可以正确执行的变更规格”。

2. Apply：按规格实现

• 目的：让 AI 根据已经确认的规格去改代码。
• 解决的问题：AI 自由发挥、乱改文件、修改范围失控。
• AI 应该做的是：按 tasks.md 分步骤实现，只改相关文件，遵守已有技术栈和项目规则。
• 这一阶段重点不是探索需求，而是执行已经确认的变更。

简单说：

Apply 是让 AI 从 “按感觉写代码” 变成 “按规格执行任务”。

3. Archive：把经验沉淀下来

• 目的：功能完成后，把这次变更中形成的新规则、新能力、新约束合并进长期规格。
• 解决的问题：每次需求都从零解释，项目知识没有积累。
• 完成后，这次变更会归档，相关规则会成为后续 AI 编程的上下文。
• 下一次 AI 再做类似功能时，就不需要重新猜业务规则。

简单说：

Archive 是把一次功能经验变成项目长期记忆。

三步对应你的痛点

• Propose：解决“我没经验，不知道怎么把需求说清楚”。
• Apply：解决“AI 改了很多我不想改的地方”。
• Archive：解决“每次都要重新解释，经验没有积累”。

一句话总结
OpenSpec 三步工作流就是：

先用 Propose 把模糊需求变成清晰规格，再用 Apply 约束 AI 按规格实现，最后用 Archive 把这次变更沉淀成项目经验。

使用方法

全局安装 OpenSpec 最新版本

Explore → Propose → Review → Apply → 验证 → Archive ↓ ↓ ↓ ↓ ↓ ↓ 澄清 生成 人工检查 按任务 浏览器 归档 需求5工件1-2分钟 实现 确认 change

OpenSpec 你需要会的只有4句话-探索/开始：请用 OpenSpec 全流程处理这个需求，先进入 Explore，多轮澄清后再生成规格：...-确认规格：规格没问题，继续 apply 实现。-调整规格：先不要实现，请修改 proposal/design/spec/tasks：...-收尾归档：测试通过后 archive 归档。

完整跑了一遍 OpenSpec 工作流之后，我对它的理解更具体了。

一开始我以为 OpenSpec 主要是在“帮我写规格文档”。但实际用下来，它真正改变的不是文档，而是开发节奏。

以前做一个需求，很容易是这样的：脑子里大概知道要做什么，然后直接让 AI 开始写代码。写到一半发现路由没想清楚，测试没覆盖，目录结构也有点别扭，于是边写边改。这个过程看起来很快，但其实很多决策都被推迟到了实现阶段。

OpenSpec 的不同在于，它把这些决策提前了。

Explore 阶段不是走形式。像 project-init 这种看起来很简单的 change，真的展开之后，会发现里面有不少隐含决策：项目初始化顺序、技术栈选择、路由结构、页面边界、测试策略、404 兜底、目录约定等等。如果没有 Explore，这些问题大概率会在 apply 阶段临时冒出来。

而 Explore 的价值就在这里：它不是让 AI 立刻给答案，而是让 AI 先追问。多轮澄清之后，需求的形状会变得稳定。

到了 propose 阶段，proposal、design、specs、review、tasks 的产出就不再是 AI 凭空发挥，而是基于前面已经澄清过的上下文自然生成。

这也是我这次最大的感受：OpenSpec 的前半段，本质上是在降低后半段的不确定性。

propose 阶段的体验也比想象中顺。

一次生成多个工件，而且是按依赖顺序生成：先有 proposal 明确为什么做、做什么；再有 design 说明怎么做；然后 specs 把行为写成可验收的要求；

review 作为质量闸门再检查一遍；最后 tasks 把实现拆成可执行步骤。

这里面我觉得 review 很关键。

以前 AI 生成任务后，我通常会直接进入实现。但这次 review 插在 design 和 tasks 之间，相当于多了一次“开工前检查”。

它能提前发现一些粗看不明显、但实现时会出问题的地方，比如路由 404 是否有测试覆盖、页面边界是否完整、初始化流程有没有顺序坑。

这个环节的意义不是增加流程负担，而是防止错误进入 tasks。因为一旦 tasks 写得不完整，apply 阶段执行得越机械，错误就越稳定地被实现出来。

真正进入 apply 之后，另一个感受也很明显：AI 的创造性被压低了。

这句话听起来像坏事，但在工程里其实是好事。

因为这次的 tasks.md 拆得足够细，8 个任务组、33 个子任务，每个 step 基本都能在 2-5 分钟内完成。路由、页面、测试都有明确步骤，甚至 TDD 的顺序也写进去了。

于是 apply 阶段的 AI 不再需要临场判断“我应该怎么设计这个功能”，它只需要按照 instructions 一步步执行。

也就是说，AI 从“设计者 + 实现者”变成了“执行者”。

这对项目可控性非常重要。因为最容易出问题的地方，往往不是 AI 不会写代码，而是 AI 在信息不完整时自作主张。OpenSpec 通过 Explore、specs、review、tasks，把这些自作主张的空间尽量去掉。

还有几个很实际的体会。

第一个是初始化顺序。先 npx create-vite，再 openspec init。反过来会因为目录非空导致 Vite 拒绝初始化。这个坑很小，但只有真实跑一遍才会遇到。它也说明，流程文档再完整，真实执行仍然会暴露细节问题。

第二个是配置的复用价值。init → config.yaml → fork schema → 添加 review 工件 这几步，第一次做需要花点时间，但后面每个 change 都能复用。从 TypeScript + Express 项目迁移到 React + Vite 项目，主要只是改 context 里的技术栈描述。这个边际成本很低。

第三个是 GitHub CLI。gh auth login 配好之后，AI 在 apply 阶段可以直接处理 git 操作。单次看只是省一点切终端的时间，但如果项目里有多个 change，这个价值会持续放大。

回到任务粒度：把 tasks instruction 这个关键 20% 调好，能覆盖大部分质量收益。

因为 tasks 是 OpenSpec 里最接近执行层的工件。proposal 写得好，能保证方向正确；design 写得好，能保证方案合理；specs 写得好，能保证验收清晰。但真正决定 apply 阶段稳不稳的，是 tasks 是否足够细、足够具体、足够可验证。

这次 project-init 的结果是比较理想的：8 组 33 个子任务，粒度基本落在 2-5 分钟一个 step。AI 执行时没有太多“自由发挥”的空间，整体过程更像是在跑一份施工清单。

当然，这期的 change 还不算复杂。项目初始化、基础路由、页面和测试，复杂度有限。后面更值得观察的是复杂功能，比如工具注册中心、Prompt 模板库、多模块数据流、权限系统这些场景，还能不能继续保持这种任务粒度。

OpenSpec 在简单到中等复杂度的 change 上，已经能明显提升 AI 编程的可控性；但在复杂业务功能上，还需要继续验证它的任务拆解能力和 review 闸门质量。

最后总结一下：

OpenSpec 真正有价值的地方，不是让 AI 写更多文档，而是把 AI 编程从“凭感觉生成代码”变成“按规格执行工程流程”。

Explore 负责澄清问题，propose 负责生成工件，review 负责提前拦截风险，tasks 负责拆成可执行步骤，apply 负责机械执行，archive 负责把结果沉淀回主规格。

这个流程跑通之后，AI 的能力不是被削弱了，而是被约束到了更可靠的位置。

对个人开发来说，它减少返工。
对团队协作来说，它统一预期。
对长期项目来说，它沉淀规格。
对 AI 编程来说，它降低失控概率。

这就是我这期对 OpenSpec 最真实的体感。