asking-clarifying-questions

提出澄清问题

概述

理解用户的真实意图，而非仅仅照搬他们的表述，从而弥合原始用户输入与结构化头脑风暴之间的鸿沟。

核心原则： 先解决矛盾，再消除歧义。必须先协调相互冲突的目标，再进行技术层面的澄清——否则你只是在精确定义错误的事情。

开始时宣布：“我正在使用提出澄清问题技能，以确保正确理解你的需求。”

何时使用

在以下情况下使用此技能：

• 收集用户的初始背景信息后
• 开始头脑风暴或设计探索前
• 用户提到可能有多种含义的技术术语时
• 范围边界不明确时
• 需要验证假设时

不要用于：

• 探索设计方案（那属于头脑风暴）
• 提出架构方案（那属于头脑风暴）
• 验证已完成的设计（那属于头脑风暴的第 3 阶段）
• 询问初始需求（那属于制定设计计划的第 1 阶段）

澄清之前

尝试根据工作目录中的上下文自行回答问题并消除歧义。使用可用的子 Agent（例如 codebase-investigator）探索现有工作，以帮助解释待澄清的主题。当你发现常见技术或专有名词等内容时，应改用 combined-researcher，综合代码库和互联网搜索结果。

你可能还拥有包含有用信息的其他技能或 MCP，例如用于产品管理的远程数据存储连接。在适当时，应派遣 haiku-general-purpose 子 Agent 调查这些资源。

禁止嵌套派遣子 Agent： 只有当前调用方可以派遣这些研究子 Agent。请告知每个子 Agent 直接完成工作，不要再派遣其他子 Agent。

需要澄清的内容

0. 矛盾（第一轮检查）

在消除技术细节的歧义之前，先检查需求中是否存在逻辑矛盾。如果用户提出了相互排斥的目标，应先解决这些矛盾——如果基础需求都可能改变，技术层面的澄清就是徒劳。

留意以下情况：

明确矛盾（用户同时提出了两点）：

• “实时更新” + “批处理也可以” → 实际需求是什么？
• “保持简单” + “处理所有边缘情况” → 尚未明确权衡
• “沿用现有模式” + “彻底重写” → 两种方法互相排斥
• “不使用外部依赖” + “集成 Stripe” → 隐含矛盾

不可能兼得的组合：

• “离线优先” + “数据始终保持最新” → 违背物理规律
• “快速构建” + “无限扩展” → 经典的不可能三角
• “零延迟” + “同步验证” → 二者无法兼得
• “不引入破坏性变更” + “进行根本性重新设计” → 必须二选一

未明确的权衡：

• “简单”往往与“灵活”冲突
• “快速”往往与“全面”冲突
• “廉价”往往与“定制”冲突
• “安全”往往与“便捷”冲突

如何指出：

不要指责，而是点明其中的矛盾：

• “我注意到你提到了 X 和 Y——二者可能会相互牵制。你更看重哪一项？”
• “这里需要在 A 和 B 之间权衡。对这个项目来说，哪一点更重要？”
• “这两个目标有时会冲突——发生冲突时，你希望我如何权衡？”

为什么要先处理：

• 矛盾揭示了尚未正视的权衡
• 解决矛盾会改变“正确”的含义
• 不先处理这些矛盾就澄清技术细节 = 精确地构建错误的东西

解决矛盾后，再进行技术层面的澄清。

1. 技术术语

当用户提到技术术语时，先明确他们实际指的是什么。

示例：

用户说“OAuth2” -> 询问：使用哪种流程？

• 授权码流程（适用于通过浏览器重定向登录的人类用户）
• 客户端凭据流程（适用于服务间身份验证）
• 根据使用场景，两者都可能适用

用户说“数据库” -> 询问：是哪种类型？

• SQL（PostgreSQL、MySQL），用于结构化数据
• NoSQL（MongoDB、DynamoDB），用于灵活的架构
• 已由现有基础设施决定

用户说“缓存” -> 询问：在哪一层？

• 应用级（Redis、Memcached）
• HTTP 缓存（CDN、浏览器缓存）
• 数据库查询缓存

对此使用 AskUserQuestion——提供具体选项及其权衡。

2. 范围边界

当用户提到宽泛的概念时，明确哪些内容包含在内，哪些不包含。

示例：

用户说“用户” -> 询问：具体指哪些用户？

• 通过 Web 浏览器登录的人类用户
• 用于 API 访问的服务账号
• 两者都有，但使用不同的身份验证流程
• 内部员工与外部客户

用户说“与 X 集成” -> 询问：具体涉及哪些部分？

• 仅身份验证
• 完整的数据同步
• 特定 API 端点
• 实时 Webhook 还是批量导入

用户说“报告” -> 询问：范围是什么？

• 基本数据导出（CSV、Excel）
• 交互式仪表板
• 定时自动生成报告
• 实时分析

使用 AskUserQuestion——提供明确区分的范围选项。

3. 假设和约束

当用户提出需求时，核实其背后的原因和约束。

示例：

用户说“必须使用库 X” -> 询问：为什么？

• 监管要求（不能更改）
• 团队已有相关经验（偏好，并非硬性要求）
• 已在其他地方使用（有利于保持一致性）
• 误解（可能有更好的选择）

用户说“需要很快” -> 询问：要多快？

• 响应时间低于 100 ms（硬性要求）
• 比当前实现更快（相对改进）
• 体感速度（乐观 UI、加载状态）
• 已发现实际性能瓶颈

用户说“应该遵循模式 Y” -> 询问：具体是哪个方面？

• 完全相同的实现（严格保持一致）
• 整体方法（灵活调整）
• 仅使用相同的库（工具链一致性）
• 实际上并非必需（已过时的指南）

使用开放式问题来了解“为什么”，以便用户解释背景。

4. 版本和 API 细节

当用户提到外部服务或库时，核实其当前情况。

示例：

用户说“与 Stripe 集成” -> 检查：

• 使用哪个 Stripe API 版本（最新版本？特定版本？）
• 使用 Payment Intents API，还是较旧的 Charges API
• 需要哪些功能（一次性付款、订阅，还是两者都有）
• 是否已设置 Stripe 账号

用户说“使用 React Router” -> 检查：

• 使用 React Router v5 还是 v6（版本间存在破坏性变更）
• 是否已在代码库中使用（遵循现有模式）
• 使用 Browser Router、Hash Router 还是 Memory Router

用于事实核查的快速 Agent 查询：

• “X 有哪个版本？” -> 快速网页搜索或检查代码库
• “当前 API 是什么？” -> 在线查阅文档
• “是否已在使用 Y？” -> 调查代码库

不要进行深入研究——将其留给头脑风暴。只核实基本信息。

5. 完成定义（必需的最后一步）

在交接给头脑风暴之前，必须明确完成定义。

完成定义回答的是：“成功是什么样的？交付物有哪些？”

解决矛盾并澄清需求后：

1. 根据目前收集到的上下文，推断完成定义：

   • 完成后会有哪些成果？
   • 用户／系统将能够做什么？
   • 具体的交付物有哪些？

2. 如果你已充分掌握情况，请复述并确认：

   Use AskUserQuestion:
   "Based on our discussion, here's what I understand success looks like:
   
   [State the definition of done in 2-4 bullet points]
   
   Does this capture what you're trying to achieve?"
   
   Options:
   - "Yes, that's right" (proceed to brainstorming)
   - "Partially, but..." (user will clarify)
   - "No, let me explain..." (user will reframe)
   

3. 如果交付物仍不明确，请提出有针对性的问题：

   • “完成后应该有哪些成果？”
   • “如何判断这是否成功？”
   • “最低可行交付物是什么？”

为什么这很重要： 头脑风暴探索的是如何实现目标。必须先明确目标，否则你只是在探索纹理，却不知道要填充成什么形状。

完成定义会成为输出包的一部分，并在最终设计文档顶部醒目呈现。

提问技巧

使用 AskUserQuestion 让用户做出选择

当存在 2 到 4 个各有利弊的选项时：

Question: "Which OAuth2 flow are you targeting?"
Options:
  - "Authorization code flow" (human users with browser redirect)
  - "Client credentials flow" (service-to-service automated auth)
  - "Both flows" (supports human users AND service accounts)

优点：

• 促使用户明确做出选择
• 清晰展示利弊
• 避免含糊的“也许都要”式回答
• 采用适合决策的结构

使用开放式问题了解原因

需要了解理由或背景时：

“为什么 X 是一项要求？” “Y 解决了什么问题？” “如果不包含 Z，会发生什么？”

优点：

• 揭示隐藏的限制条件
• 展现用户的思维模式
• 找出需要质疑的假设
• 为头脑风暴提供背景

使用快速查询核实事实

需要核实事实时：

• 派发代码库调查员：“是否已在使用库 X？”
• 快速搜索网页：“API Y 的当前版本是什么？”
• 读取文件：“检查 package.json 中是否已有身份验证依赖项”

不要分心——这些只是快速检查，不是研究项目。

输出：供头脑风暴使用的上下文包

澄清后，创建一份清晰的摘要，供头脑风暴环节使用：

已解决的权衡：

• 速度优先于灵活性（选择简单的实现，接受较低的可配置性）
• 安全优先于便利性（选择严格验证，接受更多操作阻力）
• 一致性优先于理想方案（选择现有模式，接受其单独来看并非最优）

已澄清的需求：

• OAuth2 客户端凭据流程（服务到服务）
• 仅面向外部客户（不包括内部员工）
• Stripe Payment Intents API（最新版本）
• 必须符合 PCI DSS Level 1（监管要求）
• “快速”指 p99 响应时间低于 200 毫秒（可测量的要求）

已核实的假设：

• 已在使用 React Router v6（遵循现有模式）
• PostgreSQL 数据库（现有基础设施）
• 没有现有身份验证系统（全新项目）

范围边界：

• 包含：服务账号创建、令牌签发、令牌验证
• 不包含：人类用户登录、SSO 集成、密码管理

此上下文包为头脑风暴提供了具体、明确的起点。

常见错误

错误	修正方法
忽略需求中的矛盾	在技术澄清前，先指出相互冲突的目标
不加区分地接受模糊说法	明确每个技术术语的含义
未经核实就假设范围	明确询问范围边界
不质疑“必须具备”的要求	了解限制条件背后的原因
澄清期间进行深入研究	只做快速检查，将研究留到头脑风暴阶段
澄清时提出解决方案	保持理解模式，暂不设计
“看起来很清楚”就跳过澄清	始终进行澄清，假设很危险

何时停止澄清

遇到以下情况时，停止澄清并开始头脑风暴：

• 矛盾已解决（已明确选择取舍方案）
• 技术术语已消除歧义
• 范围边界已明确
• 已理解约束条件（而非仅仅陈述）
• 假设已验证
• 不再存在重大歧义

不需要掌握完美的信息——只需有足够的信息来有效开展头脑风暴。

如果头脑风暴发现了新的歧义，可以返回澄清阶段。

与设计工作流的衔接

此技能位于收集上下文与头脑风暴之间：

Context Gathering (starting-a-design-plan Phase 1)
  -> User provides: "Build OAuth2 integration for our API"

Clarification (this skill)
  -> Disambiguate: Which OAuth2 flow? What scope? Why OAuth2?
  -> Output: Service accounts, client credentials, PCI compliance

Brainstorming (starting-a-design-plan Phase 3)
  -> Explore: Architecture options, library choices, implementation phases
  -> Uses clarified requirements as foundation

目的： 确保头脑风暴构建的是正确的东西，而不是把错误的东西做得很好。