understand

understand

Turn "the code changes newly generated this time (by AI)" into an interactive review webpage: on the left, list the changed file tree according to the real project layout; on the right, show the diff of the selected file (highlighted, with additions, deletions, and unchanged code clearly distinguished), and in the right sidebar provide section-by-sectionrelated unit requirementsandcode explanations; below the explanation, two expandable text views, "pseudocode" and "call tree," can be provided as needed (refer to the presentation style of the show-me skill).

Always produce explanations and requirements in Chinese.

When to use

• The user says /understand, "review these changes," "explain the newly written code," "see what this change did."
• The goal isunderstanding + reviewchanges in the current workspace that have not yet been fully grasped (usually just generated by AI), not refactoring or bug fixing.

Composition

The three-piece set under the skill directory (all in ~/.claude/skills/understand/）：

• understand.py — a pure standard library generator with two subcommands:scan(parse git diff → data.json + annotations.json skeleton),render(merge annotations → report.html）。
• template.html — Claude light theme two-column page (placeholder __UNDERSTAND_PAYLOAD__ injects data), Prism.js uses CDN for syntax highlighting.
• This file — process description.

Execution flow

Execute the following steps in **the user's current working directory (inside the repository)**. Throughout, treat SKILL_DIR as the absolute path of this skill directory (that is, the directory containing this file).

1. Scan changes

python3 "$SKILL_DIR/understand.py" scan

• Default baseline = the merge-base of the current branch and the main branch (origin/main→main→master); if the user specifies a range, you can add --base <ref>(for example, to view only the last commit use --base HEAD~1）。
• Default output directory .understand/(relative to CWD). You can use --out <dir> to change it.
• It covers: committed (base..HEAD) + staged + unstaged + untracked new files。
• The command prints JSON: file count, added/deleted line counts,data.json / annotations.json paths, and paths(list of changed files).Read this outputto learn which files were changed.

2. Read through the changes and write annotations

First understand the changes, then add annotations. Suggestions:

• Read For each changed file (combined with data.json 's hunks to see the specific added/deleted line numbers), and when necessary read surrounding unchanged code to fill in context.
• Determine thecorresponding unit requirementfor each change: prioritize finding real evidence from repository clues—commit message,docs/ requirement documents, requirement numbers/background written in code comments, related issues.If a real requirement is found, write it as is; if it truly cannot be found, write an "inferred intent" based on the code logic and set inferred in the annotation to true(the frontend will mark it as gray "inferred intent" rather than "requirement," avoiding disguising guesses as facts).

Thenedit .understand/annotations.json(scan has already generated the skeleton; keep its files[].path order and fill it in one by one). Structure:

{
  "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 错误。",
          "pseudocode": "on(save)\n  if content is unchanged\n    return cached result\n  write new content\n  return fresh result",
          "callTree": "submitForm\n  createSession\n    persistPrompt\n    launchAgent\n  navigateToSession",
          "inferred": false
        }
      ]
    }
  ]
}

Annotation fields:

• side — "new" anchors the new version line number (added lines/context),"old" anchors the old version line number (deleted lines). The vast majority of explanations use "new"。
• start / end — the line number range of that code segment (data.json 's corresponding side's newNo/oldNo; when single-line, end can be omitted or equal to start). Line numbers are thefile's actual line numbers, not the indices in the diff.
• requirement — the unit requirement this section corresponds to (a short sentence, displayed as a label). Can be left empty.
• explanation — Code explanation: clearly explainwhat this section is doing, why it is written this way, and what risks/prerequisites there are. You can use `code` and **bold**。
• pseudocode / callTree — Optionaltwo supplementary views (refer to the show-me skill); only when the fields are provided will the "Pseudocode" and "Call Tree" buttons appear below the card explanation, and clicking them expands a text panel:
  • pseudocode — Write the logic/algorithm of this section aslanguage-agnostic pseudocode: use two-space indentation to represent structure and branches, keep only the key decisions, boundaries, and data flow, and do not copy the source code verbatim (do not write variable declarations, types, and other noise).
  • callTree — This code'sruntime control-flow call tree: the root node is the entry point of this section, two-space indentation represents the call hierarchy, list only the calls that will actually be executed (where necessary, add a sentence # 注释 to explain branch conditions), and do not list branches that are not taken.
  • These two viewsdo not have to be written for every annotation: write them only for sections whose algorithm is more convoluted (multiple branches/state machine/cache decisions) or whose call chain is deeper (spanning multiple module layers); if neither applies, omit both.
• inferred — When the requirement is inferred, set true。

Annotation density: focus onkey/error-prone/requirement-reflectingsections (newly added core logic, boundary handling, concurrency/transactions, type pitfalls, SQL semantics, etc.), and do not need to go line by line; 1–5 per important file is enough. You can 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

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

render will merge and inject data.json + annotations.json into the template, producing .understand/report.html(single file, pure frontend, Prism via CDN). Open it in a browser: select a file in the left tree → view the diff on the right → click "Locate →" on the sidebar card to jump to the corresponding code line (it will briefly highlight); if the annotation includes pseudocode/callTree, the "Pseudocode" and "Call Tree" buttons will appear below the card explanation, and clicking them expands/collapses them (the two views within the same card are mutually exclusive). The left file tree column candrag the divider to adjust the width(the width is remembered in localStorage; double-click the divider to restore the default).

Finallybriefly explain to the user in Chinese: how many files were changed, what the core changes are, what points are worth noting, and give the report.html path.

Note

• .understand/ is the output directory; it is recommended to remind the user to git clean or add .gitignoreas needed, and not commit it by mistake.
• If data.json is empty (no changes), truthfully tell the user that no changes were detected; do not fabricate.
• Line numbers must be aligned with data.json：annotations.json in start/end use the file's actual line numbers,side determines whether the new or old line-number system is used. Filling it in incorrectly will cause sidebar cards to fail to anchor to code lines (no error, but clicking "Locate" does nothing).
• Do not modify the user's business code; this skill only reads code + writes .understand/ artifacts under .