用户输入
$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 在下面显示为文字,你在本次对话中也始终可以获取到它。不要要求用户重复,除非他们提供了空命令。
根据该功能描述,执行以下操作:
-
生成一个简洁的短名称(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”
-
分支创建(可选,通过钩子):
如果在上面的前置执行检查中,
before_specify钩子成功运行,它将创建/切换到一个 git 分支,并输出包含BRANCH_NAME和FEATURE_NUM的 JSON。记录这些值以供参考,但分支名称不决定规范目录的名称。如果用户显式提供了
GIT_BRANCH_NAME,则将其传递给钩子,以便分支脚本使用该确切值作为分支名称(绕过所有前缀/后缀生成)。 -
创建规范功能目录:
规范文件默认位于
specs/目录下,除非用户显式提供SPECIFY_FEATURE_DIRECTORY。SPECIFY_FEATURE_DIRECTORY的解析顺序:- 如果用户显式提供了
SPECIFY_FEATURE_DIRECTORY(例如,通过环境变量、参数或配置),则直接使用。 - 否则,在
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 分支名称是独立的——它们可以相同,但那是用户的选择。
- 规范目录和文件始终由此命令创建,而不是由钩子创建。
- 如果用户显式提供了
-
加载解析后的活跃
spec-template文件以了解所需的部分。 -
如果存在:加载
.specify/memory/constitution.md以获取项目原则和治理约束。 -
遵循以下执行流程:
- 从参数中解析用户描述 如果为空:错误“未提供功能描述”
- 从描述中提取关键概念 识别:参与者、动作、数据、约束
- 对于不清楚的方面:
- 根据上下文和行业标准做出有根据的猜测。
- 仅在以下情况下使用 [NEEDS CLARIFICATION: specific question] 标记:
- 该选择显著影响功能范围或用户体验。
- 存在多个具有不同影响的合理解释。
- 不存在合理的默认值。
- 限制:总共最多 3 个 [NEEDS CLARIFICATION] 标记
- 按影响程度排列待澄清项的优先级:范围 > 安全/隐私 > 用户体验 > 技术细节。
- 填写用户场景和测试部分 如果没有明确的用户流程:错误“无法确定用户场景”
- 生成功能需求 每个需求必须可测试。 对未指定的细节使用合理的默认值(在假设部分记录假设)。
- 定义成功标准 创建可衡量的、与技术无关的结果。 包括定量指标(时间、性能、数量)和定性指标(用户满意度、任务完成度)。 每个标准必须无需实现细节即可验证。
- 识别关键实体(如果涉及数据)
- 返回:成功(规范已准备好进行规划)
-
使用模板结构将规范写入
SPEC_FILE,用从功能描述(参数)中得出的具体细节替换占位符,同时保留各部分顺序和标题。 -
规范质量验证:在编写初始规范后,根据质量标准进行验证:
a. 创建规范质量检查清单:在
SPECIFY_FEATURE_DIRECTORY/checklists/requirements.md使用检查清单模板结构生成一个包含以下验证项的清单文件:# 规范质量检查清单:[功能名称] **目的**:在进入规划前验证规范的完整性和质量 **创建日期**:[日期] **功能**:[指向 spec.md 的链接] ## 内容质量 - [ ] 无实现细节(语言、框架、API) - [ ] 专注于用户价值和业务需求 - [ ] 为非技术利益相关者编写 - [ ] 所有必填部分已完成 ## 需求完整性 - [ ] 没有剩余的 [NEEDS CLARIFICATION] 标记 - [ ] 需求可测试且无二义性 - [ ] 成功标准可衡量 - [ ] 成功标准与技术无关(无实现细节) - [ ] 所有验收场景都已定义 - [ ] 识别出边缘情况 - [ ] 范围已明确界定 - [ ] 已识别依赖项和假设 ## 功能就绪状态 - [ ] 所有功能需求都有明确的验收标准 - [ ] 用户场景覆盖主要流程 - [ ] 功能满足成功标准中定义的可衡量结果 - [ ] 无实现细节泄漏到规范中 ## 备注 - 标记为不完整的项目需要在 `/speckit-clarify` 或 `/speckit-plan` 之前更新规范b. 运行验证检查:对照每个检查清单项审查规范:
- 对于每个项目,判断其通过还是失败。
- 记录发现的具体问题(引用相关规范部分)。
c. 处理验证结果:
-
如果所有项目都通过:将检查清单标记为完成,并继续到强制后置执行钩子部分。
-
如果项目失败(不包括 [NEEDS CLARIFICATION]):
- 列出失败的项目和具体问题。
- 更新规范以解决每个问题。
- 重新运行验证,直到所有项目通过(最多 3 次迭代)。
- 如果在 3 次迭代后仍然失败,在检查清单备注中记录剩余问题并警告用户。
-
如果 [NEEDS CLARIFICATION] 标记仍然存在:
-
从规范中提取所有 [NEEDS CLARIFICATION: ...] 标记。
-
限制检查:如果存在超过 3 个标记,仅保留 3 个最关键的(按范围/安全/用户体验影响),其余做出有根据的猜测。
-
对于每个所需的澄清(最多 3 个),以以下格式向用户呈现选项:
## 问题 [N]:[主题] **上下文**:[引用相关规范部分] **我们需要知道什么**:[来自 NEEDS CLARIFICATION 标记的具体问题] **建议答案**: | 选项 | 答案 | 影响 | |--------|--------|--------------| | A | [第一个建议答案] | [这对功能意味着什么] | | B | [第二个建议答案] | [这对功能意味着什么] | | C | [第三个建议答案] | [这对功能意味着什么] | | 自定义 | 提供您自己的答案 | [解释如何提供自定义输入] | **您的选择**:_[等待用户响应]_ -
关键 - 表格格式:确保 markdown 表格格式正确:
- 使用一致的空格,并对齐竖线。
- 每个单元格内容周围应有空格:
| 内容 |而不是|内容|。 - 标题分隔符必须至少包含 3 个短横线:
|--------|。 - 测试表格在 markdown 预览中是否正常渲染。
-
对问题按顺序编号(Q1、Q2、Q3 - 总共最多 3 个)。
-
在等待回复之前,将所有问题一起呈现。
-
等待用户回复他们对所有问题的选择(例如,“Q1: A, Q2: Custom - [details], Q3: B”)。
-
通过将每个 [NEEDS CLARIFICATION] 标记替换为用户选择的或提供的答案来更新规范。
-
在所有澄清解决后重新运行验证。
-
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} 执行中:`
- 强制钩子(