--- name: openspec-onboard description: OpenSpec 引导式入门教程 - 通过真实代码库工作完整演示工作流程 license: MIT compatibility: 需要 openspec CLI。 metadata: author: openspec version: "1.0" generatedBy: "1.1.1" --- 引导用户完成他们的第一个完整 OpenSpec 工作流程周期。这是一次教学体验——你将在他们的代码库中做真实的工作,同时解释每个步骤。 --- ## 准备检查 在开始之前,检查 OpenSpec 是否已初始化: ```bash openspec status --json 2>&1 || echo "NOT_INITIALIZED" ``` **如果未初始化:** > OpenSpec 还未在此项目中设置。请先运行 `openspec init`,然后再回到 `/opsx-onboard`。 如果未初始化,在这里停止。 --- ## 阶段 1: 欢迎 显示: ``` ## 欢迎使用 OpenSpec! 我将带你完成一个完整的变更周期——从想法到实现——使用代码库中的真实任务。在此过程中,你将通过实践来学习工作流程。 **我们将做什么:** 1. 在你的代码库中选择一个小的真实任务 2. 简要探索问题 3. 创建一个变更(我们工作的容器) 4. 构建工件: proposal → specs → design → tasks 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//` 中,包含你的工件——proposal、specs、design、tasks。 让我为我们的任务创建一个。 ``` **执行:** 使用派生的 kebab-case 名称创建变更: ```bash openspec new change "" ``` **显示:** ``` 创建: `openspec/changes//` 文件夹结构: ``` openspec/changes// ├── proposal.md ← 我们为什么这样做(空的,我们会填充) ├── design.md ← 我们如何构建它(空的) ├── specs/ ← 详细需求(空的) └── tasks.md ← 实现检查清单(空的) ``` 现在让我们填充第一个工件——proposal。 ``` --- ## 阶段 5: Proposal **解释:** ``` ## Proposal proposal 捕获我们为什么进行这个变更以及高层次的内容。这是工作的"电梯演讲"。 我将根据我们的任务起草一个。 ``` **执行:** 起草 proposal 内容(还不要保存): ``` 这是一个草案 proposal: --- ## 为什么 (Why) [1-2 句话解释问题/机会] ## 变更内容 (What Changes) [将会有什么不同的要点] ## 能力 (Capabilities) ### 新能力 - ``: [简要描述] ### 修改的能力 ## 影响 (Impact) - `src/path/to/file.ts`: [什么变更] - [其他适用的文件] --- 这是否捕获了意图? 我可以在保存前调整。 ``` **暂停** - 等待用户批准/反馈。 批准后,保存 proposal: ```bash openspec instructions proposal --change "" --json ``` 然后将内容写入 `openspec/changes//proposal.md`。 ``` Proposal 已保存。这是你的"为什么"文档——随着理解的演变,你总是可以回来完善它。 接下来: specs。 ``` --- ## 阶段 6: Specs **解释:** ``` ## Specs Specs 以精确、可测试的术语定义我们正在构建什么。它们使用需求/场景格式,使预期行为非常清晰。 对于像这样的小任务,我们可能只需要一个 spec 文件。 ``` **执行:** 创建 spec 文件: ```bash mkdir -p openspec/changes//specs/ ``` 起草 spec 内容: ``` 这是 spec: --- ## ADDED Requirements ### Requirement: <名称> <系统应该做什么的描述> #### Scenario: <场景名称> - **WHEN** <触发条件> - **THEN** <预期结果> - **AND** <如需要的额外结果> --- 这种格式——WHEN/THEN/AND——使需求可测试。你可以直接将它们作为测试用例来读。 ``` 保存到 `openspec/changes//specs//spec.md`。 --- ## 阶段 7: Design **解释:** ``` ## Design design 捕获我们如何构建它——技术决策、权衡、方法。 对于小变更,这可能很简短。这没关系——不是每个变更都需要深度设计讨论。 ``` **执行:** 起草 design.md: ``` 这是 design: --- ## 上下文 (Context) [关于当前状态的简要上下文] ## 目标 / 非目标 (Goals / Non-Goals) **目标:** - [我们试图实现什么] **非目标:** - [明确超出范围的内容] ## 决策 (Decisions) ### Decision 1: [关键决策] [方法和理由的解释] --- 对于小任务,这捕获了关键决策而不会过度设计。 ``` 保存到 `openspec/changes//design.md`。 --- ## 阶段 8: Tasks **解释:** ``` ## Tasks 最后,我们将工作分解为实现任务——驱动应用阶段的复选框。 这些应该小、清晰且按逻辑顺序排列。 ``` **执行:** 基于 specs 和 design 生成任务: ``` 这是实现任务: --- ## 1. [类别或文件] - [ ] 1.1 [具体任务] - [ ] 1.2 [具体任务] ## 2. 验证 (Verify) - [ ] 2.1 [验证步骤] --- 每个复选框在应用阶段成为一个工作单元。准备好实现了吗? ``` **暂停** - 等待用户确认他们准备好实现。 保存到 `openspec/changes//tasks.md`。 --- ## 阶段 9: Apply (实现) **解释:** ``` ## 实现 (Implementation) 现在我们实现每个任务,在进行时勾选它们。我会宣布每一个,偶尔注意 specs/design 如何指导方法。 ``` **执行:** 对于每个任务: 1. 宣布: "正在处理任务 N: [描述]" 2. 在代码库中进行所需的更改 3. 自然地引用 specs/design: "spec 说 X,所以我做 Y" 4. 在 tasks.md 中标记完成: `- [ ]` → `- [x]` 5. 简要状态: "✓ 任务 N 完成" 保持叙述轻量——不要过度解释每行代码。 所有任务完成后: ``` ## 实现完成 所有任务完成: - [x] Task 1 - [x] Task 2 - [x] ... 变更已实现! 还有一步——让我们归档它。 ``` --- ## 阶段 10: Archive **解释:** ``` ## 归档 (Archiving) 当变更完成时,我们归档它。这将它从 `openspec/changes/` 移动到 `openspec/changes/archive/YYYY-MM-DD-/`。 归档的变更成为你项目的决策历史——你总是可以在以后找到它们,以了解为什么某些东西是以某种方式构建的。 ``` **执行:** ```bash openspec archive "" ``` **显示:** ``` 归档到: `openspec/changes/archive/YYYY-MM-DD-/` 变更现在是你项目历史的一部分。代码在你的代码库中,决策记录被保存。 ``` --- ## 阶段 11: 回顾与下一步 ``` ## 恭喜! 你刚刚完成了一个完整的 OpenSpec 周期: 1. **Explore** - 思考问题 2. **New** - 创建变更容器 3. **Proposal** - 捕获为什么 (WHY) 4. **Specs** - 详细定义什么 (WHAT) 5. **Design** - 决定如何 (HOW) 6. **Tasks** - 分解为步骤 7. **Apply** - 实现工作 8. **Archive** - 保存记录 这个相同的节奏适用于任何规模的变更——无论是小修复还是主要功能。 --- ## 命令参考 | 命令 | 功能 | |---------|--------------| | `/opsx-explore` | 在工作前/期间思考问题 | | `/opsx-new` | 启动新变更,逐步完成工件 | | `/opsx-ff` | 快进: 一次创建所有工件 | | `/opsx-continue` | 继续现有变更的工作 | | `/opsx-apply` | 实现变更中的任务 | | `/opsx-verify` | 验证实现与工件匹配 | | `/opsx-archive` | 归档完成的变更 | --- ## 下一步是什么? 在你真正想构建的东西上尝试 `/opsx-new` 或 `/opsx-ff`。你现在已经掌握了节奏! ``` --- ## 优雅退出处理 ### 用户想中途停止 如果用户说他们需要停止、想暂停或看起来不再参与: ``` 没问题! 你的变更保存在 `openspec/changes//`。 要在以后从我们离开的地方继续: - `/opsx-continue ` - 恢复工件创建 - `/opsx-apply ` - 跳转到实现(如果任务存在) 工作不会丢失。准备好时随时回来。 ``` 优雅退出,不施加压力。 ### 用户只想要命令参考 如果用户说他们只想看命令或跳过教程: ``` ## OpenSpec 快速参考 | 命令 | 功能 | |---------|--------------| | `/opsx-explore` | 思考问题(不改代码) | | `/opsx-new ` | 启动新变更,逐步进行 | | `/opsx-ff ` | 快进: 一次所有工件 | | `/opsx-continue ` | 继续现有变更 | | `/opsx-apply ` | 实现任务 | | `/opsx-verify ` | 验证实现 | | `/opsx-archive ` | 完成时归档 | 试试 `/opsx-new` 来开始你的第一个变更,或者如果你想快速移动就用 `/opsx-ff`。 ``` 优雅退出。 --- ## 守护 - **遵循 EXPLAIN → DO → SHOW → PAUSE 模式** 在关键转换点(探索后、proposal 草案后、任务后、归档后) - **保持叙述轻量** 在实现期间——教学但不说教 - **不要跳过阶段** 即使变更很小——目标是教学工作流程 - **在标记的点暂停等待确认**,但不要过度暂停 - **优雅处理退出**——永远不要强迫用户继续 - **使用真实代码库任务**——不要模拟或使用假例子 - **温和地调整范围**——引导向更小的任务但尊重用户选择