code-read-deep-change

Imported from ElioJay/skills (.codex/skills/code-read-deep-change/SKILL.md). Install upstream with npx skills add ElioJay/skills --skill code-read-deep-change. Copyright stays with the author.

深度代码阅读 · 变更阅读 (code-read-deep-change)

从用户给出的一次变更（git diff / git show / commit 范围 A..B / PR / 用户直接给的 .diff 文本）出发，只读不改地读懂这次变更： 获取变更 → 摸清范围 → 说清改了什么 → 推断意图 → 反查影响半径 → 核对关联测试 → 诚实摊开风险面 → 顺手记录明显问题， 最后产出一份结构化、规范化的中文变更阅读报告，内含一张 Mermaid 影响半径图。

报告遵循固定的 8 段结构：变更范围 → 改了什么 → 意图推断 → 影响半径 → 关联测试 → 风险面 → 问题 → 建议下一步。

定位是理解变更（改了什么 / 为什么 / 波及谁 / 有哪些风险点）；不是质量评判（好不好 / 安不安全 / 该不该合 → code-review-deep-zh）。

核心定位

• 变更驱动：分析对象是"一次变更"（一段 diff / 一个 commit / 一个范围 / 一个 PR），不是某一个现有的方法/文件/模块/项目。
• 影响半径优先：核心价值在于把被改符号的调用方/消费方/下游契约反查出来，标清"谁需要跟着改"。
• 理解而非评判：答"改了什么 / 为什么 / 波及谁 / 有哪些风险点"；不给变更打质量分、不判断该不该合（那是 code-review-deep-zh）。
• 诚实标风险与遗漏：行为变化、可能漏改的调用方/测试/文档，显式摊开，不假装"改得很完整"。
• 只读不改：不改 diff、不改代码、不提交；阅读导向非质量审查（问题只报逻辑/流程硬伤 + 变更相关不一致）。
• 多语言：按各生态识别被改符号与其调用点（Java/Kotlin/Python/JS/TS/Go/C#）。

硬性前置：必须是「一次变更」

先判定，再做其他任何事。

只接受一次变更作为分析对象：工作区改动（git diff）、暂存区（git diff --cached）、提交范围（git diff A..B / git log A..B）、单个 commit（git show <sha>）、PR（gh pr diff <n>）、或用户直接给的 .diff/.patch 文本。

以下输入不走本 skill：

• 读现有代码的单个方法入口 类名.方法名 → code-read-deep-function。
• 读现有的单个文件 → code-read-deep-file。
• 读现有的单个模块/目录/包 → code-read-deep-module。
• 读现有的整个项目/仓库 → code-read-deep-project。
• 质量/安全/性能审查、给变更打分、判断该不该合/有没有 bug（即便对象是 PR/diff）→ code-review-deep-zh。
  • 标准回应：

    你给的是<一个现有方法/文件/模块/项目>，想读懂这个容器请用 code-read-deep-<function/file/module/project>。 若你想评判这次变更好不好 / 有没有 bug 或安全问题 / 该不该合，请用 code-review-deep-zh。 若你想读懂一次变更改了什么、波及谁、有哪些风险点（理解，不评判），把 diff / commit / PR 给我即可。

区别要点：容器 skill 答"这个现有的东西内部是什么/怎么组织"；本 skill 答"这次变更动了什么、波及哪里"；review 答"这次变更好不好/能不能合"。

何时使用 / 何时不用

使用本 skill：

• 想知道某个 PR / commit / 一段 diff 改了什么、为什么这么改。
• 想知道这次改动的影响半径：被改符号波及哪些上下游、有没有漏改的调用方。
• 想知道签名/返回/契约变化的下游是否需要同步改、新增依赖是否已装配、被删符号是否仍被引用。
• 想把一次变更的改动与波及范围讲清楚（理解导向）。

不要用本 skill（改走对应能力）：

• 读现有代码的单个方法/文件/模块/项目 → 对应的 code-read-deep-* 容器 skill。
• 质量/安全/性能审查、给变更打分、判断该不该合/找 bug（即便对象是 PR/diff）→ code-review-deep-zh。
• 加注释 → code-annotating；一句话解释 → /explain；调 bug → systematic-debugging；写新功能 → code-vibe-workflow。

工作流程

按顺序执行，不要跳阶段。详细规则按需加载 references/change-rules.md；

必要时加载 references/reading-lenses.md——尤其"git 历史"视角推断意图、"测试即规格"视角判断关联测试（"框架感知/运行期"在反查 DI 装配、动态分发的影响时也有用）。

digraph code_read_deep_change {
    "收到请求" [shape=ellipse];
    "是一次变更?" [shape=diamond];
    "是现有容器(方法/文件/模块/项目)?改道对应skill" [shape=box];
    "要质量评判/找bug/能否合?改道code-review-deep-zh" [shape=box];
    "阶段1 变更来源获取(只读git/接收.diff)" [shape=box];
    "阶段2 变更范围与分类(--stat+符号级)" [shape=box];
    "阶段3 改了什么+意图推断" [shape=box];
    "阶段4 影响半径反查(影响半径图)" [shape=box];
    "阶段5 关联测试核对" [shape=box];
    "阶段6 风险面识别" [shape=box];
    "阶段7 问题识别(逻辑硬伤+变更不一致)" [shape=box];
    "阶段8 确认输出位置+生成报告+自检" [shape=box];

    "收到请求" -> "是一次变更?";
    "是一次变更?" -> "是现有容器(方法/文件/模块/项目)?改道对应skill" [label="否:读现有代码"];
    "是一次变更?" -> "要质量评判/找bug/能否合?改道code-review-deep-zh" [label="否:要评判"];
    "是一次变更?" -> "阶段1 变更来源获取(只读git/接收.diff)" [label="是"];
    "阶段1 变更来源获取(只读git/接收.diff)" -> "阶段2 变更范围与分类(--stat+符号级)";
    "阶段2 变更范围与分类(--stat+符号级)" -> "阶段3 改了什么+意图推断";
    "阶段3 改了什么+意图推断" -> "阶段4 影响半径反查(影响半径图)";
    "阶段4 影响半径反查(影响半径图)" -> "阶段5 关联测试核对";
    "阶段5 关联测试核对" -> "阶段6 风险面识别";
    "阶段6 风险面识别" -> "阶段7 问题识别(逻辑硬伤+变更不一致)";
    "阶段7 问题识别(逻辑硬伤+变更不一致)" -> "阶段8 确认输出位置+生成报告+自检";
}

各阶段要点见 references/change-rules.md：① 变更来源获取（只读 git / 接收 .diff，含闸门判定）；② 变更范围与分类（--stat 列文件 + 落到符号级，标签名/返回/异常是否变）；③ 改了什么（说实质改动，不逐行念 diff）+ 意图推断（commit message / PR / git 历史）；④ 影响半径（对每个对外/高风险被改符号全库反查调用方，盯签名/契约变化的下游是否需同步改、新依赖是否装配、被删符号是否仍被引用，深挖委派）；⑤ 关联测试（测试即规格，哪些需更新/缺失）；⑥ 风险面（行为变化点、边界/兼容性、可能遗漏路径、未同步更新）。 阶段 7：按 references/problem-checklist.md 仅记录逻辑/流程硬伤 + 变更相关不一致。 阶段 8：先由用户指定输出位置/文件名（默认建议 docs/code-read-deep-change/<变更标识>-YYYYMMDD.md，也可仅对话输出），按 references/report-template.md 生成 8 段 + 一张图，过自检后交付。

报告结构（8 段）

完整模板见 references/report-template.md：变更范围（--stat+符号级）/ 改了什么（实质改动）/ 意图推断（带证据来源）/ 影响半径（＋影响半径图）/ 关联测试 / 风险面 / 问题 / 建议下一步。

一张 Mermaid 图

• 影响半径图（flowchart LR）：中心 = 被改符号，四周 = 受影响的调用方/消费方/下游契约；在边或节点上标注「签名变更 / 已删除 / 新增依赖未装配 / 依赖新增 setter」等。

规范化自检（交付前必过）

• 8 段齐全、顺序正确；影响半径图存在可渲染。
• 「变更范围」落到符号级（哪些类/方法/字段被增删改、签名/返回/异常是否变），不只列文件。
• 「影响半径」对每个对外/高风险被改符号都反查了调用方，明确"是否需同步改"；未反查处标「未逐一反查」。
• 「意图推断」证据不足处标「推断」，未把猜测写成结论。
• 「风险面」摊开行为变化与可能漏改的调用方/测试/文档，未假装"改得很完整"。
• 深挖某受影响容器附"向下委派"，沿某线索追到底附"委派 trace"，未在本报告展开容器内部或追穿整条链。
• 问题分级规范（🔴/🟡/🔵 + 证据 + 影响），仅逻辑硬伤 + 变更相关不一致；未做质量评分。
• 聚焦"这一次变更"，未发散成"读某个现有容器"或"给变更打分"。
• 中文表述，术语一致；位置引用为 相对路径:行号。

与其他能力的边界

增量更新与阅读索引（可选）

• 增量更新：若用户指定的输出位置已存在上一版报告，先读旧报告、对比当前代码变化做增量更新（显式标注「新增 / 变化 / 移除」），而非从零重写。
• 阅读索引：可在 docs/code-read-deep/INDEX.md 累积「已读清单」（粒度 ｜ 对象 ｜ 报告路径 ｜ 日期），让重复阅读沉淀为项目知识；首次写入时创建该文件。

常见错误

• 把理解做成评判：用户要"读懂这次改了啥/波及谁"，却去给变更打质量分、判断能不能合 —— 错，那是 code-review-deep-zh。
• 只列文件不落符号：变更范围停在文件级，没说哪些方法/签名/字段变了 —— 错。
• 漏反查影响半径：被改的是对外符号却不查调用方，错过"调用方需同步改" —— 错，这是本 skill 的重心。
• 把猜测当结论：意图推断没有证据还写得言之凿凿 —— 错，证据不足要标「推断」。
• 假装改得很完整：明明 diff 漏改了调用点/装配/测试却不在风险面摊开 —— 错。
• 容器误吃：给的是"读某个现有方法/文件/模块/项目"还硬当变更读 —— 错，改道对应容器 skill。
• 越权改码 / 越界报问题 / 自作主张存盘：同家族 —— 错。