openspec-onboard

引导用户完成他们的第一个完整OpenSpec工作流周期。这是一个教学体验——你将在他们的代码库中完成实际工作，同时解释每个步骤。 --- ## 准备阶段 开始前，检查OpenSpec是否已初始化： ```bash 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：任务选择 ### 代码库分析 扫描代码库寻找小的改进机会。寻找： 1. **TODO/FIXME注释** - 在代码文件中搜索 `TODO`、`FIXME`、`HACK`、`XXX` 2. **缺少错误处理** - 吞没错误的 `catch` 块，没有try-catch的风险操作 3. **没有测试的函数** - 交叉引用 `src/` 和测试目录 4. **类型问题** - TypeScript文件中的 `any` 类型（`: any`、`as any`） 5. **调试产出物** - 非调试代码中的 `console.log`、`console.debug`、`debugger` 语句 6. **缺少验证** - 没有验证的用户输入处理程序 同时检查最近的git活动： ```bash 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名称创建变更： ```bash openspec-cn new change "<derived-name>" ``` **显示：** ``` 已创建：`openspec/changes/<name>/` 文件夹结构： ``` openspec/changes/<name>/ ├── proposal.md ← 为什么我们要做这个（空，我们将填充它） ├── design.md ← 我们将如何构建它（空） ├── specs/ ← 详细需求（空） └── tasks.md ← 实现检查清单（空） ``` 现在让我们填充第一个产出物——提案。 ``` --- ## 阶段5：提案 **解释：** ``` ## 提案 提案捕获**为什么**我们要进行此变更以及**什么**在高层级上涉及。这是工作的"电梯演讲"。 我将根据我们的任务起草一个。 ``` **执行：** 起草提案内容（暂时不保存）： ``` 这是一个草案提案： --- ## 为什么 [1-2句话解释问题/机会] ## 什么变化 [将要不同的要点] ## 能力 ### 新能力 - `<能力名称>`: [简要描述] ### 修改的能力 <!-- 如果修改现有行为 --> ## 影响 - `src/path/to/file.ts`: [什么变化] - [其他文件如果适用] --- 这能捕捉意图吗？我可以在保存前调整。 ``` **暂停** - 等待用户批准/反馈。 批准后，保存提案： ```bash openspec-cn instructions proposal --change "<name>" --json ``` 然后将内容写入 `openspec/changes/<name>/proposal.md`。 ``` 提案已保存。这是您的"为什么"文档——您随时可以回来在理解发展时完善它。 接下来：规格说明。 ``` --- ## 阶段6：规格说明 **解释：** ``` ## 规格说明 规格说明以精确、可测试的术语定义**什么**我们正在构建。它们使用需求/场景格式，使预期行为清晰明了。 对于像这样的小任务，我们可能只需要一个规格说明文件。 ``` **执行：** 创建规格说明文件： ```bash 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：应用（实现） **解释：** ``` ## 实现 现在我们实现每个任务，在过程中勾选它们。我将宣布每个任务，并偶尔注意规格说明/设计如何影响方法。 ``` **执行：** 对于每个任务： 1. 宣布："正在处理任务N：[描述]" 2. 在代码库中实现变更 3. 自然地引用规格说明/设计："规格说明说X，所以我做Y" 4. 在tasks.md中标记完成：`- [ ]` → `- [x]` 5. 简要状态："✓ 任务N完成" 保持叙述轻量——不要过度解释每一行代码。 所有任务后： ``` ## 实现完成 所有任务完成： - [x] 任务1 - [x] 任务2 - [x] ... 变更已实现！还有一个步骤——让我们归档它。 ``` --- ## 阶段10：归档 **解释：** ``` ## 归档 当变更完成时，我们归档它。这将把它从 `openspec/changes/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。 归档的变更成为您项目的决策历史——您随时可以找到它们来理解为什么某物以某种方式构建。 ``` **执行：** ```bash openspec-cn archive "<name>" ``` **显示：** ``` 已归档到：`openspec/changes/archive/YYYY-MM-DD-<name>/` 变更现在是您项目历史的一部分。代码在您的代码库中，决策记录被保留。 ``` --- ## 阶段11：回顾与下一步 ``` ## 恭喜！ 您刚刚完成了一个完整的OpenSpec周期： 1. **探索** - 思考问题 2. **新建** - 创建变更容器 3. **提案** - 捕获为什么 4. **规格说明** - 详细定义什么 5. **设计** - 决定如何 6. **任务** - 分解为步骤 7. **应用** - 实现工作 8. **归档** - 保留记录 同样的节奏适用于任何大小的变更——小修复或主要功能。 --- ## 命令参考 | 命令 | 做什么 | |---------|--------------| | `/opsx:explore` | 在工作之前/期间思考问题 | | `/opsx:new` | 开始新变更，逐步通过产出物 | | `/opsx:ff` | 快进：一次创建所有产出物 | | `/opsx:continue` | 继续处理现有变更 | | `/opsx:apply` | 实现变更中的任务 | | `/opsx:verify` | 验证实现是否匹配产出物 | | `/opsx:archive` | 归档完成的变更 | --- ## 下一步是什么？ 尝试 `/opsx:new` 或 `/opsx:ff` 在您实际想要构建的内容上。您现在掌握了节奏！ ``` --- ## 优雅退出处理 ### 用户想要中途停止 如果用户说他们需要停止、想要暂停或似乎不投入： ``` 没问题！您的变更保存在 `openspec/changes/<name>/`。 要在以后继续： - `/opsx:continue <name>` - 恢复产出物创建 - `/opsx:apply <name>` - 跳转到实现（如果任务存在） 工作不会丢失。随时回来。 ``` 优雅退出，不施加压力。 ### 用户只想要命令参考 如果用户说他们只想看命令或跳过教程： ``` ## OpenSpec快速参考 | 命令 | 做什么 | |---------|--------------| | `/opsx:explore` | 思考问题（无代码更改） | | `/opsx:new <name>` | 开始新变更，逐步进行 | | `/opsx:ff <name>` | 快进：一次创建所有产出物 | | `/opsx:continue <name>` | 继续现有变更 | | `/opsx:apply <name>` | 实现任务 | | `/opsx:verify <name>` | 验证实现 | | `/opsx:archive <name>` | 完成后归档 | 尝试 `/opsx:new` 开始您的第一个变更，或 `/opsx:ff` 如果您想快速移动。 ``` 优雅退出。 --- ## 护栏 - **遵循解释→执行→显示→暂停模式**在关键转换点（探索后、提案草案后、任务后、归档后） - **在实现期间保持叙述轻量**——教学而不说教 - **不要跳过阶段**即使变更很小——目标是教学工作流程 - **在标记点暂停等待确认**，但不要过度暂停 - **优雅处理退出**——从不施压用户继续 - **使用真实代码库任务**——不模拟或使用虚假示例 - **温和调整范围**——引导向更小任务但尊重用户选择