Hooke / mlaj

Go to a project
Toggle navigation Toggle navigation pinning
Switch branch/tag
speckit.specify.md 11.6 KB 
description: 根据自然语言的功能描述创建或更新功能规格说明（spec）。
handoffs:
  - label: 生成技术计划
    agent: speckit.plan
    prompt: 为该 spec 生成实现计划。我将使用……
  - label: 澄清 spec 需求
    agent: speckit.clarify
    prompt: 澄清规格说明需求
    send: true

用户输入

$ARGUMENTS

在继续之前，你必须先考虑用户输入（如果不为空）。

概述

触发消息里，用户在 /speckit.specify 之后输入的文本就是功能描述。即使下面字面出现 $ARGUMENTS，也要假设在本次对话中你始终能拿到该描述。除非用户执行了空命令，否则不要让用户重复描述。

基于该功能描述，执行以下流程：

  1. 为分支生成一个精炼短名（2–4 个词）：

    • 分析功能描述并提取最有意义的关键词
    • 生成一个 2–4 词的 short name，能够概括功能核心
    • 尽量使用“动作-名词”格式（例如 "add-user-auth"、"fix-payment-bug"）
    • 保留技术术语与缩写（OAuth2、API、JWT 等）
    • 保持简洁，但要足够描述性，能一眼看懂功能概念
    • 示例：
      • “我想增加用户认证功能” → "user-auth"
      • “为 API 接入 OAuth2 集成” → "oauth2-api-integration"
      • “创建一个数据分析看板” → "analytics-dashboard"
      • “修复支付处理超时问题” → "fix-payment-timeout"

  2. 创建新分支前检查是否已存在同名分支：

a. 先拉取所有远端分支，确保信息最新：

  ```bash
  git fetch --all --prune
  ```

b. 在所有来源中查找该 short-name 的最大功能编号： - 远端分支：git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$' - 本地分支：git branch | grep -E '^[* ]*[0-9]+-<short-name>$' - Specs 目录：检查匹配 specs/[0-9]+-<short-name> 的目录

c. 计算下一个可用编号： - 从三个来源中提取所有编号 - 找到最大编号 N - 新分支编号使用 N+1

d. 使用计算出的编号与 short-name 运行脚本 .specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"： - 传入 --number N+1 与 --short-name "your-short-name"，并携带功能描述 - Bash 示例：.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" --json --number 5 --short-name "user-auth" "Add user authentication" - PowerShell 示例：.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" -Json -Number 5 -ShortName "user-auth" "Add user authentication"

重要：

  • 必须检查三处来源（远端分支、本地分支、specs 目录）以找到最大编号
  • 只匹配与 short-name 完全一致的分支/目录模式
  • 如果没有找到与 short-name 匹配的分支/目录，从编号 1 开始
  • 每个功能只允许运行该脚本一次
  • JSON 会作为终端输出打印出来 —— 获取路径等信息时必须以该 JSON 为准
  • JSON 输出里会包含 BRANCH_NAME 与 SPEC_FILE 路径
  • 当参数里包含单引号（例如 "I'm Groot"）时，使用转义写法：如 'I'\''m Groot'（或尽量用双引号："I'm Groot"）

  1. 加载 .specify/templates/spec-template.md 以了解必需章节。

  2. 按以下执行流程生成 spec：

    1. 从输入中解析用户描述 如果为空：ERROR "未提供功能描述"
    2. 从描述中提取关键概念 识别：参与者（actors）、动作（actions）、数据（data）、约束（constraints）
    3. 对于不清晰的点：
      • 基于上下文与行业常见做法做出有依据的默认判断
      • 仅在以下情况下用 [NEEDS CLARIFICATION: 具体问题] 标记：
        • 选择会显著影响功能范围或用户体验
        • 存在多个合理解释且影响不同
        • 不存在合理默认值
      • 限制：总计最多 3 个 [NEEDS CLARIFICATION] 标记
      • 按影响优先级排序澄清：范围 > 安全/隐私 > 用户体验 > 技术细节
    4. 填写“用户场景与验收”章节 如果没有明确用户流程：ERROR "无法确定用户场景"
    5. 生成“需求 → 功能需求” 每条需求都必须可测试 对未明确的细节使用合理默认值（并在“假设（Assumptions）”章节记录假设）
    6. 定义“成功标准” 产出可度量、与具体技术无关的结果 同时包含量化指标（时间、性能、容量）与定性指标（用户满意度、任务完成率） 每条标准必须在不依赖实现细节的情况下可验证
    7. 识别关键实体（当功能涉及数据时）
    8. 返回：SUCCESS（spec 已可进入规划阶段）

  3. 按模板结构将 spec 写入 SPEC_FILE：用功能描述（arguments）推导的具体内容替换占位符，同时保持章节顺序与标题不变。

  4. spec 质量校验：初版 spec 写入后，按质量标准进行校验：

a. 创建 spec 质量清单：按检查清单模板结构，在 FEATURE_DIR/checklists/requirements.md 生成清单文件，并包含以下校验项：

  ```markdown
  # spec 质量清单：[FEATURE NAME]

  **目的**：在进入规划阶段前，校验 spec 的完整性与质量
  **创建时间**：[DATE]
  **功能**：[Link to spec.md]

  ## 内容质量

  - [ ] 不包含实现细节（语言、框架、API）
  - [ ] 聚焦用户价值与业务需求
  - [ ] 面向非技术干系人撰写
  - [ ] 所有必填章节已完成

  ## 需求完整性

  - [ ] 不再遗留 [NEEDS CLARIFICATION] 标记
  - [ ] 需求可测试且无歧义
  - [ ] 成功标准可度量
  - [ ] 成功标准与技术实现无关（不包含实现细节）
  - [ ] 所有验收场景已定义
  - [ ] 已识别边界情况
  - [ ] 范围边界清晰
  - [ ] 已识别依赖与假设

  ## 功能就绪度

  - [ ] 所有功能需求都有清晰的验收标准
  - [ ] 用户场景覆盖主流程
  - [ ] 功能满足“成功标准”中定义的可度量结果
  - [ ] spec 中没有渗入实现细节

  ## 备注

  - 标记为未完成的条目，需要先更新 spec，再进入 `/speckit.clarify` 或 `/speckit.plan`
  ```

b. 执行校验：逐条对照清单检查 spec： - 对每条清单项判定通过/失败 - 记录发现的具体问题（引用 spec 的相关段落）

c. 处理校验结果：

  - **如果全部通过**：将清单标记为完成，并进入下一步

  - **如果存在失败项（不含 [NEEDS CLARIFICATION]）**：
    1. 列出失败项与具体问题
    2. 更新 spec 逐项修复
    3. 重新执行校验直到全部通过（最多 3 次迭代）
    4. 若 3 次后仍未通过，在清单备注中记录剩余问题并提醒用户

  - **如果仍存在 [NEEDS CLARIFICATION] 标记**：
    1. 从 spec 中提取所有 [NEEDS CLARIFICATION: ...] 标记
    2. **限制检查**：如果标记超过 3 个，只保留最关键的 3 个（按范围/安全/UX 影响排序），其余做有依据的默认判断
    3. 对每个需要澄清的问题（最多 3 个），按以下格式向用户给出选项：

       ```markdown
       ## 问题 [N]：[Topic]

       **上下文**：[引用 spec 相关段落]

       **需要确认的信息**：[来自 NEEDS CLARIFICATION 标记的具体问题]

       **建议答案**：

       | 选项 | 答案 | 影响 |
       |------|------|------|
       | A | [建议答案 1] | [对该功能的影响] |
       | B | [建议答案 2] | [对该功能的影响] |
       | C | [建议答案 3] | [对该功能的影响] |
       | Custom | 提供你自己的答案 | [说明如何提供自定义输入] |

       **你的选择**：_[等待用户回复]_
       ```

    4. **关键（CRITICAL）- 表格格式**：确保 Markdown 表格格式正确：
       - 使用一致的空格并对齐竖线
       - 每个单元格内容两侧要有空格：`| Content |` 而不是 `|Content|`
       - 表头分隔线至少 3 个短横线：`|--------|`
       - 确认表格在 Markdown 预览中能正确渲染
    5. 问题编号按顺序排列（Q1、Q2、Q3，最多 3 个）
    6. 在等待用户回复之前，一次性展示全部问题
    7. 等待用户按问题编号回复选项（例如 “Q1: A, Q2: Custom - [details], Q3: B”）
    8. 用用户选择/提供的答案替换每个 [NEEDS CLARIFICATION] 标记并更新 spec
    9. 当所有澄清完成后重新执行校验

d. 更新清单：每次校验迭代后，更新清单文件中的通过/失败状态

  1. 汇报完成情况：分支名、spec 文件路径、清单结果，以及进入下一阶段（/speckit.clarify 或 /speckit.plan）的就绪情况。

注意（NOTE）：脚本会先创建并切换到新分支，并在写入前初始化 spec 文件。

通用指南

快速指南

  • 聚焦用户需要什么（WHAT）与为什么（WHY）。
  • 避免描述如何实现（不写技术栈、API、代码结构）。
  • 面向业务/非技术干系人撰写，而不是只写给开发看。
  • 不要在 spec 里内嵌任何检查清单；清单由单独命令生成。

章节要求

  • 必填章节：每个功能都必须完成
  • 可选章节：只在与功能相关时保留
  • 如果某个章节不适用，直接删除（不要留下 “N/A”）

面向 AI 生成

当根据用户输入生成该 spec 时：

  1. 做出有依据的默认判断：用上下文、行业标准与常见模式补齐缺口
  2. 记录假设：在 Assumptions 章节写下合理默认值
  3. 限制澄清点：最多 3 个 [NEEDS CLARIFICATION] 标记，只用于以下关键决策：
    • 会显著影响功能范围或用户体验
    • 存在多种合理解释且影响不同
    • 没有合理默认值
  4. 澄清优先级：范围 > 安全/隐私 > 用户体验 > 技术细节
  5. 像测试人员一样思考：任何模糊需求都应在“可测试且无歧义”项上失败
  6. 常见需要澄清的领域（仅当不存在合理默认值时才问）：
    • 功能范围与边界（包含/排除哪些用例）
    • 用户类型与权限（存在多种冲突解释时）
    • 安全/合规要求（法律/财务层面影响显著时）

合理默认值示例（这些通常不必询问用户）：

  • 数据保留：该领域的行业通用做法
  • 性能目标：除非用户明确要求，否则按常规 web/移动端应用预期
  • 错误处理：用户友好的提示，并提供合适兜底
  • 认证方式：web 应用默认使用 session 或 OAuth2 的常见方式
  • 集成模式：除非另有说明，默认使用 RESTful API

“成功标准”编写指南

成功标准必须满足：

  1. 可度量：包含具体指标（时间、百分比、数量、比率等）
  2. 与技术无关：不提框架、语言、数据库或工具
  3. 以用户为中心：从用户/业务视角描述结果，而不是系统内部指标
  4. 可验证：不依赖实现细节也能测试/验证

好的示例：

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

不好的示例（偏实现细节）：

  • "API 响应时间低于 200ms"（太技术化；应改为“用户几乎瞬时看到结果”这类用户侧指标）
  • "数据库可处理 1000 TPS"（实现细节；应改为用户侧可感知/可验收的指标）
  • "React 组件渲染高效"（框架相关）
  • "Redis 缓存命中率高于 80%"（技术相关）