speckit-specify

用户输入

$ARGUMENTS

继续之前，必须考虑用户输入（如果非空）。

执行前检查

检查扩展钩子（在规范编写之前）：

• 检查项目根目录中是否存在 .specify/extensions.yml。
• 如果存在，请读取文件，并查找 hooks.before_specify 键下的条目
• 如果无法解析 YAML 或 YAML 无效，请勿默默跳过：告知用户无法读取 .specify/extensions.yml（并附上解析器错误），且未检查任何钩子，包括其中注册的所有强制钩子（optional: false），然后正常继续
• 过滤掉 enabled 明确设为 false 的钩子。未设置 enabled 字段的钩子默认视为启用。
• 对于其余钩子，不要尝试解释或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或该字段为 null/空，则视为可执行
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现
• 根据钩子命令名称构建命令调用时，将点（.）替换为连字符（-）。例如，speckit.git.commit → /speckit-git-commit。
• 对于每个可执行钩子，根据其 optional 标志输出以下内容：

  • 可选钩子（optional: true）：

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

  • 强制钩子（optional: false）：

    ## 扩展钩子
    
    **自动前置钩子**：{extension}
    正在执行：`/{command}`
    EXECUTE_COMMAND: {command}
    
    等待钩子命令执行完毕后，再继续到大纲部分。
    

    输出上述内容块后，必须实际调用该钩子，并等待其完成后再继续。以与在此 Agent/会话中自行运行命令相同的方式运行它（调用方式可能不同于显示的 {command} ID，例如，技能模式的 Agent 会运行 /skill:speckit-... 或 $speckit-...）。仅输出内容块并不代表已运行钩子。

• 如果未注册钩子，或 .specify/extensions.yml 不存在，则静默跳过

大纲

触发消息中用户在 /speckit-specify 后输入的文本就是功能描述。即使 $ARGUMENTS 在下文中按字面出现，也应假设你在本次对话中始终可以获取该功能描述。除非用户提供的是空命令，否则不要要求用户重复输入。

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

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-plan、/speckit-tasks 等）就能找到功能目录，而无需依赖 git 分支名称约定。

   重要：

   • 每次调用 /speckit-specify 只能创建一个功能
   • 规范目录名称和 git 分支名称彼此独立——两者可以相同，但由用户决定
   • 规范目录和文件始终由此命令创建，而不是由钩子创建

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

5. 如果存在：加载 .specify/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 创建检查清单文件，并包含以下验证项：

   # Specification Quality Checklist: [FEATURE NAME]
   
   **Purpose**: Validate specification completeness and quality before proceeding to planning
   **Created**: [DATE]
   **Feature**: [Link to spec.md]
   
   ## Content Quality
   
   - [ ] No implementation details (languages, frameworks, APIs)
   - [ ] Focused on user value and business needs
   - [ ] Written for non-technical stakeholders
   - [ ] All mandatory sections completed
   
   ## Requirement Completeness
   
   - [ ] No [NEEDS CLARIFICATION] markers remain
   - [ ] Requirements are testable and unambiguous
   - [ ] Success criteria are measurable
   - [ ] Success criteria are technology-agnostic (no implementation details)
   - [ ] All acceptance scenarios are defined
   - [ ] Edge cases are identified
   - [ ] Scope is clearly bounded
   - [ ] Dependencies and assumptions identified
   
   ## Feature Readiness
   
   - [ ] All functional requirements have clear acceptance criteria
   - [ ] User scenarios cover primary flows
   - [ ] Feature meets measurable outcomes defined in Success Criteria
   - [ ] No implementation details leak into specification
   
   ## Notes
   
   - Items marked incomplete require spec updates before `/speckit-clarify` or `/speckit-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 表格格式正确：

        • 使用一致的空格，并对齐竖线
        • 每个单元格的内容两侧都应有空格：| 内容 |，而不是 |内容|
        • 表头分隔行至少包含 3 个短横线：|--------|
        • 检查表格在 Markdown 预览中是否能正确显示

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

     6. 一次性提出所有问题，然后等待回复

     7. 等待用户回答所有问题（例如：“Q1: A, Q2: 自定义 - [详情], 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 实现
• 根据钩子命令名称构造命令调用时，将点号（.）替换为连字符（-）。例如，speckit.git.commit → /speckit-git-commit。
• 对每个可执行钩子，根据其 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-clarify 或 /speckit-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，并根据质量检查清单完成验证
• 已根据上述“强制执行后钩子”中的规则，触发或跳过扩展钩子
• 已向用户报告完成情况，包括功能目录、规范文件路径和检查清单结果