引导用户完成他们的第一个完整OpenSpec工作流周期。这是一个教学体验——你将在他们的代码库中完成实际工作，同时解释每个步骤。

准备阶段

开始前，检查OpenSpec是否已初始化：

openspec-cn status --json 2>&1 || echo "NOT_INITIALIZED"

如果未初始化：

OpenSpec尚未在此项目中设置。请先运行 openspec-cn init ，然后返回 /opsx:onboard 。

如果未初始化，请在此停止。

阶段1：欢迎

显示：

欢迎使用OpenSpec！

我将引导您完成一个完整的变更周期——从想法到实现——使用您代码库中的真实任务。在此过程中，您将通过实践学习工作流程。

我们将要做的事情：

1. 在您的代码库中选择一个小的真实任务
2. 简要探索问题
3. 创建一个变更（我们工作的容器）
4. 构建产出物：提案 → 规格说明 → 设计 → 任务
5. 实现任务
6. 归档完成的变更

时间： ~15-20分钟

让我们开始寻找要处理的内容。

阶段2：任务选择

代码库分析

扫描代码库寻找小的改进机会。寻找：

• TODO/FIXME注释 - 在代码文件中搜索 TODO 、FIXME 、HACK 、XXX

• 缺少错误处理 - 吞没错误的 catch 块，没有try-catch的风险操作

• 没有测试的函数 - 交叉引用 src/ 和测试目录

• 类型问题 - TypeScript文件中的 any 类型（: any 、as any ）

• 调试工件 - 非调试代码中的 console.log 、console.debug 、debugger 语句

• 缺少验证 - 没有验证的用户输入处理程序

同时检查最近的git活动：

git log --oneline -10 2>/dev/null || echo "No git history"

提出建议

根据您的分析，提出3-4个具体建议：

任务建议

基于扫描您的代码库，以下是一些好的入门任务：

1. [最有希望的任务] 位置：src/path/to/file.ts:42 范围：~1-2个文件，~20-30行 为什么好：[简要原因]

2. [第二个任务] 位置：src/another/file.ts 范围：~1个文件，~15行 为什么好：[简要原因]

3. [第三个任务] 位置：[位置] 范围：[估计] 为什么好：[简要原因]

4. 其他内容？ 告诉我您想要处理什么。

哪个任务让您感兴趣？（选择一个数字或描述您自己的）

如果未找到任何内容： 回退到询问用户想要构建什么：

我在您的代码库中没有找到明显的快速改进机会。您一直想要添加或修复什么小东西？

范围护栏

如果用户选择或描述的内容太大（主要功能，多天工作）：

这是一个有价值的任务，但对于您的第一次OpenSpec体验来说可能太大了。

对于学习工作流程，越小越好——它让您能够看到完整周期而不会陷入实现细节。

选项：

1. 切分成更小的部分 - [他们的任务]中最小的有用部分是什么？也许只是[具体切片]？
2. 选择其他内容 - 其他建议之一，或不同的任务？
3. 无论如何都做 - 如果您真的想处理这个，我们可以做。只是要知道需要更长时间。

您更喜欢哪种？

如果用户坚持，让他们覆盖——这是一个软护栏。

阶段3：探索演示

一旦选择了任务，简要演示探索模式：

在我们创建变更之前，让我快速向您展示探索模式——这是在承诺方向之前思考问题的方式。

花1-2分钟调查相关代码：

• 阅读涉及的文件

• 如果需要，绘制快速ASCII图表

• 注意任何考虑事项

快速探索

[您的简要分析——您发现了什么，任何考虑事项]

┌─────────────────────────────────────────┐ │ [可选：如果有帮助的ASCII图表] │ └─────────────────────────────────────────┘

探索模式（/opsx:explore）用于这种思考——在实现之前进行调查。您可以在需要思考问题时随时使用它。

现在让我们创建一个变更来保存我们的工作。

暂停 - 等待用户确认后再继续。

阶段4：创建变更

解释：

创建变更

OpenSpec中的"变更"是围绕一项工作的所有思考和规划的容器。它位于 openspec/changes/<name>/ 中，保存您的产出物——提案、规格说明、设计、任务。

让我为我们的任务创建一个。

执行： 使用派生的kebab-case名称创建变更：

openspec-cn new change "<derived-name>"

显示：

已创建：openspec/changes/<name>/

文件夹结构：

openspec/changes// ├── proposal.md ← 为什么我们要做这个（空，我们将填充它） ├── design.md ← 我们将如何构建它（空） ├── specs/ ← 详细需求（空） └── tasks.md ← 实现检查清单（空）

现在让我们填充第一个产出物——提案。

阶段5：提案

解释：

提案

提案捕获为什么我们要进行此变更以及什么在高层级上涉及。这是工作的"电梯演讲"。

我将根据我们的任务起草一个。

执行： 起草提案内容（暂时不保存）：

这是一个草案提案：

为什么

[1-2句话解释问题/机会]

什么变化

[将要不同的要点]

能力

新能力

• <能力名称>: [简要描述]

修改的能力

<!-- 如果修改现有行为 -->

影响

• src/path/to/file.ts: [什么变化]
• [其他文件如果适用]

这能捕捉意图吗？我可以在保存前调整。

暂停 - 等待用户批准/反馈。

批准后，保存提案：

openspec-cn instructions proposal --change "<name>" --json

然后将内容写入 openspec/changes/<name>/proposal.md 。

提案已保存。这是您的"为什么"文档——您随时可以回来在理解发展时完善它。

接下来：规格说明。

阶段6：规格说明

解释：

规格说明

规格说明以精确、可测试的术语定义什么我们正在构建。它们使用需求/场景格式，使预期行为清晰明了。

对于像这样的小任务，我们可能只需要一个规格说明文件。

执行： 创建规格说明文件：

mkdir -p openspec/changes/<name>/specs/<capability-name>

起草规格说明内容：

这是规格说明：

新增需求

需求：<名称>

<系统应该做什么的描述>

场景：<场景名称>

• 当 <触发条件>
• 那么 <预期结果>
• 并且 <如果需要额外结果>

这种格式——当/那么/并且——使需求可测试。您可以将它们字面地读作测试用例。

保存到 openspec/changes/<name>/specs/<capability>/spec.md 。

阶段7：设计

解释：

设计

设计捕获如何我们将构建它——技术决策、权衡、方法。

对于小变更，这可能很简短。没关系——不是每个变更都需要深入的设计讨论。

执行： 起草design.md：

这是设计：

上下文

[关于当前状态的简要上下文]

目标/非目标

目标：

• [我们试图实现什么]

非目标：

• [明确超出范围的内容]

决策

决策1：[关键决策]

[方法解释和理由]

对于小任务，这捕获了关键决策而不过度工程化。

保存到 openspec/changes/<name>/design.md 。

阶段8：任务

解释：

任务

最后，我们将工作分解为实现任务——驱动应用阶段的复选框。

这些应该小、清晰且逻辑顺序。

执行： 基于规格说明和设计生成任务：

这是实现任务：

1. [类别或文件]

• 1.1 [具体任务]
• 1.2 [具体任务]

2. 验证

• 2.1 [验证步骤]

每个复选框成为应用阶段的工作单元。准备好实现了吗？

暂停 - 等待用户确认他们准备好实现。

保存到 openspec/changes/<name>/tasks.md 。

阶段9：应用（实现）

解释：

实现

现在我们实现每个任务，在过程中勾选它们。我将宣布每个任务，并偶尔注意规格说明/设计如何影响方法。

执行： 对于每个任务：

• 宣布："正在处理任务N：[描述]"

• 在代码库中实现变更

• 自然地引用规格说明/设计："规格说明说X，所以我做Y"

• 在tasks.md中标记完成：- [ ] → - [x]

• 简要状态："✓ 任务N完成"

保持叙述轻量——不要过度解释每一行代码。

所有任务后：

实现完成

所有任务完成：

• 任务1
• 任务2
• ...

变更已实现！还有一个步骤——让我们归档它。

阶段10：归档

解释：

归档

当变更完成时，我们归档它。这将把它从 openspec/changes/ 移动到 openspec/changes/archive/YYYY-MM-DD-<name>/。

归档的变更成为您项目的决策历史——您随时可以找到它们来理解为什么某物以某种方式构建。

执行：

openspec-cn archive "<name>"

显示：

已归档到：openspec/changes/archive/YYYY-MM-DD-<name>/

变更现在是您项目历史的一部分。代码在您的代码库中，决策记录被保留。

阶段11：回顾与下一步

恭喜！

您刚刚完成了一个完整的OpenSpec周期：

1. 探索 - 思考问题
2. 新建 - 创建变更容器
3. 提案 - 捕获为什么
4. 规格说明 - 详细定义什么
5. 设计 - 决定如何
6. 任务 - 分解为步骤
7. 应用 - 实现工作
8. 归档 - 保留记录

同样的节奏适用于任何大小的变更——小修复或主要功能。

命令参考

下一步是什么？

尝试 /opsx:new 或 /opsx:ff 在您实际想要构建的内容上。您现在掌握了节奏！

优雅退出处理

用户想要中途停止

如果用户说他们需要停止、想要暂停或似乎不投入：

没问题！您的变更保存在 openspec/changes/<name>/。

要在以后继续：

• /opsx:continue <name> - 恢复产出物创建
• /opsx:apply <name> - 跳转到实现（如果任务存在）

工作不会丢失。随时回来。

优雅退出，不施加压力。

用户只想要命令参考

如果用户说他们只想看命令或跳过教程：

OpenSpec快速参考

尝试 /opsx:new 开始您的第一个变更，或 /opsx:ff 如果您想快速移动。

优雅退出。

护栏

• 遵循解释→执行→显示→暂停模式在关键转换点（探索后、提案草案后、任务后、归档后）

• 在实现期间保持叙述轻量——教学而不说教

• 不要跳过阶段即使变更很小——目标是教学工作流程

• 在标记点暂停等待确认，但不要过度暂停

• 优雅处理退出——从不施压用户继续

• 使用真实代码库任务——不模拟或使用虚假示例

• 温和调整范围——引导向更小任务但尊重用户选择