Hooke / mlaj

description: 通过最多 5 个高针对性的澄清问题，识别当前功能 spec 中说明不足的部分，并将答案写回 spec。
handoffs:
  - label: 生成技术计划
    agent: speckit.plan
    prompt: 为该 spec 生成实现计划。我将使用……

用户输入

$ARGUMENTS

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

概述

目标：检测并减少当前功能说明中的歧义与缺失决策点，并将澄清内容直接记录到 spec 文件中。

注意：本澄清流程预计应在调用 /speckit.plan 之前运行并完成。如果用户明确表示跳过澄清（例如做探索性验证），你可以继续，但必须提醒下游返工风险会增加。

执行步骤：

1. 在仓库根目录只运行一次 .specify/scripts/bash/check-prerequisites.sh --json --paths-only（组合模式：--json --paths-only / -Json -PathsOnly）。解析最小 JSON 字段：

   • FEATURE_DIR
   • FEATURE_SPEC
   • （可选）为后续链路保留 IMPL_PLAN、TASKS
   • 若 JSON 解析失败，立即终止并提示用户重新运行 /speckit.specify 或检查当前功能分支环境
   • 当参数里包含单引号（例如 "I'm Groot"）时，使用转义写法：如 'I'\''m Groot'（或尽量用双引号："I'm Groot"）。

2. 加载当前 spec 文件，并按以下分类做结构化的歧义与覆盖扫描。对每个类别标记状态：清晰 / 部分 / 缺失。生成一份用于排序的内部覆盖图（除非必要，不要输出原始覆盖图）。

功能范围与行为（Functional Scope & Behavior）：

• 核心用户目标与成功标准
• 明确的范围外（out-of-scope）声明
• 用户角色/人物画像的区分

领域与数据模型（Domain & Data Model）：

• 实体、属性、关系
• 身份/唯一性规则
• 生命周期/状态流转
• 数据量/规模假设

交互与 UX 流程（Interaction & UX Flow）：

• 关键用户旅程/操作序列
• 错误/空/加载状态
• 无障碍或本地化说明

非功能质量属性（Non-Functional Quality Attributes）：

• 性能（延迟、吞吐目标）
• 可扩展性（水平/垂直、上限）
• 可靠性与可用性（可用率、恢复预期）
• 可观测性（日志、指标、链路追踪信号）
• 安全与隐私（authN/Z、数据保护、威胁假设）
• 合规/监管约束（如有）

集成与外部依赖（Integration & External Dependencies）：

• 外部服务/API 与失败模式
• 数据导入/导出格式
• 协议/版本假设

边界情况与失败处理（Edge Cases & Failure Handling）：

• 负向场景
• 限流/节流
• 冲突解决（例如并发编辑）

约束与取舍（Constraints & Tradeoffs）：

• 技术约束（语言、存储、托管）
• 明确的取舍或被拒绝的备选方案

术语与一致性（Terminology & Consistency）：

• 规范术语表词条
• 避免使用的同义词/废弃术语

完成信号（Completion Signals）：

• 验收标准可测试性
• 可量化的完成定义（Definition of Done）风格指标

杂项/占位符（Misc / Placeholders）：

• TODO 标记/未决决策
• 未量化的模糊形容词（例如 “robust”“intuitive”）

对于状态为“部分”或“缺失”的类别，除非满足以下情况，否则应加入一个候选提问点：

• 澄清不会实质性改变实现或验证策略
• 信息更适合延后到规划阶段再确定（内部记录即可）

1. 在内部生成一个候选澄清问题的优先队列（最多 5 个）。不要一次性全部输出。约束如下：

   • 全会话最多 10 个问题。
   • 每个问题必须能用以下任一方式回答：
     • 简短的多选项（2–5 个明确且互斥的选项），或
     • 一个词/短语（明确限制：“回答不超过 5 个词”）。
   • 只包含那些会实质影响架构、数据建模、任务拆分、测试设计、UX 行为、运维就绪或合规验证的问题。
   • 保持类别覆盖均衡：优先覆盖高影响且未解决的类别；不要在一个高影响领域（例如安全策略）未解决时，去问两个低影响问题。
   • 排除已回答的问题、琐碎的风格偏好、或 plan 层面的执行细节（除非阻塞正确性）。
   • 优先提出能降低下游返工风险或避免验收测试错位的问题。
   • 若未解决类别超过 5 个，按（Impact * Uncertainty）启发式选取前 5 个。

2. 顺序提问循环（交互式）：

   • 每次只呈现一个问题。
   • 对于多选题：
     • 分析所有选项，并基于以下因素确定最合适的选项：
       • 该项目类型的最佳实践
       • 类似实现的常见模式
       • 风险降低（安全、性能、可维护性）
       • spec 中可见的项目目标或约束是否匹配
     • 在顶部突出展示你的推荐选项并给出清晰理由（1–2 句说明为何这是最佳选择）。
     • 格式：**推荐：** 选项 [X] - <理由>
     • 然后用 Markdown 表格列出所有选项：

   | 选项 | 描述 | |------|------| | A | <选项 A 描述> | | B | <选项 B 描述> | | C | <选项 C 描述>（如需可加 D/E，最多 5 个） | | Short | 提供不同的短答案（<=5 个词）（仅在需要自由回答时保留） |

   - 表格后追加：`你可以回复选项字母（例如 “A”），也可以回复 “yes” 或 “recommended” 来接受推荐，或给出你自己的短答案。`
- 对于短答案形式（没有有意义的离散选项）：
   - 基于最佳实践与上下文给出你的**建议答案**。
   - 格式：`**建议：** <你的建议答案> - <简短理由>`
   - 然后输出：`格式：短答案（<=5 个词）。你可以回复 “yes” 或 “suggested” 来接受建议，或提供你自己的答案。`
- 用户回答后：
   - 若用户回复 “yes”“recommended” 或 “suggested”，使用你之前给出的推荐/建议作为最终答案。
   - 否则，校验回答是否能映射到某个选项或满足 <=5 word 的限制。
   - 若仍有歧义，快速追问以消歧（仍算同一个问题，不要推进到下一题）。
   - 一旦答案满足要求，将其记录到工作记忆（先不要写盘），并进入队列里的下一个问题。
- 在以下条件下停止继续提问：
   - 关键歧义已提前全部解决（剩余问题不再必要），或
   - 用户表示结束（“done”“good”“no more”），或
   - 已问满 5 个问题。
- 不要提前泄露后续排队的问题。
- 如果一开始就没有有效问题，立即报告“未发现值得正式澄清的关键歧义”。

1. 每次采纳答案后的集成（增量更新方式）：

   • 在内存中维护一份 spec 表示（会话开始时只加载一次）以及原始文件内容。
   • 本次会话第一次写入时：
     • 确保存在 ## Clarifications 章节（若缺失，则按 spec 模板在最高层级的背景/概览段落之后创建）。
     • 在其下创建（若不存在）今日对应的 ### Session YYYY-MM-DD 小标题。
   • 每次采纳后立即追加一行 bullet：- Q: <问题> → A: <最终答案>。
   • 随后立即将澄清内容应用到最合适的章节：
     • 功能歧义 → 更新/新增 Functional Requirements 下的 bullet。
     • 用户交互/角色区分 → 在 User Stories 或 Actors 子章节（如存在）写入明确的角色、约束或场景。
     • 数据形态/实体 → 更新 Data Model（新增字段/类型/关系时保持原有顺序），并用简短语句注明新增约束。
     • 非功能约束 → 在 Non-Functional / Quality Attributes 中新增或修改可度量的标准（把模糊形容词转换为指标或明确目标）。
     • 边界情况/负向流程 → 在 Edge Cases / Error Handling 下新增 bullet（或按模板占位创建对应小节）。
     • 术语冲突 → 统一 spec 全文用词；仅在必要时保留旧称，并只在一个地方追加 （此前称为“X”）。
   • 若澄清答案使先前的模糊表述失效，应替换旧表述而不是重复追加；不要留下过时的矛盾文本。
   • 每次集成后都保存 spec 文件，尽量降低上下文丢失风险（原子覆盖写入）。
   • 保持格式：不要重排无关章节；保持标题层级不变。
   • 每次插入的澄清内容都要尽量精炼且可验证（避免叙事化扩散）。

2. 校验（每次写入后执行，最终再做一次整体检查）：

   • Clarifications 会话中每个被采纳答案只对应一条 bullet（不重复）。
   • 总提问（被采纳）数量 ≤ 5。
   • 更新后的章节中不应残留原本要被新答案解决的模糊占位符。
   • 不应遗留自相矛盾的旧表述（扫描并移除已失效的备选说法）。
   • Markdown 结构合法；仅允许新增标题：## Clarifications、### Session YYYY-MM-DD。
   • 术语一致：所有更新章节使用同一套规范术语。

3. 将更新后的 spec 写回 FEATURE_SPEC。

4. 报告完成（当提问循环结束或被提前终止后）：

   • 已提问并采纳的数量。
   • 更新后的 spec 路径。
   • 涉及修改的章节（列出名称）。
   • 覆盖摘要表：列出每个分类及状态：Resolved（原为 Partial/Missing 且已补齐）、Deferred（超出配额或更适合留到规划阶段）、Clear（已足够清晰）、Outstanding（仍 Partial/Missing 但影响低）。
   • 若仍存在 Outstanding 或 Deferred：建议是直接进入 /speckit.plan，还是在 plan 之后再跑一次 /speckit.clarify。
   • 建议下一条命令。

行为规则：

• 如果未发现有意义的歧义（或所有候选问题影响都很低），则回复：“未发现值得正式澄清的关键歧义。”并建议继续。
• 如果缺少 spec 文件，提示用户先运行 /speckit.specify（不要在这里新建 spec）。
• 总提问数不要超过 5 个（同一问题的澄清重试不算新问题）。
• 除非缺失信息会阻塞功能澄清，否则避免提出臆测性的技术栈问题。
• 尊重用户的提前终止信号（“stop”“done”“proceed”）。
• 若因覆盖完整而未提问，输出一份精简覆盖摘要（所有分类为 Clear）并建议继续推进。
• 若配额用尽但仍有未解决的高影响分类，在 Deferred 下明确标记并说明原因。

用于优先级判断的上下文：$ARGUMENTS