一、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 的三阶段工作流中动态演进的。
-
阶段一：创建变更提案 (Planning)
-
用户动作：在 Claude Code 中运行
/opsx:propose <change-id>。 -
AI 行为：AI 助手会根据你的需求，自动生成
proposal.md、tasks.md以及specs/目录下的增量规范文件。design.md仅在需要时由 AI 生成。 -
此时的意义：这个目录是一个“设计草案”，是团队（你和 AI）进行评审和迭代的对象。所有决策和计划都在这里被文档化，作为后续实施的唯一依据。
-
-
阶段二：实施变更 (Implementation)
-
用户动作：在提案审核通过后，运行
/opsx:apply（在未禁用的配置下）或交给 Superpowers 执行。 -
AI 行为：AI 会读取
tasks.md中的任务清单，并按顺序逐一实现。每完成一个任务，AI 应自动将tasks.md中对应的复选框从- [ ]更新为- [x]。 -
此时的意义：
tasks.md变成了一个实时的进度看板，你可以随时查看开发进展。specs/下的增量规范则成为了 AI 的“验收标准”，其开发过程会持续对照规范以确保不偏离。
-
-
阶段三：归档变更 (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来精确指定要操作的目标。