Communitygithub.com

功能规格说明生成器

根据自然语言描述创建或更新功能规格说明书。

功能规格说明生成器 是什么?

此技能用于根据用户的自然语言功能描述,自动生成结构化的功能规格说明书。它首先检查项目中的 `.specify/extensions.yml` 文件以运行前置钩子(例如创建Git分支),然后解析用户输入,提取关键概念(参与者、动作、数据、约束),并生成包含功能名称、需求、成功标准、用户场景、关键实体和假设的完整 `spec.md` 文件。它通过一个质量检查清单进行验证,确保规格说明书无实现细节、可测试且无二义性。如果存在待澄清项([NEEDS CLARIFICATION]),它会以问题表格的形式向用户提出,最多3个。最后执行后置钩子,并报告完成情况。该技能支持通过配置文件进行扩展,与平台无关,适用于任何需要通过自然语言驱动规格说明的开发流程。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/tangjuyo/reels-blocker/tree/HEAD/.claude/skills/speckit-specify

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

用户输入

$ARGUMENTS

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

前置执行检查

检查扩展钩子(规格说明前):

  • 检查项目根目录下是否存在 .specify/extensions.yml。
  • 如果存在,读取它并查找 hooks.before_specify 键下的条目。
  • 如果 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}
      
      在继续到大纲之前,等待钩子命令的结果。
      
      在发出上述代码块之后,你必须实际调用该钩子并等待其完成,然后再继续。以你在此代理/会话中运行该命令的相同方式运行它(调用方式可能不同于上面显示的文字 {command} ID,例如,技能模式代理将其运行为 /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. 创建规范功能目录:

    规范文件默认位于 specs/ 目录下,除非用户显式提供 SPECIFY_FEATURE_DIRECTORY。

    SPECIFY_FEATURE_DIRECTORY 的解析顺序:

    1. 如果用户显式提供了 SPECIFY_FEATURE_DIRECTORY(例如,通过环境变量、参数或配置),则直接使用。
    2. 否则,在 specs/ 下自动生成:
      • 检查 .specify/init-options.json 中的 feature_numbering(首选)或 branch_numbering(已弃用,仅用于迁移——将在未来版本中移除)。
      • 如果是 "timestamp":前缀为 YYYYMMDD-HHMMSS(当前时间戳)。
      • 如果是 "sequential" 或缺失:前缀为 NNN(扫描 specs/ 中现有目录后的下一个可用3位数字)。
      • 构建目录名称:<前缀>-<短名称>(例如,003-user-auth 或 20260319-143022-user-auth)。
      • 将 SPECIFY_FEATURE_DIRECTORY 设置为 specs/<目录名称>。
      • 如果使用了 branch_numbering(且 feature_numbering 不存在),则发出一行警告:“⚠️ init-options.json 中的 branch_numbering 已弃用。请重命名为 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": "<解析后的功能目录>"
      }
      
      写入实际解析的目录路径值(例如,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. 从参数中解析用户描述 如果为空:错误“未提供功能描述”
    2. 从描述中提取关键概念 识别:参与者、动作、数据、约束
    3. 对于不清楚的方面:
      • 根据上下文和行业标准做出有根据的猜测。
      • 仅在以下情况下使用 [NEEDS CLARIFICATION: specific question] 标记:
        • 该选择显著影响功能范围或用户体验。
        • 存在多个具有不同影响的合理解释。
        • 不存在合理的默认值。
      • 限制:总共最多 3 个 [NEEDS CLARIFICATION] 标记
      • 按影响程度排列待澄清项的优先级:范围 > 安全/隐私 > 用户体验 > 技术细节。
    4. 填写用户场景和测试部分 如果没有明确的用户流程:错误“无法确定用户场景”
    5. 生成功能需求 每个需求必须可测试。 对未指定的细节使用合理的默认值(在假设部分记录假设)。
    6. 定义成功标准 创建可衡量的、与技术无关的结果。 包括定量指标(时间、性能、数量)和定性指标(用户满意度、任务完成度)。 每个标准必须无需实现细节即可验证。
    7. 识别关键实体(如果涉及数据)
    8. 返回:成功(规范已准备好进行规划)
  7. 使用模板结构将规范写入 SPEC_FILE,用从功能描述(参数)中得出的具体细节替换占位符,同时保留各部分顺序和标题。

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

    a. 创建规范质量检查清单:在 SPECIFY_FEATURE_DIRECTORY/checklists/requirements.md 使用检查清单模板结构生成一个包含以下验证项的清单文件:

    # 规范质量检查清单:[功能名称]
    
    **目的**:在进入规划前验证规范的完整性和质量
    **创建日期**:[日期]
    **功能**:[指向 spec.md 的链接]
    
    ## 内容质量
    
    - [ ] 无实现细节(语言、框架、API)
    - [ ] 专注于用户价值和业务需求
    - [ ] 为非技术利益相关者编写
    - [ ] 所有必填部分已完成
    
    ## 需求完整性
    
    - [ ] 没有剩余的 [NEEDS CLARIFICATION] 标记
    - [ ] 需求可测试且无二义性
    - [ ] 成功标准可衡量
    - [ ] 成功标准与技术无关(无实现细节)
    - [ ] 所有验收场景都已定义
    - [ ] 识别出边缘情况
    - [ ] 范围已明确界定
    - [ ] 已识别依赖项和假设
    
    ## 功能就绪状态
    
    - [ ] 所有功能需求都有明确的验收标准
    - [ ] 用户场景覆盖主要流程
    - [ ] 功能满足成功标准中定义的可衡量结果
    - [ ] 无实现细节泄漏到规范中
    
    ## 备注
    
    - 标记为不完整的项目需要在 `/speckit-clarify` 或 `/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: Custom - [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 实现。
  • 在根据钩子命令名称构建命令调用时,将点号(.)替换为连字符(-)。例如,speckit.git.commit → /speckit-git-commit。
  • 对于每个可执行的钩子,根据其 optional 标志输出以下内容:
    • 强制钩子(optional: false) — 你必须为每个强制钩子发出 EXECUTE_COMMAND::
      ## 扩展钩子
      
      **自动钩子**:{extension}
      执行中:`
      

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

相关技能