Get AI to Explain a Codebase for Onboarding
Ask AI to "explain this codebase" and you get generic architecture and "read the controllers" — no reading order, no flow, nothing to act on. Here's how to explain a codebase for onboarding: a map of folders and flow, a reading path, safe first tasks, and the unknowns to confirm.
Build a Codebase Explanation PromptThe "explain this codebase" answer that doesn't help you start
You've joined a project, cloned the repo, and it's a wall of folders you've never seen. So you paste some of it into the AI and ask it to explain the codebase — and what comes back is the software equivalent of a shrug. "This is a typical MVC web application. Controllers handle requests, services hold business logic, views render pages. Start by reading the controllers and models." It's not wrong, exactly. It's just useless: it never says which controller, how a request actually flows, which files matter most, what the domain words mean, or where a newcomer should safely put their hands first. Worse, "typical MVC" is a guess — the model pattern-matched the folder names and told you what projects like this usually look like, not what this one does. You're exactly as lost as before, now with a confident paragraph on top.
Onboarding to a codebase needs a different thing than an explanation of a file — it needs a map: what the project does, how it's laid out, where a request enters and where it goes, which files to read in what order, and what to leave alone until someone explains it. This guide is how to get AI to explain a codebase for onboarding: give it the actual code and tree, tell it you're orienting rather than changing anything, and ask for the map, the reading path, and the unknowns it can't fill. NewPrompt helps you build that prompt: the Code Explanation Prompt builds a prompt aimed at a new team member — an onboarding-calibrated explanation, not the generic overview a bare "explain this" invites. But it's honest about the limit: it doesn't scan your repo, connect to GitHub, run the code, trace a request at runtime, or check that the architecture it describes is actually correct. It works only on the code and context you paste, and what it produces is a candidate onboarding map you verify against the real repo — not a scan of it.
Why "explain this codebase" gives you nothing to onboard with
The request fails because "explain this codebase" is really several different questions wearing one sentence, and the model answers the easiest one — a generic tour of what an app like this usually contains. Onboarding needs the specific ones, and it needs them ordered for someone who has to become productive, not just informed. A single-file explanation tells you what one thing does; an onboarding map tells you how to move through the whole thing. The difference is in what it makes explicit:
- What the project actually does — its purpose in a sentence or two, drawn from the README and the routes you provided, not from what the folder names imply.
- How it's laid out — which folder or module owns which job, so the tree stops being a list of names and becomes a map of responsibilities.
- Where a request enters and where it goes — the entry point and the path a request or piece of data takes through the layers, which is the thing a newcomer most needs and least gets.
- The domain vocabulary — the project's own words and concepts, explained the way an onboarding buddy would, because the real barrier in a mature codebase is the vocabulary, not the syntax.
- What to read first, and in what order — an actual path through the files, so "read the controllers and models" becomes "start here, then this, then that, and here's why."
- Where the edges are — the files it hasn't seen, the assumptions it's making, and the areas risky enough to leave alone until someone walks you through them.
Step 1: Give it the code — and say you're onboarding, not changing
The model can only map what it can see, so the first move is to hand it a representative slice of the actual codebase and name the job. Give it the repo tree (so it knows the shape), the README or docs (so it knows the intent), the entry point or startup file (so it knows how the app wires together), and a few real files that show the pattern — one controller, one service or module, one model, a config file, a test if there is one. Then set the frame explicitly: this is for onboarding a new developer, the goal is understanding, and it should use only the files and tree you've provided. That last instruction matters more than it looks — without it, the model fills the gaps between your files with what codebases like yours usually have, which is exactly the guessing you're trying to avoid.
That framing — mode, audience, and depth — is what the Code Explanation Prompt is built to assemble: it turns "high-level overview, for a new team member, detailed" into an explanation contract, rather than leaving the calibration to chance. The Onboarding Codebase resource is that contract tuned for exactly this reader — a strong engineer with zero context on this system — so it explains the codebase's own names and conventions like an onboarding buddy and connects each part to where it's called from, instead of teaching you the language you already know. Both give you a prompt you run in your own AI tool on the code you provide; neither reads the repo for you.
Step 2: Ask for the map, not a description
With the code in front of it, ask for the specific sections a newcomer needs, named up front, so the answer is a navigable map instead of a paragraph. A useful onboarding explanation has parts: what the project does; the folder or module map with a one-line job each; the entry points; the request or data flow traced through the layers; the key domain concepts and naming; the conventions the code repeats; the handful of critical files; and — the parts that make it actionable — a reading order and a set of safe first tasks. Asking for these by name is what turns "explain the codebase" into an answer you can act on, because the model fills a labeled structure instead of choosing its own altitude and usually landing too high.
The single most valuable section is the flow. A new developer can read every file and still not understand the system until they've followed one real request from where it enters to where it ends — the controller it hits, the service it calls, the data it reads, the response it returns. So ask for that trace explicitly: pick one representative request or operation and walk it through every layer it touches, naming each handoff. The Architecture Explanation Prompt is built around exactly that move — layers and their owners, dependency direction, and one request followed through every boundary — which is the section that turns a folder map into an understanding of how the thing actually runs.
Step 3: Make it separate what it saw from what it's guessing
The dangerous failure in a codebase explanation isn't vagueness — it's confident invention. Give a model a folder called "services" and no service files, and it will happily describe the service layer it assumes is there; give it a controller that calls something you didn't paste, and it'll narrate what that something probably does. Those inventions read exactly like the parts grounded in real code, and a newcomer can't tell which is which — so they build a mental model half made of fact and half made of the model's pattern-matching. Head it off with a rule: separate what's shown by the provided code from what's likely but unverified, label the inferences as inferences, and where behavior can't be determined from what you gave it, say "cannot be determined from this code" instead of filling the gap with a plausible story.
The instruction that does the most work is the one about missing files: if a layer, a file, or a flow isn't in what you provided, the model should name it as an unknown, not reconstruct it. "I haven't seen the data-access layer; I can't confirm how persistence works" is a genuinely useful sentence — it tells you what to go read next. A confident description of a data-access layer the model never saw is worse than useless, because it's a wrong map you'll trust. So the explanation should end where the provided code ends, and its list of unknowns — the files it didn't see, the behavior it couldn't confirm — becomes the first item on your list of questions for whoever knows the repo.
Step 4: Ask for a reading path and a safe first task, not "read everything"
"Read the whole codebase" is the advice that sounds thorough and helps no one — nobody onboards by reading a repo top to bottom, and a new developer needs a path, not a pile. So ask for one: the files to read first, in order, each with a one-line reason it's next. A good path follows the system rather than the file tree — start at the entry point to see how the app boots, then the controller for a real request, then the service or module it calls, then the data or config it depends on, then a test to see the expected behavior spelled out. The order is the value: it walks the newcomer along the flow they just learned, so each file makes sense in light of the last instead of in isolation.
Then ask for the two things that turn reading into doing: a set of safe first tasks and a list of risky areas to leave alone. A safe first task is small, low-blast-radius, and pattern-following — update a string in a content file, add a test around an existing behavior, trace one request end to end without changing anything — the kind of thing that builds familiarity without endangering the system. The risky areas are the opposite: routing, auth, the data model, caching, migrations — the structural walls a newcomer shouldn't touch until someone explains them. Naming both does something a generic explanation never does: it tells the new developer not just how the code works, but where it's safe to start participating in it.
Step 5: Treat the map as a candidate, and verify it against the real thing
What comes back is a candidate onboarding map, not a verified one — and the difference matters most exactly when you're new, because you have the least ability to catch where it's wrong. The model explained the code you gave it, and it can misread a pattern, miss a layer you didn't paste, or state an inference about intent as if it were fact. So treat the map as a scaffold for your own reading, not a substitute for it: as you actually read the files, you confirm the parts that hold and correct the parts that don't, and the map gets truer as you go. The unknowns it flagged are your reading list; the inferences it labeled are the things to check first.
And the map has a second reviewer who isn't you. On any codebase that's large, old, or high-stakes, the person who already knows it — a senior developer, the repo owner — is who confirms the architecture, corrects the assumptions, and answers the questions the model left open, and that conversation is faster because you're arriving with a specific map to check rather than a blank stare. NewPrompt gives you the structure to produce that map from the code you provide; reading the real repo, running it, and confirming how it actually works all happen on your side, with your team. The AI can get you oriented far faster than a cold read of the tree — it just can't be the last word on a system it only saw a slice of.
Common mistakes
The habits that turn a codebase explanation into a confident wrong map:
- Asking to "explain the codebase" with no code attached. The model can only map what it sees; give it the tree and real files, or it'll describe what projects like yours usually look like.
- Letting it fill the gaps between your files. Tell it to use only what you provided and to name missing layers as unknowns — a guessed data-access layer is a wrong map you'll trust.
- Accepting a description instead of a map. Ask for the labeled sections — purpose, folder map, entry points, flow, reading order — so the answer is navigable, not a paragraph.
- Skipping the request flow. A folder map isn't understanding; make it trace one real request through every layer, because that's the section that shows how the system actually runs.
- Taking "read everything" as a plan. Ask for an ordered reading path and a safe first task; nobody onboards by reading a repo top to bottom.
- Trusting the map because it's confident. It explained a slice and can be wrong; verify it against the real code and a senior dev — NewPrompt doesn't scan the repo or check the architecture for you.
A worked example: onboarding to an unfamiliar web app
Watch a one-line "explain this codebase" produce a generic MVC tour, then an onboarding-framed prompt turn the same provided files into a map with a reading path, a safe first task, and honest unknowns.
A one-line "explain this codebase" returns a generic MVC tour pattern-matched from folder names; an onboarding-framed prompt turns the provided files into a map — purpose, folder map, one traced request, an ordered reading path, safe first tasks, risky areas, and the unknowns it couldn't see — an onboarding map to check against the real repoWHAT YOU GIVE THE AI:
- the repo tree (folders: Controllers, Views, Services, App_Data, ...)
- README excerpt (what the product is)
- Program.cs (startup / routing / service wiring)
- one controller, one service, one model, one test file
- note: "onboarding a new dev; explain, don't change anything"
THE WEAK ASK, AND WHAT IT GIVES BACK:
ask: "Explain this codebase."
answer: "This is a typical MVC web application. Controllers handle
requests, services hold business logic, views render pages.
Start by reading the controllers and models."
why it doesn't help:
- "typical MVC" -- pattern-matched from folder names, not your code
- which controller? which request flow? which files matter?
- no reading order, no data flow, no safe starting point
- may assume layers (a service layer?) that the files don't show
AN ONBOARDING-FRAMED PROMPT:
Explain this codebase for onboarding a new developer. Use ONLY the files
and tree I provided; do not guess missing layers. Output, with headings:
- what this project appears to do
- folder/module map (one line each)
- entry points
- request/data flow (trace ONE real request through the layers)
- key domain concepts and naming
- files to read first, in order, each with why
- safe first tasks for a new dev
- risky areas not to change yet
- assumptions, and unknowns (files/behavior you could not see)
Rules:
- Separate "shown by the provided code" from "likely but unverified."
- If a layer/file isn't shown, mark it unknown -- do not describe it.
- Do not recommend changes; do not claim tests pass or the
architecture is correct.
PART OF WHAT COMES BACK (a candidate you verify):
What it does: from README + routes, a content/catalog web app (inferred).
Entry points: Program.cs wires routing + services; [X]Controller.Index
renders the listing (shown).
Request flow (one request): request -> [X]Controller.Index ->
[Y]Service lookup -> reads App_Data JSON -> returns View (shown for
the files provided; other routes not seen).
Read first: README, Program.cs, the provided controller, its service,
one JSON content file, the test -- in that order, and why.
Safe first tasks: edit copy in one JSON file; add a test around the
provided service; trace another request without editing.
Risky, don't touch yet: routing, the registry/data model, auth, caching.
Unknowns: no data-access/DB files seen; can't confirm auth or background
jobs; other controllers not provided.
NEXT: you read the files in that order, confirm the flow against the real
code, and take the unknowns to a senior dev. The map got you oriented --
it didn't scan the repo or verify the architecture. You do, with the team.Where this fits in NewPrompt
Getting oriented in a codebase is a prompt problem before it's a reading problem, and NewPrompt gives you the structure for the prompt, not access to the repo. The Code Explanation Prompt is what pins the answer to an onboarding map for a newcomer rather than a generic overview — it sets the explanation's mode, reader, and depth before the model starts. The Onboarding Codebase resource tunes that prompt for the new-team-member reader — someone who codes fluently but has never seen this system — so the explanation decodes the codebase's own vocabulary and connects each part to the system instead of teaching you syntax. And the Architecture Explanation Prompt supplies the section a folder map can't: the layers, the boundaries, and one request traced end to end. Each builds a prompt you run on the code you provide, in your own AI tool; none reads, runs, or validates the repo.
This guide sits next to the other code-explanation work as the codebase-wide, newcomer-facing one. Explaining an unfamiliar piece of code before you change it is aimed at one file and one edit — you're about to touch it; this is aimed at the whole repo and no edit — you're trying to find your way around it. It isn't refactoring, debugging, or generating tests, because onboarding asks the model to describe what exists, not to change, diagnose, or add to it — a distinction the prompt enforces so the explanation stays a map and doesn't wander into recommendations. The through-line: this turns a repository you've never seen into a route through it you can actually walk.
A codebase onboarding map is a trail map posted at the trailhead, not the forest walked for you. It shows where you're standing, which paths are marked and where they lead, the short loop to start on, and the areas fenced off with "not yet — ask a ranger." What it isn't is the ground itself: it was drawn from the stretch of trail you photographed and handed over, so a path it doesn't show isn't gone, just off the edge of what you gave it, and a marked route can still be out of date. Read it to know where to set out and what to leave alone — then walk the real trail, and where the map and the ground disagree, the ground is right, and the person who's hiked it before is who you ask.