Guide

An unfamiliar codebase

You have been handed a repository you have never seen and a question about it. The instinct is to start opening files. This is the alternative: six calls, each one built from what the last one returned.

Your agent walks this path on its own — you ask your question and it goes. The reason to read it anyway is to recognise the shape when you see it, and to know what to say when you want to steer: go wider, go deeper, look somewhere else.

1 · See the shape

Before anything else, find out what kind of thing this is — how it is laid out, and where the weight sits.

Folders and their file counts, for very little. Swap to tree: headlines on the one directory that looks relevant and every file arrives with a line saying what it is for.

2 · Learn the local words

Your vocabulary comes from somewhere else, and it will not match. Convert it before you search with it.

What comes back are the names this codebase actually uses — and often a concept the repository has already written down about the area you are walking into.

3 · Find the landscape

Now search with the real words, and ask the question you actually have. Results are ranked by how well they answer it, not by how often they mention it.

4 · Read only what you need

You have names now, so address them directly. One method body, not the file it lives in.

5 · Ask why it is like that

Code says what; history says why. This works down to a single method — the commits that built the text currently on screen.

6 · Check what the repository already knows

Somebody may have paid for this lesson already.

What six calls and a few thousand tokens bought is orientation, not mastery: how the code is laid out, what it calls things, where your question lives, and why the answer looks the way it does. The one file you opened, you opened by address.

This page names what exists. The depth behind every name ships inside the binary at help:///: the bounds, the failure modes, how they compose. It answers to explore and read exactly like your code does. Install it, and your agent has the manual.