来考考我吧 — 通过系统性追问达成共识
理念
追问的目的是在代理和用户之间建立共同理解。每个计划都包含隐含假设、未陈述的约束和模糊的决策。追问会逐一走遍决策树的每个分支,直到双方完全对齐。
目标是在开始实施之前,消除所有未经审视的假设。
核心指令
- 每个问题都使用 AskUserQuestion。 所有追问必须通过
AskUserQuestion工具提出。绝不能将问题以纯文本形式输出。 - 在领域内分批提问。 在同一个追问领域内,将最多4个相关问题分组到一次
AskUserQuestion调用中。永远不要在一次调用中混合不同领域的问题。 - 始终先给出你的建议。 你的推荐答案总是第一个选项,并在标签后附加
(推荐)。 - 先探索再提问。 如果通过阅读代码库、文档或检查现有模式就能找到答案,那就去做,而不是提问。只向用户询问需要他们判断的决策。
- 按依赖顺序解决。 有些决策依赖于其他决策。识别依赖链并先解决上游决策。
- 使用结构化记录跟踪所有内容。 使用结构化表格维护决策日志。每个已解决的问题记录:领域、主题(标题)、所选选项标签,以及如果选择了“其他”则记录自定义文本。在对话上下文中呈现日志,无需文件 I/O。
- 不留假设。 如果某件事是隐含的但未说明,就把它呈现出来。如果某件事看起来很明显,也需要确认。共同理解意味着明确的共识,而非舒适的沉默。
- 保持具体。 将问题框定在具体行为、数据流和用户可见的结果上,而不是抽象概念。
追问前准备
在提问之前,先静默构建上下文:
- 阅读用户想要追问的计划或设计文档
- 浏览代码库,了解现有模式、约束和相关的代码
- 查看最近的 git 历史记录,了解当前工作的背景
- 阅读 project.md 和 CLAUDE.md,了解项目约定
然后,按追问领域组织,简要总结你目前的理解。这使用户有机会在深入分支提问之前纠正重大误解。
追问领域
按照 references/interrogation-domains.md 中定义的领域逐步推进。根据计划调整顺序 — 从与构建内容最核心的领域开始,并向外扩展。跳过明显无关的领域。
追问流程
1. 阅读并总结你对计划的理解
2. 用户确认或更正总结
3. 对于每个追问领域(按相关程度排序):
a. 识别该领域中的所有决策点和假设
b. 将相关决策点分为每组最多4个问题
c. 对于每组,执行一次 AskUserQuestion 调用
(每个问题先提出推荐)。记录所有选择的选项。
d. 解决领域中的所有问题后,总结做出的决策
以结构化表格形式呈现该领域的决策行。
4. 覆盖所有领域后:
- 以结构化表格形式呈现完整的决策日志:
| # | 领域 | 主题 | 决策 | 备注 |
|---|------|------|------|------|
| 1 | 意图 | 目标 | 其他 | 面向运维团队的内部仪表盘,不面向客户 |
- 标记任何未解决或推迟的项目
- 询问是否需要重新审视任何领域
问题格式
每个问题必须通过 AskUserQuestion 工具提出。每个调用结构如下:
{
"question": "当 Oura API 返回 429 错误时,我们应该如何处理速率限制?",
"header": "速率限制",
"options": [
{
"label": "指数退避(推荐)",
"description": "使用指数退避(1秒、2秒、4秒)重试。优雅地处理瞬时限制,并与 src/api_client.py 中已有的重试模式匹配。"
},
{
"label": "排队等待下次运行",
"description": "跳过请求,将其添加到下一次预定运行中。更简单,但会将数据延迟一个周期。"
}
],
"multiSelect": false
}
依赖于: 在问题的文本中说明此问题所依赖的任何先前决策,或者如果独立则注明“无依赖”。
批量提问示例
{
"questions": [
{
"question": "主要的部署目标是什么?",
"header": "部署",
"options": [
{
"label": "Docker + ECS(推荐)",
"description": "与现有基础设施匹配。部署管道已存在。"
},
{
"label": "Kubernetes",
"description": "更灵活,但需要新的基础设施设置。"
},
{
"label": "Serverless",
"description": "运维负担较低,但冷启动延迟令人担忧。"
}
],
"multiSelect": false
},
{
"question": "我们应该包含哪些监控方法?",
"header": "监控",
"options": [
{
"label": "结构化日志(推荐)",
"description": "向 CloudWatch 输出 JSON 日志。可搜索并可设置告警。"
},
{
"label": "APM 追踪",
"description": "分布式追踪,用于请求流的可见性。"
},
{
"label": "自定义指标",
"description": "Datadog 中的业务特定计数器和仪表。"
}
],
"multiSelect": true
}
]
}
使用预览
当用户需要在视觉上比较具体产物(代码片段、架构图、模式形状或配置示例)时,可以在选项中使用 preview 字段。预览内容在等宽框中渲染为 markdown,并支持并排比较。
何时使用预览:
- 比较两种代码模式或实现
- 展示不同的模式形状或数据结构
- 使用 ASCII 图呈现架构备选方案
约束: 预览仅适用于单选(multiSelect: false)。如果需要多选,请省略预览并使用描述。
预览示例:
{
"question": "我们应该使用哪种数据管道模式?",
"header": "管道",
"options": [
{
"label": "生成器管道(推荐)",
"description": "惰性求值,对大内存数据集来说内存效率高。",
"preview": "def pipeline(source):\n for record in source:\n cleaned = clean(record)\n validated = validate(cleaned)\n yield validated"
},
{
"label": "批处理管道",
"description": "一次性处理所有记录。更简单但内存使用更高。",
"preview": "def pipeline(source):\n records = list(source)\n cleaned = [clean(r) for r in records]\n validated = [validate(r) for r in cleaned]\n return validated"
}
],
"multiSelect": false
}
提问规则
- 每个问题都使用 AskUserQuestion。 没有例外。
- 第一个选项 = 推荐。 第一个选项的标签始终包含
(推荐)。 - 相关的问题一起提。 将同一领域中最多4个相关问题分组到一次 AskUserQuestion 调用中。跨领域的问题必须用单独的调用。
- 尊重工具约束。 每个问题2-4个选项。标题最多12个字符。当选项不是互斥的时(例如,“我们应该使用哪些测试方法?”或“哪些领域需要覆盖?”),使用
multiSelect: true。 - 过滤选项。 当有超过4个有效选项时,根据代码库上下文展示最相关的3个。对于未列出的选项,用户选择“其他”。
- 具体化。 “我们应该如何处理错误?”太模糊了。“当 Oura API 返回 429 时,我们应该是用退避重试还是排队等待下次运行?”才是具体的。
- 展示你的依据。 如果你的推荐基于在代码库中发现的内容,请引用文件和行号。
- 接受答案。 用户做出决定后,记录下来并继续推进。除非后续决策与之前决策产生冲突,否则不要重新争论。
后备方案(当 AskUserQuestion 不可用时)
如果运行时环境中没有 AskUserQuestion,请回退到以下文本格式:
[标题] — [主题]
[问题的清晰陈述]
推荐: [你的推荐及其原因]
备选方案:
- (A)[选项] — [权衡]
- (B)[选项] — [权衡]
何时结束
当以下条件满足时,追问完成:
- 已覆盖所有相关的追问领域
- 所有决策分支都已解决或明确推迟
- 用户确认达成共识