SuperAPI AI 工具集

openspec-explore

编程与开发

查看项目

更新于 11-13 09:26

技能介绍

openspec-explore 是一个用于 OpenSpec 工作流的探索模式技能。它的核心定位是充当“思考伙伴”,帮助用户梳理想法、调查问题和澄清需求,而不是直接编写代码或实现功能。

用途与定位 该技能明确强调:探索模式只用于思考,不用于实现。它可以读取文件、搜索代码、调查代码库,但绝不写代码或实现功能。如果用户要求实现,技能会提醒先退出探索模式并创建变更提案。只有在用户要求时,才可以创建 OpenSpec 制品(提案、设计、规格),因为这属于“记录思考”而非实现。

工作姿态 技能强调这是一种姿态而非固定工作流:没有固定步骤、没有必需顺序、没有强制输出。它要求保持好奇而非规定式提问,开放多条线索而非审问式追问,多用 ASCII 图辅助澄清,跟随有趣线索灵活转向,保持耐心不急于结论,并在相关时深入实际代码库而非空谈理论。

主要能力 根据用户带来的内容,技能可能:探索问题空间、提出澄清问题、挑战假设、重新框定问题、寻找类比;调查代码库、梳理相关架构、发现集成点、识别已有模式、揭示隐藏复杂性;比较方案、头脑风暴多种路径、构建对比表、勾勒权衡、在被要求时推荐路线;识别风险与未知、发现理解缺口、建议技术验证(spike)。

OpenSpec 系统感知 技能对 OpenSpec 系统有完整上下文。开始时可用 openspec list --json 快速检查是否存在活跃变更及其名称、schema 和状态,并从解析出的根目录读取 openspec/config.yaml(或 config.yml)中的 context(项目背景、技术栈、约定、约束)和 rules(按制品 id 分类,仅在该制品写作时适用),将其作为约束遵循而非复述。

处理无变更的情况 当没有变更时,可自由思考;当洞察成熟时,可主动提议“这看起来可以开始一个变更了,要我创建提案吗?”,也可继续探索不急于形式化。若用户要求将探索记录为新变更,则先运行 openspec new change "<name>"(适用时加 --store <id>)进行脚手架创建,不可手动在 openspec/changes/ 下创建目录;随后运行 openspec status --change "<name>" --json,按依赖顺序处理请求的制品,并对每个就绪制品运行 openspec instructions "<artifact-id>" --change "<name>" --json。创建前需评估该制品指令中的条件是否适用于当前变更,不适用则记录为有意跳过。若请求的制品被用户未请求的直接前置制品阻塞,需为该前置制品运行指令命令,并根据其自身条件判断是否可跳过;不可跳过时需先询问再扩展采集范围。创建制品后需写入 resolvedOutputPath 并验证存在,然后重新运行 status 直至所有请求制品完成、跳过或有意跳过。依赖是使能者而非闸门。

处理已有变更的情况 当用户提及或检测到相关变更时,运行 openspec status --change "<name>" --json,使用返回的 changeRoot、artifactPaths 和 actionContext,并读取 artifactPaths.<artifact>.existingOutputPaths 中的现有文件,在对话中自然引用。当决策形成时,可提议捕获到相应位置:新需求或需求变更写入 specs/<capability-path>/spec.md,设计决策写入 design.md,范围变更写入 proposal.md,新识别的工作写入 tasks.md,假设失效则更新相关制品。用户决定是否采纳,技能只提议不施压、不自动捕获。

存储选择 若用户指定了某个 store(注册在本机上的独立 OpenSpec 仓库)或工作位于其中,需先运行 openspec store list --json 获取已注册的 store id,然后在读取或写入规格与变更的命令(new change、status、instructions、list、show、validate、archive、doctor、context、view)上追加 --store <id>,并在后续工作流中保持粘性。其他命令不接受该标志。未指定 store 时,命令作用于最近的本地 openspec/ 根目录。

适用场景示例 用户带来模糊想法(如“想加实时协作”)、具体问题(如“认证系统很乱”)、实现中卡住(如“OAuth 集成比预期复杂”)、方案对比(如“用 Postgres 还是 SQLite”)等情况时,技能会通过读代码、画图、梳理选项和权衡来辅助思考。

结束方式 没有必需的结束方式:可流入提案、更新制品、仅提供清晰结论、或稍后继续。当事情逐渐明朗时,可选择性地总结问题、方法、开放问题和下一步,但总结是可选的,有时思考本身就是价值。

限制与护栏 不实现:绝不写代码或实现功能,创建设计制品可以,写应用代码不行。不伪造理解:不清楚就深入挖掘。不催促:发现是思考时间。不强制结构:让模式自然浮现。不自动捕获:只提议保存洞察。不手动脚手架创建变更:始终使用 openspec new change "<name>"。鼓励可视化、探索代码库、质疑假设(包括用户和自身的)。