# Native 澄清参考

## 澄清

进入 Shape 后必须读取本节。完成必要提问、核实隐含假设并取得最终需求确认前，不修改项目实现或推进到 Build。

### 是否需要提问

- **可调查事实**：仓库现状、工具能力、依赖默认值和运行环境。由 Agent 调查；可以将彼此独立的事实调查委派给 subagent。
- **用户决定**：不同选择会实质改变输出、默认行为、失败结果、范围或不可逆影响。由用户确认。
- **实现选择**：不改变用户可见结果的算法、结构和工作方式。由 Agent 决定。

只有歧义会实质改变用户可见结果，且无法从用户要求、正式规格、项目文档、现有 Agent 指令或项目规则中可靠确定时才提问。把模糊行为写成可比较的“输入 → 输出”或“触发 → 结果”。每个问题应包含：

- **问题**：需要用户决定的结果差异；
- **推荐**：首选项及理由；
- **影响**：各选项对结果的实际影响。

用户把文件、附件、链接或本地路径作为需求来源时，必须先执行产物参考的[源文档完整覆盖](artifacts.md#源文档完整覆盖)，在 brief 保存用户指定的覆盖边界、边界内的完整来源需求和覆盖状态，再针对歧义、遗漏或未说明的限制提问。材料仅供排错、取证、审查或实现参考时不自动触发；用途不明先澄清。

### 未决问题与依赖

简单问题列出未决项和必要的依赖关系即可，不要求先画树或填写固定的节点字段。只有多个决定相互依赖、回答会改变后续分支时，才建立并持续维护一棵决策树。先查明问题依赖的事实，并解决前面的决定，再提出该问题；等待某项事实时，仅暂停依赖它的分支，其他独立调查和问题继续。

问题之间的关系由 Agent 在工作过程中整理，不新增 Runtime 文件或状态字段。真实未解决的用户问题保存在 brief 的 `# Open questions`；每次用户回答或事实调查产生结论后，更新受影响的未决项、前置条件和后续分支，再确定当前可提问的问题。模糊、部分或未回答的内容继续保持 `[blocking]`，一个答案只确认用户明确回答的部分。

### 提问方式与模式

需要用户决定时，等待用户明确选择。只有一个符合当前条件的选项时，说明原因并直接采用。存在两个或更多清晰、可执行的选项，并且当前平台提供 `AskUserQuestion` 或等价的结构化提问工具时，优先使用结构化提问；单选项必须互斥。开放式问题或工具不可用时使用文本提问。遵守当前平台的提问工具限制；工具调用成功后直接等待，不重复输出同一套文本选项；工具不可用或失败时本次会话继续使用文本。

- Sequential 模式一次提交一个单选或多选问题；有多个可提问项时，优先处理影响更多后续选择或用户结果的决定。
- Batch 模式在一次请求中提交本轮完整的问题集合；这些问题的前提已确定、答案彼此独立。工具无法容纳时整批使用文本，不因工具限制拆散本轮问题。
- 每个选项用短标签说明实际影响，把推荐选项放在前面并说明理由；推荐不代替用户确认。文本提问明确单选或多选、选项编号和影响，要求用户选择后等待。

#### 批量文本提问格式

Batch 使用文本提问时，保留 `Q1`、`Q2` 编号，每题使用独立的加粗标题、正文、选项和推荐区；用 💬 标记问题、💡 标记推荐回答，配合题间分隔线区分内容。以下问题块按本轮完整集合重复，在同一条消息中发出：

```markdown
💬 **Q1｜<问题标题>（单选）**

<说明背景及需要用户决定的结果差异；复杂问题可以分段。>

| 选项 | 方案         | 实际影响                   |
| ---- | ------------ | -------------------------- |
| A    | <方案短名称> | <选择后改变什么及相关代价> |
| B    | <方案短名称> | <选择后改变什么及相关代价> |

💡 **推荐回答：A（<方案短名称>）**

推荐理由：<为什么适合当前需求与约束。>

---
```

题号直接沿用 brief 中稳定的 `Qn`，例如未回答的 `Q3` 始终显示为 `Q3`，后续轮次不重新编号。多选题标为“多选”；开放题标为“开放回答”，省略选项表，有可靠建议时给出“推荐回答”和理由；事实不足时明确“需要你补充”，只给回答所需的信息或格式，不编造推荐内容。只有选项顺序可以自由调整时，才把推荐选项放在前面；Supervisor、工作区等已有固定选项表保留原标识和完整影响，放入对应问题块并单独说明推荐。

全部问题之后统一说明答复方式，例如 `Q1：A；Q2：A+C；Q3：补充内容`，也允许按题号给出自己的答案；示例不代表默认选择。结构化工具能够容纳本轮完整集合时仍优先使用工具，在工具的标题、说明和选项字段中写明相同信息，不要求工具呈现 Markdown 表格，调用成功后不再重复文本问题块。

#### Sequential 模式

1. 调查当前问题依赖的事实，只暂停前置条件尚未确定的分支。
2. 从当前可以提出的问题中选择一个，先在 brief 的 `# Open questions` 保存 `- [blocking] <问题>`。
3. 一次只提出这一个问题，给出问题、推荐及理由、各选项影响，然后等待回答。
4. 用户回答后，立即把已确定的决定写入 brief 的相关章节和完整目标规格，再移除已解决的阻塞项；补充答案写入同一个 change。
5. 更新问题之间的依赖关系，重新确定下一轮可以提出的问题，再开始下一轮。

#### Batch 模式

1. 列出本轮可以一起提出的全部问题：前置事实和决定已经确定，答案彼此独立。每个独立决定保留为单独问题。
2. 提问前，在 brief 的 `# Open questions` 为本轮全部问题保存 `- [blocking] Q1: <问题>`、`- [blocking] Q2: <问题>` 等稳定标识；后续轮次不把已有标识改用于其他问题。
3. 一次提出本轮全部问题，每题分别给出问题、推荐及理由和影响，然后等待回答；不能因为工具限制而分批提出本轮问题。
4. 用户回答后，逐项更新 brief 的相关章节和完整目标规格，移除已解决项；部分、模糊或未回答的问题保留原标识及 `[blocking]`。
5. 更新已回答和未回答问题及其依赖，再确定下一轮需要一起提出的全部问题。

两种模式都在当前没有可提问项时，继续调查尚未查明的事实，并检查是否遗漏其他情况。当前列表为空不代表澄清完成；最终确认仍需满足下一节的全部完成条件。

### 最终确认

大型需求在最终确认前必须按[Supervisor 拆分与确认](#supervisor-拆分与确认)检查一次是否需要拆分；长度和条目数本身不要求拆分。存在需求来源时，先按[源文档完整覆盖](artifacts.md#源文档完整覆盖)核对当前覆盖边界内的全部来源条目，确认新增或替代的内容、Spec 位置和验收 ID 都已更新。

完成条件：所有影响用户可见结果的决定都已确认，相关事实和隐含假设都已核实，brief 没有 `[blocking]`，`# Scope` 下的目录结构已填写完整（要求见[正式产物](artifacts.md#正式产物)），验收项具体、结果可验证且互不重复。满足后：

1. 按当前 continuation 执行 `prepare-shape-confirmation`，通过 `--summary` 提交目标、范围、关键决定、验收标准和非目标；不要为最终确认再写一条 `[blocking]`。
2. Runtime 保存确认摘要并返回 `await-user` 后，展示完整摘要和 `userCommunication`，等待用户明确确认。
3. 用户补充或否定摘要时更新正式产物，重新准备确认；只有用户明确确认后，才执行当前 `commandAlternatives` 中带有状态版本和预期动作校验参数的 `--confirmed` 命令。

用户最初提出的需求不能代替最终确认。普通实现选择只有影响用户可见行为时才进入正式需求。

## Supervisor 拆分与确认

大型需求在最终 Shape 确认前，检查是否需要由 Supervisor Change 统筹多个子任务。只有至少两个结果可独立实现和验证、每项验收都能明确分配给子任务，并且确实存在先后依赖或并行价值时，才建议拆分。

目标紧密相关、需要反复修改同一核心区域、协调成本更高或用户要求单个 Native Change 时，不进行拆分。需求文字长、任务条目多本身不能触发拆分。
建议拆分时，Skill 将 `children.yaml` 草案、子任务依赖和先后顺序、每项验收由哪个子任务负责，以及推进方式，一并提交给用户确认。用户可以调整拆分、继续使用单个 Native Change，或从以下方式中选择其一：

| 选项 | 推进方式           | 实际影响                                                                                                                  |
| ---- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| A    | 多会话协作（推荐） | 当前会话只负责统筹；优先由独立会话处理当前可执行的子任务，独立会话或 Agent Team 不可用时自动改用 subagent，并持续反馈进度 |
| B    | 单会话推进         | 不创建 Codex 独立会话或 Claude Code Agent Team；全部子任务仍按相同范围、依赖和验收要求，由当前会话依次处理                |

需要选择推进方式时，必须同时展示 A、B 两项。文本提问使用上表；结构化提问把“推进方式”作为短标签、“实际影响”作为说明，并说明推荐理由，等待用户明确选择。推荐、普通“确认”或没有回答都不能代替推进方式选择。

用户已经明确要求“多个会话”“独立会话”“跨会话协作”或“Agent Team”时，视为选择 A，不重复询问推进方式。确认前不得创建子 change、worktree、Codex 独立会话、Claude Code Agent Team 或分配任务。

当最终 Shape 包含两个或更多 Child 时，在 Decisions 中记录 Supervisor Change 和各 Child，先按 continuation 执行 `prepare-shape-confirmation`，由 Runtime 绑定完整 Shape 和子任务方案。展示保存的完整摘要、拆分方案及 A、B 两种方式后，用户可一次回复明确确认方案并选择推进方式，再执行对应的 `--confirmed` 完整备选命令。不得把普通“确认”视为已选择，也不得把仅选择方式视为确认方案。仍可先选择方式再准备确认；仅先选择方式时，用户仍需再次明确确认完整 Shape。正式产物或子任务变化后重新准备并确认，不沿用旧授权。

Runtime 把已选择的推进方式写入 `comet-state.yaml` 的 `coordination_mode`；完整 Shape 与推进方式都得到明确确认后，Runtime 才进入 Build，为 Supervisor Change 创建独立的集成分支和 worktree，并基于集成分支的当前提交，为每个子任务生成包含角色、worktree、基线提交和 `runId` 的任务包。推进方式不写入 `children.yaml`，也不改变 Runtime 的 `readyChildren`、`runId`、验收或集成规则。Skill 只启动 `readyChildren` 中列出的当前可执行子任务；选择 A 时最多同时启动两个不依赖其他子任务的任务，选择 B 时按顺序执行。每个子任务都必须属于 Supervisor Change 已确认的需求范围；出现会改变用户可见结果的新决定时，回到 Supervisor Change 的 Shape。

恢复 `/comet-native` 时以 Runtime 已保存的 `coordination_mode` 为准，不重复创建已有子任务或 worktree，也不再询问推进方式。`multi-session` 继续使用多会话协作；独立会话或 Agent Team 不可用时自动改用 subagent；`single-session` 继续由当前会话按顺序推进。原来的 Codex 独立会话或 Claude Code Agent Team 已经不存在时，先重新读取 Runtime 状态；不得根据旧会话或旧团队的状态推断子任务已经完成，也不得自动改为单会话推进。

未解决问题保持 `[blocking]`；有阻塞项时不修改项目实现。完成标准：所有会影响用户可见结果的选择均已确认，隐含假设均已核实，没有 `[blocking]`，用户明确确认目标、范围、关键决定、验收项和非目标，并且 Runtime 已进入 Build。只有用户明确确认后才使用后续指令中含 `--confirmed` 的命令推进。

编辑 `children.yaml` 前必须读取[正式产物](artifacts.md#正式产物)，填写验收映射和依赖。用户确认完整 Shape、Runtime 进入 Build 后，首次分配任务前必须读取[Supervisor 协作](commands.md#supervisor-协作)，按任务包指定的角色和工作目录执行，回传结果时保留任务标识。