specify

specify

本技能对应 /specify 命令, 下文基本为原命令说明的原文, 仅作为技能文档直接复用, 不对内容做额外改写或拆分。

用户输入

$ARGUMENTS

在继续之前, 你必须考虑用户输入(如果不为空).

概述

用户在触发消息中 /specify 后输入的文本就是 业务意图. 假设你始终可以在本次对话中访问它, 即使下面字面上显示 $ARGUMENTS. 除非用户提供了空命令, 否则不要要求用户重复.

基于该 业务意图, 执行以下操作:

注意: 此命令会自动执行上下文收集和规范生成的完整流程. 它会扫描反构文档、计算关联度、构建关联关系图、进行架构分析, 生成上下文中间态文件, 然后基于上下文生成功能规范.

0. 开始执行步骤之前，先创建本次执行的 TodoList（用于过程可视化与完成确认）：
   • 步骤0：记录 start_time
   • 步骤1：调用 create-branch
   • 步骤1.1：分支安全检查
   • 步骤2：获取文档目录配置
   • 步骤3：执行需求波及分析并写入 context.md
   • 步骤4：加载上下文
   • 步骤5：按流程生成需求/场景等内容
   • 步骤6：写入 SPEC_FILE
   • 步骤7：执行（或跳过）E2E 测试分析与设计
   • 步骤8：执行规范质量验证
   • 步骤9：执行 AI 质量评测
   • 步骤10：输出完成报告
   • 步骤11：记录运行日志信息
   • 强制要求：每执行完一个步骤，必须立即将对应 Todo 项标记为已完成，不得在全部结束后一次性补勾选。

0.1 开始执行步骤之前，需要进行一些打点记录工作，记录本skill的执行时间到 start_time字段：

• 判断当前操作系统，windows还是linux系统;
• 针对不同操作系统运行脚本获取配置 windows: Get-Date -Format "yyyy-MM-dd HH:mm:ss" linux: date +"%Y-%m-%d %H:%M:%S"
• 将获取的时间记录到 start_time

1. 使用 create-branch skill，创建特性分支
   • 强制要求：create-branch 必须被完整调用并等待返回，不允许跳过、截断执行或使用本地推断结果替代其输出。
   • 强制要求：必须以 create-branch 返回的 BRANCH_NAME、FEATURE_DIR、SPEC_FILE 作为后续步骤的唯一基准。
   • 强制校验：FEATURE_DIR 必须位于仓库根目录 changes/ 下（即满足 {REPO_ROOT}/changes/<feature> 结构）。
   • 失败处理：若 FEATURE_DIR 不在 changes/ 下（例如落到 .infra/、specs/ 或其他路径），不得继续后续步骤；必须重走 create-branch 重新生成合法路径，直到通过校验后再继续。

1.1 分支安全检查（创建/复用后立即执行）：

• 读取 create-branch 输出的 BRANCH_NAME、FEATURE_DIR；
• 获取当前仓库已提交分支集合（本地 + 远端），用于比对：
  • 本地：git for-each-ref refs/heads --format='%(refname:short)'
  • 远端：git for-each-ref refs/remotes --format='%(refname:short)'
• 定义受保护分支（禁止用于 specify 承载实现）：
  • master、main、develop、dev
  • release/*、hotfix/*（按前缀匹配）
• 校验规则：
  1. BRANCH_NAME 必须存在且非空；
  2. BRANCH_NAME 不得命中受保护分支集合；
  3. 若 BRANCH_NAME 在“已提交分支集合”中存在，允许复用同名特性分支，但仍必须满足规则2；
• 若任一校验失败：
  • 不直接终止；必须重走 create-branch 流程重新创建/选择特性分支；
  • 重试时禁止再次选择命中受保护分支集合的分支名；
  • 重试成功后，用新的 BRANCH_NAME、FEATURE_DIR 覆盖旧值并继续后续步骤；
  • 仅当连续重试仍无法得到安全分支时，才终止并输出中文错误（包含失败原因与建议分支命名）。

2. 获取文档目录配置:

   • 判断当前操作系统，windows还是linux系统;
   • 针对不同操作系统从仓库根目录运行脚本获取配置 windows:scripts/powershell/check-prerequisites.ps1 --json --paths-only linux:scripts/bash/check-prerequisites.sh --json --paths-only
   • 解析 JSON 输出获取 DOC_DIR 变量（如果未设置则默认为 "omni-doc"）
   • 重要: DOC_DIR 将用于后续所有文档路径引用，支持通过环境变量 SPECIFY_DOC_DIR 或 .infra/config 文件配置

3. 需求波及分析（使用 spec-impact-analyze技能）:

   • 将 spec-impact-analyze 返回的结构化内容写入 FEATURE_DIR/context.md

4. 加载上下文:

   • 读取 .infra/templates/spec-template.md 和 .infra/memory/constitution.md
   • 读取上下文文件:
     • 读取步骤3生成的 FEATURE_DIR/context.md 作为上下文参考
     • 如果上下文文件不存在（异常情况），可以基于 业务意图直接生成规范(不使用上下文)

5. 遵循此执行流程:

   1. 从输入解析 业务意图 如果为空: 错误 "未提供业务意图"
   2. 参考上下文文件 (FEATURE_DIR/context.md) 中的架构分析、可复用模式、术语对齐等信息
   3. 从 业务意图和上下文中提取关键概念，识别: 参与者、操作、数据、约束
   4. 对于不明确的方面:
      • 基于上下文和行业标准做出有根据的猜测
      • 仅在以下情况下标记为 [NEEDS CLARIFICATION: 具体问题]:
        • 选择显著影响功能范围或用户体验
        • 存在多个合理的解释且有不同的含义
        • 没有合理的默认值
      • 限制: 最多 3 个 [NEEDS CLARIFICATION] 标记
      • 按影响优先级排序: 范围 > 安全/隐私 > 用户体验 > 技术细节
      • 优先参考上下文文件中的约束和假设
   5. 调用 specify-requirement skill，获取需求变更内容，并追加到 FEATURE_DIR/spec.md 末尾
   6. 调用 specify-scenario skill，获取场景变更内容，并追加到 FEATURE_DIR/spec.md 末尾
   7. 定义成功标准 创建可衡量的、技术无关的结果 包括定量指标(时间、性能、数量)和定性措施(用户满意度、任务完成) 每个标准必须无需实现细节即可验证
   8. 识别关键实体(如果涉及数据) 参考上下文文件中的逻辑实体文档
   9. 返回: 成功(规范准备好进行规划)

6. 使用模板结构将规范写入 SPEC_FILE, 用 业务意图和上下文文件派生的具体细节替换占位符, 同时保持章节顺序和标题.

7. 执行测试分析与设计（仅当 $ENABLE_E2E=true 时执行）

   • 判断条件：检查传入的 $ENABLE_E2E 参数
     • 若 $ENABLE_E2E=true：执行本步骤
     • 若 $ENABLE_E2E=false 或未设置：跳过本步骤，直接进入步骤8
   • 强制要求：当执行时，测试分析与设计必须严格按照 e2e-specify 技能文件中定义的流程执行，不得跳过或修改任何步骤。
   • 执行测试分析与设计流程，包括：
     • 启动 e2e-specify skill
     • 传递规范文件和特性目录上下文
     • 使用 MFQ&PPDCS 方法论进行测试分析
     • 使用 TCON 四步法设计黑盒测试用例
     • 验证生成的测试分析报告和黑盒测试用例文档
   • 执行完本步骤后，将生成以下文档：
     • test-analysis.md：测试分析报告（包含 KYM、TCO、MFQ 建模、测试点清单、Issues）
     • e2e-test.md：黑盒测试用例文档（包含用例清单、用例详情、测试数据、追溯性矩阵）

   注意: 如果测试分析与设计验证失败且无法继续（如 agent 执行失败、文档未生成），应记录错误信息并继续执行步骤8（不阻塞整体流程）。

8. 规范质量验证: 编写初始规范后, 根据质量标准进行验证:

   a. 创建规范质量检查清单: 加载 .infra/templates/requirements-template.md获取 验证项目模版信息，使用 验证项目模版在 FEATURE_DIR/checklists/requirements.md 生成检查清单文件

   b. 运行验证检查: 根据每个检查清单项目审查规范:

   • 对于每个项目, 确定是否通过或失败
   • 记录发现的具体问题(引用相关规范章节)

   c. 处理验证结果:

   • 如果所有项目都通过: 标记检查清单完成并继续步骤 9

   • 如果项目失败(不包括 [NEEDS CLARIFICATION]):

     1. 列出失败的项目和具体问题
     2. 更新规范以解决每个问题
     3. 重新运行验证直到所有项目都通过(最多 3 次迭代)
     4. 如果 3 次迭代后仍然失败, 在检查清单备注中记录剩余问题并警告用户

   • 如果 [NEEDS CLARIFICATION] 标记仍然存在:

     1. 从规范中提取所有 [NEEDS CLARIFICATION: ...] 标记

     2. 限制检查: 如果存在超过 3 个标记, 仅保留 3 个最关键的(按范围/安全/用户体验影响)并为其余部分做出有根据的猜测

     3. 对于每个需要的澄清(最多 3 个), 以以下格式向用户呈现选项:

        ## 问题 [N]: [主题]
        
        **上下文**: [引用相关规范章节]
        
        **我们需要了解**: [来自 NEEDS CLARIFICATION 标记的具体问题]
        
        **建议答案**:
        
        | 选项   | 答案             | 含义                     |
        | ------ | ---------------- | ------------------------ |
        | A      | [第一个建议答案] | [这对功能意味着什么]     |
        | B      | [第二个建议答案] | [这对功能意味着什么]     |
        | C      | [第三个建议答案] | [这对功能意味着什么]     |
        | 自定义 | 提供你自己的答案 | [解释如何提供自定义输入] |
        
        **你的选择**: _[等待用户响应]_
        

     4. 关键 - 表格格式: 确保 markdown 表格格式正确:

        • 使用一致的间距, 管道符对齐
        • 每个单元格内容周围应有空格: | 内容 | 而不是 |内容|
        • 标题分隔符必须至少有 3 个破折号: |--------|
        • 测试表格在 markdown 预览中正确渲染

     5. 按顺序编号问题(Q1、Q2、Q3 - 最多 3 个)

     6. 在等待响应之前一起呈现所有问题

     7. 等待用户响应所有问题的选择(例如, "Q1: A, Q2: 自定义 - [详情], Q3: B")

     8. 通过用用户选择或提供的答案替换每个 [NEEDS CLARIFICATION] 标记来更新规范

     9. 在所有澄清解决后重新运行验证

   d. 更新检查清单: 每次验证迭代后, 使用当前的通过/失败状态更新检查清单文件

9. AI 质量评测: 加载 evaluation-rubric skill 的四维量规评测 SPEC_FILE：

   • Business Value / Technical Completeness / Clarity & Testability / Traceability（各 25 分）
   • 输出: FEATURE_DIR/.runs/evaluations/evaluation-report.yaml（stage: specify）
   • 通过标准: overall_score >= 95
   • 若不通过: 修复对应维度问题后重新评测（最多 2 轮，复用步骤8的迭代逻辑）

10. 报告完成情况

• 报告完成情况, 包括分支名称、上下文文件路径、规范文件路径、检查清单结果、AI 评测结果（score/status）以及下一阶段(/clarify 或 /design)的准备就绪状态.
• 如果步骤7（测试分析与设计）已执行：报告测试分析设计文档路径（test-analysis.md、e2e-test.md）
• 如果步骤7（测试分析与设计）已跳过（未启用 --e2e），应在报告中明确说明：
  • E2E测试分析与设计已跳过（未启用 --e2e）
  • 后续在 design 阶段也会相应跳过 e2e-design（因为缺少 e2e-test.md 依赖）
  • 如需测试设计，可重新执行 /specify --e2e 或在执行 design 前单独执行 e2e-specify

11. 记录本skill的运行日志信息：执行runlog-record skill，请将前面获取到的start_time的值作为参数传入runlog-record skill

注意:

• 上下文收集会在规范生成之前自动执行，生成 FEATURE_DIR/context.md 文件
• 规范生成会参考上下文文件中的架构分析、可复用模式、术语对齐等信息

通用指南

快速指南

• 专注于用户需要什么和为什么.
• 避免如何实现(不涉及技术栈、API、代码结构).
• 为业务利益相关者编写, 而不是为开发者.
• 不要创建嵌入规范中的任何检查清单. 那将是一个单独的命令.

章节要求

• 必需章节: 每个功能必须完成
• 可选章节: 仅在与功能相关时包含
• 当章节不适用时, 完全删除它(不要保留为 "N/A")

AI 生成

当从用户提示创建此规范时:

1. 做出有根据的猜测: 使用上下文、行业标准和常见模式来填补空白
2. 记录假设: 在假设章节中记录合理的默认值
3. 限制澄清: 最多 3 个 [NEEDS CLARIFICATION] 标记 - 仅用于关键决策:
   • 显著影响功能范围或用户体验
   • 存在多个合理的解释且有不同的含义
   • 缺乏任何合理的默认值
4. 优先澄清: 范围 > 安全/隐私 > 用户体验 > 技术细节
5. 像测试人员一样思考: 每个模糊的需求都应该在"可测试且明确"的检查清单项目上失败
6. NEEDS CLARIFICATION 的常见领域(仅在没有合理默认值时):
   • 功能范围和边界(包含/排除特定用例)
   • 用户类型和权限(如果可能存在多个冲突的解释)
   • 安全/合规要求(当具有法律/财务重要性时)

合理默认值的示例(不要询问这些):

• 数据保留: 该行业的行业标准实践
• 性能目标: 标准 Web/移动应用期望, 除非另有说明
• 错误处理: 用户友好的消息和适当的回退
• 认证方法: Web 应用的标准基于会话或 OAuth2
• 集成模式: RESTful API, 除非另有说明

成功标准指南

成功标准必须是:

1. 可衡量的: 包括具体指标(时间、百分比、计数、速率)
2. 技术无关的: 不提及框架、语言、数据库或工具
3. 以用户为中心的: 从用户/业务角度描述结果, 而不是系统内部
4. 可验证的: 无需了解实现细节即可测试/验证

好的示例:

• "用户可以在 3 分钟内完成结账"
• "系统支持 10,000 个并发用户"
• "95% 的搜索在 1 秒内返回结果"
• "任务完成率提高 40%"

坏的示例(以实现为中心):

• "API 响应时间在 200ms 以下"(太技术化, 使用"用户立即看到结果")
• "数据库可以处理 1000 TPS"(实现细节, 使用面向用户的指标)
• "React 组件高效渲染"(框架特定)
• "Redis 缓存命中率超过 80%"(技术特定)