在 spec-kit 项目中把自然语言功能描述转成可校验的功…

当你在 spec-kit 项目里有一条自然语言功能描述、需要生成或更新 `specs/` 下的功能规格（spec.md）并做质量校验时使用。

适用场景

解决思路

1. 必须优先考虑用户输入 `$ARGUMENTS`（非空时）。
2. 预执行检查：检查项目根目录是否存在 `.specify/extensions.yml`。
3. 若该文件存在，读取它并查找 `hooks.before_specify` 键下的条目。
4. 若 YAML 无法解析或无效，不要静默跳过：告知用户 `.specify/extensions.yml` 无法读取（附上解析错误），并且没有检查任何 hook（包括注册在那里、`optional: false` 的强制 hook），然后照常继续。
5. 过滤掉 `enabled` 显式为 `false` 的 hook；没有 `enabled` 字段的 hook 视为默认启用。
6. 不要尝试解释或求值 hook 的 `condition` 表达式：若 hook 没有 `condition` 字段、或为 null/空，视为可执行。
7. 若 hook 定义了非空 `condition`，跳过该 hook，把条件求值留给 HookExecutor 实现。
8. 由 hook 命令名构造命令调用时，把点（`.`）替换为连字符（`-`），例如 `speckit.git.commit` → `/speckit-git-commit`。
9. 对每个可执行 hook，按其 `optional` 标志输出文本块：可选 hook（`optional: true`）输出 `## Extension Hooks`、`**Optional Pre-Hook**: {extension}`、Command、Description、Prompt、To execute 行。
10. 对强制 hook（`optional: false`）输出 `## Extension Hooks`、`**Automatic Pre-Hook**: {extension}`、Executing、`EXECUTE_COMMAND: {command}`，并在继续到 Outline 前等待 hook 命令结果。
11. 输出上述强制 hook 文本块后，必须真正调用该 hook 并等它结束再继续；按你在当前 agent/会话中运行命令的同一方式运行（调用形式可能不同于字面 `{command}` id，例如 skills 模式的 agent 以 `/skill:speckit-...` 或 `$speckit-...` 运行）；只输出文本块并不等于执行 hook。
12. 若没有 hook 注册或 `.specify/extensions.yml` 不存在，静默跳过。
13. 把用户在 `/speckit-specify` 之后输入的文本当作 feature 描述；即使 `$ARGUMENTS` 在下方字面出现，也假定它已在本对话中可用；除非用户提供了空命令，否则不要让用户重复描述。
14. 生成 2-4 个词的简短名称：分析 feature 描述并提取最有意义的关键词。
15. 创建 2-4 个词的短名称，尽量使用动作-名词格式（如 `add-user-auth`、`fix-payment-bug`）。
16. 保留技术术语与缩写（OAuth2、API、JWT 等）；保持简洁但足以一眼看懂该 feature。
17. 分支创建（可选，通过 hook）：若 `before_specify` hook 成功运行，它会创建/切换 git 分支并输出含 `BRANCH_NAME` 和 `FEATURE_NUM` 的 JSON；记下这些值供参考，但分支名不决定 spec 目录名。
18. 若用户显式提供 `GIT_BRANCH_NAME`，把它传给 hook，让分支脚本把该值精确用作分支名（跳过所有前缀/后缀生成）。
19. 创建 spec feature 目录：spec 默认位于 `specs/` 目录下，除非用户显式提供 `SPECIFY_FEATURE_DIRECTORY`。
20. `SPECIFY_FEATURE_DIRECTORY` 解析顺序第 1 条：若用户显式提供（如通过环境变量、参数或配置），原样使用。
21. `SPECIFY_FEATURE_DIRECTORY` 解析顺序第 2 条：否则在 `specs/` 下自动生成。
22. 自动生成时检查 `.specify/init-options.json` 的 `feature_numbering`（首选）或 `branch_numbering`（已弃用，仅用于迁移，将在未来版本移除）。
23. 若为 `"timestamp"`，前缀是 `YYYYMMDD-HHMMSS`（当前时间戳）。
24. 若为 `"sequential"` 或缺省，前缀是 `NNN`（扫描 `specs/` 下现有目录后取下一个可用的 3 位数字）。
25. 构造目录名：`<prefix>-<short-name>`（如 `003-user-auth` 或 `20260319-143022-user-auth`），并把 `SPECIFY_FEATURE_DIRECTORY` 设为 `specs/<directory-name>`。
26. 若使用了 `branch_numbering`（且 `feature_numbering` 缺失），输出一行警告：`⚠️ branch_numbering in init-options.json is deprecated. Rename to feature_numbering.`
27. 创建目录与 spec 文件：执行 `mkdir -p SPECIFY_FEATURE_DIRECTORY`。
28. 通过 Spec Kit preset/template 解析栈解析活动的 `spec-template`（等价于 `specify preset resolve spec-template`）。
29. 把解析出的 `spec-template` 文件复制到 `SPECIFY_FEATURE_DIRECTORY/spec.md` 作为起点，并把 `SPEC_FILE` 设为 `SPECIFY_FEATURE_DIRECTORY/spec.md`。
30. 把解析出的路径持久化到 `.specify/feature.json`，内容为 `{"feature_directory": "<resolved feature dir>"}`，写入实际解析出的目录路径值（例如 `specs/003-user-auth`），而不是字面字符串 `SPECIFY_FEATURE_DIRECTORY`；这样下游命令（`/speckit-plan`、`/speckit-tasks` 等）无需依赖 git 分支名约定即可定位 feature 目录。
31. 重要约束：每次 `/speckit-specify` 调用只能创建一个 feature。
32. 重要约束：spec 目录名与 git 分支名彼此独立——可以相同，但那是用户的选择。
33. 重要约束：spec 目录和文件始终由本命令创建，绝不由 hook 创建。
34. 加载解析出的活动 `spec-template` 文件，了解必需章节。
35. 若存在，加载 `.specify/memory/constitution.md` 获取项目原则与治理约束。
36. 执行流程 1：从参数解析用户描述；若为空则报错 `No feature description provided`。
37. 执行流程 2：从描述提取关键概念，识别 actors、actions、data、constraints。
38. 执行流程 3：对不明确处基于上下文与行业标准做有依据的猜测；仅当该选择显著影响功能范围或用户体验、存在多种含义不同的合理解释、且没有合理默认时，才标 `[NEEDS CLARIFICATION: 具体问题]`。
39. 执行流程 3 限制：`[NEEDS CLARIFICATION]` 标记总数最多 3 个。
40. 执行流程 3 优先级：按影响排序为 scope > security/privacy > user experience > technical details。
41. 执行流程 4：填写 User Scenarios & Testing 章节；若没有清晰用户流程则报错 `Cannot determine user scenarios`。
42. 执行流程 5：生成 Functional Requirements，每条需求必须可测试；未指定的细节使用合理默认值，并把假设记录在 Assumptions 章节。
43. 执行流程 6：定义 Success Criteria，创建可度量、与技术无关的结果，同时包含定量指标（时间、性能、数量）和定性衡量（用户满意度、任务完成度）；每条标准必须无需实现细节即可验证。
44. 执行流程 7：识别 Key Entities（若涉及数据）。
45. 执行流程 8：返回 SUCCESS（spec 已就绪可进入规划）。
46. 按模板结构把规格写入 `SPEC_FILE`，用从 feature 描述（参数）推导出的具体细节替换占位符，同时保留章节顺序与标题。
47. 质量校验 a：在 `SPECIFY_FEATURE_DIRECTORY/checklists/requirements.md` 生成 checklist 文件，使用 checklist 模板结构，包含以下校验项——Content Quality：无实现细节（语言、框架、API）、聚焦用户价值与业务需求、面向非技术干系人、所有必填章节已完成。
48. 质量校验 a 继续——Requirement Completeness：无 `[NEEDS CLARIFICATION]` 标记残留、需求可测试且无歧义、成功标准可度量、成功标准与技术无关（无实现细节）、所有验收场景已定义、边界情况已识别、范围清晰界定、依赖与假设已识别。
49. 质量校验 a 继续——Feature Readiness：所有功能需求都有明确验收标准、用户场景覆盖主要流程、功能满足 Success Criteria 中定义的可度量结果、无实现细节泄漏到规格。
50. 质量校验 a 继续——Notes：标记为未完成的项需在 `/speckit-clarify` 或 `/speckit-plan` 之前更新 spec。
51. 质量校验 b：对照每个 checklist 项审查 spec，判断通过或失败，并记录发现的具体问题（引用相关 spec 章节）。
52. 质量校验 c（全部通过时）：标记 checklist 完成并进入 Mandatory Post-Execution Hooks 章节。
53. 质量校验 c（有不通过项且不含 `[NEEDS CLARIFICATION]` 时）：列出失败项与具体问题，更新 spec 逐项解决，重跑校验直到全部通过（最多 3 轮迭代）；若 3 轮后仍失败，把剩余问题记录到 checklist notes 并警告用户。
54. 质量校验 c（仍有 `[NEEDS CLARIFICATION]` 标记时）：从 spec 中提取所有 `[NEEDS CLARIFICATION: ...]` 标记。
55. 标记数量限制检查：若超过 3 个，只保留影响最关键的 3 个（按 scope/security/UX 影响），其余做有依据的猜测。
56. 对每个待澄清项（最多 3 个），按给定 markdown 格式向用户呈现：`## Question [N]: [Topic]`、Context（引用相关 spec 章节）、What we need to know（来自 NEEDS CLARIFICATION 标记的具体问题）、Suggested Answers 表格（Option A/B/C 与 Custom，含各自 Implications）、`**Your choice**: _[Wait for user response]_`。
57. 表格格式要求：管道对齐、间距一致；每格内容两侧留空格（`| Content |` 而非 `|Content|`）；表头分隔符至少 3 个短横线（`|--------|`）；在 markdown 预览中确认表格渲染正确。
58. 问题按 Q1、Q2、Q3 顺序编号（最多 3 个）；一次性呈现所有问题后再等待用户回复。
59. 等待用户给出所有问题的选择（例如 `Q1: A, Q2: Custom - [详情], Q3: B`）。
60. 用用户选定或提供的答案替换每个 `[NEEDS CLARIFICATION]` 标记来更新 spec；所有澄清解决后重跑校验。
61. 每次校验迭代后，用当前的通过/失败状态更新 checklist 文件。
62. 强制后置 hook：在向用户报告完成之前必须完成本节；检查项目根目录是否存在 `.specify/extensions.yml`。
63. 后置 hook：若文件不存在，或 `hooks.after_specify` 下没有注册 hook，跳到 Completion Report。
64. 后置 hook：若文件存在，读取它并查找 `hooks.after_specify` 键下的条目。
65. 后置 hook：若 YAML 无法解析或无效，不要静默跳过：告知用户 `.specify/extensions.yml` 无法读取（附解析错误）且未检查任何 hook（包括注册其中、`optional: false` 的强制 hook），然后继续到 Completion Report。
66. 后置 hook：过滤掉 `enabled` 显式为 `false` 的 hook；没有 `enabled` 字段的视为默认启用。
67. 后置 hook：不要解释或求值 `condition` 表达式——无 `condition` 字段或为 null/空则视为可执行，定义了非空 `condition` 则跳过并留给 HookExecutor。
68. 后置 hook：由 hook 命令名构造调用时把点替换为连字符，例如 `speckit.git.commit` → `/speckit-git-commit`。
69. 后置 hook：对每个强制 hook（`optional: false`）必须输出 `## Extension Hooks`、`**Automatic Hook**: {extension}`、Executing、`EXECUTE_COMMAND: {command}`。
70. 后置 hook：输出上述文本块后必须真正调用该 hook 并等它结束再继续；按你在当前 agent/会话中运行命令的同一方式运行（调用形式可能不同于字面 `{command}`，例如 skills 模式的 agent 以 `/skill:speckit-...` 或 `$speckit-...` 运行）；只输出文本块本身并不运行 hook。
71. 后置 hook：对可选 hook（`optional: true`）输出 `## Extension Hooks`、`**Optional Hook**: {extension}`、Command、Description、Prompt、To execute。
72. Completion Report：向用户报告 `SPECIFY_FEATURE_DIRECTORY`（feature 目录路径）、`SPEC_FILE`（spec 文件路径）、checklist 结果摘要，以及进入下一阶段（`/speckit-clarify` 或 `/speckit-plan`）的就绪状态。
73. 注意：分支创建由 `before_specify` hook（git 扩展）处理；spec 目录与文件创建始终由本核心命令处理。
74. 快速指南：聚焦 WHAT（用户需要什么）与 WHY。
75. 快速指南：避免描述 HOW 实现——不要写技术栈、API、代码结构。
76. 快速指南：面向业务干系人撰写，而不是面向开发者。
77. 快速指南：不要创建嵌入 spec 的 checklist，那将是另一个独立命令。
78. 章节要求：必填章节必须为每个 feature 完成。
79. 章节要求：可选章节仅在与该 feature 相关时包含。
80. 章节要求：某章节不适用时整节删除，不要留 `N/A`。
81. AI 生成规则 1：做有依据的猜测——用上下文、行业标准和常见模式填补空白。
82. AI 生成规则 2：把合理默认记录在 Assumptions 章节。
83. AI 生成规则 3：限制澄清——最多 3 个 `[NEEDS CLARIFICATION]` 标记，仅用于显著影响功能范围或用户体验、有多种含义不同的合理解释、且没有任何合理默认的关键决策。
84. AI 生成规则 4：澄清优先级为 scope > security/privacy > user experience > technical details。
85. AI 生成规则 5：像测试者一样思考——每条含糊的需求都应无法通过「可测试且无歧义」检查项。
86. AI 生成规则 6：常见需要澄清的领域（仅在没有合理默认时）——功能范围与边界（包含/排除具体用例）、用户类型与权限（存在多种冲突解释时）、安全/合规要求（法律或财务上重要时）。
87. 合理默认示例（不要就这些提问）：数据保留用该领域的行业标准做法。
88. 合理默认示例：性能目标用标准 Web/移动应用预期（除非另有指定）。
89. 合理默认示例：错误处理用用户友好消息加适当回退。
90. 合理默认示例：Web 应用认证方式用标准的基于会话或 OAuth2。
91. 合理默认示例：集成模式用适合项目的模式（Web 服务用 REST/GraphQL、库用函数调用、工具用 CLI 参数等）。
92. 成功标准指南：必须可度量——包含具体指标（时间、百分比、数量、速率）。
93. 成功标准指南：必须与技术无关——不提及框架、语言、数据库或工具。
94. 成功标准指南：必须面向用户——从用户/业务视角描述结果，而非系统内部。
95. 成功标准指南：必须可验证——无需了解实现细节即可测试/验证。
96. 成功标准正例：`Users can complete checkout in under 3 minutes`、`System supports 10,000 concurrent users`、`95% of searches return results in under 1 second`、`Task completion rate improves by 40%`。
97. 成功标准反例：`API response time is under 200ms`（太技术，应改为用户视角）、`Database can handle 1000 TPS`（实现细节，应用面向用户的指标）、`React components render efficiently`（框架特定）、`Redis cache hit rate above 80%`（技术特定）。
98. Done When 检查 1：规格已写入 `SPEC_FILE` 并通过质量 checklist 校验。
99. Done When 检查 2：扩展 hook 已按 Mandatory Post-Execution Hooks 的规则派发或跳过。
100. Done When 检查 3：已向用户报告完成，包含 feature 目录、spec 文件路径和 checklist 结果。

适用边界 · 注意事项

• 项目未安装 spec-kit、没有 `.specify/` 目录结构（或缺少 preset/template 解析栈）时无法使用。
• 只想直接拿到技术实现方案时（本命令只产出 WHAT/WHY，不写技术栈、API、代码结构），应改用 `/speckit-plan`。
• 用户未提供任何功能描述（空参数）时无法执行。