Comprehend: Claude Code skill to understand AI code changes

Comprehend is a Claude Code skill, built at AR Labs, that helps a person understand a code change an AI agent made. When AI agents write most of the code, the risk is that the owner of a codebase stops knowing how it works. Specs (written specifications for one task: what to build and how each criterion is proved) and implementation notes are good reference documents, which an agent can search, but poor reading documents. This skill produces the reading document: a guide that walks the reader through the changed code in the order it runs, with short explanations alongside, so they can rebuild their mental model of what changed. It is run on demand by a person who wants to understand, usually after an implementation lands, and it never blocks our coding pipeline or runs during unattended work. It is one of the tools behind our practice of understanding agent-written code.

How it works

The skill takes the current branch (compared with the point where it left the main line), a tracked task, an explicit revision range or a pull request, and works in four phases.

Gather. Read the shape of the diff, then the hunks (the changed blocks of lines), then the changed files in their current form wherever a hunk cannot be understood alone. Find the intent documents where they exist: the task's spec, its implementation walkthrough, and the project's design record.

Write the guide in a fixed order: a plain-English overview, the runtime flow from entry point to outcome, where the change sits in the architecture, five to nine reading chunks, a file map, then the concepts and invariants that hold it together, and a short self-check quiz at the end. Each section assumes only the sections above it. A small change, about 150 changed lines or fewer with one mechanism, gets a compact guide of overview, flow, two or three chunks and a file map; a large or architectural one gets every section.

Diagram the change when it adds or removes components, crosses container boundaries or introduces new relationships. A separate diagram agent, using our C4 diagrams skill, draws a C4 diagram (a standard notation for software architecture at four levels of zoom), usually at component level, with the touched elements marked. A change inside one function gets no diagram, and the guide says why in one line.

Offer a live pass and a self-check. The skill shows the guide's overview in the conversation and offers two things: a guided pass, in which the agent presents each chunk while the reader opens the code, by text or by voice; and the quiz, one question at a time.

The judgement it encodes

The code is the text; the guide is the margin notes. The guide never reproduces functions. It points at code with clickable file and line references and quotes at most a line or three when one line carries the whole idea.

Flow before files. A reader understands a feature by following what happens at runtime before caring which file holds which piece. The reading order follows the flow, not alphabetical order and not commit order.

Chunk to working memory. Each chunk holds one concept and at most about a hundred words of explanation, and tells the reader what to notice: "watch how the lock is taken before the cache read; that ordering is the whole fix".

The diff is the ground truth. The spec and notes supply intent; the diff supplies fact. Every claim in the guide traces to a hunk, and where intent and diff disagree, the guide says so. That gap is what comprehension is for.

Text is expensive. The reader's attention is the budget, so explanations supply concepts and mechanisms to lean on, not a narration of what each line does.

Quiz on understanding, not trivia. Three to five questions grounded in the diff: what must be true before a call, what breaks if a line is removed, which module now knows about which. Never names, counts or file paths, which a reader could answer without having understood. A wrong answer is pointed at the code that answers it, then asked again in a different form. The quiz is never a gate and keeps no score; its job is to show which chunk to reread.

What exists today

The skill is in use on changes from our coding pipeline. It sits between two related skills: Walkthrough tours a whole codebase, and Code Tutor teaches the ground before a feature is built.

Example

Illustrative example. One reading chunk from a guide to a change that fixed duplicate notifications:

### 3. The deduplication key is taken before the send
 
Read: src/notify/fanout.ts:41-58, then src/notify/store.ts:12-20
 
The fan-out now writes a key made of the event id and the recipient
before it calls the sender. If the key already exists, it stops.
Notice the order: write first, send second. If the send fails, the
key is removed in the catch block (fanout.ts:63), so a retry can
still deliver. That ordering is the whole fix; the old code sent
first and recorded afterwards, so two workers could both send.