understand

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

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

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

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. Scan Changes

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. Read Through Changes and Write Annotations

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. Render and Open

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/
```
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/
```

understand

NPX Install

Tags

SKILL.md Content (Chinese)

understand

When to Use

Components

Execution Flow

1. Scan Changes

2. Read Through Changes and Write Annotations

3. Render and Open

Notes