实现设计对齐

Announce at start: "我正在使用 arkweb-design-alignment skill 进行实现设计对齐。"

运行模式

模式 A：Subagent 模式

作为独立 subagent 被 arkweb-architect 调度。主 Session 提供设计文档路径和代码仓库路径，subagent 执行差异比对并逐一向用户请求决策。

模式 B：独立调用

用户直接调用时，需提供：

• 设计文档路径（requirement.md + design.md）
• 实现代码所在目录
• 需求分析报告路径（可选）

如未提供，skill 会自动查找 {DOCS_REPO}/docs/features/{feature-name}/ 下的文档。

输入

输入项	路径	必需	说明
requirement.md	{docs_dir}{feature-name}/{date}-{feature}-requirement.md	是	需求基线评审文档
design.md	{docs_dir}{feature-name}/{date}-{feature}-design.md	是	架构设计文档
spec.md	{docs_dir}{feature-name}/spec.md	否	统一规格文档（补充参考）
analysis.md	{analysis_dir}{date}-{feature}-analysis.md	否	代码分析报告
实现代码目录	{WORK_HOME}/	是	代码仓库根路径

执行步骤

Step 1: 收集三方信息并识别差异

并行读取所有输入文档，提取对比所需的全部信息：

1. Read requirement.md + design.md
   → 提取：接口定义、API 签名、数据结构、流程描述、约束条件

2. Read spec.md（如存在）
   → 提取：结构化接口规格、参数约束、行为场景

3. Read analysis.md（如存在）
   → 提取：实现步骤清单、代码探查结果

4. 在代码仓库中搜索实现代码
   → 使用 Grep + Read 查找头文件和实现文件
   → 提取实际的类定义、方法签名、数据结构

比对维度：

设计要素	比对方法	差异类型
接口/API 签名	设计文档的 API 定义 vs 实际代码的头文件	签名差异
数据结构/枚举	设计文档的字段定义 vs 实际 struct/enum	字段差异
类/继承关系	设计文档的类图 vs 实际 class 定义	结构差异
方法列表	设计文档的方法列表 vs 实际方法列表	增减差异
参数/返回值	设计文档的参数描述 vs 实际参数类型	类型差异
流程/状态机	设计文档的流程图 vs 实际控制流	逻辑差异
错误码/异常	设计文档的错误定义 vs 实际错误处理	异常差异
Feature Flag	设计文档的开关规划 vs 实际 flag 定义	配置差异
多语言绑定范围	设计文档的绑定要求 vs 实际绑定覆盖	范围差异
模块划分	设计文档的模块边界 vs 实际文件组织	架构差异

执行方式：对设计文档中描述的每个接口/类/方法，使用 Grep + Read 在实际代码中查找对应实现，逐项对比。

将所有差异收集为列表，准备进入用户决策环节。

Step 2: 逐一向用户展示差异并请求决策

对每个差异点，使用 AskUserQuestion 工具向用户展示并请求决策。每次仅展示一个差异点，等待用户明确回复后再处理下一个。

展示格式：

差异 {N}/{Total}: {差异标题}

设计文档描述：
  {设计文档中的原始描述，包含章节引用}

实际实现：
  {代码中实际的实现情况}

差异分析：
  {简要说明差异的原因和影响}

请选择处理方式：
  A) 接受实现 — 将设计文档修改为与实现一致（回写设计文档）
  B) 要求重做 — 按设计文档的要求重新实现代码（启动 coder+reviewer）
  C) 暂时搁置 — 记录为遗留事项，后续处理

用户决策选项说明：

选项	含义	后续操作
A) 接受实现	实现合理，设计文档需要更新	直接 Edit 设计文档原始章节
B) 要求重做	实现偏离设计意图，需修正代码	启动 coder → reviewer 循环
C) 暂时搁置	无法立即决策，后续处理	记录到遗留事项列表

Step 3: 根据用户决策分类处理

收集所有差异点的用户决策，按处理方式分组：

决策 A（接受实现）的差异数量: {a_count}
决策 B（要求重做）的差异数量: {b_count}
决策 C（暂时搁置）的差异数量: {c_count}

Step 4: 执行用户决策

对决策 A（接受实现）的差异：直接回写设计文档

关键原则：直接修改设计文档的原始章节，而不是在末尾追加说明。

对每个决策 A 的差异：

1. 使用 Read 定位设计文档中对应的原始章节
2. 使用 Edit 就地修改原始描述，使其与实际实现一致
3. 不在末尾追加汇总章节，仅在修改处标注修改来源

修改原则：

• 仅修改与实现不一致的段落/章节，不改动文档整体结构
• 保持原文档的写作风格和术语
• 使用 Edit 精确替换，不覆盖整个文档
• 每处修改通过行内注释标注变更来源和原因

对决策 B（要求重做）的差异：启动 coder+reviewer 重做循环

将所有决策 B 的差异整合为重做需求，传递给 arkweb-coder Agent：

请根据以下用户决策，重新实现代码以对齐设计文档。

需求设计文档路径：{requirement_path}
设计文档路径：{design_path}

用户要求重做的差异点：

差异 1: {差异标题}
  设计文档要求：{设计文档的原始描述}
  当前实现：{当前代码的实现}
  需要修改为：{与设计文档一致}

差异 2: ...

请按以下步骤执行：
1. 读取需求设计文档中对应的章节
2. 使用 TodoWrite 创建修复任务列表
3. 逐个修改代码文件以对齐设计文档
4. 修改完成后输出变更文件清单

重做完成后，启动 arkweb-reviewer Agent 仅检视重做涉及的文件。

如果检视仍有 BLOCKER/CRITICAL 问题，继续修复循环（最多 3 轮）。

对决策 C（暂时搁置）的差异：记录到遗留事项

不修改设计文档，不修改代码。仅在最终总结中列出。

Step 5: 差异对齐循环检查

如果有决策 B 的差异触发了重做：
    → 重新执行 Step 1（重新收集信息并比对）
    → 检查重做是否引入了新的差异
    → 如果有新差异 → 回到 Step 2（向用户展示新差异）
    → 如果无新差异 → 退出循环

如果无决策 B 的差异：
    → 直接退出循环，所有差异已处理完毕

循环保护：

max_diff_rounds = 5
如果差异对齐循环超过 5 轮：
    → 向用户报告仍有未对齐的差异
    → 列出剩余差异
    → 建议人工介入

Step 6: 输出差异处理总结

完成所有差异处理后，向用户输出总结：

═══════════════════════════════════════════
  设计差异对齐完成
═══════════════════════════════════════════
需求文档: {requirement_path}
设计文档: {design_path}

差异统计:
  总差异点: {N}

用户决策分布:
  接受实现（已回写设计文档）: {A_count} 处
  要求重做（已重新实现）:     {B_count} 处
  暂时搁置（记录为遗留）:     {C_count} 处

已直接修改的设计文档章节:
  - {章节1} ({差异标题}): {修改摘要}
  - {章节2} ({差异标题}): {修改摘要}

已重新实现的代码文件:
  - {文件1}: {修改说明}
  - {文件2}: {修改说明}

遗留事项（用户选择搁置）:
  - [ ] {差异标题}: {设计要求 vs 实际实现}
═══════════════════════════════════════════

流程状态追踪

使用 TodoWrite 维护进度：

Step 1: 收集信息并识别差异    [pending / in_progress / completed]
Step 2: 向用户展示差异并决策  [pending / in_progress / completed]
Step 3: 分类处理              [pending / in_progress / completed]
Step 4: 执行用户决策          [pending / in_progress / completed]
Step 5: 差异对齐循环检查      [pending / in_progress / completed]
Step 6: 输出总结              [pending / in_progress / completed]
  └─ 差异决策轮次 (1~5)       [追踪当前是第几轮差异对齐]

异常处理

无差异

• 向用户报告"设计文档与实现完全一致，无需对齐"
• 直接退出

达到最大轮次仍有差异

• 停止差异对齐循环
• 向用户报告仍有未对齐的差异
• 列出剩余差异及建议处理方式
• 保留已完成的差异处理结果

设计文档不存在

• 向用户报告路径错误
• 提示正确的文档路径

代码仓库中未找到实现

• 向用户报告未找到对应的实现代码
• 列出设计文档中定义但未实现的接口/类
• 建议先完成代码实现