git:20260622.71b252e to git:20260725.41a1808

234 added, 163 removed. Audit A to A.

---

disable-model-invocation: true

name: intent-confirmation

- description: 当用户的请求在执行前需要澄清目标或边界时使用：需求抽象、涉及架构或设计决策、影响范围大、存在多种实现路径、可能修改重要文件，或用户明确要求先确认。不要用于简单问答、只读查询、明确的小修小改或可安全直接执行的任务。

- allowed-tools: AskUserQuestion

+ description: >

+ 当用户的请求在执行前需要澄清目标、边界或实现思路时使用：需求抽象、涉及架构

+ 或设计决策、影响范围大、存在多种实现路径、可能修改重要文件、用户思路尚不清晰，

+ 或用户明确要求先确认。也用于 R&K Flow 阶段门禁（需求对齐、plan/test-plan 确认、

+ 归档/提交前确认）。本 skill 要求在复述理解后主动反问，帮用户补全信息并梳理

+ 代码编写思路，而不是只做「是/否」确认。不要用于简单问答、只读查询、明确的

+ 小修小改、已确认 Spec 的直接执行，或用户已明确表示「直接做、不用问」。

---

# 意图确认规范

## 概述

- 本 Skill 定义了 Agent 在执行任务前确认用户意图的标准流程。目的是避免因理解偏差导致的无效工作，确保 Agent 与用户对任务目标达成一致。

+ 本 Skill 定义 Agent 在执行任务前与用户对齐意图的标准流程。目标不仅是「避免理解偏差」，更是：

+ 1. **读懂用户真正要什么**

+ 2. **用反问补全缺失信息**

+ 3. **帮用户把模糊想法梳成可写代码的思路**

+ 4. **在 R&K 关键节点把门禁结论落盘**

+ 确认通过后，用户应对「目标 / 范围 / 关键取舍 / 大致实现路径」有共同画面；Agent 再动手。

## 核心原则

- **先确认，后执行** - 在执行任何非简单任务前，必须先复述用户意图并获得确认。

+ 1. **先理解，再反问，后确认** — 不是复读原话，也不是上来就写代码

+ 2. **反问为了梳理思路** — 问题应推动用户想清：改哪里、先做什么、成功长什么样

+ 3. **短而可执行** — 复述用可落地条目；反问 2–5 个阻塞点，不审讯

+ 4. **带假设反问** — 每个问题尽量附「我的默认理解是 X，对吗？」，降低用户负担

+ 5. **少问精问** — 仓库/上下文能推断的不问；只问影响设计与编码路径的点

+ 6. **运行时中立** — 优先结构化提问（OMP: `ask`）；无 UI 时用文本

+ 7. **门禁落盘** — R&K 关键结论写入 `lead/team-context.md` Gate Decisions

- ## 确认流程

+ ## 三步工作法

- ```

+ ```text

用户提出需求

↓

- 判断是否需要确认（见「触发条件」）

+ Step A · 理解转述

+ - 用自己的话写成可执行目标

+ - 标出已假设的默认值

+ - 标出明显边界（做 / 暂不做）

↓

- ┌─ 需要确认 ─────────────────────────┐

- │ 1. 复述用户意图 │

- │ 2. 列出关键理解点 │

- │ 3. 询问"是这个意思吗？" │

- │ 4. 等待用户确认 │

- │ ├─ 确认正确 → 开始执行 │

- │ └─ 需要修正 → 重新理解后再确认 │

- └────────────────────────────────────┘

+ Step B · 反问梳理（编码思路）

+ - 针对缺口提 2–5 个关键问题

+ - 覆盖：目标验收、范围、触点、路径取舍、约束、风险

+ - 每问尽量带推荐默认

↓

- ┌─ 无需确认 ─────────────────────────┐

- │ 直接执行任务 │

- └────────────────────────────────────┘

+ Step C · 收敛确认

+ - 合并用户回答，输出「编码思路小结」

+ - 请用户确认或修正

+ - 通过 → 执行 / 进入下一 Spec 阶段

+ - 不通过 → 回到 B 补问，不开工

```

- ## 触发条件

- ### 需要确认的场景

- | 场景 | 说明 | 示例 |

- |------|------|------|

- | **抽象需求** | 需求描述较为抽象或模糊 | "优化一下这个功能" |

- | **设计决策** | 涉及架构变更或设计选择 | "重构用户认证模块" |

- | **多义表达** | 用户表达可能有多种理解 | "更新文档"（哪个文档？更新什么？） |

- | **大范围影响** | 任务影响范围较大 | "统一项目的错误处理方式" |

- | **隐含假设** | 需要做出假设才能执行 | "添加一个新功能"（具体什么功能？） |

- | **多步骤任务** | 涉及多个步骤的复杂任务 | "实现用户注册流程" |

+ **禁止**：只做「是这个意思吗？是/否」就结束，却不帮用户想清怎么写。

+ **禁止**：反问变成技术审讯（一次抛十个实现细节）。

+ **允许**：用户说「你定/按你说的」时，采用已声明的推荐默认并写进小结。

- ### 无需确认的场景（例外情况）

+ ## 反问维度（编码思路清单）

- | 场景 | 说明 | 示例 |

- |------|------|------|

- | **明确简单任务** | 任务明确且简单 | "提交代码"、"运行测试" |

- | **详细 Spec** | 用户已给出详细的 Spec 文档 | "按照 plan.md 执行" |

- | **信息查询** | 纯粹的信息查询 | "这个函数是做什么的？" |

- | **单文件操作** | 针对特定文件的简单操作 | "修复 login.js 第 42 行的拼写错误" |

- | **用户明确指示** | 用户明确表示不需要确认 | "直接做，不用问我" |

+ 按任务需要选用，不必全问。优先问**阻塞编码**的项：

- ## 确认话术模板

+ | 维度 | 反问目的 | 示例问法 |

+ |------|----------|----------|

+ | **目标与验收** | 怎样算做完 | 「上线标准是单测通过，还是要有可演示接口？」 |

+ | **范围边界** | 做/不做 | 「本次只改后端，前端先不动，可以吗？」 |

+ | **用户/调用链** | 谁触发、输入输出 | 「是 SSE 流式返回，还是 REST 一次返回？」 |

+ | **代码触点** | 改哪些模块 | 「我倾向动 `services/report_*.py`，是否还有别的入口？」 |

+ | **实现路径** | 方案分叉 | 「A 最小补丁 / B 抽公共层，你更倾向？我建议 A」 |

+ | **数据与状态** | 存哪、兼容性 | 「是否要兼容旧缓存 key？」 |

+ | **约束** | 时间/兼容/性能 | 「必须保持现有 API 字段不变吗？」 |

+ | **风险与回滚** | 怕踩什么坑 | 「若命中失败，是降级查库还是直接报错？」 |

+ | **验证方式** | 怎么证明对了 | 「用现有 pytest，还是要补一条 e2e？」 |

+ | **优先级切片** | MVP vs 完整 | 「先做可运行 MVP，细节二期？」 |

- ### 标准模板

+ ### 好的反问

- ```

- 我理解你的意思是：

- - [理解点1]

- - [理解点2]

- - [理解点3（如有）]

+ - 绑定用户原话中的模糊点

+ - 给出 2–4 个互斥选项 + 推荐默认

+ - 帮用户做取舍，而不是要用户从零设计

+ - 问完能直接写出 plan 或动手步骤

- 是这个意思吗？

- ```

+ ### 差的反问

- ### 带选项的模板（当存在多种可能理解时）

+ - 「你有没有想过用设计模式？」类空泛题

+ - 重复用户已说清的内容

+ - 一次要用户写整份技术方案

+ - 与当前阶段无关（需求对齐时追问 commit message 格式）

- ```

- 我理解你的需求，但有几种可能的实现方式：

+ ## 触发条件

- **理解 A**：

- - [描述理解 A]

+ ### 需要走本规范

- **理解 B**：

- - [描述理解 B]

+ | 场景 | 说明 | 示例 |

+ |------|------|------|

+ | **抽象需求** | 描述模糊 | 「优化一下这个功能」 |

+ | **思路未成形** | 用户知道痛点但不知怎么改 | 「这里总是重复代码，想整理下」 |

+ | **设计决策** | 架构/方案分叉 | 「重构用户认证模块」 |

+ | **多义表达** | 多种解读 | 「更新文档」 |

+ | **大范围影响** | 跨模块/协议 | 「统一错误处理」 |

+ | **多步骤任务** | 复杂链路 | 「实现用户注册流程」 |

+ | **R&K 门禁** | 阶段切换 | 需求对齐、批准实现、归档/PR |

+ | **破坏性操作** | 高风险 | 清库、强推、改生产配置 |

- 你希望采用哪种方式？或者有其他想法？

- ```

+ ### 可跳过或极简

- ### 带补充问题的模板（当需要更多信息时）

+ | 场景 | 处理 |

+ |------|------|

+ | 明确简单任务 | 直接做（如「运行测试」） |

+ | 已确认 Spec | 按 plan 执行，不重开需求讨论 |

+ | 信息查询 | 直接答 |

+ | 单点小修 | 直接改 |

+ | 用户豁免 | 「直接做，不用问」→ 执行，但破坏性操作仍要拦 |

- ```

- 我理解你的意思是：

- - [理解点1]

- - [理解点2]

+ ## 运行时适配

- 在开始之前，我需要确认几个问题：

- 1. [问题1]？

- 2. [问题2]？

+ ### OMP（推荐）

- 是这个意思吗？

- ```

+ 用 `ask` 做结构化反问与确认：

- ## 示例

+ - 每题 `id` / `question` / `options`（2–5 项）

+ - **不要**手写 Other（UI 自带）

+ - `recommended`：你的默认建议

+ - `multi: true`：范围多选（模块、验收项）

+ - 可分两轮：先「理解 + 关键取舍」，再「编码思路小结确认」

+ - headless：改用文本模板，等用户下一条消息

- ### 示例 1：抽象需求

+ **反问示例（梳理实现路径）：**

+ ```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

+ }

+ ]

+ })

```

- 用户：更新 skill，当针对该功能更新时，同样要创建更新文档

- Agent：我理解你的意思是：

- - 更新 spec-executor skill 的内容

- - 在 skill 中增加一条规则：当针对某项功能进行更新时，需要先创建更新 Spec 文档，放在该功能原有 Spec 的同一目录下

+ **收敛确认示例：**

- 是这个意思吗？

+ ```text

+ ask({

+ questions: [{

+ id: "approach_ok",

+ question: "编码思路小结：1) 只改后端 publish 管线 2) 命中/未命中各打结构化日志 3) 补单测 4) 不改 API。按此开始？",

+ options: [

+ { label: "按此开始" },

+ { label: "基本可以，我补充一点" },

+ { label: "不对，重梳思路" }

+ ],

+ recommended: 0

+ }]

+ })

```

- ### 示例 2：多义表达

- ```

- 用户：帮我处理一下登录的问题

+ ### Claude Code / 其他

- Agent：我理解你遇到了登录相关的问题，但我需要确认具体是哪方面：

+ - 有原生提问 UI 则用；否则用下方文本模板

+ - 不要写死 `AskUserQuestion` / `TodoWrite` 等工具名

- **可能是**：

- - 登录功能有 bug 需要修复

- - 登录流程需要优化或重构

- - 登录页面 UI 需要调整

- - 登录安全性需要加强

+ ## 文本模板

- 你具体想解决哪个问题？或者能描述一下遇到的具体情况吗？

- ```

+ ### A. 理解转述

- ### 示例 3：设计决策

+ ```text

+ 我先用自己的话理解你的目标：

+ - 目标：…

+ - 范围：…（默认：…）

+ - 不做：…

+ 我的默认假设：…

```

- 用户：给项目添加缓存功能

- Agent：我理解你希望为项目添加缓存功能。在开始之前，我需要确认几点：

+ ### B. 反问梳理

- - **缓存范围**：是针对 API 响应缓存，还是数据库查询缓存，或者两者都要？

- - **缓存方案**：倾向于使用 Redis 这样的外部缓存，还是内存缓存？

- - **缓存策略**：有特定的过期时间或失效策略要求吗？

+ ```text

+ 为把编码思路定清楚，需要你拍板：

+ 1. [验收] …？我建议 …

+ 2. [路径] A … / B …？我建议 A，因为 …

+ 3. [范围] …？

- 请告诉我你的想法，我再制定具体方案。

+ 你可以直接选建议项，或改条件。

```

- ### 示例 4：无需确认

+ ### C. 编码思路小结（确认用）

- ```

- 用户：运行一下测试

+ ```text

+ 根据你的反馈，编码思路如下：

+ 1. 入口/触点：改哪些文件或模块

+ 2. 步骤顺序：先 … 再 … 最后 …

+ 3. 关键取舍：选了 A 而非 B，因为 …

+ 4. 验收：怎样算完成

+ 5. 风险：…；回滚/降级：…

- Agent：[直接执行测试命令，无需确认]

+ 确认按此执行吗？

```

- ```

- 用户：查看 src/api/auth.py 的内容

+ ## R&K Flow 集成

- Agent：[直接读取文件，无需确认]

- ```

+ | 时机 | 谁发起 | 反问/确认重点 | 落盘 |

+ |------|--------|----------------|------|

- ## 确认后的行为

+ 规则：

- ### 用户确认正确

+ - **阶段一必须反问梳理**，不能只「需求 ok 吗」

+ - TeamLead 对用户；子角色默认不直接连环问用户

+ - 已批准的 `writer/plan.md` 执行期不重开需求研讨会，除非需求变更

+ - 反问得到的「编码思路小结」应能直接喂给 spec-explorer / spec-writer 作为输入

- ```

- 用户：对的

+ ### spec-start 阶段一最小问题集

- Agent：好的，我开始执行...

- [开始执行任务]

- ```

+ 至少覆盖（可合并进 2–4 个 `ask` 题）：

- ### 用户指出理解偏差

+ 1. 任务目标一句话 + 验收标准

+ 2. 范围（模块/做不做前端或文档）

+ 3. 实现倾向（最小补丁 / 重构 / 先调研）

+ 4. Git：新分支 / 当前分支 / 先不建分支

- ```

- 用户：不是，我的意思是...

+ ## 确认后的行为

- Agent：明白了，让我重新理解：

- - [修正后的理解点1]

- - [修正后的理解点2]

+ ### 用户确认思路正确

- 这次理解对了吗？

- ```

+ 1. 简短回执

+ 2. 复杂任务用 `todo`（或等价工具）拆步

+ 3. 进入对应流程（explore/write/execute…）

+ 4. 把**编码思路小结**交给下游角色，避免 explorer/writer 重新猜

- ### 用户补充信息

+ ### 用户补充或纠正

- ```

- 用户：差不多，但还需要考虑...

+ 1. 合并进小结

+ 2. 若仍缺阻塞信息 → 再反问一轮（收敛，不发散）

+ 3. 再确认后执行

- Agent：收到，我更新一下理解：

- - [原有理解点]

- - [新增的考虑点]

+ ### 取消 / 超时

- 这样完整了吗？

- ```

+ - `ask` 取消：不执行

+ - 超时采用 recommended：必须声明「已按推荐项 X」，允许用户立刻推翻

## 质量标准

- ### 好的确认

+ ### 好

- - 准确捕捉用户的核心意图

- - 用具体、可执行的语言描述

- - 主动识别潜在的歧义点

- - 适当提出需要澄清的问题

+ - 用户离开对话时比进来时更清楚怎么写

+ - 有明确触点、步骤、验收、不做列表

+ - 反问带默认建议

+ - 与当前 R&K 阶段匹配

- ### 差的确认

+ ### 差

- - 简单重复用户的话（没有理解转化）

- - 遗漏关键信息

- - 过度确认简单任务（浪费时间）

- - 确认内容过于冗长

+ - 只复读 + 「是吗？」

+ - 反问空泛或过多

+ - 替用户隐瞒风险假设却不声明

+ - 确认完不落盘、下游角色收不到思路小结

## 与其他 Skill 的协作

- ### 与 spec-writer 协作

- 在创建 Spec 之前，应先确认：

- - 功能的具体范围

- - 技术方案的选择

- - 优先级和约束条件

- ### 与 spec-executor 协作

- 如果 Spec 已经明确，通常无需再次确认，直接执行即可。

- ### 与 project-memory 协作

- 如果在确认过程中发现了重要的需求澄清模式，可以考虑记录到战略记忆中。

- ---

- ## 后续动作（工具记忆）

+ | Skill | 协作 |

+ |-------|------|

+ | `spec-start` | 阶段一强制本规范（理解+反问+确认） |

+ | `spec-explore` | 输入含已确认范围与思路要点，避免空泛探索 |

+ | `spec-write` | 基于确认后的思路写 plan，不另起炉灶改目标 |

+ | `spec-test` | 验收标准来自确认结果 |

+ | `spec-execute` | 已确认 plan → 直接实现 |

+ | `spec-debug` | 修前确认诊断；可轻量反问复现条件 |

+ | `spec-end` / `spec-update` | 结束与小迭代门禁 |

+ | `exp-reflect` | 长期偏好可在收尾沉淀 |

- 完成意图确认后，你应该：

+ ## 反模式

- ### 如果用户确认理解正确

- 1. 立即开始执行任务

- 2. 如果是复杂任务，使用 TodoWrite 工具规划步骤

- 3. 执行过程中如遇新的歧义，再次确认

+ - 审讯式连问，无推荐默认

+ - 用户思路不清时直接开写，导致返工

+ - 用静默假设代替反问（尤其是 API 兼容、数据迁移、范围）

+ - 子 Agent 绕过 TeamLead 改门禁

+ - headless 硬调交互 UI 后卡住不降级

- ### 如果用户指出理解偏差

- 1. 仔细阅读用户的修正说明

- 2. 重新组织理解并再次确认

- 3. 不要在未确认的情况下开始执行

+ ## 后续动作

- ### 相关 Skill

- - `/spec-writer` - 如果需要创建功能 Spec

- - `/memory` - 如果发现了值得记录的沟通模式

+ 1. 新 Spec → 继续 `/spec-start` 后续阶段

+ 2. 小迭代 → `/spec-update`

+ 3. 已有确认 plan → `/spec-execute`

+ 4. 纯沟通澄清 → 输出思路小结后结束或按用户下一步做