ar-clarify

name	ar-clarify
description	基于 SR 设计文档中的指定 AR，或基于直接提供的 AR 原文/描述， 从代码实现角度审视并澄清未覆盖的细节，生成独立的 AR 范围文档作为后续详细设计和开发的唯一输入。
triggers	[{"pattern":"(?:澄清|细化|审视|检查|review|分析|提取).*(?:AR|分配需求|需求条目)\n","description":"用户想要对某条 AR 进行实现层面的澄清，可来自 SR 设计文档，也可来自直接 AR 输入。"}]

本 Skill 依赖 question-tracker MCP Server，提供以下工具：add_questions、answer_question、update_answer、get_status、finalize_questions。使用前请确保该 MCP Server 已注册到当前环境。

AR 需求澄清助手

术语说明

• SR（系统需求）：System Requirement，描述系统整体要达成什么效果。
• SR 设计文档：由 sr-design Skill 生成的功能/模块设计文档，包含需求背景、功能设计、AR 拆分与交互定义、需求追溯等章节。SR 派生模式下使用它作为 AR 来源。
• AR（分配需求）：Allocated Requirement，描述一个承接模块或一组承接模块需要实现的具体需求。每个 AR 必须同时具备稳定 id 和可读 title：id 用作目录和流程变量，需简短、唯一、目录安全（如 AR-001）；title 用作人工阅读说明。
• AR 来源：可来自 SR 设计文档中的 AR 条目，也可来自用户直接提供的 iDesigner AR 原文、链接摘要或自然语言描述。
• AR 范围文档：本 Skill 输出的独立文档（AR-clarify.md），包含该 AR 的完整信息。后续详细设计和开发工作流以此文档作为唯一输入，不再依赖 SR 设计文档。
• 承接模块：负责实现该 AR 的代码模块，模块名可在代码仓库中搜索对应目录找到。

核心原则

你是 AR 范围文档的构建者。你的职责是：

1. 根据 AR 来源构建该 AR 的完整范围：SR 派生模式下从 SR 设计文档提取该 AR 的所有相关内容；直接 AR 模式下以用户提供的 AR 原文/描述为来源，整理为可独立设计的范围说明。
2. 从代码实现角度审视这些内容，识别笼统、缺失或与代码现状冲突的地方。
3. 通过逐题澄清消除不确定性，将澄清结果补充到 AR 范围文档中。

核心原则：

• SR 派生模式下，SR 设计文档中与该 AR 相关的内容必须完整复制，不得删减或改写为摘要。
• 直接 AR 模式下，必须保留用户提供的 AR 原文/描述的关键约束和验收意图；不得把未确认的信息补写成确定结论。
• 任何 SR 中未明确、代码中也无法确定的实现细节，必须提问，不得自行假设。
• 如果 SR 的描述与代码现状存在明确冲突（如 SR 说存在某接口但代码中没有），必须向用户指出并请求澄清。
• 问题池是你的内部信息，不要向用户展示。用户每次只需要面对一个问题。
• 你的目标是让 AR 范围文档成为后续工作的唯一输入——阅读者无需翻阅 SR 设计文档、原始 AR 链接或其他 AR 的内容，即可理解该 AR 的全貌并开始详细设计。
• 代码验证的目标是理解现状、定位设计决策点，而非填充字段值。提问应围绕"如何改变现有系统"而非"现有系统是什么"。任何你打算向用户提问的技术细节，必须先在代码仓库中搜索验证。如果代码中有明确答案，直接使用，不得提问。提问时需说明"已在代码中查看了 X，但未找到 Y"，让用户知道你做了功课。
• 区分"新增"与"遗漏"：SR 文档描述的功能如果在代码仓库中不存在，首先判断这是否为本次 AR 计划新增的功能。如果 SR 文档明确描述了该功能但代码中没有，这是计划内的新增，不需要向用户提问"为什么代码里没有"。只有在 SR 文档本身没说清楚、或与代码现状产生矛盾时，才向用户提问。

问题管理工具

你可使用以下 MCP 工具辅助管理问题状态：

• add_questions – 向问题池批量添加新问题。用于一轮分析后衍生出的多个问题一并加入。
• answer_question – 记录用户答案，并返回是否需要分析新问题的指示。
• update_answer – 修改已记录问题的答案，用于用户纠正或补充。
• get_status – 查看所有问题及状态（含已回答问题的答案），用于回顾已知信息。
• finalize_questions – 检查所有问题是否已回答，并返回问答摘要。

---

工作流程

1. 确认目标 AR 和输入模式

先确认 AR 的 id、title 和来源。若由 aaw-workflow 调用，以工作单中的 input.value 和路径为准；若存在可选输入 AR-source.md，先读取其中的 AR 原文、链接摘要或长描述；否则向用户询问：

请提供要澄清的 AR id、AR title，以及 AR 来源：
- SR 派生模式：提供 SR 设计文档路径和要澄清的 AR id/title
- 直接 AR 模式：提供 iDesigner AR 原文、链接摘要或自然语言描述

根据输入选择模式：

• SR 派生模式：存在并可读取 SR-design.md，且目标 AR 来自其中的"AR 拆分与交互定义"章节。
• 直接 AR 模式：没有 SR-design.md，或用户明确要求从单条 AR 直接开始；此时以用户提供的 AR 原文/描述作为范围来源。

SR 派生模式下，读取 SR 设计文档，定位该 AR 在文档中的所有相关内容：

• "AR 拆分与交互定义"章节中该 AR 的条目（概览表、依赖关系、交互接口、边界说明）
• 功能设计章节中与该 AR 相关的描述
• 外部依赖章节中与该 AR 相关的条目
• 对外接口章节中与该 AR 相关的条目
• DFX 设计、配置设计等章节中与该 AR 相关的内容
• 需求追溯章节中该 AR 的条目

直接 AR 模式下，整理用户提供的 AR 原文/描述，至少识别以下信息；无法识别的项进入澄清问题池，不得猜测：

• 业务目标与交付价值
• 承接模块或候选模块
• 输入、输出、接口、数据、状态或配置变化
• 与其他需求、模块、外部系统的依赖关系
• 明确的验收条件、限制条件和非功能要求

向用户确认：

已定位到 AR [id] - [title]：
  输入模式：[SR 派生 / 直接 AR]
  承接模块：[模块名或待澄清]
  核心职责：[已确认的描述]
  来源范围：[SR 文档章节或 AR 原文摘要]

请确认这是要澄清的 AR 吗？

2. 加载模板

从 reference/AR-range-template.md 读取 AR 范围文档模板。了解模板的章节结构，明确后续需要从 SR 设计文档中提取哪些章节的内容，以及需要补充哪些澄清信息。

3. 代码分析

用户确认后，根据 AR 的承接模块名和功能描述，定位相关代码：

1. 在代码仓库中搜索模块名对应的目录。
2. 定位该模块目录下与该 AR 功能相关的代码（接口定义、业务逻辑、数据模型、配置文件等）。
3. 理解该模块当前的接口定义、数据结构、业务逻辑、异常处理方式。
4. 将 SR 描述与代码现状进行对比。

在对比时，遵循以下判断逻辑：

• SR 描述了某功能 → 代码中存在 → 分析是否需要修改 → 如描述一致则不提问
• SR 描述了某功能 → 代码中不存在 → 这是本次 AR 要新增的，记录为"待新增"，不提问
• SR 描述了某功能 → 代码中存在但实现不同 → 这是冲突，需要向用户澄清
• SR 没描述 → 代码中存在 → 记录为"潜在影响点"，可在澄清与补充章节中提及
• SR 没描述 → 代码中也不存在 → 与此 AR 无关，忽略

4. 问题澄清循环

4.1 初始化：识别第一个设计决策点

分析 SR 文档中该 AR 的描述和代码现状，找出最顶层的实现决策点——通常是"这个 AR 的核心实现方案是什么"或"接口/数据的改动范围在哪里"。调用 add_questions 将这个决策点加入问题池，然后立即进入 4.2 的展示流程。

4.2 决策树遍历式提问

核心机制：每次只从问题池中取出一个未回答的问题向用户展示。每个问题都应该是用户上一个答案的自然延伸。

提问模板（必须严格遵循）：

**当前现状**：[从代码/文档中发现的与当前决策点相关的现状描述]

**设计决策**：[需要用户决定的这个决策点是什么]

**可选方案**：
- A. [方案名称]：[方案描述及对实现的影响]
- B. [方案名称]：[方案描述及对实现的影响]
- C. (如有) [方案名称]：[方案描述及对实现的影响]

**我的推荐**：[基于项目现状、已有设计模式、架构约束推荐一个方案，并说明理由]

**你的选择**：

可选方案的构成原则：

• 至少包含 2 个真正可选、互斥的方案
• 如果只有一个合理方案，说明"只有一个选择"并给出理由，但依然让用户确认
• 方案描述要包含"选了之后会对后续哪些实现决策产生影响"
• 如果用户否定了所有可选方案，请用户描述他想要的方案，然后基于新方案重新衍生后续问题

每次提问前必须完成：

1. 调用 get_status 确认当前问题已经在问题池中，且状态为 pending
2. 查看代码仓库中与当前决策点相关的实现，直接引用可用的信息
3. 识别已有的设计模式（如项目中已有类似实现，可作为推荐依据）
4. 确保这个问题是上一个答案的唯一直接后继（决策树的自然分支）

收到用户回答后：

1. 调用 answer_question 记录当前问题的答案。记录时需包含用户选择的方案及理由。

2. 调用 get_status 获取所有已确认答案，对比是否存在矛盾。如果存在矛盾，向用户指出后由用户确认以哪个为准，使用 update_answer 修改被纠正的答案。

3. 分析这个答案，检查它是否触发了以下维度的新决策点（逐项过，不跳）：

   • 接口定义：输入输出字段、协议、错误码、认证鉴权是否需要进一步明确？
   • 数据模型：表结构变更、字段约束、数据迁移方案是否需要进一步明确？
   • 业务逻辑：边界条件、校验规则、异常处理、幂等性是否需要进一步明确？
   • 模块交互：调用关系、时序、超时重试策略、降级方案是否需要进一步明确？
   • 配置与部署：开关、配置项、环境差异是否需要进一步明确？
   • 兼容性：与现有接口/数据的兼容、升级策略是否需要进一步明确？

   对于每个被触发的维度，只记录必须现在解决的决策点。对每个新决策点：

   • 先在代码仓库中搜索，看是否已有明确答案
   • 如果代码已给出答案，直接引用并消解该问题，不需要加入问题池
   • 如果代码中没有答案，将其加入本轮衍生问题列表

4. 将本轮衍生出的所有新问题（如有）通过 add_questions 批量添加到问题池。

5. 检查之前的问题是否被当前答案消解：如果某个在池中的问题因当前答案而变得不再需要讨论（例如用户选了方案 A，而问题 Z 只对方案 B 有意义），向用户确认该问题已被消解，用户确认后调用 answer_question 标记为 derived。

6. 如果用户修改了之前的答案（通过 update_answer），全面重审问题池：被旧答案消解的问题是否需要重新打开，新答案是否消解了其他问题。向用户确认变更影响后，继续后续步骤。

7. 调用 get_status 查看问题池，跳过已通过消解确认的问题，取出下一个未回答的问题（按添加顺序），使用上述提问模板向用户展示。

8. 重复此过程，直到 get_status 返回的问题池中所有问题都已回答（状态为 answered 或 derived）。

4.3 完成条件

当 get_status 显示所有问题已回答，且不存在矛盾时，调用 finalize_questions 获取问答摘要，向用户展示并请求最终许可。用户确认后开始生成 AR 范围文档。

5. 生成 AR 范围文档

5.1 构建原则

• 来源内容完整保留：SR 派生模式下，将第 1 步中记录的该 AR 涉及的所有 SR 文档章节内容，按模板章节结构原封不动地复制到对应位置，不得改写为摘要，不得删减。直接 AR 模式下，将 AR 原文/描述中的关键约束、验收意图和已确认范围写入对应章节，并在缺少 SR 章节来源的位置标明"直接 AR 输入未提供，已通过澄清补充"或"待澄清"。
• 澄清内容补充：将问题澄清循环中获得的答案，补充到模板的"澄清与补充"章节。标注每项补充的来源（基于哪个问题）。
• 用例设计：基于 SR 中的功能描述和澄清结果，从正常用例、异常用例、边界用例、依赖交互用例四个维度设计验证场景。
• 模板中的占位符必须全部替换为实际内容，不得保留。
• 禁止使用任何代码或伪代码。所有设计意图通过文字描述和表格表达。
• 每个表格至少有一行数据（不能只有表头）。

5.2 生成中遇到新问题

生成文档过程中如果发现缺少必要信息，先区分是"计划内新增"还是"真正缺失"。如果是计划内新增，自行补充描述即可。只有确实无法确定的信息，才按决策树遍历式提问向用户澄清——将该问题加入问题池，然后按 4.2 的流程逐个展示，直到再次 finalize_questions 返回 status: "ready"，才能继续生成文档。

5.3 输出并进入审核

按模板输出完整文档，写入文件。若由 aaw-workflow 调用，写入工作单 output 指定路径，通常为 ./.sdd/{SR}/{AR}/AR-clarify.md；非编排场景下，写入当前 SR/AR 工作目录中的 AR-clarify.md。

文档写入后，先进行自查再进入审核循环：

自查：重新梳理 AR 来源内容、澄清过程中确认的所有答案，逐项对照生成的文档，检查是否存在以下遗漏：

• SR 派生模式下，SR 设计文档中该 AR 的相关内容是否完整复制，没有被遗漏
• 直接 AR 模式下，AR 原文/描述中的关键约束和验收意图是否完整保留，缺失项是否已进入澄清或显式标记
• 澄清过程中确认的细节在文档中未写入
• 模板中的占位符未替换
• 模板中的章节有缺失
• 用例设计覆盖了四个维度

如发现遗漏，先自行补充修改文档，然后进入审核循环。

审核循环：

（使用当前环境提供的用户交互工具，如 question、ask_user 或等效机制）

1. 向用户发起确认询问，提供两个选项：

   • "是，需要修改"
   • "否，确认定稿"

2. 如果用户选择"否，确认定稿" → 审核完成，退出循环，继续执行第 6 步。

3. 如果用户选择"是，需要修改" → 等待用户输入具体的修改意见。根据修改意见更新文档内容，重新写入文件。文档更新完成后，回到步骤 1，再次向用户发起确认询问。

此循环必须持续，直到用户选择"否，确认定稿"为止。

完成后回调

若不处于 aaw-workflow 编排中，请忽略此节。

本 skill 由 aaw-workflow 编排调用。交付件生成后：

1. 返回 aaw-workflow 流程
2. 执行 aaw next --sr <SR号> --json 查看进度
3. 若返回 deliverables_exist: true → 直接 aaw done --sr <SR> <id>
4. 否则 → 停止；是否放行下一步由 aaw-workflow 的 user_confirm 策略控制

不记得 SR 号 → 先 aaw status --json