Skip to main content

03.15Rule

Implementation walkthroughs

Why AR Labs' AI coding agents write an implementation walkthrough as they work: a plain account of why each change was made and in what order.

A trail of numbered waypoints winds up to a flag, each signed WHY, with a notebook recording each step as it happens.A trail of numbered waypoints winds up to a flag, each with a small sign reading why; a notebook in the corner records each step as it happens.RULE03.14RECORD WHY,AS YOU GODRAWINGENG-03.14SUBJECTimplementation walkthroughsSHEET14 OF 26 · AR LABS12345WHYWHYWHY
On this page
  1. The problem it prevents
  2. Write it as you go
  3. What each step records
  4. How it relates to the other artefacts
  5. Where it lives

Every implementation by an AI coding agent (an AI agent that writes code, such as Claude Code or Codex) at AR Labs produces a walkthrough: a sequential, plain-language account of what the agent did, in the order it did it, and why, with each step linked to the part of the spec or design it carries out. The diff records what changed. The walkthrough records why it changed and how the reasoning went. Adopt it if reviewers, or the agents that build on a change later, cannot tell why agent-written code is shaped the way it is.

The problem it prevents

A diff shows the end state but not the reasons for it or the order of decisions that produced it. Notes on the tracked task capture milestones, not the step-by-step. When a review finds a problem, when a later task builds on this one, or when the session that did the work is gone, nobody can reconstruct the implementer's intent. An agent's reasoning otherwise disappears with its context window.

Write it as you go

The walkthrough is built during implementation. The agent creates a stub before writing code, with the one-sentence goal and links to the spec, the design decisions and the branch, and appends a section as each coherent piece lands: a build step, a module, a test cycle.

Written live, it captures the real order, the dead ends and the reasons while they are fresh. Reconstructed at the end, it collapses into a tidy story that hides the decisions it was supposed to preserve. Written as you go it costs almost nothing; reconstructed later it is expensive and less accurate.

What each step records

  • What changed: the files and the concrete edit.
  • Why: the reason the step exists, in plain words.
  • Link: the spec section or architecture decision it carries out.
  • Tests: what was added and what it proves.

The document closes with what was deliberately left out, so the next task's boundary is unambiguous, and how to extend the work.

# app-42.3: Persist sessions across restarts (walkthrough)
 
Goal: a visitor's unfinished session survives a server restart.
Spec: build/specs/app-42.3.md · Decision: ADR-004 (SQLite for sessions)
Branch: task/app-42.3-persist-session
 
## Step 1: Session table and repository
Changed: server/sessions.ts (new SessionStore), migrations/004_sessions.sql
Why: the in-memory map was the only store; restart dropped it.
Discharges: spec §4 "Persistence boundary"; ADR-004.
Tests: test_returning_visitor_resumes_an_unfinished_session (red, then green).
 
## Step 2: ...
 
## Left out
Expiry of abandoned sessions; tracked as its own task.

How it relates to the other artefacts

Artefact Answers Reader
Spec What to build and why it matters The implementer
Diff or pull request What changed, mechanically The reviewer
Walkthrough Why it changed, in what order, linked to intent Reviewers, later agents, anyone onboarding
Proof manifest Which artefact proves each criterion The evidence reviewer

The walkthrough and the proof manifest do different jobs. The manifest proves that the outcomes happened (see evidence of completion); the walkthrough explains how the code got there.

Where it lives

One walkthrough per task, in the project's build folder, named after the task (for example build/app-42.3-implementation-walkthrough.md), committed on the task branch so it reaches review in the same pull request as the code. Because the agent writes it during the work rather than after, it is also what makes a guided reading of a change possible: we generate comprehension guides for a reviewer from the spec, the walkthrough and the diff together (see Comprehend).