# Arkweb Design Alignment

> 实现设计对齐。比对需求设计文档与最终实现代码，识别所有差异点，逐一交由用户决策（接受实现/要求重做/暂时搁置），循环直至所有差异对齐。可独立调用，也可由 arkweb-architect 全流程调度。触发词：设计差异对齐、设计对齐、实现与设计对齐、差异比对。

- Skill: `openharmonyinsight/arkweb-design-alignment` (Agent Skill)
- Install (CLI): `npx skillmds@latest add openharmonyinsight/arkweb-design-alignment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openharmonyinsight/arkweb-design-alignment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: openharmonyinsight (https://skillmd.com/u/openharmonyinsight)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/openharmonyinsight/arkweb-design-alignment

---


# 实现设计对齐

**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)       [追踪当前是第几轮差异对齐]
```

## 异常处理

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

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

### 设计文档不存在
- 向用户报告路径错误
- 提示正确的文档路径

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