Learning a new codebase in a day, with an agent as your guide

Every engineer knows the feeling of week one on a new codebase: two hundred directories, a README that was true in 2023, and a nagging sense that the real knowledge lives in three people's heads. It used to take a month of reading and hallway questions to feel oriented. An agent that can read the entire repository in seconds changes the math — but only if you use it as a guide, not an oracle. Here's a one-day plan that gets you from "where do I even start" to a map you'd trust enough to ship a change against.

Why the old way took a month

Traditional onboarding was slow for a structural reason: the person who needed the map was the least equipped to draw it. You didn't know which files mattered, so you read them all. You didn't know which conventions were load-bearing, so you asked about each one. The senior engineers who could have answered in thirty seconds were busy, and every question cost you a little social capital. Most of the month wasn't learning — it was searching for the things worth learning.

An agent removes the search cost. It can read every file, trace every import, and answer "where does this get called?" without a meeting. What it can't do is decide what *you* need to know, or tell the difference between how the code works and how the team wishes it worked. That's your half of the partnership, and it's why the order of questions matters more than the questions themselves.

Morning: build the map top-down

Start wide and refuse to go deep for the first two hours. Point the agent at the repository and ask for the shape of the thing: what the top-level directories are for, what the entry points are, how a request or a job flows from the edge to the database and back. Ask it to name the five modules everything else depends on. Then ask the question nobody's README answers: "what would I most likely break if I changed something here without knowing better?"

Write the answers down yourself, in your own words, in a single document. This is not busywork — it's the whole technique. The agent's explanation is fluent and forgettable; your restatement is clumsy and sticky. If you can't restate a piece, you don't understand it yet, and that's the next question to ask.

• Entry points. Where does execution begin — servers, CLIs, cron jobs, queue consumers? Ask for all of them, not just the obvious one.
• The spine. The handful of modules that everything imports. These are where the conventions live and where a careless change hurts most.
• The data. Schemas, migrations, and the one table everyone's afraid of. Ask what's denormalized on purpose.
• The seams. Where the system talks to the outside world — APIs, webhooks, third-party SDKs — because that's where the surprising failure modes are.

Midday: verify the map against reality

Here's the step people skip, and it's the one that separates a map from a rumor. Agents describe code confidently, and they are sometimes confidently wrong — especially about behavior that's determined at runtime, by config, or by that feature flag nobody remembers. So spend an hour testing your morning's map against the running system. Pick three claims the agent made and check them yourself: set a breakpoint, run a request, read the log line. Trace one real request end to end with your own eyes.

Every place the map is wrong is worth more than ten places it's right. A wrong claim tells you where the codebase diverges from its own apparent design — which is exactly the tribal knowledge that used to take a month to absorb. Note each one in your document with the correction. You're building the errata sheet your future teammates never got.

Afternoon: make one small, real change

Understanding you haven't used is understanding you don't have. By early afternoon, pick a change that's small enough to finish today and real enough to touch the spine — a log line that's missing context, a validation gap, a test for a path nobody covered. Ask the agent where the change belongs and what it would affect, then compare its answer to your map. Disagreements are good. Resolve them by reading the code, not by asking again.

Write the change yourself, or have the agent draft it and then rewrite the parts you don't fully understand. Run the tests. Open the pull request with a description that explains not just what you changed, but what you learned about how this area works. That description is your first contribution to the team's shared map, and a reviewer will read it more carefully than any introduction you could give.

End of day: ask the questions the code can't answer

Save the humans for last, and go to them with specifics. Instead of "can you walk me through the architecture?" — a forty-minute ask — bring your document and say, "the agent and I think requests flow like this, and I verified these three points; what's wrong or missing?" Senior engineers love correcting a concrete map far more than they love explaining from scratch. You'll get the two or three pieces of history that live nowhere in the repo — the module that's being deprecated, the constraint from a customer contract, the reason the obvious refactor was never done — in ten minutes instead of a month.

Then update the document one last time and share it. A new engineer's map of the system, corrected by the people who built it, is the onboarding doc every team wishes it had and none of them have time to write. You just wrote it as a side effect of learning.

What this is really training

Notice that the agent did the reading and you did the judgment: deciding what mattered, checking what was true, choosing what to touch first. That's the same division of labor that makes every other agent workflow safe, and a new codebase is the best gym for it — because you have no prior model to lean on, every wrong claim is detectable, and the stakes are one small pull request. Do this once and you've built a habit worth more than the map: never accepting a fluent explanation of a system you haven't watched run.

The month-long onboarding wasn't a rite of passage. It was a search problem, and the search just got cheap. Spend the day it now takes, spend it deliberately, and walk into your second day already useful.