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 → archive。Propose先把需求说清楚目的不要直接让 AI 写代码而是先生成一份“变更提案”。解决的问题用户没经验、需求模糊、边界没说清。产物通常包括proposal.md、规格变更、设计说明、任务列表。这一阶段 AI 要帮你回答为什么做、做什么、不做什么、影响哪里、怎么验收。简单说Propose 是把 “我想要一个功能” 变成 “AI 可以正确执行的变更规格”。Apply按规格实现目的让 AI 根据已经确认的规格去改代码。解决的问题AI 自由发挥、乱改文件、修改范围失控。AI 应该做的是按 tasks.md 分步骤实现只改相关文件遵守已有技术栈和项目规则。这一阶段重点不是探索需求而是执行已经确认的变更。简单说Apply 是让 AI 从 “按感觉写代码” 变成 “按规格执行任务”。Archive把经验沉淀下来目的功能完成后把这次变更中形成的新规则、新能力、新约束合并进长期规格。解决的问题每次需求都从零解释项目知识没有积累。完成后这次变更会归档相关规则会成为后续 AI 编程的上下文。下一次 AI 再做类似功能时就不需要重新猜业务规则。简单说Archive 是把一次功能经验变成项目长期记忆。三步对应你的痛点Propose解决“我没经验不知道怎么把需求说清楚”。Apply解决“AI 改了很多我不想改的地方”。Archive解决“每次都要重新解释经验没有积累”。一句话总结OpenSpec 三步工作流就是先用 Propose 把模糊需求变成清晰规格再用 Apply 约束 AI 按规格实现最后用 Archive 把这次变更沉淀成项目经验。使用方法全局安装 OpenSpec 最新版本Explore → Propose → Review → Apply → 验证 → Archive ↓ ↓ ↓ ↓ ↓ ↓ 澄清 生成 人工检查 按任务 浏览器 归档 需求5工件1-2分钟 实现 确认 changeOpenSpec 你需要会的只有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 最真实的体感。