Menu
OpenSpec 引导式入门 - 通过讲解与在真实代码库中动手，走完一个完整的工作流周期。
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/studyzy/imewlconverter --skill openspec-onboardThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
Based on SOC occupation classification
| name | openspec-onboard |
| description | OpenSpec 引导式入门 - 通过讲解与在真实代码库中动手，走完一个完整的工作流周期。 |
| license | MIT |
| compatibility | 需要 openspec CLI。 |
| metadata | {"author":"openspec","version":"1.0","generatedBy":"1.1.1-1"} |
引导用户完成他们的第一个完整OpenSpec工作流周期。这是一个教学体验——你将在他们的代码库中完成实际工作，同时解释每个步骤。
开始前，检查OpenSpec是否已初始化：
openspec-cn status --json 2>&1 || echo "NOT_INITIALIZED"
如果未初始化：
OpenSpec尚未在此项目中设置。请先运行
openspec-cn init，然后返回/opsx:onboard。
如果未初始化，请在此停止。
显示：
## 欢迎使用OpenSpec！
我将引导您完成一个完整的变更周期——从想法到实现——使用您代码库中的真实任务。在此过程中，您将通过实践学习工作流程。
**我们将要做的事情：**
1. 在您的代码库中选择一个小的真实任务
2. 简要探索问题
3. 创建一个变更（我们工作的容器）
4. 构建产出物：提案 → 规格说明 → 设计 → 任务
5. 实现任务
6. 归档完成的变更
**时间：** ~15-20分钟
让我们开始寻找要处理的内容。
扫描代码库寻找小的改进机会。寻找：
TODO、FIXME、HACK、XXXcatch 块，没有try-catch的风险操作src/ 和测试目录any 类型（: any、as any）console.log、console.debug、debugger 语句同时检查最近的git活动：
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. **无论如何都做** - 如果您真的想处理这个，我们可以做。只是要知道需要更长时间。
您更喜欢哪种？
如果用户坚持，让他们覆盖——这是一个软护栏。
一旦选择了任务，简要演示探索模式：
在我们创建变更之前，让我快速向您展示**探索模式**——这是在承诺方向之前思考问题的方式。
花1-2分钟调查相关代码：
## 快速探索
[您的简要分析——您发现了什么，任何考虑事项]
┌─────────────────────────────────────────┐
│ [可选：如果有帮助的ASCII图表] │
└─────────────────────────────────────────┘
探索模式（`/opsx:explore`）用于这种思考——在实现之前进行调查。您可以在需要思考问题时随时使用它。
现在让我们创建一个变更来保存我们的工作。
暂停 - 等待用户确认后再继续。
解释：
## 创建变更
OpenSpec中的"变更"是围绕一项工作的所有思考和规划的容器。它位于 `openspec/changes/<name>/` 中，保存您的产出物——提案、规格说明、设计、任务。
让我为我们的任务创建一个。
执行： 使用派生的kebab-case名称创建变更：
openspec-cn new change "<derived-name>"
显示：
已创建：`openspec/changes/<name>/`
文件夹结构：
openspec/changes// ├── proposal.md ← 为什么我们要做这个（空，我们将填充它） ├── design.md ← 我们将如何构建它（空） ├── specs/ ← 详细需求（空） └── tasks.md ← 实现检查清单（空）
现在让我们填充第一个产出物——提案。
解释：
## 提案
提案捕获**为什么**我们要进行此变更以及**什么**在高层级上涉及。这是工作的"电梯演讲"。
我将根据我们的任务起草一个。
执行： 起草提案内容（暂时不保存）：
这是一个草案提案：
---
## 为什么
[1-2句话解释问题/机会]
## 什么变化
[将要不同的要点]
## 能力
### 新能力
- `<能力名称>`: [简要描述]
### 修改的能力
<!-- 如果修改现有行为 -->
## 影响
- `src/path/to/file.ts`: [什么变化]
- [其他文件如果适用]
---
这能捕捉意图吗？我可以在保存前调整。
暂停 - 等待用户批准/反馈。
批准后，保存提案：
openspec-cn instructions proposal --change "<name>" --json
然后将内容写入 openspec/changes/<name>/proposal.md。
提案已保存。这是您的"为什么"文档——您随时可以回来在理解发展时完善它。
接下来：规格说明。
解释：
## 规格说明
规格说明以精确、可测试的术语定义**什么**我们正在构建。它们使用需求/场景格式，使预期行为清晰明了。
对于像这样的小任务，我们可能只需要一个规格说明文件。
执行： 创建规格说明文件：
mkdir -p openspec/changes/<name>/specs/<capability-name>
起草规格说明内容：
这是规格说明：
---
## 新增需求
### 需求：<名称>
<系统应该做什么的描述>
#### 场景：<场景名称>
- **当** <触发条件>
- **那么** <预期结果>
- **并且** <如果需要额外结果>
---
这种格式——当/那么/并且——使需求可测试。您可以将它们字面地读作测试用例。
保存到 openspec/changes/<name>/specs/<capability>/spec.md。
解释：
## 设计
设计捕获**如何**我们将构建它——技术决策、权衡、方法。
对于小变更，这可能很简短。没关系——不是每个变更都需要深入的设计讨论。
执行： 起草design.md：
这是设计：
---
## 上下文
[关于当前状态的简要上下文]
## 目标/非目标
**目标：**
- [我们试图实现什么]
**非目标：**
- [明确超出范围的内容]
## 决策
### 决策1：[关键决策]
[方法解释和理由]
---
对于小任务，这捕获了关键决策而不过度工程化。
保存到 openspec/changes/<name>/design.md。
解释：
## 任务
最后，我们将工作分解为实现任务——驱动应用阶段的复选框。
这些应该小、清晰且逻辑顺序。
执行： 基于规格说明和设计生成任务：
这是实现任务：
---
## 1. [类别或文件]
- [ ] 1.1 [具体任务]
- [ ] 1.2 [具体任务]
## 2. 验证
- [ ] 2.1 [验证步骤]
---
每个复选框成为应用阶段的工作单元。准备好实现了吗？
暂停 - 等待用户确认他们准备好实现。
保存到 openspec/changes/<name>/tasks.md。
解释：
## 实现
现在我们实现每个任务，在过程中勾选它们。我将宣布每个任务，并偶尔注意规格说明/设计如何影响方法。
执行： 对于每个任务：
- [ ] → - [x]保持叙述轻量——不要过度解释每一行代码。
所有任务后：
## 实现完成
所有任务完成：
- [x] 任务1
- [x] 任务2
- [x] ...
变更已实现！还有一个步骤——让我们归档它。
解释：
## 归档
当变更完成时，我们归档它。这将把它从 `openspec/changes/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。
归档的变更成为您项目的决策历史——您随时可以找到它们来理解为什么某物以某种方式构建。
执行：
openspec-cn archive "<name>"
显示：
已归档到：`openspec/changes/archive/YYYY-MM-DD-<name>/`
变更现在是您项目历史的一部分。代码在您的代码库中，决策记录被保留。
## 恭喜！
您刚刚完成了一个完整的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` 如果您想快速移动。
优雅退出。