clarify

用户输入

$ARGUMENTS

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

语言要求

• 所有澄清问题、建议、表格、规范更新、覆盖摘要和完成报告都必须使用简体中文。
• 为保证精确性，技术术语、ID 和文件路径在需要时保留原始形式。

概述

目标：识别并减少当前功能规范中的歧义与缺失决策点，并将澄清结果直接写回规范文件。

说明：该澄清流程应当在执行计划命令之前完成。大多数 agent 使用 /speckit.plan，Codex CLI 使用 /prompts:speckit-plan。如果用户明确表示跳过澄清（例如仅做探索性验证），则可以继续，但必须提醒其后续返工风险会提高。

执行步骤：

第 1 步：获取前置环境信息

从仓库根目录执行 {SCRIPT} 一次（使用 --json --paths-only / -Json -PathsOnly 模式），解析以下最小 JSON 字段：

• FEATURE_DIR
• FEATURE_SPEC
• （可选：捕获 IMPL_PLAN、TASKS 以便后续链式流程使用）

若 JSON 解析失败，立即中止并告知用户重新运行 spec 命令（/speckit.specify 或 Codex /prompts:speckit-specify）或检查功能分支环境。

参数中如包含单引号（如 "I'm Groot"），请使用转义语法：'I'\''m Groot'（或尽量使用双引号："I'm Groot"）。

第 2 步：加载规范并执行结构化歧义扫描

加载当前规范文件，按以下分类体系进行覆盖度扫描。对每个类别标记状态：清晰 / 部分 / 缺失。生成内部覆盖度映射用于优先级排序（除非不会提出任何问题，否则不直接输出原始映射）。

功能范围与行为

• 核心用户目标与成功标准
• 明确的范围外声明
• 用户角色 / 用户画像的区分

领域与数据模型

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

交互与用户体验流程

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

非功能质量属性

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

集成与外部依赖

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

边界情况与故障处理

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

约束与权衡

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

术语与一致性

• 规范词汇表中的权威术语
• 需避免的同义词 / 已废弃术语

完成信号

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

其他 / 占位符

• TODO 标记 / 未决决策
• 缺乏量化的模糊形容词（如"健壮""直观"）

对每个状态为部分或缺失的类别，添加候选问题机会，除非：

• 澄清该问题不会实质性影响实现或验证策略
• 该信息更适合在计划阶段再明确（在内部记录）

第 3 步：生成优先澄清问题队列

在内部生成最多 5 个候选澄清问题（不得一次性全部输出）。须遵守以下约束：

• 整个会话最多 5 个问题。
• 每个问题必须可通过以下方式之一回答：
  • 简短的多选（2–5 个互斥选项），或
  • 一词 / 短语回答（明确约束："请用 ≤5 个词回答"）。
• 只包含答案会实质性影响架构、数据建模、任务分解、测试设计、用户体验行为、运营就绪度或合规验证的问题。
• 确保类别覆盖均衡：优先覆盖影响最高的未解决类别；避免在单个高影响领域（如安全态势）未解决时询问两个低影响问题。
• 排除已回答的问题、琐碎的风格偏好或计划层面的执行细节（除非会阻塞正确性）。
• 优先选择能降低下游返工风险或防止验收测试不对齐的澄清问题。
• 若 5 个以上类别仍未解决，按"影响 × 不确定性"启发式选取前 5 个。

第 4 步：顺序提问循环（交互式）