understand

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

understand

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

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

Turn "this batch of (AI-)generated code changes" into an interactive review webpage: the left side lists the changed file tree following the actual project structure, the right side displays the diff of the selected file (with syntax highlighting, clearly distinguishing additions/deletions from unchanged code), and the right sidebar provides related unit requirements and code explanations for each code segment.

Always generate explanations and requirements in Chinese.

何时用

When to Use

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

When the user says "/understand", "review this change", "explain the newly written code", "check what this change does"
The goal is to understand and review changes in the current workspace that haven't been fully grasped (usually newly generated by AI), not to refactor or fix bugs.

组成

Components

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 做语法高亮。
本文件 — 流程说明。

Three core files in the skill directory (located at

~/.claude/skills/understand/

```
understand.py
```
— A pure standard library generator with two subcommands:
```
scan
```
(parses git diff → generates skeleton for
```
data.json
```
+
```
annotations.json
```
),
```
render
```
(merges annotations → outputs
```
report.html
```
)
```
template.html
```
— A two-column page with Claude light theme (injects data via placeholder
```
__UNDERSTAND_PAYLOAD__
```
), using Prism.js via CDN for syntax highlighting
This file — Process documentation

执行流程

Execution Flow

在**用户当前工作目录（仓库内）**执行以下步骤。全程把

SKILL_DIR

当作本 skill 目录的绝对路径（即本文件所在目录）。

Execute the following steps in the user's current working directory (within the repo). Treat

SKILL_DIR

as the absolute path to this skill directory (i.e., the directory where this file resides) throughout the process.

1. 扫描变更

1. Scan Changes

bash

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
```
（变更文件列表）。读这个输出了解改了哪些文件。

bash

python3 "$SKILL_DIR/understand.py" scan

Default baseline = merge-base of the current branch and the main branch (origin/main→main→master); if the user specifies a range, add
```
--base <ref>
```
(e.g., use
```
--base HEAD~1
```
to only view the last commit)
Default output directory is
```
.understand/
```
(relative to CWD). Use
```
--out <dir>
```
to modify it
It covers: committed changes (base..HEAD) + staged changes + unstaged changes + untracked new files
The command will print JSON: number of files, lines added/deleted, paths to
```
data.json
```
/
```
annotations.json
```
, and
```
paths
```
(list of changed files). Read this output to understand which files were modified

2. 通读改动并撰写注释

2. Read Through Changes and Write Annotations

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

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

然后编辑
.understand/annotations.json
（scan 已生成骨架，保留其

files[].path

顺序，逐个填充）。结构：

json

{
  "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
```
。

注释密度：聚焦关键/易错/体现需求的段落（新增的核心逻辑、边界处理、并发/事务、类型坑、SQL 口径等），不必逐行；每个重要文件给 1~5 条即可。可参考项目记忆里的常见坑（如 Vert.x

Future.await()

、PG

= ANY

数值数组、

timestamptz

编码）来判断哪些点值得解释。

First understand the changes thoroughly, then write annotations. Recommendations:

```
Read
```
each changed file (refer to the hunks in
```
data.json
```
to see specific line numbers of additions/deletions), and read surrounding unchanged code if necessary to supplement context
Determine the related unit requirement for each change: prioritize finding real evidence from repo clues — commit messages, requirement documents in
```
docs/
```
, requirement IDs/background written in code comments, related issues. Write the real requirement if found; if none can be found, write an "inferred intent" based on code logic and set
```
inferred
```
to
```
true
```
in the annotation (the frontend will mark it as gray "Inferred Intent" instead of "Requirement" to avoid passing guesses off as facts)

Then edit
.understand/annotations.json
(the scan has generated a skeleton; keep the order of

files[].path

and fill them one by one). Structure:

json

{
  "title": "One-sentence theme of this change",
  "summary": "Overall what's being done and why (2~4 sentences, can use **bold** and `code`)",
  "files": [
    {
      "path": "src/main/java/.../PwaTierInvitationService.java",
      "summary": "What was changed in this file and why (1~3 sentences)",
      "annotations": [
        {
          "side": "new",
          "start": 52,
          "end": 53,
          "requirement": "expires_at is timestamptz, needs correct encoding",
          "explanation": "Vert.x PG client does not support `java.time.Instant`, changed to bind `OffsetDateTime` (using `atOffset(UTC)`), otherwise a coercion error will occur at runtime.",
          "inferred": false
        }
      ]
    }
  ]
}

Annotation fields:

```
side
```
—
```
"new"
```
anchors to line numbers in the new version (added lines/context),
```
"old"
```
anchors to line numbers in the old version (deleted lines). Most explanations use
```
"new"
```
```
start
```
/
```
end
```
— Line number range of the code segment (corresponding to
```
newNo
```
/
```
oldNo
```
of the specified side in
```
data.json
```
; for single lines,
```
end
```
can be omitted or equal to
```
start
```
). Line numbers are the actual line numbers of the file, not the sequence numbers in the diff
```
requirement
```
— Related unit requirement for this segment (short sentence, displayed as a tag). Can be left blank
```
explanation
```
— Code explanation: clearly state what this segment does, why it's written this way, and any risks/preconditions. Can use
```
`code`
```
and
```
**bold**
```
```
inferred
```
— Set to
```
true
```
if the requirement is inferred

Annotation density: Focus on key/error-prone/requirement-reflecting segments (new core logic, boundary handling, concurrency/transactions, type pitfalls, SQL calibers, etc.), no need to explain line by line; 1~5 annotations per important file are sufficient. Refer to common pitfalls in project memory (such as Vert.x

Future.await()

, PG

= ANY

numeric arrays,

timestamptz

encoding) to judge which points are worth explaining

3. 渲染并打开

3. Render and Open

bash

python3 "$SKILL_DIR/understand.py" render
open .understand/report.html    # macOS；Linux 用 xdg-open

render

会把

data.json

annotations.json

合并注入模板，产出

.understand/report.html

（单文件，纯前端，Prism 走 CDN）。用浏览器打开即可：左树选文件 → 右侧看 diff → 边栏卡片点「定位 →」跳到对应代码行（会高亮闪一下）。左侧文件树栏可拖动分隔条调整宽度（宽度记忆在 localStorage，双击分隔条恢复默认）。

最后用中文向用户简述：改了几个文件、核心变更是什么、有哪些值得注意的点，并给出

report.html

路径。

bash

python3 "$SKILL_DIR/understand.py" render
open .understand/report.html    # macOS; use xdg-open for Linux

render

will merge

data.json

annotations.json

and inject them into the template to generate

.understand/report.html

(a single file, pure frontend, Prism via CDN). Open it in a browser: select a file from the left tree → view the diff on the right → click "Locate →" on the sidebar card to jump to the corresponding code line (it will flash to highlight). The left file tree panel allows dragging the separator to adjust width (width is stored in localStorage, double-click the separator to restore default)

Finally, briefly inform the user in Chinese: how many files were changed, what the core changes are, any notable points, and provide the path to

report.html

注意

Notes

```
.understand/
```
是产物目录，建议提醒用户按需
```
git clean
```
或加
```
.gitignore
```
，别误提交。
若
```
data.json
```
为空（无变更），如实告知用户没有检测到改动，不要硬造。
行号务必对齐
```
data.json
```
：
```
annotations.json
```
里的
```
start/end
```
用文件真实行号，
```
side
```
决定用新/旧行号系。填错会导致边栏卡片锚不到代码行（不报错，但点「定位」无反应）。
不改动用户业务代码；本 skill 只读代码 + 写
```
.understand/
```
下的产物。

```
.understand/
```
is the output directory; it is recommended to remind the user to use
```
git clean
```
as needed or add it to
```
.gitignore
```
to avoid accidental commits
If
```
data.json
```
is empty (no changes detected), truthfully inform the user that no changes were found, do not fabricate content
Line numbers must align with
```
data.json
```
:
```
start/end
```
in
```
annotations.json
```
use the actual file line numbers, and
```
side
```
determines whether to use the new/old line number system. Incorrect entries will cause sidebar cards to fail to anchor to code lines (no error will be reported, but clicking "Locate" will have no effect)
Do not modify the user's business code; this skill only reads code + writes outputs under
```
.understand/
```