speckit-specify

speckit-specify

本技能内容源自 GitHub Spec Kit 官方提示词模板。

• 上游：https://github.com/github/spec-kit
• 许可：MIT License, Copyright GitHub, Inc.（完整文本见同目录 LICENSE.txt）
• 适配说明：官方模板面向斜杠命令场景；原文中的 $ARGUMENTS 指用户在对话中给出的请求， 跨命令引用（如 speckit.plan）在本技能体系中对应同名的 speckit-* 技能。 其余内容保持与上游一致，未作改写。

---

用户输入

$ARGUMENTS

如果用户输入不为空，你必须先考虑用户输入，再继续执行。

执行前检查

检查扩展钩子（生成规格说明前）：

• 检查项目根目录中是否存在 .specify/extensions.yml。
• 如果存在，读取文件并查找 hooks.before_specify 键下的条目
• 如果 YAML 无法解析或无效，不要悄悄跳过：告知用户 .specify/extensions.yml 无法读取（包含解析器错误），且未检查任何钩子，包括在那里注册的任何必需钩子（optional: false），然后正常继续
• 筛除 enabled 明确设置为 false 的钩子。未设置 enabled 字段的钩子默认视为已启用。
• 对剩余的每个钩子，不要尝试解读或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或其值为 null/空，则视为可执行
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现处理
• 对每个可执行钩子，根据其 optional 标志输出以下内容：
  • 可选钩子（optional: true）：

    ## 扩展钩子
    
    **可选前置钩子**：{extension}
    命令：`/{command}`
    描述：{description}
    
    提示词：{prompt}
    执行方式：`/{command}`
    

  • 必需钩子（optional: false）：

    ## 扩展钩子
    
    **自动前置钩子**：{extension}
    正在执行：`/{command}`
    EXECUTE_COMMAND: {command}
    
    继续到大纲之前，等待钩子命令的结果。
    

    输出上述代码块后，你必须实际调用该钩子，并等待其执行完毕后才能继续。调用方式与在当前 Agent/会话中自行运行命令的方式相同（实际调用方式可能与上方显示的字面 {command} 标识不同，例如，技能模式的 Agent 会运行 /skill:speckit-... 或 $speckit-...）。仅输出代码块并不代表运行了钩子。
• 如果未注册钩子，或 .specify/extensions.yml 不存在，则静默跳过

大纲

触发消息中 __SPECKIT_COMMAND_SPECIFY__ 之后用户输入的文本就是功能描述。即使下方字面出现 {ARGS}，也应假定本次对话中始终可以获取该描述。除非用户提供了空命令，否则不要要求用户重复提供。

根据该功能描述，执行以下操作：

1. 生成简洁的短名称（2-4 个词）：

   • 分析功能描述，提取最有意义的关键词
   • 创建一个能概括核心内容的 2-4 词短名称
   • 尽可能采用“动作-名词”格式（例如，“add-user-auth”“fix-payment-bug”）
   • 保留技术术语和缩写（OAuth2、API、JWT 等）
   • 名称应简洁明了，同时足以让人一眼理解
   • 示例：
     • “我想添加用户身份验证” → “user-auth”
     • “为 API 实现 OAuth2 集成” → “oauth2-api-integration”
     • “创建分析仪表板” → “analytics-dashboard”
     • “修复支付处理超时错误” → “fix-payment-timeout”

2. 创建分支（可选，通过钩子实现）：

   如果上方执行前检查中的 before_specify 钩子成功运行，它将创建/切换到一个 git 分支，并输出包含 BRANCH_NAME 和 FEATURE_NUM 的 JSON。记录这些值以供参考，但分支名称不决定规格说明目录名称。

   如果用户明确提供了 GIT_BRANCH_NAME，请将其传递给钩子，以便分支脚本将该值原样用作分支名称（绕过所有前缀/后缀生成）。

3. 创建规格功能目录：

   除非用户明确提供 SPECIFY_FEATURE_DIRECTORY，否则规格文件存放在默认的 specs/ 目录下。

   SPECIFY_FEATURE_DIRECTORY 的解析顺序：

   1. 如果用户明确提供了 SPECIFY_FEATURE_DIRECTORY（例如，通过环境变量、参数或配置），则按原样使用
   2. 否则，在 specs/ 下自动生成：
      • 检查 .specify/init-options.json 中的 feature_numbering（优先）或 branch_numbering（已弃用，仅用于迁移，未来版本中将移除）
      • 如果值为 "timestamp"：前缀为 YYYYMMDD-HHMMSS（当前时间戳）
      • 如果值为 "sequential" 或未设置：前缀为 NNN（扫描 specs/ 中已有目录后，使用下一个可用的 3 位数字）
      • 构造目录名称：<prefix>-<short-name>（例如，003-user-auth 或 20260319-143022-user-auth）
      • 将 SPECIFY_FEATURE_DIRECTORY 设置为 specs/<directory-name>
      • 如果使用了 branch_numbering（且未设置 feature_numbering），则输出一行警告："⚠️ branch_numbering in init-options.json is deprecated. Rename to feature_numbering."

   创建目录和规格文件：

   • mkdir -p SPECIFY_FEATURE_DIRECTORY
   • 通过 Spec Kit 预设／模板解析流程解析当前启用的 spec-template（等同于 specify preset resolve spec-template）
   • 将解析得到的 spec-template 文件复制到 SPECIFY_FEATURE_DIRECTORY/spec.md，作为起始模板
   • 将 SPEC_FILE 设置为 SPECIFY_FEATURE_DIRECTORY/spec.md
   • 将解析后的路径写入 .specify/feature.json：

     {
       "feature_directory": "<resolved feature dir>"
     }
     

     写入实际解析出的目录路径值（例如，specs/003-user-auth），而不是字面字符串 SPECIFY_FEATURE_DIRECTORY。 这样，下游命令（__SPECKIT_COMMAND_PLAN__、__SPECKIT_COMMAND_TASKS__ 等）无需依赖 git 分支名称约定，即可定位功能目录。

   重要：

   • 每次调用 __SPECKIT_COMMAND_SPECIFY__ 时，只能创建一个功能
   • 规格目录名称与 git 分支名称相互独立——两者可以相同，但由用户决定
   • 规格目录和文件始终由此命令创建，不由钩子创建

4. 加载解析后当前启用的 spec-template 文件，了解必需的章节。

5. 如果存在：加载 /memory/constitution.md，了解项目原则和治理约束。

6. 按照以下执行流程操作：

   1. 从参数中解析用户描述 如果为空：错误 "No feature description provided"
   2. 从描述中提取关键概念 识别：参与者、操作、数据、约束
   3. 对于不明确的方面：
      • 根据上下文和行业标准作出合理推断
      • 仅在以下情况下标记为 [NEEDS CLARIFICATION: specific question]：
        • 该选择会显著影响功能范围或用户体验
        • 存在多种合理解释，且会产生不同影响
        • 没有合理的默认选项
      • 上限：总共最多 3 个 [NEEDS CLARIFICATION] 标记
      • 按影响程度优先处理待澄清事项：范围 > 安全／隐私 > 用户体验 > 技术细节
   4. 填写用户场景与测试章节 如果无法确定清晰的用户流程：错误 "Cannot determine user scenarios"
   5. 生成功能需求 每项需求都必须可测试 对未指定的细节采用合理的默认值（在假设章节中记录假设）
   6. 定义成功标准 制定可衡量且与技术无关的结果 同时包含定量指标（时间、性能、规模）和定性指标（用户满意度、任务完成情况） 每项标准都必须能够在不涉及实现细节的情况下进行验证
   7. 识别关键实体（如果涉及数据）
   8. 返回：SUCCESS（规格已准备好进行规划）

7. 使用模板结构将规格写入 SPEC_FILE，根据功能描述（参数）填写具体内容，同时保留各章节的顺序和标题。

8. 规格质量验证：编写初始规格后，根据质量标准进行验证：

   a. 创建规格质量检查清单：使用检查清单模板结构，在 SPECIFY_FEATURE_DIRECTORY/checklists/requirements.md 创建检查清单文件，包含以下验证项：

   # 规格质量检查清单：[FEATURE NAME]
   
   **目的**：在继续规划之前，验证规格的完整性和质量
   **创建日期**：[DATE]
   **功能**：[spec.md 链接]
   
   ## 内容质量
   
   - [ ] 不包含实现细节（语言、框架、API）
   - [ ] 聚焦于用户价值和业务需求
   - [ ] 面向非技术相关方编写
   - [ ] 所有必填章节均已完成
   
   ## 需求完整性
   
   - [ ] 不再包含 [NEEDS CLARIFICATION] 标记
   - [ ] 需求可测试且含义明确
   - [ ] 成功标准可衡量
   - [ ] 成功标准与技术无关（不包含实现细节）
   - [ ] 已定义所有验收场景
   - [ ] 已识别边缘情况
   - [ ] 范围界定清晰
   - [ ] 已识别依赖项和假设
   
   ## 功能就绪度
   
   - [ ] 所有功能需求均有明确的验收标准
   - [ ] 用户场景涵盖主要流程
   - [ ] 功能满足成功标准中定义的可衡量结果
   - [ ] 规格中未泄露任何实现细节
   
   ## 备注
   
   - 标记为未完成的项目需要在执行 `__SPECKIT_COMMAND_CLARIFY__` 或 `__SPECKIT_COMMAND_PLAN__` 前更新规格
   

   b. 运行验证检查：根据检查清单中的每一项审查规格：

   • 判断每项是通过还是未通过
   • 记录发现的具体问题（引用相关规格章节）

   c. 处理验证结果：

   • 如果所有项目均通过：将检查清单标记为已完成，并继续执行“强制性执行后钩子”部分

   • 如果有项目未通过（不包括 [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 表格格式正确：

        • 使用统一的间距，并对齐竖线
        • 每个单元格的内容两侧都应留有空格：| Content |，而不是 |Content|
        • 表头分隔行至少要有 3 个短横线：|--------|
        • 在 Markdown 预览中测试表格能否正确渲染

     5. 按顺序为问题编号（Q1、Q2、Q3，最多 3 个）

     6. 将所有问题一起列出，然后等待回复

     7. 等待用户回答所有问题（例如：“Q1：A，Q2：自定义 - [details]，Q3：B”）

     8. 更新规格说明，将每个 [NEEDS CLARIFICATION] 标记替换为用户选择或提供的答案

     9. 解决所有待澄清事项后，重新运行验证

   d. 更新检查清单：每次验证迭代后，更新检查清单文件，注明当前的通过/失败状态

执行后强制钩子

在向用户报告完成之前，必须完成本节。

检查项目根目录中是否存在 .specify/extensions.yml。

• 如果不存在，或 hooks.after_specify 下未注册任何钩子，则跳至完成报告。
• 如果存在，请读取该文件并查找 hooks.after_specify 键下的条目。
• 如果 YAML 无法解析或格式无效，不要默默跳过：告知用户无法读取 .specify/extensions.yml（包括解析器错误），且未检查任何钩子，包括其中注册的任何强制钩子（optional: false），然后继续撰写完成报告。
• 排除 enabled 明确设为 false 的钩子。未设置 enabled 字段的钩子默认视为启用。
• 对于其余钩子，不要尝试解读或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或其值为 null/空，则视为可执行
  • 如果钩子定义了非空的 condition，则跳过该钩子，将条件评估留给 HookExecutor 实现处理
• 对于每个可执行钩子，根据其 optional 标记输出以下内容：
  • 强制钩子（optional: false）——每个强制钩子都必须输出 EXECUTE_COMMAND:：

    ## 扩展钩子
    
    **自动钩子**：{extension}
    正在执行：`/{command}`
    EXECUTE_COMMAND: {command}
    

    输出上述代码块后，必须实际调用钩子并等待其完成，然后才能继续。调用方式应与在此 Agent/会话中自行运行命令的方式相同（实际调用方式可能与上面显示的字面量 {command} ID 不同，例如，skills 模式的 Agent 会运行 /skill:speckit-... 或 $speckit-...）。仅输出代码块并不会运行钩子。
  • 可选钩子（optional: true）：

    ## 扩展钩子
    
    **可选钩子**：{extension}
    命令：`/{command}`
    描述：{description}
    
    提示词：{prompt}
    执行方式：`/{command}`
    

完成报告

向用户报告完成情况，包括：

• SPECIFY_FEATURE_DIRECTORY——功能目录路径
• SPEC_FILE——规格说明文件路径
• 检查清单结果摘要
• 下一阶段的准备情况（__SPECKIT_COMMAND_CLARIFY__ 或 __SPECKIT_COMMAND_PLAN__）

**注意：**分支创建由 before_specify 钩子（git 扩展）处理。规格说明目录和文件始终由此核心命令创建。

快速指南

• 关注用户需要什么以及为什么。
• 避免描述如何实现（不涉及技术栈、API、代码结构）。
• 面向业务相关人员，而非开发人员。
• 不要在规格说明中创建内嵌的检查清单。这将由单独的命令处理。

章节要求

• 必需章节：每项功能都必须填写
• 可选章节：仅在与功能相关时添加
• 如果某个章节不适用，请将其完全删除（不要保留为“N/A”）

用于 AI 生成

根据用户提示创建此规范时：

1. 做出有依据的猜测：利用上下文、行业标准和常见模式填补空白
2. 记录假设：在“假设”部分记录合理的默认值
3. 限制澄清项：最多使用 3 个 [NEEDS CLARIFICATION] 标记；仅用于以下关键决策：
   • 对功能范围或用户体验有重大影响
   • 存在多种合理解释，且各自影响不同
   • 没有任何合理的默认值
4. 确定澄清优先级：范围 > 安全/隐私 > 用户体验 > 技术细节
5. 像测试人员一样思考：每项模糊需求都应无法通过“可测试且明确无歧义”检查项
6. 通常需要澄清的领域（仅在没有合理默认值时）：
   • 功能范围和边界（是否纳入或排除特定用例）
   • 用户类型和权限（存在多种相互冲突的合理解释时）
   • 安全/合规要求（可能造成重大法律/财务影响时）

合理默认值示例（无需询问）：

• 数据保留：采用该领域的行业标准做法
• 性能目标：未指定时，采用标准 Web/移动应用的预期
• 错误处理：提供对用户友好的消息和恰当的回退方案
• 身份验证方式：Web 应用采用标准的基于会话或 OAuth2 的方式
• 集成模式：采用适合项目的模式（Web 服务使用 REST/GraphQL，库使用函数调用，工具使用 CLI 参数等）

成功标准指南

成功标准必须：

1. 可衡量：包含具体指标（时间、百分比、数量、比率）
2. 与技术无关：不得提及框架、语言、数据库或工具
3. 以用户为中心：描述用户/业务层面的结果，而非系统内部情况
4. 可验证：无需了解实现细节即可测试/验证

良好示例：

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

不良示例（以实现为重点）：

• “API 响应时间低于 200ms”（过于技术化，应改为“用户能立即看到结果”）
• “数据库可处理 1000 TPS”（实现细节，应改为面向用户的指标）
• “React 组件渲染效率高”（特定于框架）
• “Redis 缓存命中率高于 80%”（特定于技术）

完成条件

• 规范已写入 SPEC_FILE，并根据质量检查清单完成验证
• 已根据上述“强制执行后钩子”中的规则，触发或跳过扩展钩子
• 已向用户报告完成情况，包括功能目录、规范文件路径和检查清单结果