该技能用于从现有代码中创建 OpenSpec 规格,为已经上线但从未被 OpenSpec 记录的行为补写基线 spec。
用途:OpenSpec 变更只能 MODIFY 或 REMOVE 已存在于 openspec/specs/ 中的需求。团队采用 OpenSpec 之前构建的行为没有 spec,后续每次改动都会以 ADDED 方式落入,导致规格遗忘原有行为。本技能为已交付行为编写主 spec,即如果该功能当初用 OpenSpec 构建、最终会被归档的那份规格:已实现且已验证的意图,每句话都能与代码对上,每条需求都出自人的本意。
主要能力:
- 检查前置条件:运行 openspec --version,定位含 config.yaml 的 openspec/ 根目录(若配置指向 store,则 spec 位于 store 中),读取 config.yaml 的 context 决定规格语言,缺失时用英文。
- 界定能力边界:能力是以业务概念命名的 kebab-case 文件夹(如 checkout、order-management),不按类、表或目录命名;运行 openspec list --specs 判断是新建还是扩展现有 spec;若涉及区域无共同业务概念则建议拆分;对用户即将进行的变更,列出其会触及的现有行为并与用户确认范围;检查活跃变更中是否已有该能力的 delta,若有则警告扩展主 spec 可能破坏该变更的归档并询问是否继续。
- 收集证据:阅读 resources/evidence-guidelines.md 并按其描述派发子代理探索,技能自身负责交叉核对报告而非直接阅读代码库。
- 分类:将候选行为归入证据指南中的四种情形,对模糊候选一次性向用户集中询问。
- 编写规格:阅读 resources/spec-format.md,仅写入意图明确且已验证的行为;扩展既有 spec 时只新增需求与场景,原有内容原样保留;代码与既有需求矛盾属于漂移,写入报告,修改它属于 OpenSpec 变更的职责。
- 校验:对每个 spec 运行 openspec validate <capability> --type spec --strict,修复所有错误与警告后重跑。
- 报告与收尾:按顺序报告写入或扩展的 spec 及其能力 id、范围决策(拆分、扩展、排除项及原因)、被排除的候选及其情形与证据、既有需求与代码间的漂移;不转述 spec 内容,文件即交付物。随后按本次事实给出后续步骤:始终提示审阅 spec 路径并用 /codely-git-conventional-commit 提交;若输入是用户即将进行的变更,提示用 /openspec-explore 继续;若有被排除的缺陷,每个缺陷给出一条可直接粘贴的命令,内联证据。
使用方式:以自由文本作为参数,可为空(或询问哪些功能缺少 spec,此时先构建清单并等待用户选择)、一个能力名、一个用户即将进行的变更、或一个路径/界面。技能按检查前提、界定范围、收集证据、分类、编写、校验、报告七步执行。
适用场景:为存量功能补写基线 spec;为即将进行的变更梳理将被触及的现有行为;从路径或界面反推其服务的业务概念;识别无 spec 的功能。
限制:仅可写入 openspec/specs/,变更、config.yaml 与代码保持不动;spec 不代为提交,须等用户审阅后再提交;缺少 OpenSpec CLI 时须停止并请用户安装;证据收集依赖 resources/evidence-guidelines.md 与 resources/spec-format.md 等资源文件;不编造未经验证的行为。