⚡

OpenSpec引导工作流教程Skill openspec-onboard

这个技能是一个引导式教程，用于 OpenSpec 工具，帮助用户通过一个完整的工作流程周期，从任务选择到实施和归档，学习软件开发中的工作流程管理。关键词：OpenSpec, 引导教程, 工作流程, 软件开发, DevOps, 项目管理, 代码库, 文档化。

DevOps 0 次安装 0 次浏览 更新于 3/11/2026

name: openspec-onboard description: OpenSpec 引导入门 - 通过叙述和真实代码库工作，完成一个完整工作流程周期的引导。 license: MIT compatibility: 需要 openspec CLI。 metadata: author: openspec version: “1.0” generatedBy: “1.0.0”

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

准备

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

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

如果未初始化：

此项目中尚未设置 OpenSpec。先运行 openspec 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 活动：

git log --oneline -10 2>/dev/null || echo "无 git 历史"

呈现建议

基于你的分析，呈现 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 new change "<derived-name>"

显示：

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

文件夹结构：

openspec/changes/<name>/
├── proposal.md ← 我们为什么这样做（空，我们将填充它）
├── design.md ← 我们如何构建它（空）
├── specs/ ← 详细需求（空）
└── tasks.md ← 实施清单（空）

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

阶段 5：提案

解释：

## 提案

提案捕捉**为什么**我们进行此更改以及**什么**在高级别涉及。它是工作的“电梯推销”。

我将基于我们的任务起草一个。

做： 起草提案内容（尚未保存）：

这是一个草案提案：

---

## 为什么

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

## 什么变化

[不同之处的要点]

## 能力

### 新能力
- `<capability-name>`: [简要描述]

### 修改的能力
<!-- 如果修改现有行为 -->

## 影响

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

---

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

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

批准后，保存提案：

openspec 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：应用（实施）

解释：

## 实施

现在我们将实施每个任务，完成时勾选它们。我会宣布每一个，偶尔注意规格/设计如何通知方法。

做： 对于每个任务：

  1. 宣布：“任务 N 工作中：[描述]”
  2. 在代码库中实施更改
  3. 自然参考规格/设计：“规格说 X，所以我做 Y”
  4. 在 tasks.md 中标记完成：- [ ] → - [x]
  5. 简要状态：“✓ 任务 N 完成”

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

所有任务后：

## 实施完成

所有任务完成：
- [x] 任务 1
- [x] 任务 2
- [x] ...

更改已实施！最后一步——让我们归档它。

阶段 10：归档

解释：

## 归档

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

归档的更改成为你项目的决策历史——你以后总能找到它们来理解为什么某事以某种方式构建。

做：

openspec archive "<name>"

显示：

归档到：`openspec/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` 如果你想快速移动。

优雅退出。

护栏

  • 遵循解释 → 做 → 显示 → 暂停模式 在关键过渡点（探索后，提案草案后，任务后，归档后）
  • 在实施期间保持叙述轻量——不讲课地教学
  • 不要跳过阶段 即使更改小——目标是教学工作流程
  • 在标记点暂停等待确认，但不要过度暂停
  • 优雅处理退出——从不压力用户继续
  • 使用真实代码库任务——不模拟或使用假例子
  • 温和调整范围——引导向小任务但尊重用户选择