OpenSpec详解

一、OpenSpec 目录结构概览

openspec init 命令会在项目根目录下创建以下标准化的目录结构

项目根目录/
├── openspec/
│   ├── specs/               # [核心] 项目的“宪法”，存放所有已实现功能的最终规范
│   ├── changes/             # [核心] 存放所有进行中的变更提案
│   │   └── archive/         # 已完成变更的“档案馆”
│   ├── config.yaml          # 项目级配置文件，定义全局规则和技术栈
│   └── schemas/             # （可选）自定义工作流模式，满足特定项目需求

二、核心目录详解：项目的“三部曲”

这套目录结构遵循“提案-实施-归档”的核心理念，通过物理路径的分离，实现了开发过程的清晰化。

• openspec/specs/：项目的“宪法”与唯一真相

  • 内容：存放所有已部署、已实现功能的最终规范（spec.md 文件）。这是系统的“Source of Truth”，描述了代码应该表现出的最终行为。

  • 如何形成：它由已完成并通过审核的变更提案，在归档时“合并”而来。

  • 意义：它是项目行为的权威来源，是所有开发者（包括 AI）理解和构建系统的最高准则。这里只记录最终的结果，不记录实现过程。

• openspec/changes/：进行中的“工作计划”

  • 内容：存放所有正在进行或待审核的变更提案。每一个功能开发或重大修改，都在这里有一个独立的子目录。

  • 意义：这是团队的“工作台”。它将“正在讨论的”和“已经确定的”内容物理隔离，避免了混乱。

• openspec/changes/archive/：项目的“历史档案”

  • 内容：存放所有已归档的变更提案。

  • 意义：这是项目的完整演进历史。当你想回顾一个功能是如何一步步设计和实现出来的，可以来这里查阅。

• openspec/config.yaml：项目的“统一上下文”

  • 内容：定义项目的全局配置，如默认工作流模式、技术栈（context）以及针对特定工件的规则（rules）。

  • 意义：它为 AI 提供了统一的项目背景知识，确保所有 AI 生成的工件都符合项目约定。这是实现“团队规范”的关键。

三、关键文件详解：一个变更的“生命线”

一个完整的变更，其核心文件都存放在 changes/<change-id>/ 目录下，它们共同构成了一条完整的“生命线”。

文件	作用（回答什么问题？）	使用时机
proposal.md	“为什么做”：阐述变更的背景、动机、目标和影响范围。	提案阶段：在开始任何实质性工作前，必须先创建此文件以明确价值。
specs/<capability>/spec.md	“做什么”：以 GIVEN/WHEN/THEN 的格式，定义具体的、可测试的功能需求。这是“增量规范”，只描述本次变更新增或修改的部分。	提案阶段：在提案获批后，将模糊的需求转化为精确的规范。
design.md	“怎么做”：记录技术选型、架构决策和实现方案。	提案阶段（可选）：仅当变更涉及复杂决策、跨模块协作或新架构引入时才需要创建。
tasks.md	“分几步做”：一个包含复选框的实施清单，将开发工作拆解为可追踪的小任务-。	提案阶段：在设计和规范明确后，将工作分解成具体的执行步骤。
.openspec.yaml	变更的“身份证”：记录变更的元数据，如其使用的工作流模式（schema）和创建时间戳。	初始化阶段：在运行 /opsx:new 创建变更目录时自动生成，无需手动编辑。

四、 文件的生命周期与工作流

这些文件并非一次性生成，而是在 OpenSpec 的三阶段工作流中动态演进的。

1. 阶段一：创建变更提案 (Planning)

   • 用户动作：在 Claude Code 中运行 /opsx:propose <change-id>。

   • AI 行为：AI 助手会根据你的需求，自动生成 proposal.md、tasks.md 以及 specs/ 目录下的增量规范文件。design.md 仅在需要时由 AI 生成。

   • 此时的意义：这个目录是一个“设计草案”，是团队（你和 AI）进行评审和迭代的对象。所有决策和计划都在这里被文档化，作为后续实施的唯一依据。

2. 阶段二：实施变更 (Implementation)

   • 用户动作：在提案审核通过后，运行 /opsx:apply（在未禁用的配置下）或交给 Superpowers 执行。

   • AI 行为：AI 会读取 tasks.md 中的任务清单，并按顺序逐一实现。每完成一个任务，AI 应自动将 tasks.md 中对应的复选框从 - [ ] 更新为 - [x]。

   • 此时的意义：tasks.md 变成了一个实时的进度看板，你可以随时查看开发进展。specs/ 下的增量规范则成为了 AI 的“验收标准”，其开发过程会持续对照规范以确保不偏离。

3. 阶段三：归档变更 (Archiving)

   • 用户动作：当所有任务完成且代码验证通过后，运行 /opsx:archive <change-id>。

   • AI 行为：OpenSpec 会将 changes/<change-id>/specs/ 中的增量规范“合并” 到 specs/ 主目录中，更新项目的“宪法”。同时，整个 changes/<change-id>/ 目录会被移动到 changes/archive/ 下。

   • 此时的意义：此次变更的成果被正式纳入项目规范，成为了项目历史的一部分。这个闭环保证了 specs/ 始终与代码实现保持同步，实现了“代码即规范”的理想状态。

五、openspec常用命令使用详解

命令	参数要求	语法	核心功能	使用示例
/opsx:explore	可选	/opsx:explore [topic]	需求梳理：在创建正式变更前，用于头脑风暴、调研技术方案或澄清需求。这是一个低成本的探索阶段，不会生成任何文件。	- /opsx:explore - /opsx:explore “如何设计用户认证的JWT刷新机制？”
/opsx:propose	可选	/opsx:propose [change-name-or-description]	生成提案：这是最核心的命令，它会一步到位地创建变更目录并生成所有必需的规划文件。	- /opsx:propose - /opsx:propose add-user-auth - /opsx:propose “为用户模块增加JWT认证”
/opsx:verify	必须	/opsx:verify [change-id]	验证实现：在代码编写完成后，检查你的实现是否与 proposal.md、tasks.md 等规划文件的要求一致。	/opsx:verify add-user-auth
/opsx:archive	必须	/opsx:archive [change-id]	归档变更：当一个变更的开发、验证全部完成后，执行此命令将其标记为已完成。它会将增量规范合并到主规范库中，并将整个变更目录移入归档。	/opsx:archive add-user-auth

简单来说，这几个命令的差异在于：

• /opsx:explore 和 /opsx:propose 属于规划阶段的命令，非常灵活，AI 会根据你的自然语言描述来工作，因此 change-id 不是必需的。

• /opsx:verify 和 /opsx:archive 属于收尾阶段的命令，操作对象是已经存在的变更，因此必须通过 change-id 来精确指定要操作的目标。