别再让 AI 猜需求:用 OpenSpec 把开发意图真正留下来

你可能是这样开始 Vibe Coding 的：先用一句话告诉 AI 想做什么，它很快给出一版能运行的代码；接着你补充边界、调整交互、修复异常，再换一个会话继续迭代。几轮之后，功能越来越完整，聊天记录也越来越长。

聊天记录一长，早期确认的需求、边界和技术决策就会被后续对话淹没。切换会话或上下文被压缩后，AI 只能根据零散信息重新猜测，结果往往是满足了最新一句要求，却破坏了前面已经确认的规则，最终带来反复解释和返工。

问题不在于 AI 不会写代码，而在于需求和决策没有离开聊天记录。OpenSpec 正是为此而生：它把一次改动的意图、需求、技术方案和任务清单放进代码仓库，让人和智能体在动手前先对齐，开发过程中有据可查，完成后还能回头审计。

OpenSpec 是一套面向 AI Coding 的轻量级规范驱动开发框架。它不替代 Claude Code、Codex 这类编码智能体，而是通过 CLI 为不同工具生成可识别的 skills 或 commands，并在代码仓库中用 specs 和 changes 组织当前规范与每次变更。白话一点说，它在聊天和代码之间增加了一层可版本化的工程事实：先把要做什么、为什么做、准备怎么做写清楚，再让 AI 实现。

它和传统的“先写一份厚文档，再按瀑布流程执行”不是一回事。OpenSpec 官方强调五个方向：流动而非僵化、迭代而非瀑布、简单而非复杂、面向存量项目而非只服务新项目，并且能从个人项目扩展到企业协作。

关键在于，规范不是写完就锁进文档库的纪念品，而是 AI 可以读取、实现和持续修订的工程材料。

— OpenSpec 在聊天与代码之间增加一层可追踪的规范协议

没有规范层时，需求容易藏在聊天历史里。上下文一旦变长、切换会话或更换智能体，重要约束就可能被压缩、遗漏甚至重新猜测。OpenSpec 把一次功能开发封装成独立 change，并让当前有效的 specs 跟代码一起版本化。

因此，它解决的不是“AI 不够聪明”，而是“工程事实没有稳定落点”。模型可以更换，会话可以清空，但仓库里的规范、设计、任务和归档记录仍然存在。

把抽象问题放进一个真实项目

我们之前用 Vibe Coding 做过一款名为 In Reading 的英语学习浏览器插件，目前可以安装在 Chrome 和 Edge 桌面浏览器中。它的目标不是把整页英语替换成中文，而是尽量减少阅读过程中反复退出上下文的次数。

它的主要功能包括：

在真实开发中，我们发现了一个更具体的问题：原位注解主要依赖本地核心词库，部分中高级词汇以及 life-threatening 这类连字符复合词无法被完整识别。团队因此创建了 inline-ai-backfill change，让已经主动开启 AI 的用户，在不影响本地注解速度的前提下补齐这些词：

这次变更明确不修改核心词库、难度模型和 confusion-map，不新增设置项，也不扩展成生词复习系统。换句话说，产品可以很完整，但一次 change 最好只承担一个能够独立解释、实现和验证的目标。

— In Reading 在 A2 与 C1 等级下呈现不同的原位提示密度

这不是为文章编写的教学示例，而是 In Reading 项目已经完成并归档的真实 change。活动阶段的名称是 inline-ai-backfill，归档后目录变为 2026-06-30-inline-ai-backfill。读者可以在GitHub 查看完整归档：

https://github.com/mohiria/In-Reading/tree/main/openspec/changes/archive/2026-06-30-inline-ai-backfill 

后面的四张制品图也直接由这组真实 Markdown 文件生成。

有了产品背景和本次变更边界，接下来再看 OpenSpec 的四类制品，就不必一边读文件名，一边猜它们究竟在描述什么。

一次典型变更会产生四类核心制品。不要被“制品”这个词吓到，它们本质上就是四组职责明确的 Markdown 文件。

— proposal、specs、design、tasks 四类制品的职责关系

proposal：为什么要做

proposal.md记录问题、目标、范围和影响。这个真实 change的起点很具体：本地词库覆盖不到一部分中高级词，连字符复合词还会被拆开，导致“沉浸式原位注解”在最需要帮助的地方失效。目标是在用户主动开启 AI 时异步回填未覆盖词，同时明确不改核心词库、难度模型和现有设置结构。

— 真实 proposal：从本地词库覆盖缺口到 AI 回填边界

specs：系统应该表现成什么样

specs/ 记录可验证的需求和场景，回答“做成什么才算完成”。这个 change 写明：AI 开启且在线时，未被本地词库覆盖的进阶词应在异步查询后得到注解；AI 关闭、离线或请求失败时，不得改变原有本地行为；life-threatening 应作为完整候选；已经回填过的词再次出现时，应直接使用本地缓存而不是重复请求。

这里要注意一个容易混淆的结构：openspec/specs/ 描述系统当前已经成立的行为，是主规范；openspec/changes/<name>/specs/ 描述这次准备新增、修改或移除的行为，是 delta specs。归档时，后者才会合并进主规范。

— 真实 spec：触发条件、候选筛选、连字符和缓存场景

design：准备怎么做

design.md 记录技术方案和关键决策。这个 change 把流程拆成两阶段：本地词典先完成第一轮注解，再筛出本地无法解析且不像专有名词的候选词；缓存未命中的词按批次发送给后台 LLM，结果写入 IndexedDB 后再进行第二轮注解。批量上限、并发控制、缓存键和静默降级都在设计里明确下来，避免实现时临时猜测。

— 真实 design：记录两阶段渲染、批量回填、缓存与静默降级

tasks：按什么顺序落地

tasks.md 把方案拆成可以逐项完成的任务，并用复选框记录进度。这个真实 change 分为五组：候选筛选与连字符处理、AI 缓存、批量 LLM 回填、scanner 第二阶段编排、验证与提交。归档中自动化测试和构建已经完成，但“在真实文章中手动验证在线、离线和缓存命中”的任务仍未勾选。真实记录不一定整齐完美，未完成项本身也是审计信息。

— 真实 tasks：候选、缓存、批量回填、编排和验证

四类制品合起来，刚好回答：为什么做、做什么、怎么做、分几步做。它们的依赖关系用于帮助协作，不是不可回头的阶段门。实现中发现原方案不成立，可以先修正制品，再继续编码。

OpenSpec 当前主线可以记成四个动作：explore → propose → apply → archive。不同版本和 profile 可能还会显示 sync、update 等命令，因此不要死记“固定有几个命令”，以初始化后的自动补全和官方文档为准。

第一步：需求模糊，先 explore

如果你只知道“想让本地词库之外的难词也能显示提示”，但还不确定触发条件、缓存方式或失败处理，可以先在智能体聊天框运行：

explore 会阅读代码、比较方案、澄清约束，但默认不创建 change。它适合高风险、信息不足或必须先理解存量代码的场景。

如果需求已经很清楚，可以跳过探索，直接进入 propose。

第二步：propose 生成规划制品

智能体会创建 openspec/changes/inline-ai-backfill/，并生成 proposal、specs、design 和 tasks。此时不要急着 apply。先由人检查范围、业务规则、异常场景和技术约束，尤其要看“明确不做什么”。

这一步是 OpenSpec 最重要的控制点：AI 可以起草，但需求责任不能外包给 AI。

第三步：apply 按任务实现

智能体会读取任务清单，逐项修改代码、补充测试，并把完成项更新为 [x]。如果实现过程中发现设计不成立，不应偷偷绕过去，而应同步修订相关 artifact，让文档和代码重新一致。

第四步：验证后 archive

expanded workflow 提供 /opsx:verify，用于从完整性、正确性和一致性三个维度检查实现与 artifacts 是否匹配。它能提醒某个需求没有实现、某个场景没有测试证据，或 design 与代码已经漂移。

确认后运行：

归档会检查制品和任务状态，在需要时同步 delta specs，并把 change 移到带日期的 archive 目录。归档后，AI 行内回填的规则会进入主 specs，2026-06-30-inline-ai-backfill 则保留本次决策的完整轨迹。

— OpenSpec 核心工作流及人工控制点

复杂 change 不必一次写完

propose 适合大多数需求，因为它能一次生成进入实现所需的规划制品。但当变更牵涉多个业务规则、技术方案尚未收敛，或者需要不同角色分别审阅时，可以启用 expanded workflow，把制品分步完成。

/opsx:new 只创建 change 骨架；/opsx:continue 根据依赖关系生成下一个可用 artifact，适合每完成一步就停下来评审；/opsx:ff 会按依赖顺序快速补齐制品，适合范围已经很清楚的中小需求。

如果需求在实现中改变，优先用 /opsx:update 修订已有规划制品并检查相互矛盾，再重新 apply。若连变更意图都已经不同，则新建 change 比反复改写旧 proposal 更容易保留清晰历史。

OpenSpec 当前要求 Node.js 20.19.0 或更高版本。先在终端安装 CLI：

进入项目根目录，选择要接入的智能体：

也可以只运行 openspec init，按交互提示选择工具。初始化会创建 openspec/ 目录，并为选中的智能体生成相应 skills、commands 或 prompts。

初始化后项目根目录应该出现 openspec/specs/ 与 openspec/changes/；所选智能体的配置目录里应该出现 OpenSpec 生成的 command 或 skill。Claude Code、Gemini CLI 和 Cursor 可以先输入 / 查看自动补全；Codex 则用 /skills 或 $ 检查对应 skill。

这些生成文件建议与代码一起纳入版本控制。这样同一仓库的其他成员拉取代码后，既能读到 specs 和历史 change，也能复用项目约定的工作流。需要刷新 OpenSpec 版本或切换 profile 时，运行 openspec update，不要手工复制一套可能已经过时的命令文件。

OpenSpec 没有一个需要单独启动的后台服务。初始化后，仍然打开你原来使用的 Claude Code、Codex、Gemini CLI 或 Cursor，在聊天框输入相应命令即可。

如果想启用 new、continue、ff、verify、bulk-archive、onboard 等扩展能力，可以运行：

对第一次使用的人，建议先走主线，不要一开始就把全部命令都打开。需求模糊时用 explore，需求清楚时 propose，审阅后 apply，验证后 archive，已经足够理解 OpenSpec 的价值。

OpenSpec 官方支持 30 余种 AI Coding 工具。它的核心思路是：CLI 维护统一的规范结构，再根据不同工具的约定生成 command、prompt 或 skill。你学的是同一套工作流，差别主要在入口语法和文件位置。

本文只展开 Claude Code、Codex、Gemini CLI 和 Cursor 四种常用工具。命令形式以当前官方文档为依据，但各工具的扩展机制仍在演进，初始化后应先输入 / 或 $ 查看自动补全。

Codex 需要多解释一句。OpenSpec 当前把 Codex 作为 skills-only 工具：初始化后把能力写入 .codex/skills/openspec-*，不会生成 OpenSpec custom prompt 文件。在 Codex 中可以先用 /skills 查看已安装能力，也可以通过 $ 显式选择，例如 $openspec-propose。如果旧教程仍在介绍 OpenSpec prompt 入口，那是已经过时的集成方式，应以当前 skills 和自动补全为准。

如果初始化后看不到命令或 skill，依次检查：是否在正确的项目根目录、是否选中了对应 tool ID、是否运行过 openspec update，以及智能体是否需要重启或新开会话才能重新扫描扩展文件。

OpenSpec 很适合三类场景。

第一，存量项目持续迭代。旧系统有既有行为和隐含约束，直接让 AI“照描述改”很容易顾此失彼。主 specs 能帮助后续 change 对照当前事实。

第二，一个需求会跨多个模块、多人或多个智能体。把范围和场景写进仓库，比把关键决定留在某个人的会话里更容易复用和审查。

第三，需求会反复调整，但又需要知道“为什么改成现在这样”。change 与 archive 为每次决策留下了边界。

它也不值得被机械套用。改一个错别字、做一次性探索原型，通常不需要四类完整制品；而高风险功能即使用了 OpenSpec，也不能省略测试、安全评审和上线验证。

会议分享中有一个很实际的经验：把大需求拆成较小的 change，AI 的上下文更集中，影响范围也更可控。比如 inline-ai-backfill 只负责触发门、未覆盖词筛选、批量回填、缓存和失败降级；核心词库修复、难度模型、confusion-map 与生词复习仍由其他 change 负责，而不是让一个 change 承担整个插件。

与其他 SDD 工具相比，OpenSpec 的定位偏轻量和工具无关。GitHub Spec Kit 更强调从规范、计划、任务到实现的完整方法；Kiro 把 Specs 深度整合进自身 IDE，并提供 Requirements-First、Design-First 等流程。三者不是简单的“谁更强”，而是控制力度、工具绑定和存量项目适配方式不同。选择之前，应该先看团队真正缺的是规范、测试、记忆，还是 IDE 内的一体化体验。

最后保留五个人工检查点：proposal 是否值得做，spec 是否可验证，design 是否符合现有架构，apply 后测试是否真实通过，archive 前 artifacts 与代码是否一致。OpenSpec 能把检查点摆到台面上，但不能替你做最终判断。

团队落地时，先约定四件小事

第一，明确谁对主 specs 负责。开发者可以发起 delta spec，但涉及业务口径、权限和数据定义时，应由真正拥有该领域的人确认。否则“有文档”仍然可能只是把错误写得更正式。

第二，统一 change 的颗粒度和命名。一个 change 最好对应一个可以独立解释、实现和验证的目标。名称使用动词加对象或清楚描述动作，例如真实归档中的 inline-ai-backfill、fix-dictionary-glosses，不要堆成长期不结束的 update-reading-extension。

第三，把 artifacts 评审放进现有代码评审，而不是另起一套仪式。提交实现前，检查需求场景是否对应测试，设计决策是否反映在代码中，tasks 是否真实完成。规范与代码放在同一个 diff 里，审阅者更容易发现两者漂移。

第四，完成后及时 archive。长期把已上线的 change 留在活动目录，会让后续智能体误以为工作仍未结束。归档不是整理卫生，而是把新的系统行为合入事实源，并明确下一次变更应该从哪里出发。

OpenSpec 的核心不是让项目多出几份 Markdown，而是把容易消失在聊天里的开发意图，变成可阅读、可修订、可归档的工程协议。

对小白，它提供了一条不容易走丢的路线：先想清楚，再写清楚，然后实现和验证。对有经验的开发者，它提供的是更稳定的协作边界：需求、设计、任务与代码可以互相校验，换模型、换会话、换智能体时不必从头猜测。

第一次尝试不需要改造整个团队流程。选一个边界明确、但又不止改一行代码的小功能，走完一次 explore → propose → apply → archive。当你能从归档里回答“为什么这样做”，OpenSpec 才真正开始发挥作用。