Skip to main content

04.28Teaching

Code Tutor: Claude Code commands for learning a codebase

Claude Code commands from AR Labs for learning code by building it: an agent writes a tutorial on the feature, then tutors you Socratically as you code.

Engraved plate: an open copybook with dotted guide letters of code, half traced over by a dip pen, questions in the margin.An engraved open copybook with ruled guide lines: a line of code traced in dotted letters is half written over in ink by a dip pen, with question marks in the margin.AR LABS · INSTRUMENT CABINET · DRAWER 04CALL NO. 04.280123456789def greet(name):def greet(name):return …Why name?What comes back?ABCDFIG. 28 · CODE TUTORCOPYBOOK& DIP PENPARTSAA tutorialwritten firstBYou writeevery lineCSocraticquestionsDLearning bybuildingTHE AGENT TEACHES, YOU WRITE
On this page
  1. How it works
  2. The judgement it encodes
  3. What exists today
  4. Example

Code Tutor is a pair of Claude Code commands, built at AR Labs, for developers who want to learn a part of a codebase by building it themselves, with an AI agent as tutor rather than author. The developer asks the agent to teach them a feature instead of writing it: first the agent explores the code on its own and writes a tutorial, then it runs a live Socratic session (teaching by questions) in which the developer writes every line. We use it when understanding the code matters more than getting the change made quickly.

The two-phase shape follows a working pattern Geoffrey Litt describes in his essay Code like a surgeon: hand the preparation, such as a guide to the relevant parts of the codebase, to an agent working in the background, so that the person arrives at a prepared starting point and spends their own time on the part that matters. The tutoring method in the live phase is our own.

How it works

The method is two commands.

FIG. 01
flowchart LR
  F["Feature or problem"] --> P["Async prep: explore and write tutorial"]
  P --> L["Live session: Socratic tutoring"]
  L --> B["Developer builds it"]
  B --> R["Reflection"]

Async prep (/code-tutor <feature>). An agent explores the codebase without asking questions and writes a tutorial-style document about the feature. It covers seven topics: the feature's purpose, its current structure, where it is used and what depends on it, what could be simplified, design critiques, patterns from similar parts of the codebase, and a recommended implementation order with the likely pitfalls and a testing approach. The document has a table of contents, explains the reasons behind the existing design, and cites file paths and line numbers. When the feature has several complex parts, the agent writes a master document and then launches one sub-agent per part to write a tutorial for it, one level deep. The result is saved in a code-tutor/ folder inside the project being studied. It is a learning reference, never code to ship, and the agent edits no existing code.

Live session (/code-tutor-live <feature>). The agent becomes a tutor. It reads the code first, then explains the current system in words and asks whether that matches the developer's understanding. Next it proposes a short task list of three to five high-level areas and works through them one at a time in short exchanges. It closes with a reflection: what made the idea click, what the developer would do differently, and what remains uncertain. Throughout, the developer writes the code. If a prep document exists, the tutor uses it for context rather than reciting it.

The judgement it encodes

Short turns, then stop. The tutor gives at most about five paragraphs, ends with a question or a prompt to act, and waits. The command measures a good session by how often the developer responds, so it aims for many short exchanges rather than a long explanation with a question at the bottom.

Explain the mechanism, then ask. Questions guide thinking only after the context is clear. The tutor explains what a mechanism does before asking the developer to implement it.

Escalate support only as needed. Help comes in four levels: a Socratic question, then an explanation of the mechanism, then guidance on the pattern this codebase uses, and only then the syntax. The tutor moves to the next level only when the developer shows they need it, and never opens with syntax.

Allow productive struggle. Some confusion before clarification is part of learning, so the tutor does not rush to fill every pause.

Narrative over checklists. The command carries a worked example of the wrong opening: a list of phases, each with sub-steps and a time box, followed by "Let's start with Phase 1". It replaces that with a few paragraphs on how the current system works, what has to change and why, and the architectural principle involved, before any code.

What exists today

We use both commands as Claude Code slash commands; they are not published separately. For understanding a change an agent has already made, we use Comprehend; the wider practice is described in understanding agent-written code.

Example

Illustrative example. An early exchange in a live session about adding retry logic to an HTTP client:

Tutor: Right now every request in client.ts goes through one function,
send(). When the server returns a 503, send() throws and the caller
sees the error immediately.
 
Retrying is about deciding which failures are worth a second attempt.
A 503 means "busy, try later". A 400 means "your request is wrong",
and sending it again will fail the same way.
 
Before we touch the code: which responses do you think should be
retried, and which should fail straight away?