核心概念速览

OpenSpec 是你与 AI 之间的轻量级约定层。 你写下变更应该实现什么，AI 起草细节，你们共同审阅同一份计划，然后才开始编写代码。本页在一屏内介绍完整的思维模型。想了解详细说明，请看概念。

用五个词概括整个理念：先达成一致，再放心构建。

五个理念

OpenSpec 中的一切都建立在五个概念之上。理解它们，其余内容就只是细节。

1. 规格说明是真实依据。 规格说明描述系统当前的行为，存放在 openspec/specs/ 中，并按领域（auth/、payments/、ui/）组织。规格说明由需求（例如“系统 SHALL 在 30 分钟后使会话过期”）和场景（具体的给定/当/则示例）组成。可以把规格说明看作“这款软件做什么？”这一问题唯一且共同认可的答案。

2. 一个变更就是一个工作单元。 想要新增、修改或删除行为时，就创建一个变更：在 openspec/changes/ 下建立一个文件夹，把这项工作的所有内容放在一起，包括提案、设计、任务清单和规格说明修改。一个变更，一个文件夹，一项功能。

3. 差异规格说明描述的是变更，而不是整个世界。 在变更中，你无需重写整份规格说明，而是写一小段差异：新增 (ADDED) 这项需求、修改 (MODIFIED) 那项需求、移除 (REMOVED) 另一项需求。这正是 OpenSpec 既适合编辑现有系统、又不仅限于从零构建的关键。描述差异，而非最终全貌。

4. 产物层层衔接。 一个变更包含若干文档，它们按自然顺序创建，并以前一项为基础：

proposal ──► specs ──► design ──► tasks ──► implement
   why        what       how       steps      do it

任何时候都可以回头修改其中任一文档。它们是助力，不是关卡。（下文详述。）

5. 归档会将变更并入真实依据。 工作完成后，归档这个变更。其差异规格说明会合并到主规格说明中，变更文件夹则带日期标记并移至 changes/archive/。此时，规格说明反映新的实际情况，你也可以开始下一个变更，整个循环就此闭合。

示意图

┌─────────────────────────────────────────────────────────────────┐
│                          openspec/                              │
│                                                                 │
│   ┌──────────────────┐         ┌──────────────────────────┐    │
│   │     specs/       │         │        changes/          │    │
│   │                  │ ◄─────  │                          │    │
│   │ source of truth  │  merge  │ one folder per change    │    │
│   │ how things work  │  on     │ proposal · design ·      │    │
│   │ today            │ archive │ tasks · delta specs      │    │
│   └──────────────────┘         └──────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

两个文件夹。specs/ 存放既定事实，changes/ 存放拟议变更。归档会将提案纳入既定事实。

实际使用的循环

在默认设置下，你的日常流程如下。可以先自行梳理思路；接着用一条命令起草计划，阅读计划后再用下一条命令实现，最后一条命令将其归档。

/opsx:explore                   →  (optional) think it through with the AI first
/opsx:propose add-dark-mode     →  AI drafts proposal, specs, design, tasks
        (you read and adjust the plan)
/opsx:apply                     →  AI builds it, checking off tasks
/opsx:archive                   →  specs updated, change archived

拿不准时，先从探索开始。 /opsx:explore 是一位没有压力的思考伙伴：它会读取代码、列出选项，并在编写任何代码之前，把模糊的想法整理成具体计划。它最能避免 AI 根据含糊的提示就“随便构建点什么”。如果你已经完全清楚自己要什么？直接执行 /opsx:propose 即可。无论如何，默认配置都包含 explore，因此随时可用。参阅探索指南。

这些斜杠命令是在 AI 助手的聊天中输入的。项目设置 (openspec init) 则在终端中完成。如果你对这种分工感到陌生，请先阅读命令的工作方式；这是最常见的困惑点。

“助力，而非关卡”

OpenSpec 中经常出现这句话，下面用通俗的话解释其含义。

传统规格说明流程是瀑布式的：必须先完成规划，然后才能实现，回头修改还很困难。OpenSpec 不这样做。proposal → specs → design → tasks 的顺序说明下一步可以做什么，而不是必须做什么。

如果在实现过程中发现设计有误？编辑 design.md 后继续。发现范围应该缩小？更新提案即可。没有任何内容会锁死。依赖关系只是为了给 AI 提供所需上下文（没有规格说明作为基础，就无法写出好的任务），并不是为了限制你。

这种做法的优点是诚实：真实工作本就杂乱且反复迭代，OpenSpec 允许它如实发生。代价则是需要自律：没有什么会强迫你继续推进，因此你需要自己让变更保持聚焦，避免范围不断膨胀。工作流指南介绍了有助于做到这一点的习惯。

为什么这点额外投入值得

坦白说，OpenSpec 会多加一个步骤：构建之前先写一份简短计划。那么它能带来什么？

• 趁走错方向还不费钱时及时发现。 在一段提案中纠正误解几乎不费成本；等 AI 写完 400 行代码后再纠正，就不是这样了。
• 计划与代码保存在同一个仓库。 六个月后，你（以及下一次 AI 会话）仍能从规格说明中了解系统为何如此运行。
• 变更便于审查。 一个变更文件夹就是一个整洁的工作包：阅读提案、浏览差异、检查任务即可，不必从聊天记录中考古。
• 适用于现有代码库。 有了差异规格说明，你可以为一个 50,000 行的应用编写变更规格，而无需先记录整个系统。

同时也要坦诚地看待代价：对真正简单的一行修复而言，这套流程的仪式感可能不值得，没关系。OpenSpec 的设计目标是轻量，但并非零成本。在需要达成共识时使用它——一旦你与一个会自信地实现任何模糊要求的 AI 合作，就会发现大多数时候都需要共识。

接下来读什么

• 刚接触 OpenSpec？快速入门会完整演示第一个变更。
• 还不确定该构建什么？从先探索开始。
• 不清楚命令在哪儿运行？阅读命令的工作方式。
• 想深入了解以上所有内容？阅读概念。
• 想通过示例学习？阅读示例与配方。
• 需要术语解释？阅读术语表。