AI Generates Code Fast, You Understand Slow: Closing the Gap with /understand

The author identifies a fundamental rate mismatch in AI-assisted development: code generation is concurrent and near-instant (multiple agents can produce thousands of lines in hours), while human understanding is serial and slow — one mind, line by line. This gap turns codebases into "archaeological sites" where every line recognizes you but you recognize none.

Three Concrete Risks of Ununderstood Code

Fear to change : Developers avoid modifying code they didn't write, creating "no-go zones" that accumulate technical debt.

Inability to explain : When teammates or QA ask "why this logic?", the author cannot answer without asking the AI — reducing the engineer to a messenger.

Unownable incidents : Production failures rooted in months-old AI-generated code become the committer's responsibility, yet they lack the mental model to debug quickly.

Why Common Mitigations Fail

Tests-only (Uncle Bob approach) : Mutation testing and coverage guarantee correctness , not comprehension . Tests verify behavior matches expectations; they don't transfer intent into the developer's mind.

Skimming diffs : A quick visual pass creates illusion of familiarity that evaporates in minutes.

AI-written summaries : The author tried a /note-it skill that produced textual summaries. Summaries are second-hand, lossy, and float above the code — they don't answer "which exact lines implement the sliding-window rate limiter and why not token bucket?".

The /understand Skill: Design and Workflow

Part of the open-source goal-workflow (repository: github.com/smallnest/goal-workflow), /understand produces an interactive HTML report that binds every explanation to real source lines. Three-step pipeline:

Scan changes ( python3 understand.py scan): Computes structured diff from merge-base, capturing committed, staged, unstaged, and untracked files. Scope is configurable (time range, issue, etc.).

Agent annotates : The agent reads each hunk and writes "cards" for key segments only (1–5 per important file). Each card contains:

Linked requirement — traced to commit message, spec, or issue; if missing, explicitly labeled inferred and rendered gray.

Plain-language explanation — e.g., "Instant rebound to OffsetDateTime because PG driver rejects Instant; runtime crash otherwise."

Render single-file HTML ( python3 understand.py render): Left pane shows file tree with A/M/D/R status and line deltas; center shows syntax-highlighted diff with real line numbers; right sidebar lists cards. Clicking a card jumps the diff to the exact lines and flashes a highlight.

Key Design Decisions (and Why They Matter)

Explicit "inferred" tag : Prevents hallucinated requirements from masquerading as facts. Honesty > polish.

Real line-number anchoring : Explanations cannot exist apart from code; clicking forces the reader to look at the actual implementation.

Controlled annotation density : Only core new logic, edge cases, and requirement-defining sections get cards. Full-line commentary equals noise.

Offline, portable artifact : The report is a standalone HTML file — shareable in PR comments, chat, or archived in docs/ for future archaeology.

Paired with /review-it for a Complete Loop

/review-it

asks "Is this code correct?" — finds bugs, enforces standards, iterates fixes. /understand asks "Why does this code exist?" — surfaces intent, rationale, and trade-offs.

Suggested daily flow: AI generates → /review-it cleans → /understand builds review page → developer spends 10–15 minutes walking cards → /ship-it delivers. Understanding becomes an explicit pipeline stage, not a vague "later" promise.

Install: npx skills add smallnest/goal-workflow --skill understand. Invoke in Claude Code with /understand or "explain this batch of generated code." Project page: https://goal.rpcx.io/index_cn.html.

Referenced issue example: https://github.com/smallnest/pigo/issues/562. Related reading: https://mp.weixin.qq.com/s/vo_mDk9e2aw-yyHXpgP63Q.