Quickly Get Up to Speed on an Unfamiliar Codebase with AI

Taking over an unfamiliar codebase is a rite of passage every developer can't avoid. Especially projects left by others, or the one you walk into on your first day—no docs (or docs that went stale long ago), dozens or hundreds of directories, tens of thousands of lines of code. You open the editor, and the directory structure alone makes your head spin: what's the difference between core/ and engine/? Among the dozen files in services/, which one is the entry point? When an API request comes in, which layers does it actually pass through?

The standard approach used to be "brute-force reading": pick an entry file, follow the calls layer by layer, drawing a dependency graph in your head as you go. For a medium-sized backend project, you can't get a feel for the skeleton in less than three to five days; for a monorepo or legacy system, a week is the floor. Along the way you'll get lost repeatedly—reading A you find a dependency on B, B references C, and by the time you loop back you've forgotten what you were originally looking at.

AI agents compress this time by an order of magnitude. Not because they're smarter than you, but because they read fast, don't tire, can scan systematically, and won't "zone out halfway through." But the precondition is: you can't ask it "how's this project" like a headless fly; you need a structured set of questioning and verification methods. This article lays out an onboarding workflow I've validated repeatedly across a dozen-plus unfamiliar repos.

1. First step: have the agent read through and generate an architecture overview

The first thing in onboarding isn't to read some specific file; it's to first build a global map. Without a map, every file you read is an island.

My first instruction to the agent is almost always this:

You are a senior architect. Read through this repo and give me an architecture overview that includes:
1. What the project does (one sentence)
2. The top-level directory structure, plus the responsibility of each directory
3. The main entry points (where the service start, CLI entry, and page entry each are)
4. The dependencies between core modules (who depends on whom; is there layering)
5. The tech stack and key dependencies
Start from package.json / config files / README, then read key source to verify.
Output should be layered; don't paste code right out of the gate.

Why write it this way? A few points: define the role explicitly (architect's perspective, not programmer's), define the output structure explicitly (a five-point list, to keep it from rambling), specify the entry path (start from config files—this is the trick I most often tell newcomers: config files are the project's "table of contents"), and require layering and no code pasting (in the overview stage, pasting code is just noise).

The agent will first read package.json (for scripts and dependencies), tsconfig.json/next.config.ts (for the tech stack and path aliases), prisma/schema.prisma (for the data model), and the directory tree, then sample a few core files to verify its judgment. Within minutes it gives you an overview with directory responsibilities, entry-point locations, and dependency directions.

The key action here is: make it read real files, not guess from directory names. A low-quality overview looks like: "services/ is probably the service layer, utils/ is utility functions"—all "probably." A good overview looks like: "src/services/ has 8 files; userService.ts is the core of the user domain, called by api/users/route.ts and api/auth/route.ts, and depends on prisma and lib/redis"—with evidence.

After getting the overview, I always do one thing: pick two of the entry points it mentioned and verify them by hand. This is the key to building trust. If it says the entry is in src/server.ts, you open it, confirm it's actually there and the responsibilities match, and only then can you let it loose to trace on its own. If it's wrong (say, mistaking a test entry for the main entry), correcting it now is the cheapest it'll ever be.

2. Tracing call chains: the full path from entry to landing

With the map in hand, the next high-frequency need is tracing a specific path. A typical question: "When a user fires a POST /api/orders request, from arrival to the order being written to the database, which code does it pass through entirely?"

Tracing this by hand, you'd open the routing file → find the handler → see which service the handler calls → see which repository the service calls → see which SQL the repository runs. In between are interleaved middleware, auth, validation, and transactions. A moment's inattention and you miss a layer.

Hand it to the agent:

Trace the full handling chain of this request: POST /api/orders
Starting from the routing layer, follow each layer's calls all the way to the database write.
What I want: for each layer, which file and function it's in, what it does (auth? validation? business logic? persistence?),
and to whom it hands control. Finally, give me a call graph (text is fine),
flagging places that cross layers and places that may have performance issues (e.g., querying the DB inside a loop).

The essence of this prompt: give the starting point, the ending point, the information to capture along the way, and extra analysis dimensions (flag cross-layer and performance hazards). The agent will grep + read its way down the call chain, list every stop, and casually point out "this queries the DB inside a for loop, N+1."

A practical tip: when tracing a call chain, it's also useful to have the agent draw a "reverse dependency graph"—i.e., "who calls this service." Before changing a module, knowing its blast radius is often more important than understanding the module itself.

3. Asking "how is a feature implemented": locate and explain in one step

The third typical scenario is feature understanding: "How is this project's permission control implemented?" "How is subscription expiry handled?" "How is the search feature done?"

The hallmark of these questions is that you don't know which files the relevant code is scattered across. A novice asks "where are the permissions," gets a filename, and is satisfied; a veteran wants location + logic explanation + key design intent.

How does this project do permission control?
Please: 1. Find all relevant files (middleware, decorators, guards, utility functions)
2. Explain the overall strategy (RBAC? ABAC? hardcoded?)
3. Point out at which entry points the permission check takes effect, and which entry points "miss" the permission check
4. If I wanted to add a new role, which places would I need to change

Point 3 is especially valuable—"which entry points miss the permission check" is something the agent can hand you in passing but that you'd struggle to systematically audit yourself. It can list every route handler, annotate each with "has guard / no guard," and the unguarded endpoints immediately surface. At this point you've upgraded from "reading code" to "auditing code."

4. Identify risks and technical debt: have the agent be your auditor

Onboarding isn't just about understanding; it's also about knowing where the landmines are. Landmines are often more important than the normal flow, because that's the debt you'll be paying off after you take over.

Have the agent switch to an "auditor" perspective and sweep once:

As a senior engineer, audit this repo, focusing on:
1. Suspicious patterns: hardcoded keys/passwords, eval, SQL concatenation, unvalidated external input
2. Complexity hotspots: overly long functions, overly deep nesting, overly large single files (Top 5)
3. Test gaps: which parts of the core business logic have no test coverage at all
4. Technical-debt signals: large amounts of TODO/FIXME, deprecated but undeleted code, duplicated implementations
For each, give the specific file and line number, and why it's a risk.

The agent gives you an evidence-backed list. The value here is systematization—when you read code yourself, you only notice the few spots you pass through; the agent can sweep the whole repo and surface the "you don't know what you don't know" problems.

But there's an iron rule: risks the agent reports must be re-checked by a human before you change anything. It sometimes mistakes "intentional design" for a risk (e.g., something that looks like SQL concatenation but whose input is internally generated and safe). Re-checking is cheap; trusting the mistake is costly.

5. Give the agent good indexes: semantic search + AST/LSP, so it reads accurately

The precondition for the previous four steps to work is that the agent finds things accurately. A brutal fact: an agent relying purely on grep + full-text reading will be wildly inaccurate in a real codebase—it'll treat same-named methods as the same one, miss dynamic calls, and misattribute symbols (we covered this in detail in "Code Intelligence: The AST + LLM Combo").

So to make the onboarding conclusions reliable, you need to equip the agent with structured indexes:

• Semantic search / codebase indexing: like Cursor's codebase index or Claude Code's codebase retrieval tool, turning the repo into a semantically recallable knowledge base. Asking for "permission-related code" recalls everything, not just files that literally contain "permission" via grep.
• AST / LSP: for structural questions like "call sites," "references," and "types," use LSP's references/definition or the TS Compiler API to get semantic-level real answers, instead of letting the LLM guess from text.

In practice, I have the agent first use semantic search for a coarse filter, then LSP/AST for precise location. When tracing a call chain, semantic search helps it quickly lock onto "the few order-related files," and LSP helps it confirm "who actually calls this createOrder." The former handles breadth, the latter precision. Without structured indexes, the overview the agent gives you might be "looks right but actually missed three dynamic call paths"—and that kind of omission is exactly the root cause of the wrecks you'll have later when changing code.

6. Limitations: huge repos, runtime behavior, implicit conventions—the overview must be verified

Finally, the boundaries of AI onboarding must be made clear, so you don't over-trust and wreck things.

First, very large repos exceed the agent's effective context. For a monorepo of hundreds of thousands of lines, the agent can't read it all in one session; it samples—and sampling has bias. In that case, first split by subpackage/subdirectory, have the agent produce overviews per chunk, then assemble them by hand.

Second, the agent reads static code and can't see runtime behavior. It can tell you "Redis caching is used here," but it doesn't know "the actual hit rate of this key in production, or whether there's a cache stampede." Questions involving runtime performance, real traffic, and data distribution can only be answered by monitoring and logs; the agent can't give you the answer.

Third, it can't read implicit conventions. The team's code standards, who owns which area, why it was designed this way in the first place (maybe because someone stepped on a landmine three years ago)—these live in people's heads and in PR history, not in the code. The agent can see "the code looks like this" but not "why it looks like this."

So one non-negotiable principle: the overview the agent gives is a "high-quality draft," not "verified fact." Every conclusion you'd act on—especially before changing code—must be spot-checked by a human. The cost of verification is far lower than the cost of rework after acting on a wrong understanding.

Summary

• Build the map before reading details: the first instruction is always to have the agent read through and produce an architecture overview (directory responsibilities / entries / dependencies); without a map, no number of files you read is anything but islands.
• Bake analysis dimensions into the prompt: when tracing call chains or asking about features, don't just ask "how is it implemented"—also have it flag cross-layer calls, missing permissions, and N+1—upgrading code reading into code auditing.
• Systematize risk identification: have the agent sweep the whole repo with an auditor's eye for suspicious patterns / complexity / test gaps, but the landmines it reports must be re-checked by a human.
• Give the agent structured indexes: semantic search handles breadth, AST/LSP handles precision; a pure-grep agent will miss dynamic calls and misattribute symbols in a real codebase, and its conclusions can't be trusted.
• The overview is a draft, not fact: sampling bias in huge repos, runtime behavior, and implicit conventions are all the agent's blind spots; before changing code, you must spot-check.

AI agents compress onboarding from "a week of reading" to "a few hours of reading," not by being smarter, but by reading fast, not tiring, and scanning systematically. But reading fast isn't reading accurately—what really determines the quality of onboarding is the structure of your questions, the indexes you provide, and that final gate of human verification.