SuperAPI AI 工具集

openspec-onboard

编程与开发

查看项目

更新于 10-19 16:19

技能介绍

用途

openspec-onboard 是一个面向 OpenSpec 新用户的引导式入门技能。它不是单纯讲解命令,而是在用户自己的代码库中完成一个真实的小型变更,通过“边做边学”帮助用户理解 OpenSpec 的完整工作流。官方说明将其定位为一次教学体验:在解释每个步骤的同时,在代码库中做实际工作。

主要能力

  • 预检:在开始前执行 openspec status --json 2>&1 || echo "NOT_INITIALIZED" 检查 OpenSpec 是否已初始化。若未初始化,会提示先运行 openspec init,然后停止引导。

  • 任务发现:扫描代码库寻找小型改进机会,包括 TODO/FIXME/HACK/XXX 注释、吞掉错误的 catch 块、缺少测试的函数、TypeScript 中的 : any/as any、非调试代码中的 console.log/console.debug/debugger、缺少输入校验的用户输入处理等;同时通过 git log --oneline -10 2>/dev/null || echo "No git history" 查看最近提交。

  • 候选建议:基于扫描结果给出 3-4 个具体任务建议,标明位置、范围和推荐理由;若未找到明显机会,则询问用户想添加或修复什么小功能。

  • 范围护栏:如果用户选择的任务过大(重大功能或多日工作),会软性建议切片变小、换一个任务,或尊重用户选择继续做大任务。

  • 探索演示:用 1-2 分钟阅读相关文件、绘制简单 ASCII 示意图、记录注意事项,演示 /opsx:explore 的“先想清楚再动手”模式。

  • 创建变更:使用 openspec new change "<derived-name>" 创建变更目录,并展示 openspec/changes/<name>/ 下 proposal.md、design.md、specs/、tasks.md 的结构。

  • 逐项构建工件:依次起草 proposal(为什么做、改什么、能力与影响)、specs(采用 Requirement + Scenario 的 WHEN/THEN/AND 可测试格式)、design(背景、目标/非目标、决策)、tasks(带复选框的实施清单)。每个关键节点会暂停等待用户确认或反馈。提案保存前会执行 openspec instructions proposal --change "<name>" --json。

  • 实施:按任务清单逐项实施,在代码库中真实修改,自然引用 specs/design 说明依据,并将 tasks.md 中对应复选框从 - [ ] 改为 - [x],保持轻量讲解。

  • 归档:执行 openspec archive "<name>",将变更移动到 openspec/changes/archive/YYYY-MM-DD-<name>/,保留为项目决策历史。

  • 收尾与命令参考:总结完整周期(Explore、New、Proposal、Specs、Design、Tasks、Apply、Archive),并提供 /opsx:explore、/opsx:new、/opsx:ff、/opsx:continue、/opsx:apply、/opsx:verify、/opsx:archive 的命令速查表。

  • 优雅退出:若用户中途想停止,会说明变更已保存在 openspec/changes/<name>/,之后可用 /opsx:continue <name> 继续创建工件,或用 /opsx:apply <name> 直接进入实施;若用户只想看命令,则直接给出速查表,不施压继续。

使用方式

该技能以引导流程运行,核心命令包括 openspec init、openspec status --json、openspec new change "<name>"、openspec instructions proposal --change "<name>" --json、openspec archive "<name>",以及 /opsx: 系列斜杠命令。流程遵循 EXPLAIN → DO → SHOW → PAUSE 的模式,在探索后、提案草稿后、任务清单后、归档后等关键转换点暂停等待确认,实施阶段保持轻量叙述,不跳过阶段,即便变更很小也完整走一遍以达成教学目的。

适用场景

适合刚接触 OpenSpec、希望用 15-20 分钟在真实代码库中体验从想法到实现完整周期的开发者;也适合团队新成员熟悉 OpenSpec 的工件结构与变更管理节奏。它强调使用真实代码库任务,不模拟或使用假例子。

限制

  • 项目必须已执行 openspec init,否则引导会停止。
  • 定位为入门教学,不替代完整文档;对大型任务仅提供软性范围建议。
  • 资料未提供具体收费、平台支持范围或与其他工具的集成细节,暂未提供。