understand

understand

把「本次（AI）新生成的代码变更」变成一个可交互的审阅网页：左侧按真实项目布局列出变更文件树，右侧显示所选文件的 diff（高亮、增删与未变更代码明显区分），并在右侧边栏逐段给出相关单位需求与代码解释。

始终用中文产出解释与需求。

何时用

• 用户说 /understand、"review 这次改动"、"解释下新写的代码"、"看看这次变更做了啥"。
• 目标是理解 + 审阅当前工作区里尚未吃透的改动（通常是 AI 刚生成的），不是重构或修 bug。

组成

skill 目录下三件套（都在 ~/.claude/skills/understand/）：

• understand.py — 纯标准库生成器，两个子命令：scan（解析 git diff → data.json + annotations.json 骨架）、render（合并注释 → report.html）。
• template.html — Claude light 主题两栏页面（占位符 __UNDERSTAND_PAYLOAD__ 注入数据），Prism.js 走 CDN 做语法高亮。
• 本文件 — 流程说明。

执行流程

在**用户当前工作目录（仓库内）**执行以下步骤。全程把 SKILL_DIR 当作本 skill 目录的绝对路径（即本文件所在目录）。

1. 扫描变更

python3 "$SKILL_DIR/understand.py" scan

• 默认基线 = 当前分支与主分支（origin/main→main→master）的 merge-base；如用户指定范围可加 --base <ref>（例如只看最后一次提交用 --base HEAD~1）。
• 默认输出目录 .understand/（相对 CWD）。可用 --out <dir> 改。
• 它覆盖：已提交(base..HEAD) + 已暂存 + 未暂存 + 未跟踪新文件。
• 命令会打印 JSON：文件数、增删行数、data.json / annotations.json 路径、以及 paths（变更文件列表）。读这个输出了解改了哪些文件。

2. 通读改动并撰写注释

先把改动读懂，再落注释。建议：

• Read 每个变更文件（结合 data.json 里的 hunks 看具体增删行号），必要时读周边未改代码补足上下文。
• 判断每处改动对应的单位需求：优先从仓库线索找真实依据——commit message、docs/ 需求文档、代码注释里写的需求编号/背景、相关 issue。找到真实需求就照写；确实找不到，就基于代码逻辑写「推测意图」并在注释里把 inferred 置为 true（前端会标成灰色「推测意图」而非「需求」，避免把猜测伪装成事实）。

然后编辑 .understand/annotations.json（scan 已生成骨架，保留其 files[].path 顺序，逐个填充）。结构：

{
  "title": "本次变更的一句话主题",
  "summary": "整体在做什么、为什么（2~4 句，可用 **加粗** 与 `代码`）",
  "files": [
    {
      "path": "src/main/java/.../PwaTierInvitationService.java",
      "summary": "这个文件这次改了什么、为何改（1~3 句）",
      "annotations": [
        {
          "side": "new",
          "start": 52,
          "end": 53,
          "requirement": "expires_at 为 timestamptz，需正确编码",
          "explanation": "Vert.x PG 客户端不支持 `java.time.Instant`，改绑 `OffsetDateTime`（`atOffset(UTC)`），否则运行期报 coercion 错误。",
          "inferred": false
        }
      ]
    }
  ]
}

注释字段：

• side — "new" 锚定新版本行号（增行/上下文），"old" 锚定旧版本行号（删行）。绝大多数解释用 "new"。
• start / end — 该段代码的行号区间（data.json 里对应 side 的 newNo/oldNo；单行时 end 可省或等于 start）。行号是文件真实行号，不是 diff 里的序号。
• requirement — 该段对应的单位需求（简短一句，作为标签展示）。可留空。
• explanation — 代码解释：讲清这段在干嘛、为什么这么写、有何风险/前提。可用 `code` 和 **bold**。
• inferred — 需求为推测时置 true。