understand
Review and understand freshly AI-generated code. Scans the current repo's uncommitted/branch changes and builds a Claude-style light-themed two-column webpage — left is the project folder tree of changed files, right is the selected file's syntax-highlighted diff (additions/deletions clearly distinguished from unchanged code) with a side rail showing, per code segment, the related unit requirement (相关单位需求) and a plain-language code explanation (代码解释). Invoke for "/understand", "code review 这次改动", "解释一下新生成的代码", "看看这次变更".
- Installs
- 146
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/smallnest/goal-workflow --skill understand- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads understand automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
understand
把「本次（AI）新生成的代码变更」变成一个可交互的审阅网页：左侧按真实项目布局列出变更文件树，右侧显示所选文件的 diff（高亮、增删与未变更代码明显区分），并在右侧边栏逐段给出相关单位需求与代码解释；解释下方可按需提供「伪代码」「调用树」两个展开式文本视图（参考 show-me skill 的呈现方式）。
始终用中文产出解释与需求。
何时用
- 用户说
/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 错误。",
"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
}
]
}
]
}
注释字段：
side—"new"锚定新版本行号（增行/上下文），"old"锚定旧版本行号（删行）。绝大多数解释用"new"。start/end— 该段代码的行号区间（data.json里对应 side 的newNo/oldNo；单行时end可省或等于start）。行号是文件真实行号，不是 diff 里的序号。requirement— 该段对应的单位需求（简短一句，作为标签展示）。可留空。explanation— 代码解释：讲清这段在干嘛、为什么这么写、有何风险/前提。可用`code`和**bold**。pseudocode/callTree— 可选的两种补充视图（参考 show-me skill），给了字段，该卡片解释下方才会出现「伪代码」「调用树」按钮，点击展开文本面板：pseudocode— 把这段的逻辑/算法写成语言无关的伪代码：两空格缩进表结构与分支，只保留关键判断、边界与数据流向，不照抄源码（不写变量声明、类型等噪音）。callTree— 这段代码运行期的控制流调用树：根节点是本段入口，两空格缩进表调用层级，只列真正会执行到的调用（必要处可带一句# 注释说明分支条件），不列未走过的分支。- 这两个视图不必每条注释都写：只为算法较绕（多分支/状态机/缓存判定）或调用链较深（跨多层模块）的段落写；都不适用就两个都省略。
inferred— 需求为推测时置true。
注释密度：聚焦关键/易错/体现需求的段落（新增的核心逻辑、边界处理、并发/事务、类型坑、SQL 口径等），不必逐行；每个重要文件给 1~5 条即可。可参考项目记忆里的常见坑（如 Vert.x Future.await()、PG = ANY 数值数组、timestamptz 编码）来判断哪些点值得解释。
3. 渲染并打开
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 → 边栏卡片点「定位 →」跳到对应代码行（会高亮闪一下）；若注释写了 pseudocode/callTree，卡片解释下方会出现「伪代码」「调用树」按钮，点击展开/收起（同卡片内两个视图互斥）。左侧文件树栏可拖动分隔条调整宽度（宽度记忆在 localStorage，双击分隔条恢复默认）。
最后用中文向用户简述：改了几个文件、核心变更是什么、有哪些值得注意的点，并给出 report.html 路径。
注意
.understand/是产物目录，建议提醒用户按需git clean或加.gitignore，别误提交。- 若
data.json为空（无变更），如实告知用户没有检测到改动，不要硬造。 - 行号务必对齐
data.json：annotations.json里的start/end用文件真实行号，side决定用新/旧行号系。填错会导致边栏卡片锚不到代码行（不报错，但点「定位」无反应）。 - 不改动用户业务代码；本 skill 只读代码 + 写
.understand/下的产物。
FAQ
What does the understand skill do?
Review and understand freshly AI-generated code. Scans the current repo's uncommitted/branch changes and builds a Claude-style light-themed two-column webpage — left is the project folder tree of changed files, right is the selected file's syntax-highlighted diff (additions/deletions clearly distinguished from unchanged code) with a side rail showing, per code segment, the related unit requirement (相关单位需求) and a plain-language code explanation (代码解释). Invoke for "/understand", "code review 这次改动", "解释一下新生成的代码", "看看这次变更".
How do I install understand?
Run npx skills add https://github.com/smallnest/goal-workflow --skill understand in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/understand/ (personal) or .claude/skills/understand/ (project).
Which AI agents can use understand?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is understand safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains understand?
It is published by smallnest in smallnest/goal-workflow. It has 146 recorded installs.
More from smallnest/goal-workflow
smell
smallnest/goal-workflow
Detect software architecture bad smells, algorithmic complexity hotspots, and anti-patterns in a codebase. Produces a detailed markdown report identifying violations of architectural principles, design patterns, code quality, and performance complexity. Triggers on: smell, code smell, architecture smell, find anti-patterns, detect bad smells, complexity analysis, 代码坏味道, 架构坏味道, 反模式, 找出坏味道, 复杂度分析.
prd
smallnest/goal-workflow
Generate a Product Requirements Document (PRD) for a new feature. Use when planning a feature, starting a new project, or when asked to create a PRD. After PRD is confirmed, use /prd-to-spec (optional) for technical design, then /to-issues to create implementable tickets. Triggers on: create a prd, write prd for, plan this feature, requirements for, spec out, 写PRD, 需求文档, 需求分析, 规格说明.
humanize-it
smallnest/goal-workflow
对指定文档进行去 AI 味的改写。自动选择最合适的人性化策略（humanizer-zh / humanize-chinese / technical-writing）， 迭代改写直到效果达标或迭代 42 次为止。适用于中文文本的去 AI 化处理，包括通用文章、技术文档、学术论文等。 Use when user says: "humanize this", "去AI味", "降AIGC", "人性化改写", "改成人话", "去除AI痕迹", "humanize document", "make text human-like", "去机器味", "降低AI率", "过AIGC检测"
refactor
smallnest/goal-workflow
Expert code refactoring based on Martin Fowler's catalog — improve maintainability without changing behavior. Covers code smells, composing methods, moving features, organizing data, simplifying conditionals, method calls, and generalization. Triggers on: refactor, 重构, clean up, improve code, code smell, extract method, rename, simplify.
insight-diagram
smallnest/goal-workflow
为任意项目生成 UML 图、架构图和流程图。分析代码库后让用户选择要生成的图表类型，使用 architecture-diagram skill 渲染为 HTML+SVG，保存到 docs/ 目录。适用于任何软件项目的文档可视化。
modern-go
smallnest/goal-workflow
Modernize Go code by applying version-appropriate idioms and APIs (gofix-style transformations). Scans go.mod for the Go version, then transforms Go source files to use modern patterns—from Go 1.0 through 1.26+. Use when the user says "现代化","现代Go语言", "地道的", "idiomatic", "modernize", "modern-go", "update Go code", "gofix", or wants to upgrade Go idioms.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.