intent-confirmation · git:20260730.e815cfb · 2026-07-30 · sha256 8ff20976bb4d3057
intent-confirmation git:20260730.e815cfbA
Immutable. This exact content is served forever at /api/v1/blob/8ff20976bb4d3057.
---
disable-model-invocation: true
name: intent-confirmation
description: >
当用户的请求在执行前需要澄清目标、边界或实现思路时使用：需求抽象、涉及架构
或设计决策、影响范围大、存在多种实现路径、可能修改重要文件、用户思路尚不清晰，
或用户明确要求先确认。也用于 R&K Flow 阶段门禁（需求对齐、plan/test-plan 确认、
归档/提交前确认）。本 skill 要求提问前先交代「我做了什么、发现了什么、要你决策
什么」，再复述理解并主动反问，帮用户补全信息并梳理代码编写思路，而不是只做
「是/否」确认，也不是不给背景就抛问题。不要用于简单问答、只读查询、明确的
小修小改、已确认 Spec 的直接执行，或用户已明确表示「直接做、不用问」。
---
# 意图确认规范
## 概述
本 Skill 定义 Agent 在执行任务前与用户对齐意图的标准流程。目标不仅是「避免理解偏差」，更是：
1. **让用户知道你问的是什么** — 提问必须自带上下文
2. **读懂用户真正要什么**
3. **用反问补全缺失信息**
4. **帮用户把模糊想法梳成可写代码的思路**
5. **在 R&K 关键节点把门禁结论和决策理由落盘**
确认通过后，用户应对「目标 / 范围 / 关键取舍 / 大致实现路径」有共同画面；Agent 再动手。
## 核心原则
1. **先交代情境，再提问** — 用户不该为了理解你的问题去猜你刚做了什么
2. **先理解，再反问，后确认** — 不是复读原话，也不是上来就写代码
3. **反问为了梳理思路** — 问题应推动用户想清：改哪里、先做什么、成功长什么样
4. **短而可执行** — 复述用可落地条目；反问 2–5 个阻塞点，不审讯
5. **带假设反问** — 每个问题尽量附「我的默认理解是 X，对吗？」，降低用户负担
6. **少问精问** — 仓库/上下文能推断的不问；只问影响设计与编码路径的点
7. **运行时中立** — 优先结构化提问（OMP: `ask`）；无 UI 时用文本
8. **门禁与决策落盘** — 门禁结论写入 `lead/team-context.md` 的 `Gate Decisions`；决策的选项、结论和理由写入 `Decision Log`
## 四步工作法
```text
用户提出需求
↓
Step 0 · 情境交代（Situation Brief）【强制前置】
- 我做了什么：读了哪些文件、跑了什么命令、查了什么
- 我发现了什么：与提问直接相关的事实和结论
- 卡在哪：为什么这件事我不能自己定
- 要你决策什么：一句话点题
↓
Step A · 理解转述
- 用自己的话写成可执行目标
- 标出已假设的默认值
- 标出明显边界（做 / 暂不做）
↓
Step B · 反问梳理（编码思路）
- 针对缺口提 2–5 个关键问题
- 覆盖：目标验收、范围、触点、路径取舍、约束、风险
- 每问尽量带推荐默认
↓
Step C · 收敛确认
- 合并用户回答，输出「编码思路小结」
- 请用户确认或修正
- 通过 → 落盘 Decision Log → 执行 / 进入下一 Spec 阶段
- 不通过 → 回到 B 补问，不开工
```
**禁止**：不给情境直接抛问题，让用户猜「你在问什么东西」。
**禁止**：只做「是这个意思吗？是/否」就结束，却不帮用户想清怎么写。
**禁止**：反问变成技术审讯（一次抛十个实现细节）。
**允许**：用户说「你定/按你说的」时，采用已声明的推荐默认并写进小结与 `Decision Log`。
## Step 0 · 情境交代（必读）
用户最常见的抱怨是「Agent 直接问我问题，我不知道他在问什么」。根因是提问缺少前置状态同步。任何提问前，先输出四段极短情境，每段 1–3 行：
| 段 | 内容 | 反例 |
|----|------|------|
| **已做（Did）** | 具体动作 + 对象：读了 `x.py`、跑了 `pytest tests/y`、查了配置 | 「我调研了一下」（没说查了什么） |
| **发现（Found）** | 与本次提问因果相关的事实/结论，带证据位置 | 「有点问题」（没说什么问题、在哪） |
| **卡点（Blocked）** | 为什么这是用户的决策而非你能定的默认 | 直接跳到问题，不说为何要问 |
| **求决策（Need）** | 一句话点明要拍板的事 | 「你怎么看？」 |
规则：
- **有证据**：`Found` 的每条结论尽量带文件路径、行号、命令名或报错关键字。
- **可省不省**：即使只有一个问题，也要有 `Did` + `Need`；`Found`/`Blocked` 无实质内容时可各一行说明。
- **不复述全文**：情境总长控制在 10 行内；细节放已落盘的产物路径，让用户按需查。
- **结构化提问同样适用**：`ask` 的 UI 只承载选项，情境写在 `ask` 之前的正文里；不要把整段情境塞进 `question` 字段。
- **零调查时说明**：如果还没做任何调查就要提问（如刚接到需求），`Did` 写「尚未动代码，仅读取你的需求描述」，不要编造调查动作。
### 情境交代模板
```text
【已做】
- 读了 services/report_publish.py:120-180、config/cache.yaml
- 跑了 pytest tests/test_publish.py（12 passed）
【发现】
- 缓存命中/未命中两条分支都没有日志，命中率无法观测（report_publish.py:143、:151）
- 现有 logger 是纯文本格式，没有结构化字段
【卡点】
- 加结构化日志会改动现有 logger 输出格式，可能影响你们已有的日志采集，这不是我能替你定的
【要你决策】
- 日志格式：沿用纯文本，还是切 JSON 结构化？
```
紧接其后才是 Step A 的理解转述与 Step B 的反问。
### 情境交代质量自检
提问前自问三条，任一为「否」就先补情境再问：
1. 用户只看我这条消息，能否明白我为什么问这个问题？
2. 我给出的每个选项，用户能否判断它的后果？
3. 我是否把「能自己查到的事实」错当成了「要用户回答的问题」？
## 反问维度（编码思路清单）
按任务需要选用，不必全问。优先问**阻塞编码**的项：
| 维度 | 反问目的 | 示例问法 |
|------|----------|----------|
| **目标与验收** | 怎样算做完 | 「上线标准是单测通过，还是要有可演示接口？」 |
| **范围边界** | 做/不做 | 「本次只改后端，前端先不动，可以吗？」 |
| **用户/调用链** | 谁触发、输入输出 | 「是 SSE 流式返回，还是 REST 一次返回？」 |
| **代码触点** | 改哪些模块 | 「我倾向动 `services/report_*.py`，是否还有别的入口？」 |
| **实现路径** | 方案分叉 | 「A 最小补丁 / B 抽公共层，你更倾向？我建议 A」 |
| **数据与状态** | 存哪、兼容性 | 「是否要兼容旧缓存 key？」 |
| **约束** | 时间/兼容/性能 | 「必须保持现有 API 字段不变吗？」 |
| **风险与回滚** | 怕踩什么坑 | 「若命中失败，是降级查库还是直接报错？」 |
| **验证方式** | 怎么证明对了 | 「用现有 pytest，还是要补一条 e2e？」 |
| **优先级切片** | MVP vs 完整 | 「先做可运行 MVP，细节二期？」 |
### 好的反问
- 绑定用户原话中的模糊点
- 给出 2–4 个互斥选项 + 推荐默认
- 帮用户做取舍，而不是要用户从零设计
- 问完能直接写出 plan 或动手步骤
### 差的反问
- 「你有没有想过用设计模式？」类空泛题
- 重复用户已说清的内容
- 一次要用户写整份技术方案
- 与当前阶段无关（需求对齐时追问 commit message 格式）
- 无情境裸问：「用 A 还是 B？」但没说 A/B 是什么、你为何在这里遇到分叉
## 触发条件
### 需要走本规范
| 场景 | 说明 | 示例 |
|------|------|------|
| **抽象需求** | 描述模糊 | 「优化一下这个功能」 |
| **思路未成形** | 用户知道痛点但不知怎么改 | 「这里总是重复代码，想整理下」 |
| **设计决策** | 架构/方案分叉 | 「重构用户认证模块」 |
| **多义表达** | 多种解读 | 「更新文档」 |
| **大范围影响** | 跨模块/协议 | 「统一错误处理」 |
| **多步骤任务** | 复杂链路 | 「实现用户注册流程」 |
| **R&K 门禁** | 阶段切换 | 需求对齐、批准实现、归档/PR |
| **破坏性操作** | 高风险 | 清库、强推、改生产配置 |
### 可跳过或极简
| 场景 | 处理 |
|------|------|
| 明确简单任务 | 直接做（如「运行测试」） |
| 已确认 Spec | 按 plan 执行，不重开需求讨论 |
| 信息查询 | 直接答 |
| 单点小修 | 直接改 |
| 用户豁免 | 「直接做，不用问」→ 执行，但破坏性操作仍要拦 |
## 运行时适配
### OMP（推荐）
用 `ask` 做结构化反问与确认。**调用 `ask` 前必须先在正文输出 Step 0 情境交代**，`ask` 只承载选项：
- 每题 `id` / `question` / `options`（2–5 项）
- **不要**手写 Other（UI 自带）
- `recommended`：你的默认建议
- `multi: true`：范围多选（模块、验收项）
- 可分两轮：先「理解 + 关键取舍」，再「编码思路小结确认」
- headless：改用文本模板，等用户下一条消息
- 每个 `option` 的 `description` 写清「选了它会发生什么」，不要只写方案名
**反问示例（梳理实现路径）：**
先输出情境（正文）：
```text
【已做】读了 services/report_publish.py 的 publish 管线，跑通现有 pytest
【发现】命中/未命中两条分支都无日志；现有 logger 为纯文本
【卡点】改 logger 格式会影响既有日志采集，需要你拍板
【要你决策】验收标准、实现路径、改动范围
```
再发起结构化提问：
```text
ask({
questions: [
{
id: "goal",
question: "我理解目标是：报告缓存命中时写出可检索日志。成功标准选哪个？",
options: [
{ label: "单测覆盖关键分支即可", description: "推荐，改动小" },
{ label: "单测 + 本地手跑一条请求看日志" },
{ label: "还要 e2e / 线上可观测字段" }
],
recommended: 0
},
{
id: "path",
question: "实现路径我建议最小补丁。你选？",
options: [
{ label: "A 最小补丁", description: "只在 publish 管线命中/未命中处打日志" },
{ label: "B 抽统一 logging helper", description: "多点复用，改动面更大" },
{ label: "先只写 plan，不改代码" }
],
recommended: 0
},
{
id: "scope",
question: "本次范围？",
options: [
{ label: "仅后端", description: "推荐" },
{ label: "后端 + SSE 事件字段" },
{ label: "后端 + 文档/注释" }
],
recommended: 0,
multi: false
}
]
})
```
**收敛确认示例：**
```text
ask({
questions: [{
id: "approach_ok",
question: "编码思路小结：1) 只改后端 publish 管线 2) 命中/未命中各打结构化日志 3) 补单测 4) 不改 API。按此开始？",
options: [
{ label: "按此开始" },
{ label: "基本可以，我补充一点" },
{ label: "不对，重梳思路" }
],
recommended: 0
}]
})
```
### Claude Code / 其他
- 有原生提问 UI 则用；否则用下方文本模板
- 不要写死 `AskUserQuestion` / `TodoWrite` 等工具名
## 文本模板
### 0. 情境交代（提问前强制）
```text
【已做】…（读了哪些文件 / 跑了什么命令 / 查了什么）
【发现】…（与提问相关的事实，带路径或报错关键字）
【卡点】…（为什么需要你定）
【要你决策】…（一句话）
```
### A. 理解转述
```text
我先用自己的话理解你的目标：
- 目标：…
- 范围：…（默认：…）
- 不做：…
我的默认假设：…
```
### B. 反问梳理
```text
为把编码思路定清楚，需要你拍板：
1. [验收] …？我建议 …
2. [路径] A … / B …？我建议 A，因为 …
3. [范围] …？
你可以直接选建议项，或改条件。
```
### C. 编码思路小结（确认用）
```text
根据你的反馈，编码思路如下：
1. 入口/触点：改哪些文件或模块
2. 步骤顺序：先 … 再 … 最后 …
3. 关键取舍：选了 A 而非 B，因为 …
4. 验收：怎样算完成
5. 风险：…；回滚/降级：…
确认按此执行吗？
```
## R&K Flow 集成
| 时机 | 谁发起 | 情境交代要点 | 反问/确认重点 | 落盘 |
|------|--------|--------------|----------------|------|
| `spec-start` 阶段一 | TeamLead | 读了哪些既有代码/文档、当前仓库与分支状态 | 目标、范围、分类、分支、**实现思路粗纲** | `Gate Decisions` + `Decision Log` + `Next Action` |
| plan + test-plan 完成 | TeamLead | plan/test-plan 的核心方案与关键取舍摘要、未解风险 | 是否批准实现（不再重梳需求，除非用户改需求） | Gate：设计/测试计划确认 + `Decision Log` |
| 修复循环前 | TeamLead | 失败用例、已定位的根因或未定位的原因 | Loop Budget + 是否同意按诊断修 | `Loop Budget` + Gate + `Decision Log` |
| 循环触上限升级 | TeamLead | 已用轮数、每轮进展、仍失败的具体项 | 加预算 / 改方案 / 暂停 | `Loop Budget` + `Decision Log` |
| `spec-end` 前 | TeamLead/ender | 交付内容、测试结论、遗留问题 | 归档/提交/PR | end-report + Gate + `Decision Log` |
| `spec-update` | TeamLead | 本次更新触发原因、与原 Spec 的差异 | 更新范围是否仍在原 Spec | updater + Gate + `Decision Log` |
规则：
- **每个门禁提问都必须带 Step 0 情境交代**，禁止只发一句「确认吗」
- **阶段一必须反问梳理**，不能只「需求 ok 吗」
- TeamLead 对用户；子角色默认不直接连环问用户
- 子角色向 TeamLead 上报时也按 `Did / Found / Blocked / Need` 四段写，TeamLead 才能不改写就转述给用户
- 已批准的 `writer/plan.md` 执行期不重开需求研讨会，除非需求变更
- 反问得到的「编码思路小结」应能直接喂给 spec-explorer / spec-writer 作为输入
- 用户拍板后立即在 `lead/team-context.md` 的 `Decision Log` 追加一行，记录 `options`（当时给的选项）、`decision`、`rationale`、`decided_by: user`；被否决的选项不要丢，它是后续复盘的关键上下文
### spec-start 阶段一最小问题集
至少覆盖（可合并进 2–4 个 `ask` 题）：
1. 任务目标一句话 + 验收标准
2. 范围（模块/做不做前端或文档）
3. 实现倾向（最小补丁 / 重构 / 先调研）
4. Git：新分支 / 当前分支 / 先不建分支
## 确认后的行为
### 用户确认思路正确
1. 简短回执
2. 复杂任务用 `todo`（或等价工具）拆步
3. 进入对应流程（explore/write/execute…）
4. 把**编码思路小结**交给下游角色，避免 explorer/writer 重新猜
### 用户补充或纠正
1. 合并进小结
2. 若仍缺阻塞信息 → 再反问一轮（收敛，不发散）
3. 再确认后执行
### 取消 / 超时
- `ask` 取消：不执行
- 超时采用 recommended：必须声明「已按推荐项 X」，允许用户立刻推翻
## 质量标准
### 好
- 用户只看提问这条消息，就知道你做了什么、为什么问
- 用户离开对话时比进来时更清楚怎么写
- 有明确触点、步骤、验收、不做列表
- 反问带默认建议，选项带后果说明
- 与当前 R&K 阶段匹配
- 决策拍板后 `Decision Log` 有对应行
### 差
- 不给情境裸问，用户看不懂在问什么
- 只复读 + 「是吗？」
- 反问空泛或过多
- 替用户隐瞒风险假设却不声明
- 确认完不落盘、下游角色收不到思路小结
- 决策做了却不进 `Decision Log`，后续无从复盘
## 与其他 Skill 的协作
| Skill | 协作 |
|-------|------|
| `spec-start` | 阶段一强制本规范（理解+反问+确认） |
| `spec-explore` | 输入含已确认范围与思路要点，避免空泛探索 |
| `spec-write` | 基于确认后的思路写 plan，不另起炉灶改目标 |
| `spec-test` | 验收标准来自确认结果 |
| `spec-execute` | 已确认 plan → 直接实现 |
| `spec-debug` | 修前确认诊断；可轻量反问复现条件 |
| `spec-end` / `spec-update` | 结束与小迭代门禁 |
| `exp-reflect` | 长期偏好可在收尾沉淀 |
## 反模式
- **裸问**：不交代情境直接抛问题，用户不知道在问什么
- 审讯式连问，无推荐默认
- 选项只给方案名，不说选了会发生什么
- 把能自己查的事实包装成问题丢给用户
- 用户思路不清时直接开写，导致返工
- 用静默假设代替反问（尤其是 API 兼容、数据迁移、范围）
- 子 Agent 绕过 TeamLead 改门禁
- 决策不落 `Decision Log`，或只记结论不记被否决的选项和理由
- headless 硬调交互 UI 后卡住不降级
## 后续动作
1. 新 Spec → 继续 `/spec-start` 后续阶段
2. 小迭代 → `/spec-update`
3. 已有确认 plan → `/spec-execute`
4. 纯沟通澄清 → 输出思路小结后结束或按用户下一步做