实现设计对齐 Skill

实现设计对齐

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 的差异：

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

修改原则：

仅修改与实现不一致的段落/章节，不改动文档整体结构
保持原文档的写作风格和术语
使用 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)       [追踪当前是第几轮差异对齐]

异常处理

无差异

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

达到最大轮次仍有差异

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

设计文档不存在

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

代码仓库中未找到实现

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

Agent Skills: 实现设计对齐

Install this agent skill to your local

Skill Files