Reading unfamiliar code is mostly a search problem you can’t phrase yet. You don’t know the vocabulary of the codebase, so you can’t grep for the thing you need, because you don’t know what it’s called.
So you do the slow version: open the entry point, follow an import, lose the thread, go back, try a different file. An hour later you have a rough map and no idea whether it’s accurate.
The fastest way through is the thing you’d do with a colleague who knows the repo, ask a vague question and let them narrow it. That’s a conversation, and conversations are much cheaper spoken.
Vague questions are the point
A good first question about an unfamiliar codebase is embarrassingly imprecise: “where does a request actually enter this thing?”, “what talks to the database?”, “is there a reason there are two config loaders?”
Those are terrible things to type. They feel unserious, so you rephrase them into something more technical-sounding, and the rephrasing smuggles in assumptions you have no basis for, you ask about “the middleware chain” before you know whether there is one.
This is where voice coding earns its keep on a codebase you didn’t write. Spoken, you just ask the vague thing. It doesn’t have to look good. And the vague version is more honest about what you actually don’t know, which makes the answer more useful.
The question you’re willing to type has already been cleaned up. The cleaning is where your real confusion went missing.
Follow-ups are where it pays off
Orientation isn’t one question, it’s twenty in a row, each depending on the last. That chain is where typing gets expensive, not any single prompt, but the twentieth one, when you’ve been reformulating for half an hour.
Out loud, a follow-up is four words. “Which one runs first?” “Who calls that?” “Is that dead?” You keep asking because asking is free, and the map assembles faster than reading would have built it.
It also survives interruption better. When the answer comes back spoken, you can be looking at the file it’s describing rather than at a chat panel, your eyes stay on the code while the explanation arrives.
Point instead of describing
Some questions are much faster shown. A hotkey attaches a screenshot to your next spoken request, so “what is this doing?” can mean this, on screen, rather than a paragraph describing which part of which file you mean.
Half of onboarding friction is locating the thing you’re confused about well enough to ask about it. Pointing removes that step entirely.
The day-one version
If you’ve just been handed a repository, the sequence that works is roughly:
- Ask where execution starts, in the vaguest terms you like.
- Ask what the three or four main moving parts are, and don’t worry about naming them correctly.
- Pick the part you’ll be changing and ask it to walk you through one real path end to end.
- Ask what surprised it, what looks unusual, inconsistent or load-bearing in this repo.
That last one is the question people forget to ask, and it’s often where the useful warning lives.
The point isn’t to avoid reading the code. It’s to know which code is worth reading before you’ve spent the afternoon finding out. Connect a project and try it on the next repo you inherit.
