# Openspec Onboard

> OpenSpec 引导式入门——通过叙述和真实代码库工作，完整走一遍工作流循环。

- Skill: `txyzznc/openspec-onboard` (Agent Skill)
- Install (CLI): `npx skillmds@latest add txyzznc/openspec-onboard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/txyzznc/openspec-onboard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: txyzznc (https://skillmd.com/u/txyzznc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/txyzznc/openspec-onboard

---


引导用户完成第一个完整的 OpenSpec 工作流循环。这是一次教学体验——您将在他们的代码库中做真实的工作，同时讲解每个步骤。

---

## 预检

开始前，检查 OpenSpec CLI 是否已安装：

```bash
# Unix/macOS
openspec --version 2>&1 || echo "CLI_NOT_INSTALLED"
# Windows (PowerShell)
# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" }
```

**若 CLI 未安装：**
> OpenSpec CLI 未安装。请先安装，然后再回来使用 `/opsx:onboard`。

若未安装则停止。

---

## 第一阶段：欢迎

显示：

```
## 欢迎使用 OpenSpec！

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

**我们将做什么：**
1. 在您的代码库中挑选一个小的真实任务
2. 简要探索问题
3. 创建变更（工作的容器）
4. 构建 artifact：proposal → specs → design → tasks
5. 实现任务
6. 归档已完成的变更

**时间：** 约 15-20 分钟

让我们先找点要做的事情。
```

---

## 第二阶段：任务选择

### 代码库分析

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

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
# Unix/macOS
git log --oneline -10 2>/dev/null || echo "无 git 历史"
# Windows (PowerShell)
# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { 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. **就这个** - 若您真的想处理这个，也可以。只是会花更长时间。

您更倾向于哪种？
```

若用户坚持，可以继续——这是软性限制。

---

## 第三阶段：探索演示

选定任务后，简短演示探索模式：

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

花 1-2 分钟调查相关代码：
- 读取涉及的文件
- 若有帮助，画一个简短的 ASCII 图
- 记录任何注意事项

```
## 快速探索

[您的简短分析——发现了什么，任何注意事项]

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

探索模式（`/opsx:explore`）就是用于这种思考——在实现前先调查。您随时可以使用它来思考问题。

现在让我们创建一个变更来容纳我们的工作。
```

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

---

## 第四阶段：创建变更

**讲解：**
```
## 创建变更

OpenSpec 中的"变更"是围绕一块工作的所有思考和规划的容器。它存放在 `openspec/changes/<name>/` 中，保存您的 artifact——proposal、specs、design、tasks。

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

**执行：** 用推导出的 kebab-case 名称创建变更：
```bash
openspec new change "<derived-name>"
```

**展示：**
```
已创建：`openspec/changes/<name>/`

目录结构：
```
openspec/changes/<name>/
├── proposal.md    ← 我们为什么要做这件事（空，我们来填）
├── design.md      ← 我们如何构建它（空）
├── specs/         ← 详细需求（空）
└── tasks.md       ← 实现清单（空）
```

现在让我们填写第一个 artifact——proposal。
```

---

## 第五阶段：Proposal

**讲解：**
```
## Proposal

Proposal 记录我们**为什么**要进行此变更，以及它在高层面上涉及什么。这是工作的"电梯演讲"。

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

**执行：** 起草 proposal 内容（暂不保存）：

```
这是一个 proposal 草稿：

---

## Why（为什么）

[1-2 句话说明问题/机会]

## What Changes（变更内容）

[将发生什么不同的要点]

## Capabilities（功能）

### New Capabilities（新功能）
- `<capability-name>`：[简短描述]

### Modified Capabilities（修改的功能）
<!-- 若修改现有行为 -->

## Impact（影响）

- `src/path/to/file.ts`：[变更内容]
- [其他文件，如适用]

---

这是否准确表达了意图？我可以在保存之前调整。
```

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

批准后保存 proposal：
```bash
openspec instructions proposal --change "<name>" --json
```
然后将内容写入 `openspec/changes/<name>/proposal.md`。

```
Proposal 已保存。这是您的"为什么"文档——随着理解的演进，您随时可以回来完善它。

下一步：specs。
```

---

## 第六阶段：Specs

**讲解：**
```
## Specs

Spec 以精确、可测试的方式定义**我们在构建什么**。它们使用需求/场景格式，使预期行为一目了然。

对于像这样的小任务，我们可能只需要一个 spec 文件。
```

**执行：** 创建 spec 文件：
```bash
# Unix/macOS
mkdir -p openspec/changes/<name>/specs/<capability-name>
# Windows (PowerShell)
# New-Item -ItemType Directory -Force -Path "openspec/changes/<name>/specs/<capability-name>"
```

起草 spec 内容：

```
这是 spec：

---

## ADDED Requirements

### Requirement: <名称>

<系统应做什么的描述>

#### Scenario: <场景名称>

- **WHEN** <触发条件>
- **THEN** <预期结果>
- **AND** <额外结果（如需要）>

---

这种格式——WHEN/THEN/AND——使需求可测试。您可以直接将它们读作测试用例。
```

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

---

## 第七阶段：Design

**讲解：**
```
## Design

Design 记录**我们如何构建它**——技术决策、权衡、方案。

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

**执行：** 起草 design.md：

```
这是设计：

---

## Context（背景）

[关于当前状态的简短背景]

## Goals / Non-Goals（目标/非目标）

**目标：**
- [我们试图实现什么]

**非目标：**
- [明确排除在外的内容]

## Decisions（决策）

### 决策 1：[关键决策]

[方案说明和理由]

---

对于小任务，这记录了关键决策，而不过度设计。
```

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

---

## 第八阶段：Tasks

**讲解：**
```
## Tasks

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

这些应该小、清晰，并按逻辑顺序排列。
```

**执行：** 根据 spec 和 design 生成任务：

```
这是实现任务：

---

## 1. [类别或文件]

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

## 2. 验证

- [ ] 2.1 [验证步骤]

---

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

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

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

---

## 第九阶段：应用（实现）

**讲解：**
```
## 实现

现在我们逐个实现任务，完成时打勾。我会声明每一个，偶尔说明 spec/design 如何指导了这个方案。
```

**执行：** 对每个任务：

1. 声明："正在处理任务 N：[描述]"
2. 在代码库中实现更改
3. 自然地引用 spec/design："Spec 说 X，所以我做 Y"
4. 在 tasks.md 中标记完成：`- [ ]` → `- [x]`
5. 简短状态："✓ 任务 N 完成"

保持叙述简洁——不要对每行代码过度解释。

所有任务完成后：

```
## 实现完成

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

变更已实现！还有最后一步——让我们归档它。
```

---

## 第十阶段：归档

**讲解：**
```
## 归档

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

归档的变更成为项目的决策历史——您随时可以找到它们，了解某些东西为什么以特定方式构建。
```

**执行：**
```bash
openspec archive "<name>"
```

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

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

---

## 第十一阶段：回顾与下一步

```
## 恭喜！

您刚刚完成了一个完整的 OpenSpec 循环：

1. **探索** - 思考了问题
2. **New** - 创建了变更容器
3. **Proposal** - 记录了为什么（WHY）
4. **Specs** - 详细定义了做什么（WHAT）
5. **Design** - 决定了如何做（HOW）
6. **Tasks** - 分解成了步骤
7. **Apply** - 实现了工作
8. **Archive** - 保存了记录

这个节奏适用于任何规模的变更——小修复或大功能。

---

## 命令参考

**核心工作流：**

| 命令 | 作用 |
|---------|--------------|
| `/opsx:propose` | 创建变更并生成所有 artifact |
| `/opsx:explore` | 在工作前/中思考问题 |
| `/opsx:apply` | 实现变更中的任务 |
| `/opsx:archive` | 完成后归档变更 |

**其他命令：**

| 命令 | 作用 |
|---------|--------------|
| `/opsx:new` | 启动新变更，逐步完成 artifact |
| `/opsx:continue` | 继续现有变更 |
| `/opsx:ff` | 快进：一次创建所有 artifact |
| `/opsx:verify` | 验证实现是否匹配 artifact |

---

## 下一步？

在您真正想构建的东西上试试 `/opsx:propose`。您已经掌握节奏了！
```

---

## 优雅退出处理

### 用户想要中途停止

若用户表示需要停止、想暂停或看起来不感兴趣：

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

稍后继续：
- `/opsx:continue <name>` - 继续创建 artifact
- `/opsx:apply <name>` - 直接跳到实现（若任务已存在）

工作不会丢失。准备好了随时回来。
```

优雅退出，不施加压力。

### 用户只想要命令参考

若用户表示只想查看命令或跳过教程：

```
## OpenSpec 快速参考

**核心工作流：**

| 命令 | 作用 |
|---------|--------------|
| `/opsx:propose <name>` | 创建变更并生成所有 artifact |
| `/opsx:explore` | 思考问题（不改代码） |
| `/opsx:apply <name>` | 实现任务 |
| `/opsx:archive <name>` | 完成后归档 |

**其他命令：**

| 命令 | 作用 |
|---------|--------------|
| `/opsx:new <name>` | 启动新变更，逐步操作 |
| `/opsx:continue <name>` | 继续现有变更 |
| `/opsx:ff <name>` | 快进：一次完成所有 artifact |
| `/opsx:verify <name>` | 验证实现 |

用 `/opsx:propose` 开始您的第一个变更。
```

优雅退出。

---

## 注意事项

- **遵循「讲解 → 执行 → 展示 → 暂停」模式**，在关键过渡点（探索后、proposal 草稿后、任务后、归档后）
- **保持叙述简洁**——在实现时教学，不说教
- **不要跳过阶段**，即使变更很小——目标是教授工作流
- **在标记点等待确认**，但不要过度暂停
- **优雅处理退出**——不要施压让用户继续
- **使用真实代码库任务**——不要模拟或使用假例子
- **温和地调整范围**——引导向较小的任务，但尊重用户选择