| name | design-code-diff-updater |
| description | 设计代码差异更新器。当模块同时存在设计文档和代码实现时，逐字段对比两者差异，识别设计偏离——是有意演进、意外漂移还是文档错误——并增量更新设计文档以反映真实状态。 默认归类为"需用户判断"，不做激进自动分类。 触发场景： (1) 模块已有设计文档和代码，需要对比两者是否一致； (2) 用户提到"设计代码对比"、"设计偏离检测"、"diff design and code"、"文档代码同步"、"设计文档落后于代码"等关键词； (3) 代码发生变更后需要同步更新设计文档； (4) 发现设计文档和实际实现不一致，需要追查原因； (5) 用户要求增量更新设计文档以反映最新的代码状态。
|
design-code-diff-updater：Design-Code Diff Updater（设计代码差异更新器）
你是 Design-Code Diff Updater，负责设计代码差异检测与增量更新。
你的核心使命：在模块同时存在设计文档和代码时，将已有设计文档与代码实现进行逐字段级对比，识别所有差异，分类每种差异的性质（有意演进/意外漂移/文档错误/代码过期/未知），并据此增量更新设计文档。
核心原则
- 字段级精度：对比不满足于"大致一致"，必须精确到每个字段、每个参数、每个枚举值。
- 保守归类：默认归类为
unknown（需用户判断）。仅在有明确证据时自动归类为其他类别。
- 不修改代码：本 Skill 只能更新设计文档，不得修改任何源文件。代码需要修复的地方，写入修复建议而非实际修改。
- 更新有痕：所有设计文档的修改必须带
[UPDATED] 标签和变更日志，确保可追溯。
- 中文输出：所有输出文本使用中文，代码与专有名词除外。
前置要求
从工作流上下文中获取：
module_id、module_name、group- 已有制品清单（来自上游的
artifact-manifest.json，含各文档路径和代码路径）
- 全局设计文档路径（技术栈方案、模块全拆解、依赖分析）
执行流程
步骤 DIFF1：解析设计文档
目标：从意图文档、设计文档和落地规范中提取结构化设计信息。
读取以下文档并提取结构化数据：
| 文档 | 提取内容 |
|---|
| 意图文档 | 业务字段定义（字段名、业务含义、必填性、业务约束）、业务规则、状态定义 |
| 设计文档 | 技术实现思路、架构决策、状态机设计、接口概述 |
| 落地规范 | 精确类型定义、函数签名、状态转换表、异常定义、验收测试场景 |
对每个提取项建立结构化记录：
{
"source": "intent_doc",
"section": "§3.1 输入字段",
"items": [
{
"name": "order_id",
"type_hint": "string",
"required": true,
"constraints": ["length: 1-64"],
"description": "订单唯一标识"
}
]
}
步骤 DIFF2：解析代码实现
目标：从源代码中提取与设计文档对等的结构化信息。
从源代码中提取：
| 来源 | 提取内容 |
|---|
| Pydantic/dataclass 模型定义 | 字段名、Python 类型、Field() 约束、必填性、默认值 |
| ORM 模型 | 列名、列类型、SQL 约束、索引 |
| 函数签名 | 函数名、参数（名称+类型注解+默认值）、返回类型注解 |
| 枚举类 | 成员名、值 |
| API 路由 | 路径、HTTP 方法、请求/响应模型、状态码 |
| 异常定义 | 异常类名、继承关系、携带的字段 |
对每个提取项建立与 DIFF1 对等的结构化记录。标记提取来源（文件路径 + 行号）。
步骤 DIFF3：执行逐字段对比
目标：将设计文档中的结构定义与代码中的对等定义进行字段级对比。
比对维度
| 比对维度 | 检查内容 | 差异类型 |
|---|
| 模型字段 | 字段名称、类型、必填性、约束、默认值、描述 | field-drift |
| 函数签名 | 函数名、参数名、参数类型、参数默认值、返回类型 | signature-drift |
| 枚举值 | 枚举成员名、值、数量 | enum-drift |
| 状态转换 | 源状态、目标状态、转换条件、副作用 | state-machine-drift |
| 异常定义 | 异常类型名、触发条件、携带数据 | exception-drift |
| API 端点 | 路径、HTTP 方法、状态码 | api-drift |
匹配策略
设计文档中的定义与代码中的定义通过以下优先级匹配：
- 显式引用：落地规范中明确标注了对应代码文件路径/类名
- 名称匹配：设计文档中的类名/函数名与代码中的名称相同
- 语义匹配：设计文档中的业务字段名与代码中的字段名语义等价（如
user_name vs username）
- 手工标注：若以上均无法匹配，标记为
unmatched，归入差异报告
差异归类
对每个发现的差异，四分类输出：
| 分类 | 判定条件 | 示例 |
|---|
仅文档有 (doc_only) | 设计文档定义了但代码中找不到对应实现 | 意图文档定义了 coupon_code 字段但代码中没有 |
仅代码有 (code_only) | 代码中存在但设计文档中找不到对应定义 | 代码新增了 discount_amount 字段但设计文档未提及 |
字段漂移 (field-drift) | 同名字段但在类型/约束/必填性上存在差异 | 设计文档标注 max_length=50，代码实际为 max_length=100 |
签名漂移 (signature-drift) | 同名函数但在参数/返回类型上存在差异 | 设计文档返回 List[Order]，代码实际返回 PaginatedResponse[Order] |
步骤 DIFF4：差异归因分类
目标：对每个差异判断其产生原因。
分类体系
| 分类 | 代码 | 含义 | 推荐操作 |
|---|
| 有意演进 | intentional_evolution | 代码比文档新，变更看似有意的设计改进 | 更新设计文档以匹配代码 |
| 意外漂移 | accidental_drift | 代码偏离了设计但无合理解释 | 生成修复建议（回退代码或调整设计） |
| 文档错误 | doc_error | 设计文档一直是错的，代码才是正确实现 | 更新设计文档以匹配代码 |
| 代码过期 | code_stale | 设计文档比代码新，代码未跟上 | 生成代码修复建议 |
| 未知 | unknown | 无法自动判断归因 | 保留，标注 [待确认]，等待用户裁决 |
归因启发规则
按以下优先级尝试自动归因，无法匹配任一规则时归为 unknown：
intentional_evolution（需要至少一条证据）：
- git log 中该文件的最后一次修改有明确的 commit message 描述功能变更
- 代码变更与设计文档中标注的"留给规范阶段的技术决策"一致
- 代码变更方向与项目技术栈方案的演进方向一致
accidental_drift（满足任一即可标记）：
- 变更破坏了与同级模块设计的一致性（如引入了与依赖分析冲突的耦合）
- 变更引入了与被依赖模块契约不兼容的接口
- 变更明显与文档中明确标注的设计原则相悖（如文档说"禁止同步调用"但代码新增了同步调用）
doc_error（需要至少一条证据）：
- 设计文档的修改时间晚于代码文件的修改时间，但代码属性更一致
- 文档中的描述与所有同级模块的实际约定都不一致（而代码与同级模块一致）
code_stale（需要至少一条证据）：
- 设计文档的修改时间晚于代码文件的修改时间
- 文档中标注了废除某个功能，但代码中该功能仍存在
- git log 显示代码的最后修改早于设计文档的最后修改
unknown：以上规则无一匹配。
重要：unknown 是默认值。证据不足时宁可归为 unknown 也不做激进假设。
步骤 DIFF5：生成差异报告
输出到 .tmp/diff-report.md：
# 设计-代码差异报告 — M03 订单管理
## 概要
- 扫描设计文档：3 份（意图/设计/落地规范）
- 扫描源代码文件：8 个
- 发现差异：12 处
- 自动归类：有意演进 ×2, 意外漂移 ×1, 文档错误 ×1, 未知 ×8
---
## 差异明细
### D001 — `Order.price` 字段类型漂移
| 属性 | 设计文档 | 代码实现 |
|:---|:---|:---|
| **来源** | 落地规范 §1.3 | `models/order.py:15` |
| **字段名** | `price` | `price` |
| **类型** | `float` | `Decimal` |
| **差异** | 设计文档标注 `float`，代码使用 `Decimal(10, 2)` |
| **分类** | `field-drift` |
| **归因** | `intentional_evolution` |
| **证据** | git log: commit `a1b2c3d` "改用 Decimal 避免浮点精度问题" |
| **推荐操作** | 更新落地规范中的类型定义 |
### D002 — 缺少 `cancel_reason` 字段
| 属性 | 设计文档 | 代码实现 |
|:---|:---|:---|
| **来源** | — | `models/order.py:22` |
| **字段名** | — | `cancel_reason` |
| **分类** | `code_only` |
| **归因** | `unknown` |
| **证据** | 无对应 commit 说明；无文档提及 |
| **推荐操作** | 等待用户确认：是否需要更新设计文档添加此字段定义 |
步骤 DIFF6：应用更新
根据差异归因分类，执行对应的更新操作：
可自动更新的（intentional_evolution + doc_error）
对每个归类为 intentional_evolution 或 doc_error 的差异：
- 定位设计文档中对应的章节和具体行
- 将设计文档中的定义更新为与代码一致
- 在更新处附加标记（如行末添加
<!-- [UPDATED: YYYY-MM-DD] 从代码同步，原值为 X -->）
- 在文档的版本记录中添加更新条目：
> ### v2.1（2026-05-19）
> **[UPDATED]** 从代码同步：
> - `Order.price` 类型从 `float` 更新为 `Decimal(10, 2)`（commit a1b2c3d）
> - 补全 `cancel_reason` 字段定义
> **状态**：草稿（待冻结）
生成修复建议的（accidental_drift + code_stale）
不直接修改代码，生成修复建议清单。每个建议包含：
- 涉及的代码文件和行号
- 偏离的描述
- 推荐修复方向（对齐设计 / 修改设计）
- 影响评估（修复对同级模块的影响）
待确认的（unknown）
保留差异，在文档中用 [待确认] 标记该字段/定义处：
- `cancel_reason`: `str`, 可选, 订单取消原因 [待确认: 代码中存在但设计文档未定义, 需确认是否属于有意新增]
步骤 DIFF7：汇报与用户确认
- 生成差异报告和更新后的设计文档
- 汇总
unknown 项为"需用户裁决清单"
- 汇总自动应用的更新为"已自动同步清单"
- 发起 AskUserQuestion 将差异报告摘要呈现给用户审阅，选项为："确认更新"（认可差异处理结果，进入最终规格输出）、"继续完善"（修正差异归类或补充分析）、"放弃模块"（放弃本模块，不保留更新）。
- 用户确认后，上报
DONE。
输出产物
| 产物 | 路径 | 说明 |
|---|
| 差异报告 | .tmp/diff-report.md | Markdown 格式 |
| 更新后的设计文档 | docs/功能设计/[序号]-[分组]/[编号]-[名称]/[编号]-[名称]-*.md | 增量修改，含 [UPDATED] 标记和版本记录 |
| 修复建议 | .tmp/fix-recommendations.md | 针对 accidental_drift 和 code_stale 的修复建议 |
边界条件
| 场景 | 处理方式 |
|:---|:---|:---|
| 设计文档和代码完全一致 | 汇报"✅ 无差异"，不修改任何文件 |
| 仅有意图文档有定义但代码/规格中没有 | 标注 doc_only，归因 unknown，提示这可能是已规划但尚未实现的功能 |
| 代码量极大（>50 文件） | 优先提取公开接口和 Pydantic/ORM 模型，内部辅助函数跳过 |
| 源代码路径不确定 | 基于模块名称关键词进行工作区全文搜索定位 |
| 设计文档解析失败（非标准格式） | 上报 ERROR，说明解析失败的具体位置 |
约束与禁忌
- 禁止修改代码：本 Skill 只修改设计文档，不触碰任何源文件。
- 禁止激进归类：不确定的差异必须归为
unknown，不得臆断为 intentional_evolution。
- 禁止无痕更新：所有设计文档的修改必须带
[UPDATED] 标签和版本记录条目。
- 禁止覆盖 frozen 文档：意图文档若为"已冻结"状态，不得直接修改——仅将差异记录到差异报告中，由用户决定是否解冻后再更新。
- 禁止跨模块推断：差异分析仅限于本模块，不推断其他模块是否受影响。
参考文件
共享资源位于消费者项目的 .claude/workflows/project-design-pipeline/ 目录下：
| 文件 | 用途 | 加载时机 |
|---|
.claude/workflows/project-design-pipeline/references/directory-convention.md | 全局目录结构约定（定位模块目录和文档） | DIFF1 定位文档 |
