codely-openspec-spec-create-from-code

🧬 如何根据现有代码创建 OpenSpec 规范

OpenSpec 变更只能 MODIFY 或 REMOVE 已存在于 openspec/specs/ 中的需求。团队采用 OpenSpec 之前构建的行为没有规范，因此针对这些行为的每项变更都会被标记为 ADDED，规范也会忘记原有内容。这项技能用于补上缺失的基线：为已经发布的行为编写主规范。

基线是指如果某项功能当初是用 OpenSpec 构建的，OpenSpec 会归档的那份规范：已经实现并验证的意图。每句话都必须符合代码现状，每项需求也都必须是有人有意为之的。美化代码现状的基线还不如没有，因为下一份提案会以它为基础。

📥 输入

参数可以是自由文本。将其理解为以下类型之一：

输入	示例	范围
无输入，或询问哪些内容缺少规范	which features have no spec?	resources/evidence-guidelines.md 中的清单。生成清单后停止，等待用户选择一项。
一项功能	checkout	该功能。
用户即将进行的变更	add discount coupons to checkout	该变更会涉及的当前行为。新行为属于变更本身，而非基线。
路径或界面	src/app/admin/orders	该路径所服务的业务概念，并从路径追溯回去。

🪜 步骤

1. 检查前置条件

• 运行 openspec --version。如果缺少 CLI，请停止并让用户安装。
• 找到 OpenSpec 根目录：包含 config.yaml 的 openspec/ 文件夹。如果配置指向某个存储位置，规范就位于该存储位置。
• 阅读 config.yaml 中的 context:。它指定规范的语言；如果没有该字段，则用英文编写规范。

完成条件：CLI 能正常响应，并且你知道规范应写入哪个文件夹。

2. 界定功能范围

• 一项功能对应 openspec/specs/ 下的一个文件夹，以 kebab-case 命名，名称取自业务概念（checkout、order-management），绝不能取自类、表或文件夹名称。
• 运行 openspec list --specs。如果现有规范已经涵盖部分行为，就扩展该规范。
• 如果涉及的领域没有共同的业务概念，则它们属于多项功能：向用户提出拆分方案。
• 对于用户即将进行的变更，列出该变更会涉及的现有行为，并向用户确认范围。
• 运行 openspec list，并在每项活跃变更中查找 openspec/changes/<change>/specs/<capability>/。如果某项活跃变更包含该功能的差异规范，请提醒用户扩展主规范可能会破坏该变更的归档，并询问是否继续。

完成条件：用户已确认每项功能，以及它是新建还是扩展。

3. 收集证据

阅读 resources/evidence-guidelines.md，并分派其中描述的子 Agent。将代码探索工作委派出去：你的任务是交叉核对报告，而不是阅读整个代码库。

完成条件：每项功能的每个领域都有报告，且报告中的每个候选行为都附有证据。

4. 分类

将每个候选行为归入 resources/evidence-guidelines.md 中的四种情况之一。然后按照该文件的说明，在一轮中询问用户所有模糊不清的候选行为。如果有提问工具，请使用它向用户提问。

完成条件：每个候选行为都有分类，且每个模糊不清的候选行为都有用户的判定。

5. 编写规格

阅读 resources/spec-format.md，并编写 openspec/specs/<capability>/spec.md，只记录预期且已验证的行为。

扩展现有规格时，添加需求和场景，并确保每一条现有内容都保持原样。若代码与现有需求矛盾，则该需求属于偏差：将其列入报告，修改需求则应通过 OpenSpec 变更完成。

完成标准：每个预期且已验证的候选项都已作为需求或场景写入规格。

6. 验证

对你编写的每个规格运行 openspec validate <capability> --type spec --strict，修复所有错误和警告，然后重新运行。

完成标准：每个规格都通过严格验证。

7. 报告并结束

使用用户所用的语言作答，并按以下顺序报告：

1. 编写或扩展的规格，以及各自的 capability id。
2. 范围决策：拆分、扩展、未纳入范围的内容及其原因。
3. 未纳入规格的候选项，并逐项说明其案例和证据。
4. 现有需求与代码之间的偏差。

不要转述规格内容：文件就是交付物。最后，按以下顺序给出本次运行实际需要的后续步骤，并使用用户所用的语言翻译：

• 始终进行审查：

  Review <spec paths>: they come from the code, and from now on agents will treat them as the truth. Once you agree with them, commit them with `/codely-git-conventional-commit`.
  

• 当输入是用户即将进行的变更时，提供返回该变更的方式：

  With the baseline ready, go on with your change: `/openspec-explore <the change, as the user described it>`
  

• 当你未将某个 bug 纳入规格时，每个 bug 提供一条可直接粘贴的命令，并在命令中附上证据：

  ⚠️ <n> inconsistencies left out of the spec. To fix one:
  - `/openspec-explore <the behaviour the intent asks for> fails when <the case that breaks> (<file:line>; <the test that covers it, or "no test covers it">)`
  

🧱 边界

• 仅在 openspec/specs/ 下写入。变更、config.yaml 和代码保持不变。
• 不要提交规格；应在用户审查后再提交。