Understanding code that AI coding agents write

When AI coding agents (AI agents that write code, such as Claude Code or Codex) write most of a codebase, the people who own it can stop knowing how it works, so AR Labs uses agents to teach as well as to build: every implementation leaves a plain-language walkthrough, a person can ask for a guided reading of any change or a tour of a whole codebase, and when understanding matters more than speed, the agent becomes a tutor and the person writes the code.

The problem it answers

The documents an agent pipeline produces are good reference material and poor reading material. A spec says what was meant to be built, a diff says which lines changed, and a review says what was wrong with them. None of them walks a person through how the code now runs. A reviewer who approves a pull request they do not understand is approving on trust, and an owner who cannot explain their own system cannot direct the next change to it well. We treat keeping human understanding current as part of the engineering, not a separate activity.

Four tools for four moments

flowchart LR
  B["During the build"] --> W["Implementation walkthrough"]
  C["After a change lands"] --> G["Guided reading of the diff"]
  N["Entering a codebase"] --> T["Executable codebase tour"]
  L["Before building something new"] --> U["Code tutor: you write it"]

During the build: the implementation walkthrough. Every implementing agent writes a walkthrough as it works, one entry per step, recording what changed and why, in the order it happened. It is written while the reasoning is still in the agent's context, because a walkthrough reconstructed afterwards from the diff loses the why. See implementation walkthroughs.

After a change: a guided reading. The Comprehend skill takes a branch, task, commit range or pull request and writes a reading 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 of the actual code with margin notes, a file map, and the invariants that hold it together. If the change altered the system's structure, it adds a C4 diagram showing only what moved. It can finish with a short self-check quiz. It is run on demand by a person who wants to understand, never as a gate.

Entering a codebase: an executable tour. The Walkthrough skill produces a linear tour of a codebase in which every code excerpt is pulled from the real files by a command, using Simon Willison's Showboat tool. Because the excerpts are generated rather than typed, none of them can be invented or drift from the source.

Before building: the code tutor. The Code Tutor method reverses the usual roles. Its first phase follows a practice Geoffrey Litt describes in his essay "Code like a surgeon": before a big task, an agent works in the background to write a guide to the relevant parts of the codebase, so the person starts prepared. In our version, an agent explores the codebase on its own and writes a tutorial on the feature to be built: its purpose, current structure, dependents, likely pitfalls and a suggested order of work. It edits no code. Then, in a live session, the agent tutors and the person writes every line. Help escalates only as needed, from a question, to an explanation of the mechanism, to the pattern the codebase uses, and only then to syntax.

Rules that make the material readable

• Flow order, not file order. Readers understand code in the order it runs, so guides follow execution from entry point to outcome rather than listing files alphabetically.
• Short turns. A tutor gives at most a few paragraphs, then asks a question or prompts an action and waits. A wall of text with a question at the bottom is not tutoring.
• Explain, then ask. A question guides thinking only once the reader has the context to answer it.
• Real code only. Excerpts are pulled from the files, not paraphrased, so the reader learns the code that exists.
• Plain language. The same writing rules apply as for every other document we produce: define terms at first use, and name the thing before using its name (see writing rules).

A worked example

Illustrative example, with generic names. An agent has implemented app-42.3, which makes visitor sessions survive a server restart, and a person must decide whether to merge it.

The pull request's opening paragraphs say what was broken and what changed. The person wants more before merging, so they ask for a guided reading of the branch. The guide opens with three sentences: sessions were held in memory and lost on restart; they are now written to SQLite on every step change and read back when a visitor returns; the visitor sees no difference except that nothing is lost. It then follows one request: the request arrives, the session store is asked for the visitor's session, the store reads from the database on a cache miss, and the step is restored. Each stop shows the actual lines with a short note in the margin. A diagram shows one new arrow, from the application to its database. The quiz asks what happens if two requests for the same visitor arrive during a restart, and the person, unable to answer, finds the gap the tests do not cover. That becomes a new task before the merge.

What exists today

Walkthroughs are written on every implemented task in our coding pipeline. Comprehend is in use on changes from that pipeline, Walkthrough is available for codebase orientation, and the two Code Tutor commands are in use as Claude Code slash commands.