Stop writing docs for your AI agent. Record a walkthrough instead.

A senior engineer recently walked a junior through a payment flow. She drew on a whiteboard, pointed at three files, said "don't touch this part, it's load-bearing," and finished in eight minutes.

It would have taken her two hours to write the same thing as a doc. And the doc would have been worse.

The bandwidth gap

Writing is a slow, lossy translation of what's in your head. Speaking is faster and richer. You stress different syllables. You point. You backtrack. You say things like "this looks weird but it's intentional" — exactly the kind of context the next person needs and almost nobody writes down.

For a long time, the choice was forced: write it down or it doesn't exist. Walkthroughs lived in heads, in Slack DMs, in onboarding sessions that nobody recorded.

That choice is gone now. Transcription is a solved problem. So is summarization. The bottleneck is no longer turning speech into text. It's deciding to record at all.

Why walkthroughs work for AI agents

AI coding agents are exceptionally good at reading structured prose and exceptionally bad at inferring tribal knowledge. A walkthrough — once transcribed — is structured prose written by the person who actually knows the codebase, in their own language, with the parts they care about emphasized.

Two things make walkthroughs higher-signal than written docs:

• Speakers don't censor themselves the way writers do. "Don't refactor this" spoken with a sigh becomes bold in the transcript. Caveats you'd never bother typing get captured anyway.
• Digressions are signal, not noise. "We tried doing it the other way in 2024 and it broke prod" — that's exactly the kind of footnote agents need.

The objection: "but the transcript is messy"

Yes. Raw transcripts are full of uh, like, and dead ends. Agents handle that fine. The signal lives in the words; the disfluencies don't change meaning. If you want it cleaner, run the transcript through a model with a one-line prompt: "clean this up, preserve every technical decision."

The output is a brief. The agent reads briefs better than it reads polished prose, because polished prose strips out the digressions that contained the actual constraints.

When to record vs write

Walkthroughs are not a replacement for everything. Use them where they win:

• Onboarding flows — anything that takes a senior 10+ minutes to explain in person.
• Architectural decisions — the why behind the choice, where written docs always go thin.
• Load-bearing weirdness — code that looks wrong but exists for a reason.
• Migrations and one-time setups — the things you only do once and forget.

Stick with writing for:

• API references that need to be exhaustive.
• Anything that needs to be edited frequently in small ways.
• Quick reminders that are faster to type than to record.

The pitch

A 5-minute walkthrough captures more usable context than a 50-page wiki, and your AI agent reads it faster.

That's the bet behind Brifly: record once, generate the brief, query it from the CLI, and let Cursor, Claude Code, and Codex pull from the same source the human onboarding does.

Stop writing docs for your agent. Just talk to it the same way you talk to a junior. Then make sure someone — or something — is recording.