ContextQMD
Back to Imewlconverter

Speckit.Clarify

.codebuddy/commands/speckit.clarify.md

3.3.19.6 KB
Original Source

用户输入

text
$ARGUMENTS

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

概述

目标: 检测并减少活跃功能规范中的模糊性或缺失的决策点, 并将澄清内容直接记录在规范文件中.

注意: 此澄清工作流应在调用 /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. 加载当前规范文件. 使用此分类法执行结构化模糊性和覆盖范围扫描. 对于每个类别, 标记状态: 清晰 / 部分 / 缺失. 生成用于优先级排序的内部覆盖范围图(除非不会提问, 否则不输出原始图).

    功能范围与行为:

    • 核心用户目标和成功标准
    • 明确的超出范围声明
    • 用户角色 / 角色区分

    领域与数据模型:

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

    交互与 UX 流程:

    • 关键用户旅程 / 序列
    • 错误 / 空白 / 加载状态
    • 可访问性或本地化说明

    非功能性质量属性:

    • 性能(延迟、吞吐量目标)
    • 可扩展性(水平 / 垂直、限制)
    • 可靠性和可用性(正常运行时间、恢复期望)
    • 可观察性(日志、指标、追踪信号)
    • 安全性和隐私(身份验证 / 授权、数据保护、威胁假设)
    • 合规性 / 监管约束(如有)

    集成与外部依赖:

    • 外部服务 / API 和故障模式
    • 数据导入 / 导出格式
    • 协议 / 版本控制假设

    边缘情况与故障处理:

    • 负面场景
    • 速率限制 / 节流
    • 冲突解决(例如, 并发编辑)

    约束与权衡:

    • 技术约束(语言、存储、托管)
    • 明确的权衡或被拒绝的替代方案

    术语与一致性:

    • 规范术语表术语
    • 避免的同义词 / 已弃用术语

    完成信号:

    • 验收标准可测试性
    • 可衡量的完成定义风格指标

    其他 / 占位符:

    • TODO 标记 / 未解决的决策
    • 缺少量化的模糊形容词("robust"、"intuitive")

    对于每个处于部分或缺失状态的类别, 添加候选问题机会, 除非:

    • 澄清不会实质性地改变实施或验证策略
    • 信息更适合推迟到规划阶段(内部记录)

  3. (内部)生成候选澄清问题的优先级队列(最多5个). 不要一次性输出所有问题. 应用这些约束:

    • 整个会话最多10个问题.
    • 每个问题必须可以用以下任一方式回答:
      • 简短的多项选择(2-5个不同的、互斥的选项), 或
      • 单词 / 短语答案(明确约束: "Answer in <=5 words").
    • 仅包含答案实质上影响架构、数据建模、任务分解、测试设计、UX 行为、运营准备或合规性验证的问题.
    • 确保类别覆盖平衡: 尝试首先覆盖最高影响的未解决类别; 避免在单个高影响领域(例如, 安全态势)未解决时询问两个低影响问题.
    • 排除已回答的问题、琐碎的风格偏好或规划级别的执行细节(除非阻碍正确性).
    • 偏好减少下游返工风险或防止不一致验收测试的澄清.
    • 如果超过5个类别仍未解决, 通过(影响 * 不确定性)启发式选择前5个.

  4. 顺序提问流程(交互式):

    • 一次只提出确切一个问题.
    • 对于多项选择题:

      • 分析所有选项并基于以下确定最合适的选项:

        • 项目类型的最佳实践
        • 类似实现中的常见模式
        • 风险降低(安全性、性能、可维护性)
        • 与规范中可见的任何明确项目目标或约束的一致性

      • 在顶部突出显示你的推荐选项并附上清晰推理(1-2句话解释为什么这是最佳选择).

      • 格式为: **Recommended:** Option [X] - <reasoning>

      • 然后将所有选项渲染为 Markdown 表格:

        OptionDescription
        A<Option A description>
        B<Option B description>
        C<Option C description>
        ShortProvide a different short answer (<=5 words)

      • 表格后添加: You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.

    • 对于简答题风格(没有有意义的不同选项):
      • 基于最佳实践和上下文提供你的建议答案.
      • 格式为: **Suggested:** <your proposed answer> - <brief reasoning>
      • 然后输出: Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.
    • 用户回答后:
      • 如果用户回复 "yes"、"recommended" 或 "suggested", 使用你之前陈述的推荐 / 建议作为答案.
      • 否则, 验证答案映射到一个选项或符合 <=5 个词的约束.
      • 如果模糊, 要求快速消除歧义(计数仍属于同一问题; 不前进).
      • 一旦满意, 将其记录在工作内存中(尚未写入磁盘)并移动到下一个排队的问题.
    • 在以下情况时停止进一步提问:
      • 所有关键模糊性早期解决(剩余排队项目变得不必要), 或
      • 用户发出完成信号("done"、"good"、"no more"), 或
      • 你达到5个已问问题.
    • 永远不要提前揭示未来的排队问题.
    • 如果开始时没有有效问题, 立即报告没有关键模糊性.

  5. 每次接受答案后的集成(增量更新方法):

    • 维护规范的内存表示(开始时加载一次)加上原始文件内容.
    • 对于此会话中第一个集成的答案:
      • 确保 ## Clarifications 部分存在(如果缺失, 根据规范模板在最高级别的上下文 / 概述部分之后创建).
      • 在其下, 创建(如果不存在)今天的 ### Session YYYY-MM-DD 子标题.
    • 接受后立即追加项目符号行: - Q: <question> → A: <final answer>.
    • 然后立即将澄清应用到最合适的部分:
      • 功能模糊性 → 更新或在功能需求中添加项目符号.
      • 用户交互 / 角色区分 → 更新用户故事或角色子部分(如果存在), 包含澄清的角色、约束或场景.
      • 数据形状 / 实体 → 更新数据模型(添加字段、类型、关系)保持顺序; 简洁地记录添加的约束.
      • 非功能性约束 → 在非功能性 / 质量属性部分添加 / 修改可衡量标准(将模糊形容词转换为指标或明确目标).
      • 边缘情况 / 负面流程 → 在边缘情况 / 错误处理下添加新项目符号(或如果模板提供占位符则创建此类子部分).
      • 术语冲突 → 在整个规范中规范化术语; 仅在必要时通过添加一次 (formerly referred to as "X") 保留原始术语.
    • 如果澄清使早期模糊声明无效, 替换该声明而不是重复; 不留用过时的矛盾文本.
    • 每次集成后保存规范文件以最小化上下文丢失风险(原子覆盖).
    • 保持格式: 不重新排序不相关的部分; 保持标题层次结构完整.
    • 保持每个插入的澄清最小化和可测试(避免叙述性偏离).

  6. 验证(每次写入后执行, 最终再进行一次完整检查):

    • 澄清会话每个接受的答案只包含一个项目符号(无重复).
    • 总共询问(接受)的问题 ≤ 5.
    • 更新的部分不包含新答案旨在解决的持续模糊占位符.
    • 没有矛盾的早期声明保留(扫描已删除的现在无效的替代选择).
    • Markdown 结构有效; 仅允许新标题: ## Clarifications、### Session YYYY-MM-DD.
    • 术语一致性: 所有更新部分使用相同的规范术语.

  7. 将更新的规范写回 FEATURE_SPEC.

  8. 报告完成(提问循环结束或提前终止后):

    • 询问和回答的问题数量.
    • 更新规范的路径.
    • 涉及的部分(列出名称).
    • 覆盖范围摘要表, 列出每个分类类别及状态: 已解决(曾是部分 / 缺失并已处理)、已推迟(超过问题配额或更适合规划)、清晰(已足够)、未完成(仍是部分 / 缺失但影响低).
    • 如果有任何未完成或已推迟的剩余, 建议是继续到 /speckit.plan 还是在规划后再次运行 /speckit.clarify.
    • 建议的下一个命令.

行为规则:

  • 如果没有发现有意义的模糊性(或所有潜在问题都是低影响的), 回应: "No critical ambiguities detected worth formal clarification." 并建议继续.
  • 如果规范文件缺失, 指示用户首先运行 /speckit.specify(不要在此创建新规范).
  • 永远不要超过总共5个询问的问题(单个问题的澄清重试不计为新问题).
  • 避免推测性技术堆栈问题, 除非缺失阻碍功能清晰性.
  • 尊重用户提前终止信号("stop"、"done"、"proceed").
  • 如果由于完全覆盖而没有提问, 输出紧凑的覆盖范围摘要(所有类别清晰)然后建议前进.
  • 如果达到配额但仍有未解决的高影响类别, 在已推迟下明确标记它们并附上理由.

优先级排序的上下文: $ARGUMENTS