⚡

OpenSpec工作流程入门指导Skill openspec-onboard

这个技能提供OpenSpec的完整工作流程教学，指导用户在实际代码库中执行从小型任务选择到归档的整个周期，涵盖探索、变化创建、提案、规范、设计、任务实施和归档。关键词包括OpenSpec、软件开发、工作流程、文档化、任务管理、代码实施、DevOps实践。

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

名称: openspec-onboard 描述: OpenSpec的引导入门 - 通过叙述和真实代码库工作，走过一个完整的工作流程周期。 许可证: MIT 兼容性: 需要openspec CLI。 元数据: 作者: openspec 版本: “1.0” 生成者: “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>/`，并持有你的工件——提案、规范、设计、任务。

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

做： 用派生的小写连字符名称创建变化：

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`如果你想快速移动。

优雅退出。

护栏

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