clarification

通过迭代探索进行澄清

将模糊的用户请求缩小为明确的工作范围。先探索代码库，再根据探索结果提出问题，并反复迭代，直到消除歧义。

核心原则

歧义无法通过一轮对话消除。多轮探索和提问相互交织，逐步让问题变得清晰。先探索：了解过代码库的 Agent 能提出有把握、具体的问题；不了解代码库的 Agent 只会提出泛泛的问题，浪费用户的回答。这项技能的目的不是“编写代码”，而是让“用户想要什么”和“代码库处于什么状态”都变得清晰明确。

硬性要求

1. 先探索，再提问。 在提出第一个问题之前，先派遣侦察子 Agent。每个问题都必须以探索结果为依据——绝不要询问代码库本身就能回答的问题。
2. 始终使用子 Agent。 在提出第一个问题之前派遣子 Agent，并在用户回答后再次派遣。
3. 在能够说“这已经足够清楚”之前，不要开始实施。 必须从代码库层面充分理解情况。
4. 每个问题都必须缩小范围。 不要在同一模糊程度上重复提问。互不依赖的问题可以合并到一轮中（最多 4 个，例如通过 AskUserQuestion）；相互依赖的问题则应逐轮提问。歧义消除后，循环才结束，而不是达到固定轮数后结束。
5. 绝不要把原始代码探索结果直接倾倒给用户。 应结合用户的问题总结发现。

适用场景

• 用户说“我想……”但范围不明确
• 请求足够模糊，可能有多种实施方向
• 用户自己也没有完全说明想要什么
• 存在与现有代码库结构冲突的风险，因此需要探索

不适用场景

• 请求已经具体明确（直接实施或使用规划技能）
• 范围显而易见，例如简单的 Bug 修复或配置更改
• 用户明确表示“别问问题，直接做”

流程：先侦察，再进入问答循环

阶段 0：初步侦察（提出任何问题之前）

收到模糊请求后，立即派遣 Explore 子 Agent——先不要向用户提问。侦察要梳理请求可能涉及的范围：文件结构、现有模式、接口边界、近期相关更改、测试覆盖情况。

侦察进行期间，分析请求并列出其中的歧义。只有在侦察结果返回后，才组织第一轮问题，以便每个问题都能引用代码的实际情况：“代码库已经在 services/y.ts 中处理了 X——这个需求应该沿用该模式，还是取而代之？”

轨道 1：用户问答（消除歧义）

向用户提问以消除歧义。

提问原则：

• 每个问题都要以探索结果为依据——说明发现了什么
• 将互不依赖的问题合并到一轮中（最多 4 个）；相互依赖的问题则逐轮提问
• 尽可能提供选项（A/B/C）
• 如果回答中出现新的歧义，在下一轮深入追问
• 问“是哪种情况？”，而不是“为什么？”——引导用户说明具体情形，而非抽象意图
• 如果回答与之前的说法矛盾，立即指出并重新对齐
• 每轮提问后，简要更新“目前已确认的内容”

问题顺序指南：

1. 目的：“这项工作的最终目标是什么？”（想要实现什么）
2. 范围：“包含哪些内容，不包含哪些内容？”（划定边界）
3. 约束：“是否存在影响这项工作的现有约束？”（时间、兼容性、依赖项）
4. 成功标准：“完成后，状态应该是什么样的？”（可验证的结果）
5. 优先级：“如果有多种方案，最重要的是什么？”（权衡取舍）

轨道 2：代码库探索（技术背景）

探索从第一个问题之前（阶段 0）开始，并在各轮之间持续进行——每次用户回答通常都会开启一个值得探索的新领域。

如何分派探索任务：

只要某个回答（或先前的发现）开启了新的领域，就立即启动后续子 Agent——通常是在提出下一轮问题后立即启动，这样用户回答时，探索也能同步进行。子 Agent 将调查：

• 相关的文件结构和命名约定
• 现有的实现模式（错误处理、状态管理、数据流）
• 依赖项和接口边界
• 近期的变更历史（相关提交）
• 测试覆盖情况

子 Agent 提示词模板：

subagent_type: Explore
description: "Explore [topic] codebase"
prompt: |
  The user has requested [summarized request].

  Investigate and report on:
  1. Related files and the role of each
  2. Existing implementation patterns (is something similar already in place?)
  3. Boundary areas this work is likely to affect
  4. Recent related changes
  5. Existing test state

  Report only key findings concisely.
  Do not dump entire file contents.

处理子 Agent 的结果：

子 Agent 返回调查结果后：

1. 与用户的回答交叉验证
2. 如果发现用户不了解的技术限制，在下一轮问题中体现出来
3. 如果可能与现有代码冲突，通知用户

综合起来：循环

digraph clarification {
    rankdir=TB;
    "User states vague request" [shape=box];
    "Dispatch recon subagents" [shape=box, style=dashed];
    "Assess ambiguities + receive recon findings" [shape=box];
    "Ask informed question round" [shape=box];
    "Dispatch follow-up exploration" [shape=box, style=dashed];
    "Receive user answers" [shape=box];
    "Synthesize: still ambiguous?" [shape=diamond];
    "Present context brief" [shape=doublecircle];

    "User states vague request" -> "Dispatch recon subagents";
    "Dispatch recon subagents" -> "Assess ambiguities + receive recon findings";
    "Assess ambiguities + receive recon findings" -> "Ask informed question round";
    "Ask informed question round" -> "Dispatch follow-up exploration" [style=dashed, label="parallel"];
    "Ask informed question round" -> "Receive user answers";
    "Dispatch follow-up exploration" -> "Synthesize: still ambiguous?" [style=dashed];
    "Receive user answers" -> "Synthesize: still ambiguous?";
    "Synthesize: still ambiguous?" -> "Ask informed question round" [label="yes"];
    "Synthesize: still ambiguous?" -> "Present context brief" [label="no"];
}

每个周期：

1. 接收用户的回答
2. 合并子 Agent 的结果（如果仍在进行中，则在下一个周期合并）
3. 更新“剩余歧义”列表
4. 组织下一轮问题（优先考虑对范围影响最大的内容；只将彼此独立的问题合并）
5. 如果需要，启动其他子 Agent（当回答或先前的探索揭示了需要调查的新领域时）

输出：背景简报

歧义得到充分消除后，向用户提供一份背景简报。这是此技能的最终交付物。

背景简报格式：

## Context Brief: [Task Title]

### Goal
[One-sentence task goal]

### Scope
- **In scope**: [Included work]
- **Out of scope**: [Explicitly excluded work]

### Technical Context
[Technical facts discovered through code exploration]
- Current implementation state
- Affected areas
- Existing patterns to follow

### Constraints
[Identified constraints]
- External constraints
- Technical constraints
- Time/priority constraints

### Success Criteria
[Specific criteria for the completed state]

### Open Questions (if any)
[Questions still open — unresolved but not blocking]

### Complexity Assessment

Assess task complexity using these 5 signals. Score each signal, then determine the routing.

| Signal | Low (1) | Medium (2) | High (3) |
|--------|---------|-----------|----------|
| **Scope breadth** | Single feature or component | 2-3 related components | 4+ components or cross-cutting concerns |
| **File impact** | ≤3 files | 4-8 files | 9+ files or across 3+ directories |
| **Interface boundaries** | Works within existing interfaces | Extends existing interfaces | Defines new interfaces or modifies contracts |
| **Dependency depth** | No ordering constraints | Linear dependency chain | Branching dependencies requiring DAG |
| **Risk surface** | No integration risk | Internal integration between components | External systems, schema changes, backward compatibility |

**Score:** [sum of signals, range 5-15]
**Verdict:** [Simple (5-8) | Borderline (9) | Complex (10-15)]
**Rationale:** [1-2 sentences explaining the dominant complexity factor]

### Suggested Next Step
[Auto-determined by Complexity Assessment verdict — see Routing Rules below]

将背景简报保存到文件：

docs/engineering-discipline/context/YYYY-MM-DD-<topic>-brief.md

（如果用户指定了其他位置，则遵照其指定位置。）

先在对话中展示背景简报，用户批准后再保存到文件。此文件将直接用作 plan-crafting 技能的输入。

危险信号

如果发生以下任一情况，请暂停并重新校准：

情况	响应
用户说“你看着办”	提醒用户：在歧义尚未消除时开始，极有可能导致返工。至少确认目的和成功标准
同一主题被询问 3 次以上	用户确实不清楚。区分已知与未知内容，为未知内容提出假设并进行确认
子 Agent 发现现有代码中存在冲突	立即通知用户。与现有结构冲突时，需要做出设计决策
请求可拆解为多个彼此独立的子任务	向用户展示拆解结果，并建议逐一确定优先级

反模式

反模式	失败原因
在侦察返回前就提出第一个问题	提出代码库本可回答的泛泛问题；浪费用户的时间和信任
在同一轮中合并存在依赖关系的问题	同一批次中，后续回答会使先前的回答失效
不进行代码探索就提问	范围可能会朝着与现有代码冲突的方向缩小
向用户展示子 Agent 的完整输出	信息过多。只提供与用户背景相关的摘要
擅自决定“信息已经足够”	始终向用户展示背景简报并获得确认
开始实现	此技能止步于“背景清晰”，而不是“代码已实现”

最简检查清单

每个周期结束时进行自检：

• 本周期是否至少消除了一项歧义？
• 子 Agent 探索是否正在进行或已经完成？
• 下一轮问题是否基于先前的回答和探索结果？
• 是否已向用户清晰传达进展？

路由规则

Context Brief 获得批准后，由 Complexity Assessment 的判定结果决定下一项技能：

判定结果	路由	原因
简单（得分 5-8）	plan-crafting	任务适合在单个计划周期内完成。直接规划即可。
临界（得分 9）	用户决定	提供两个选项并给出建议。
复杂（得分 10-15）	milestone-planning	任务需要多个计划周期。规划前需先拆解里程碑。

覆盖规则： 用户始终可以覆盖路由。如果用户对复杂任务说“直接规划”，则路由到 plan-crafting。如果用户对简单任务说“拆分成里程碑”，则路由到 milestone-planning。

临界（得分 9）： 向用户提供两个选项并给出建议。例如：“此任务得分为 9，处于临界范围。我建议使用 milestone-planning，因为 [主要因素]；但如果满足 [条件]，plan-crafting 也可行。您倾向于哪一种？”

Context Brief 中的“Suggested Next Step”字段必须反映此路由：

• 简单（5-8）：“Proceed to plan-crafting — task fits in a single plan cycle.”
• 临界（9）：“Recommend [route] because [dominant factor], but [other route] is viable if [condition]. User choice needed.”
• 复杂（10-15）：“Proceed to milestone-planning — task requires milestone decomposition for multi-phase execution.”

过渡

用户批准 Context Brief 后，根据 Complexity Assessment 进行路由：

• 简单（得分 5-8）→ plan-crafting 技能 — 单周期实施规划
• 临界（得分 9）→ 提供两个选项并给出建议，由用户决定
• 复杂（得分 10-15）→ milestone-planning 技能 — 多阶段里程碑拆解，然后使用 long-run 执行
• 如果需要进一步探索 → 继续 clarification 技能本身的问答循环
• 如果范围已十分简单，无需规划 → 直接实施

此技能本身不会调用下一项技能。它会以呈现 Context Brief、将其保存到文件并建议相应的下一步路由作为结束。

Context Brief → plan-crafting 映射：

Context Brief 字段	plan-crafting 输入
Goal	计划标题中的“目标”
Scope (In/Out)	计划标题中的“工作范围”
Technical Context	“架构” + “技术栈” + 文件结构映射的基础
Constraints	在任务拆解时纳入约束条件
Success Criteria	Self-Review 标准
Open Questions	在计划中作为假设（assumption）纳入，然后向用户确认