Ask for a walkthrough.md before you ask for changes

You open a repository you did not write — a contractor's, a departed colleague's, or one an agent produced over a weekend while you reviewed diffs and not architecture. The instinct is to start asking questions: how does auth work, where do requests enter, what is this queue for. You get good answers, you make your change, and two days later the answers are gone with the session.

Ask for the explanation as a file instead, before you ask for a single change.

Read this repository top to bottom and write walkthrough.md.

Linear, not a reference: entry points first, then the path a request takes
through the system, then each subsystem in the order a new engineer would
meet it. For every non-obvious implementation decision, say what was chosen
and what the alternative would have been. Cite file:line for every claim.
End with a section listing the parts you are least confident about.

Then read it like a new hire would, and keep it.

Why the file and not the chat

The last row is the one that matters most on agent-written code. The walkthrough tends to surface decisions you never inspected — a protocol implemented by hand where a library existed, a retry loop with a policy nobody chose deliberately. Those are invisible in a diff review and obvious in a linear narrative.

What the docs actually say about this

Nothing, directly — and that is worth stating plainly rather than implying blessing.

The docs cover the ephemeral half. best-practices recommends onboarding by asking Claude the questions you would ask another engineer ("How does logging work?", "What edge cases does this handle?") and says no special prompting is required. common-workflows opens with "give me an overview of this codebase". Both are conversations that end when the session does.

The durable-artifact mechanism is documented, just pointed at new code rather than existing code. The same best-practices page tells you to have Claude interview you and "write a complete spec to SPEC.md", then start a fresh session to execute it — the value being explicitly that you now have a written spec to reference. memory documents /init, where Claude explores your codebase and writes what it finds to CLAUDE.md.

So: the practice of persisting an agent's understanding to a markdown file, then re-feeding it, is a documented mechanism. Applying it to comprehension of code that already exists is an extrapolation. No page tells you to do it.

What is unverified, and what would settle it

The claim that a walkthrough surfaces decisions you would otherwise miss is a practitioner report, not a measurement. Nobody has run a controlled version of it, and the failure mode of a generated document — confident, fluent, wrong in a few places — is exactly the failure mode a casual read will not catch.

What would settle it, on your own repo: generate the walkthrough, then spot-check it mechanically. Every claim carries a file:line, so pull the citations and confirm the referenced lines exist and say what the document says they say. A second, fresh session with no memory of writing it makes a decent auditor:

Read walkthrough.md and verify each claim against the code it cites.
List every statement that is wrong, stale, or unsupported by the cited lines.
Do not fix anything.

If that pass comes back with nothing substantive, the document is a map you can trust for navigation. If it comes back with five inventions, you have learned something more useful than the walkthrough itself.

Keeping it from rotting

A walkthrough committed and then ignored is worse than none, because it reads authoritative while describing a version that no longer exists. Two cheap defenses:

• Put the generating prompt in a slash command or skill so regenerating is one keystroke, and regenerate rather than patch after any structural change.
• Do not point CLAUDE.md at it as a source of truth. CLAUDE.md is loaded every session and should hold rules you wrote; the walkthrough is a document you pull in with @walkthrough.md when you need orientation, and leave out when you do not.

The two habits that travel with it

From the same source, and equally undocumented as technique: run the tests yourself rather than trusting that generated code works — unexecuted code working in production is luck, not evidence. And drive changes red/green, confirming the test fails before the agent implements against it. The docs come close on the second one: best-practices' prompting table gives "write a failing test that reproduces the issue, then fix it" as its example of a well-specified debugging prompt, but never names test-driven development as a workflow.

Of the three, the walkthrough is the one that changes what you do first when you open an unfamiliar repo. The other two change what you accept as done.