How to learn a new codebase fast with AI coding agents

Two hundred thousand lines. Four people who understood it, three of whom have left. A README that was accurate in 2023.

Everyone has met this codebase: a new job, an inherited client project, an open-source repo you need one fix in. The traditional response is to open files semi-randomly for a fortnight and hope a shape emerges.

An AI coding agent can compress that to an afternoon. But only if you stop asking it the question everyone asks first.

"Explain this codebase" is the wrong prompt

Ask an agent to explain a large repo and you get a confident tour of the folder names. Two paragraphs on src/, a bullet list of dependencies, and a closing line about how it "follows a modular architecture."

None of that is wrong. None of it helps you ship anything either.

The problem is that the question has no failure condition. Nothing about the answer can be checked, so you have no idea which parts were read and which were assumed. Ask instead for things that can be verified.

Ask for artefacts, not explanations

Four requests that reliably return something useful:

"How do I run this, and how do I run the tests?" Make it work from the actual setup files, not the README, that's always the first thing to rot. Have it produce the exact commands and run them.

"Trace one real request end to end." Pick something concrete: a user logging in, a webhook arriving, one CLI command. Ask for the ordered list of files and functions it passes through, with line references. This beats any architecture summary, because it crosses every layer the system actually has rather than the ones it's supposed to have.

"What are the ten files that change most often?" git log knows where the system's real centre of gravity is. It's rarely where the folder structure suggests.

"Where are the seams?" Which modules everything imports, which ones nothing imports, and where you can change one thing without breaking five others.

Every one of those has a right answer sitting in the repo. That's the point.

Verify by prediction, not by vibes

Here's the honest part: an agent describing an unfamiliar system will state architecture it inferred with exactly the same confidence as architecture it read. Sometimes it's summarising code; sometimes it's autocompleting what a project like this usually looks like.

You can't tell the difference from the prose, so make claims testable. Ask for file paths and line numbers with every structural claim, then spot-check two or three. Ask "what would break if I deleted this function?" and go see whether the callers it named exist.

Treat the first pass as a hypothesis, not a handover document, the same scepticism you'd apply to reviewing AI-generated code, pointed at prose instead of a diff.

Don't let it read the whole repo

The instinct is to give the agent everything and let it figure things out. That backfires: thousands of lines of source in one session leaves the important detail buried among files nobody needed.

Scope each question to a subsystem. Run separate sessions for separate areas (auth in one, billing in another) so no single session carries the whole system's noise. It's the difference between an agent that stays sharp and one that gets vaguer the longer it runs.

Write down what you learn, where the agent will read it again

Everything discovered so far lives in a chat log that dies when you close the window. Next session, yours or the agent's, starts from zero again.

So end the exploration by having the agent write it down: the run commands, the request trace, the modules that matter, the landmines ("don't touch legacy/", "the tests need a flag"). Put that in your project's AGENTS.md file and it becomes the briefing every future session gets for free.

Onboarding yourself and onboarding your agents turn out to be the same task. The durable version of it is shaping the repo so any cold reader orients fast, which is the whole subject of the agent-ready codebase.

Then make one small, boring change

You don't understand a system until you've changed it and watched something respond. Pick a task with a tight feedback loop: fix the flaky test, add the missing validation, rename the confusing thing. Small enough to verify, real enough to prove your mental model is correct rather than merely fluent.

A workspace that keeps the map

This is the kind of work SanuDesk was built to hold. It's a desktop app where your Claude Code, Codex and Gemini sessions tile into one grid, each workspace pointed at a project folder, with a Kanban board the agents take their work from.

Exploring a big system, that means one session per subsystem side by side instead of a queue of half-remembered tabs, each with its own clean context. Your open questions become cards; deploying one opens a fresh session with that question as the brief, and the answer comes back to the card with a what-changed note, so what you learn accumulates somewhere durable instead of scrolling away. The git pane beside each session shows the history graph and live diffs, often the fastest way to find who last touched the confusing part and why.

Loops cover the parts worth repeating, like a weekly pass checking whether your notes still match the code. It drives the agent subscriptions you already pay for, and the free tier doesn't need one of ours.

Start with the trace

Next unfamiliar repo you open, don't ask for an overview. Ask it to follow one real request from the front door to the database and back, with file paths.

Twenty minutes later you'll know more than a week of reading folder names would have taught you, and you'll have written the first half of the documentation on the way.

Download SanuDesk free and point a workspace at the repo you've been putting off, or see how the grid, the board and Loops fit together on the features page.