快速上手
你的第一个变更：从想法到归档，适用于新项目或现有项目。
开始之前，你需要在本机安装 CLI（安装），并在项目中初始化 OpenSpec（设置你的项目）。
从空项目开始
你可以在尚未选定技术栈或没有完整架构的情况下开始。在你的项目文件夹中初始化 OpenSpec，然后让你的 agent 和你一起探索各种选项。在你的 AI 对话中：
帮我从零开始探索一个任务追踪器。我还没有选定技术栈。请比较各个选项，帮我选择第一个要实现的行为。先想清楚第一个变更需要什么，把后续的架构决策留待以后。让你的 agent 提出这一个变更，然后按照下面的步骤操作。随着项目成长，你可以随时重新审视架构。
循环流程概览
每个变更都要经历同样的五个步骤：你和 agent 一起把想法想透彻，agent 起草一份计划，你在写任何代码之前修正这份计划，agent 依据计划进行构建，最后归档会用已交付的内容更新你的规格。
flowchart LR
explore["1 · 探索<br/>共同深入思考"] --> propose["2 · 提议<br/>agent 起草计划"]
propose --> review["3 · 审查<br/>你修正计划"]
review --> apply["4 · 应用<br/>agent 按任务逐项构建"]
apply --> archive["5 · 归档<br/>specs 吸收此次变更"]
archive -. "下一次变更" .-> explore
下面每条提示词都发送到你的 AI 对话中，也就是你平时要求写代码的地方。示例使用平实的语言，因此可以跨工具使用。你也可以直接调用技能（skill）；具体语法因工具而异（支持的工具）。
步骤 1：探索
在要求计划之前，先和你的 agent 一起把想法想透彻。在你的 AI 对话中：
帮我探索这个应用中的速率限制应该如何工作。探索是一种思考模式。agent 会调研你的代码库，提出关键问题，勾勒出各种选项，并挑战既有假设。它绝不会写代码。除非你让它记录你们做出的决定，或者在它主动提出时你表示同意，否则它不会撰写任何其他内容。这一步的产出是一个更清晰的想法。
在这一步停留多久都可以，视问题的需要而定。当想法的轮廓让你觉得对了，就交给下一步：
对我们刚才讨论的内容提出变更提案。这句话会替你启动提议步骤，并带上你们已经确定的所有内容。你可以跳过步骤 2 的第一条提示词。
步骤 2：提议
提议把想法变成一份可供审查的计划。如果从探索阶段接续而来，它已经在运行了。如果是全新开始——当你脑中已经清楚这个变更是什么——直接提出请求即可。在你的 AI 对话中：
提出一个添加速率限制的变更。agent 会询问它需要了解的内容，然后写出一个变更文件夹：
openspec/changes/add-rate-limiting/
├── proposal.md 为什么做，以及变更什么
├── specs/ 以可测试的需求定义"完成"
├── design.md 技术决策（仅当变更需要时）
└── tasks.md 实现清单此时还没有代码。提议到计划为止。
步骤 3：审查并修正计划
趁计划还只是文字、还没构建任何东西时，把它修正好。按以下顺序阅读：
proposal.md：问题是否正确？规模是否合适？specs/：最值得细读的部分。你能接受这些需求作为"完成"的标准吗？tasks.md：任务是否恰好覆盖了规格，而不多做任何事？
要修改内容，以下任一方式都可以：
- 自己编辑文件。这些产物都是纯 markdown，文件本身就是计划。
- 告诉你的 agent 哪里不对（"规格缺少未认证场景"）。它会修订这些产物。
步骤 4：应用
应用把计划变成代码。请开一个全新的会话，因为实现工作在干净的上下文窗口中效果更好。在你的 AI 对话中：
应用 add-rate-limiting 变更。agent 会读取变更文件夹，然后按 tasks.md 逐项推进，每落地一项任务就勾选一项。
- 被中断，或上下文用尽了？ 开一个新会话，再让它应用一次。它会从第一个未勾选的任务处继续。
- 计划事实证明有误？ 先修正产物（用步骤 3 中的任一方式），然后继续应用。
- 进度保存在
tasks.md的复选框中。没有任何隐藏状态。
步骤 5：归档
归档做两件事：用变更的需求更新你的主规格，并把变更文件夹移动到归档文件夹（位于 /openspec/changes/archive/*）中。
当 tasks.md 中的每一项都已勾选时，在你的 AI 对话中：
归档 add-rate-limiting 变更。逐步查看归档会做的事情：
## 已完成的变更
> 实现已完成。增量规格（本次变更新增的内容）仍位于变更文件夹中；specs/ 还不知道 rate limiting 的存在。
openspec/
├── specs/ （尚无 rate-limiting 规格）
└── changes/
└── add-rate-limiting/
├── proposal.md
├── tasks.md 所有复选框已勾选
└── specs/
└── rate-limiting/
└── spec.md 增量：ADDED 需求
## 需求落入 specs/
> 增量中的每条需求都会进入主规格：新增的需求被追加，修改的需求替换旧版本。新能力会获得一个新的规格文件。
openspec/
├── specs/
+ │ └── rate-limiting/
+ │ └── spec.md 获得 "Requirement: Rate limiting"
└── changes/
└── add-rate-limiting/
└── specs/
└── rate-limiting/
└── spec.md 增量，即合并的来源
## 文件夹移动到 archive/
> 整个变更文件夹（包括增量）会移动到归档目录下，并添加日期前缀。不会删除任何内容。
openspec/
├── specs/
│ └── rate-limiting/
│ └── spec.md
└── changes/
- └── add-rate-limiting/
+ └── archive/
+ └── 2026-08-08-add-rate-limiting/
+ ├── proposal.md
+ ├── tasks.md
+ └── specs/rate-limiting/spec.md
## 规格描述系统的实际构建结果
> changes/ 已清空，为下一次变更做好准备。specs/ 是系统实际行为的唯一事实来源；archive/ 记录了系统如何一步步演变至今。
openspec/
├── specs/
│ └── rate-limiting/
│ └── spec.md 实际构建出的规格
└── changes/
└── archive/
└── 2026-08-08-add-rate-limiting/Git 是另一件独立的事。把变更文件夹连同代码一起提交即可，除此之外你的工作流不需要任何改变。
保留或精简已归档的变更
openspec/changes/archive/ 会保存每个已完成变更的提案、设计、任务和增量。在上面的归档流程中，增量已经更新了 openspec/specs/。
- 保留整个变更文件夹：当你希望在当前检出中拥有一份自包含的记录时。
- 删除已归档变更的
specs/文件夹：当 Git 就是你规格历史的时候。先提交归档，然后删除openspec/changes/archive/<change>/specs/。提案、设计和任务仍保留在检出中。openspec validate --archived仍然可用，因为它检查的是任务完成情况，而非已应用的增量。 - 删除整个变更文件夹：只有当你不再需要在检出中保留其提案、设计或任务历史时才这样做。当前规格不会改变，但
openspec validate --archived以及对检出的搜索将不再包含该变更。
WARNING
如果你想让 Git 保留被删除的文件，请将归档提交保留在仓库历史中。把归档提交和清理提交压缩（squash）成一次提交，会移除那个中间快照。
OpenSpec 不会自动清理已归档的变更，也不提供保留期设置。
深入了解
进阶指南
尚未编写；我们计划添加以下指南：
- 先做原型：在编写任何规格之前先做代码试验（spike），然后根据原型带来的经验补写提案。
- 迭代式构建：用一系列小变更代替一份大提案。
- 修订已实现的变更：应用之后计划需要再次调整，而变更尚未合并或归档。