核心概念概览

OpenSpec 是您和 AI 之间的一个轻量级协议层。 您写下一个变更应该做什么，AI 负责起草细节，你们双方都查看同一个计划，然后才开始编写代码。本页面就是将整个心智模型集中在一个屏幕上。如果您需要更详细的版本，Concepts 中有介绍。

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

五个核心思想

OpenSpec 的一切都建立在这五个概念之上。掌握了这些，其余的细节就水到渠成了。

1. Specs 是真相。 Spec 描述您的系统当前如何运行。它存放在 openspec/specs/ 中，并按领域（auth/、payments/、ui/）组织。Specs 由需求（“系统应在 30 分钟后过期会话”）和场景（具体的 given/when/then 示例）组成。可以将 Specs 理解为对“这个软件做什么？”这一问题的单一共识答案。

2. 一个变更是一项工作单元。 当您想要添加、修改或删除某个行为时，您就创建一个变更：一个位于 openspec/changes/ 中的文件夹，将该工作的所有内容集中在一个地方。包括提案、设计、任务列表和 Spec 的编辑。一个变更，一个文件夹，一个功能。

3. Delta specs 描述的是正在发生的变化，而不是整个世界。 在一个变更内部，您不需要重写整个 Spec。您只需编写一个小小的 delta：ADDED（添加）这个需求，MODIFIED（修改）那个，REMOVED（移除）另一个。这是 OpenSpec 擅长于编辑现有系统而非仅限于全新项目的秘诀。您描述的是差异（diff），而不是最终目标状态。

4. Artifacts（产物）层层递进。 一个变更包含一些文档，它们按照自然的顺序创建，每一份都为下一份提供输入：

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

您可以随时回顾其中的任何一份。它们是推动者（enablers），而不是限制器（gates）。（更多细节请看下文。）

5. Archiving 将变更重新整合到真相中。 当工作完成时，您就归档这个变更。它的 delta specs 会合并到主 Spec 中，而该变更文件夹则会带着日期戳记移动到 changes/archive/。现在您的 Specs 描述的是新的现实，您已准备好迎接下一个变更。循环闭合。

结构图

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

两个文件夹。specs/ 是真相所在。changes/ 是您正在提议的内容。归档操作将一个提案（proposal）转化为真相的一部分。

您实际会运行的流程

在默认设置下，您的日常工作是这样的。您可以选择先进行思考；然后一条命令草拟计划，您阅读并调整该计划，下一条命令构建它，最后一条命令存档文件。

/opsx:explore                   →  (可选) 先与 AI 共同思考
/opsx:propose add-dark-mode     →  AI 草拟提案、Specs、设计和任务
        (您阅读并调整计划)
/opsx:apply                     →  AI 构建它，完成各项任务
/opsx:archive                   →  更新 Specs，归档变更

如有疑问，请先探索。 /opsx:explore 是一个零风险的思考伙伴：它会读取您的代码，列出选项，并在任何产物存在之前，将模糊的想法转化为具体的计划。这是对那些可能从模糊提示中构建某物的 AI 的最佳解药。已经确切知道自己想要什么？直接跳到 /opsx:propose 即可。无论哪种情况，探索功能都包含在默认配置中，因此它始终可用。请参阅 Explore guide。

这些都是在您的 AI 助手聊天框中输入的斜杠命令（slash commands）。设置（openspec init）是在您的终端中完成的。如果这种划分对您来说是新的概念，请先阅读 How Commands Work；这是最常见的困惑点。

“推动者，而非限制器”

这个短语出现在 OpenSpec 的各个地方，所以这里用通俗的话解释一下它的含义。

传统的 Spec 流程是瀑布流：完成规划后，才被允许实现，而回溯修改则非常痛苦。OpenSpec 反对这种做法。proposal → specs → design → tasks 这个顺序显示的是接下来可能做什么，而不是您被迫要做什么。

在实施过程中发现设计有误？编辑 design.md 并继续进行。意识到范围需要缩小？更新提案（proposal）。没有任何东西会锁定住您。依赖关系仅仅是为了让 AI 有所需上下文（没有 Specs 作为基础，您就无法编写出好的任务），而不是为了将您限制住。

这里的优势在于诚实：真实的工作是混乱和迭代的，而 OpenSpec 允许这一点。代价则是纪律性：因为没有任何东西会强迫您前进，所以有责任感地保持变更的聚焦，而不是任由其蔓延开来。Workflows 指南提供了良好的习惯做法。

这值得付出一点点额外成本的原因

说实话：OpenSpec 增加了一个步骤。在构建之前，您需要写一份简短的计划。那么，您得到了什么呢？

• 在成本高昂前就发现错误方向。 在一份一小段落的提案中修正一个误解是免费的。在 AI 写了 400 行代码之后修正它则不是。
• 计划和代码保留在同一个仓库中。 六个月后，Specs 会告诉您（以及下一个 AI 会话）系统为何如此运作。
• 变更可以被审查。 一个变更文件夹就是一个整洁的包：阅读提案，浏览 delta，检查任务。无需通过聊天记录进行考古挖掘。
• 它适用于现有的代码库。 Delta 意味着您可以在不先文档化整个应用的情况下，就一个拥有 50,000 行代码的应用提出变更。

诚实的权衡是：对于一个真正微不足道的单行修复，这个仪式可能不会带来回报，这也没关系。OpenSpec 的设计初衷是轻量级的，但它并非免费的。请在“达成一致”至关重要的地方使用它，而事实证明，一旦您开始与一个会自信地构建您模糊要求之物的 AI 合作，这种情况就几乎总是成立的。

下一步去哪里？

• 新手？Getting Started 会完整地演示第一个变更流程。
• 不确定要构建什么？Explore First 是您的起点。
• 对命令在哪里运行感到困惑？How Commands Work。
• 想了解上述所有内容的深度版本？Concepts。
• 通过示例学习？Examples & Recipes。
• 需要定义某个术语？Glossary。