W
AI-Wiki
ENTITY

OpenSpec

定义或身份

OpenSpec 是文中与 Superpowers 配套使用的规范管理与归档工具，核心职责不是“帮忙想方案”，也不是“边写边改代码”，而是把已经确认的设计方向固化为正式、固定、可执行、可验收、可追溯的变更文档。

文中把整套方法概括为：先用 Superpowers 把方向探明白，再用 OpenSpec 把规则定下来锁死，最后回到 Superpowers 做编码、测试、验证，收尾再交给 OpenSpec 归档留存。

它解决的是“标准不一、后续说不清”的问题：一旦进入 OpenSpec 阶段，重点就从探索转为定版，避免在开发过程中继续随意改口径、改边界、改验收标准。

角色职责

1. 锁定规范，而不是前期探索

OpenSpec 不是流程的起点。文中明确要求，在探索阶段结束、设计方向完全确认之前，不能创建规范，也不应让 OpenSpec 提前介入。

前一阶段要先把这些问题厘清：

  • 需求目标是什么
  • 边界在哪里
  • 明确不做什么
  • 输入、输出、异常场景是什么
  • 验收标准是什么
  • 2 到 3 个可行方案的优缺点分别是什么
  • 推荐方案及其理由是什么
  • 风险与测试思路是什么

只有当团队对设计方向达成一致后，才进入 OpenSpec。也就是说，OpenSpec 处理的是“已确认内容的正式化”，不是“模糊需求的澄清”。

2. 创建 change 并形成正式工件

OpenSpec 在流程中的直接动作是先确定变更名称，然后创建一个 change，并围绕这个 change 补齐完整文档。文中要求的关键工件包括：

  • proposal：说明为什么做、要做什么、影响范围
  • design：说明怎么做，包括技术方案、替代方案、风险与测试策略
  • spec：写清正式需求与验收场景，作为需求判断和验收依据
  • tasks：把实现工作拆成可执行的任务清单

这四类工件共同构成后续开发的统一依据。文中强调，所有文档补齐并经团队确认后，才能进入编码阶段。

3. 作为编码前置条件

OpenSpec 产物不是可有可无的附属材料，而是进入执行阶段的前提条件。文中的闸门规则写得很明确：

  1. 设计没确认，不进入 OpenSpec 规范阶段
  2. 规范文档没补齐，不进入编码阶段
  3. 没有真实测试验证结果，不宣称功能完成
  4. 代码、测试、规范不一致，不允许归档

因此，proposal、design、spec、tasks 不是写给归档看的形式材料，而是编码前必须具备的约束条件。没有这些工件，后续开发就不应开始。

4. 作为验收与归档的一致性依据

在实现完成后，OpenSpec 还负责把变更从“进行中”收尾为“正式完成的规范”。归档前要检查：

  • 所有规范文档齐全完整
  • 任务清单全部完成
  • 测试覆盖关键场景，且结果通过
  • 代码实现与规范完全一致

这说明 OpenSpec 不只是开发前的“立项文档工具”，也是开发后的“验收与留痕工具”。它把“当初说要做什么”和“最终实际交付了什么”绑定到同一套 change 工件上，保证验收、复盘和备查时口径一致。

关键信息

流程位置

文中的总体流程是：

  1. 用户或业务方提出需求
  2. Superpowers 开始探索性规划
  3. 团队确认设计方向
  4. OpenSpec 开始锁定规范
  5. 团队确认 proposal/design/spec/tasks
  6. Superpowers 开始执行编码、测试和验证
  7. 团队确认验证结果
  8. OpenSpec 归档已完成变更

从这个顺序可以看出，OpenSpec 只出现在两个节点：

  • 中段：把已确认设计固化为 change 与规范工件
  • 末段：把已实现且已验证的 change 归档

它不负责探索阶段，也不负责具体编码执行。

常用命令

文中列出的 OpenSpec 常用命令包括：

openspec new change ""
openspec status --change "" --json
openspec instructions proposal --change "" --json
openspec instructions design --change "" --json
openspec instructions specs --change "" --json
openspec instructions tasks --change "" --json

这些命令分别对应 change 的创建、状态查看，以及 proposal、design、specs、tasks 的说明或生成指引获取。

归档命令则是：

openspec archive ""

原文在排版中将该命令挤成了 openspecarchive""，但其语义明确是执行 archive 归档操作。

推荐产物路径

文中给出的推荐组织方式位于 openspec/changes 目录下，主要路径为：

openspec/changes/<change>/proposal.md
openspec/changes/<change>/design.md
openspec/changes/<change>/specs/<name>/spec.md
openspec/changes/<change>/tasks.md

原文示例里 change 名称和 spec 子目录名称以占位形式省略，但结构意图很清楚：一个 change 目录下至少应有 proposal、design、tasks，以及 specs 子目录中的 spec 文档。

细节与边界

进入时机有严格前提

OpenSpec 不是拿到需求就立刻创建的。文中反复强调：

  • 设计未确认前，不进入 OpenSpec
  • 探索阶段未结束前，不创建规范
  • 团队未确认方向前，不要开始锁定 proposal/design/spec/tasks

这背后的原因是，需求如果仍然模糊，过早写规范很容易被整体推翻，前面的工作会白费。

它的目标是“锁死”，不是“灵活试错”

文中对 OpenSpec 的描述是“把确定好的内容固化成正式规范，谁也不能随便改”。这意味着它适合承接已经收敛的方案，不适合承接还在快速变动、边界未定、需要反复试错的内容。

一旦文档进入 OpenSpec 阶段，后续编码、测试和验证都要以这些工件为依据，开发人员不能擅自加功能、不能随意改逻辑。

适用的是重要、复杂、需要留痕的变更

虽然这篇词条聚焦 OpenSpec，但原文对整套流程的适用范围给了明确边界。需要完整使用该流程、因此通常也需要进入 OpenSpec 的情况包括：

  • 新增接口或者业务能力
  • 修改已有的核心业务行为
  • 调整权限、审计、交易、数据一致性这类关键逻辑
  • 跨多个模块的改造工作
  • 需要测试验收、留痕备查的重要功能

而对于不影响功能、不改变行为的小改动，原文认为没必要走完整流程，例如：

  • 简单的问答内容调整
  • 修正文字拼写错误
  • 调整文档格式、排版
  • 不改变业务逻辑的小型文档优化