Using AI to Understand an Unfamiliar Codebase

TL;DR: To use AI to explain an unfamiliar codebase, work in five phases: orient (entry points, directory shape), map (how modules call each other), trace (one request end to end), interrogate (why the code is shaped this way, what breaks if you touch it), and verify (catch confident guesses before you act on them). Paste interfaces and entry points, not whole files, and use an agent with repo access once pasting stops scaling.

How Do You Use AI to Explain an Unfamiliar Codebase?

You use it in five ordered phases, each building on the last: orient, map, trace, interrogate, verify. Skipping straight to "explain this function" is the single most common way this goes wrong.

The reason a one-shot prompt underperforms isn't the model; it's that "explain this codebase" has no clear scope. The model has to guess what you actually need: a tour for someone about to fix a bug, a security review, an architecture summary for a rewrite decision. Each of those needs different code pasted and produces a different useful answer. The five-phase sequence exists to remove that guesswork one step at a time.

Orient tells you where to start reading and what the project even is. Map tells you how the pieces you found actually talk to each other. Trace proves the map is right by following one real request through it. Interrogate gets at the "why," which the code itself often doesn't say. Verify is the step most engineers skip, and it's the one that catches the model being wrong with total confidence about something it never actually read.

This is also, not coincidentally, close to how an engineer reads a new repo without AI. You just do it faster, and with a second opinion checking your read as you go. What changes with AI in the loop is the constraint on what you can hand it at once, which is why the paste-versus-agent question below matters as much as the phases themselves.

What Should You Ask AI to Orient You in a New Codebase First?

Ask for a map of entry points and structure before you ask about any specific piece of logic. Orientation answers "what is this and where do I start," not "what does this function do."

The highest-value things to paste at this stage are cheap to produce and expensive to skip: the directory tree, the README, the package manifest (package.json, pyproject.toml, go.mod, whatever applies), and any top-level config file that names the framework. None of these require you to have read a single line of business logic yet, and together they tell you and the model what kind of project this is before either of you commits to a theory about it.

Role: You are a senior engineer doing a first-day read of an unfamiliar repository.

Task: Based on the directory tree, README, and manifest file below, identify: (1) what this project does in plain terms, (2) the likely entry point file(s) for a running instance, (3) the major top-level directories and what each is probably for, (4) anything in the manifest that signals architecture (framework, database driver, queue library).

Format: Four short headed sections matching the four items above. If something can't be determined from what's pasted, say so explicitly instead of guessing.

[paste directory tree]
[paste README]
[paste manifest file]

Role: You are onboarding a new engineer to a codebase you already know well.

Task: Given the entry point file below, trace what happens in the first 30 seconds after this file runs — what gets initialized, in what order, and what it's waiting for.

Format: A numbered sequence, one step per initialization action, plain language.

[paste entry point file, e.g. main.py, index.ts, server.js]

Role: You are a technical writer producing a one-page project brief for a stakeholder who will never read code.

Task: Summarize what this project does, who it's likely for, and its three or four biggest architectural building blocks, using only the manifest and README below.

Format: One paragraph, then a three-to-four bullet list of building blocks. No code, no file names.

[paste manifest + README]

How Do You Get AI to Map How the Pieces Actually Talk to Each Other?

Ask it to trace calls between the specific modules you found in orientation, not to describe architecture in the abstract. A map is only useful if it's built from files you actually pasted.

This is where "explain this codebase" prompts usually go wrong. They invite an abstract, generic answer ("this follows an MVC pattern with a service layer") that sounds right for almost any project and is checkable against almost none of them. Ask instead about the specific modules orientation surfaced: which file imports which, which function calls which service, where the boundary between "handles HTTP" and "touches the database" actually sits.

Role: You are a staff engineer mapping module boundaries for a team about to work in this codebase.

Task: Given the files below, list which files import or call which others, and describe the boundary between them (e.g. "routes/ calls services/, services/ calls db/, nothing calls routes/ back").

Format: A short directed list in the form "A calls B for X," followed by one sentence naming any boundary that looks unusually blurry (a file that seems to skip a layer).

[paste 3-6 related files: routes, a service, a data-access module]

Role: You are reviewing a codebase's dependency structure for a technical audit.

Task: Based on the import statements across the files below, identify any module that is imported by many others (a likely shared utility or core abstraction) versus one that imports many others (a likely orchestrator).

Format: Two short lists: "Widely depended on" and "Depends on many others," each with the file name and a one-line reason.

[paste import/require lines from the files you have, or the files themselves]

How Do You Trace One Request Through the Codebase End to End?

Pick one concrete, real request (a specific API call, a specific button click, a specific CLI command) and ask the model to follow only that path from entry to exit. A traced example checks the map from the previous phase; an abstract "how does data flow through this system" question does not.

Tracing is where you convert the map into something you can trust, because a single concrete path is falsifiable in a way "here's the general architecture" isn't. If the model claims the request goes through a caching layer that doesn't appear in any file you pasted, that's a signal to paste more, not to accept the claim.

Role: You are a senior engineer explaining request flow to someone new to this codebase.

Task: Trace exactly what happens when a client sends [describe the specific request, e.g. "POST /api/orders"], using only the files below. Note every file, function, and external call (database, queue, third-party API) the request passes through, in order.

Format: A numbered trace: file → function → what it does → what it calls next. Stop and say "not visible in the files provided" rather than inferring a step you can't see.

[paste the route handler]
[paste the service/business-logic file it calls]
[paste the data-access file, if separate]

Role: You are debugging a request that behaves unexpectedly.

Task: Given the trace below and this specific input [describe input], identify at which step the behavior would diverge from a normal request, and why, based only on the code shown.

Format: Point to the exact step number and file, quote the relevant line, then explain the divergence in one or two sentences.

[paste the same files as the trace above]
[describe the specific unexpected behavior]

Role: You are tracing a single variable's lifecycle through a request.

Task: Track the variable [name] from where it's created to every place it's read, modified, or passed to another function, using only the file(s) below.

Format: A numbered list — line number, what happens to the variable at that line, and whether that's a read or a write.

[paste the file(s) containing the variable's full lifecycle]

How Do You Get AI to Interrogate Code Instead of Just Describing It?

Ask "why" and "what breaks," not "what does this do"; description is what phases one through three already gave you. Interrogation is where you find out whether a piece of code is load-bearing, incidental, or a landmine.

Code answers "what" on its own. It rarely answers "why" without help, because intent lives in commit history, tickets, and Slack threads that never make it into the file. If you have any of that context (a commit message, a comment, a related test), paste it alongside the code and ask the model to reason from both. Without it, treat any "this exists because..." answer as a guess to check, not a fact to repeat. Interrogation and code review share a lot of technique; once you've built the understanding this phase gives you, how to prompt for a genuinely useful code review covers briefing an AI reviewer with the same discipline: curated context, falsifiable findings, severity tied to actual consequences.

Role: You are a principal engineer asked to justify a piece of legacy code before a planned rewrite.

Task: Based on the code, comment, and commit message below, propose the most likely reason this code exists in its current form. Separate what's supported by the pasted evidence from what you're inferring.

Format: Two labeled sections, "Supported by evidence" and "Inferred, unverified," each a short paragraph.

[paste the code]
[paste the commit message or comment, if you have one]

Role: You are assessing the blast radius of a proposed change.

Task: Given the function below and its callers, list everything that would need to change or could break if you altered its return type or its error-handling behavior.

Format: A list of concrete impacts, each tied to a specific caller file and line. If you weren't given all the callers, say so and name what's missing rather than assuming there are none.

[paste the function]
[paste every caller you can find — grep for the function name first]

Role: You are reviewing whether a piece of code is still in active use before deleting it.

Task: Based on the search results below (all references to this function/file in the codebase), determine whether this code appears to be dead, still actively called, or ambiguous.

Format: One of three verdicts (Dead, Active, or Ambiguous) with the specific reference lines that support the verdict.

[paste grep/search results for the function or file name across the repo]

How Do You Catch AI Being Confidently Wrong About Code It Never Actually Read?

You force it to cite the exact line it's basing each claim on, then you check that line exists and says what it claims. A confident, well-written explanation is not evidence the explanation is correct; it's evidence the model is good at writing confident explanations.

This is the phase most engineers skip, and it's the one that matters most, because hallucination in code explanation doesn't look like nonsense. It looks like a plausible paragraph about a caller, a config default, or an error path that simply isn't in the files you pasted. The model isn't lying; it's pattern-matching from millions of similar codebases it trained on, and similar isn't the same as yours.

Role: You are fact-checking an AI-generated explanation of a codebase against the actual source.

Task: Below is an explanation of a function, followed by the function's actual code. For every factual claim in the explanation, mark it Confirmed (quote the matching line), Contradicted (quote the line that disagrees), or Unverifiable (nothing in the code confirms or denies it).

Format: A numbered list, one claim per line, with its verdict and supporting quote.

[paste the previous explanation]
[paste the actual function/file it was describing]

Role: You are a skeptical senior reviewer checking your own prior explanation for overreach.

Task: Re-read the explanation you gave earlier against the code below. Identify anything you stated as fact that you cannot actually point to a specific line for.

Format: A short list of "unsupported claims," each with what you'd need to see to confirm or retract it.

[paste your own earlier explanation]
[paste the code again]

Role: You are auditing an AI's architectural summary of a codebase for invented details.

Task: List every specific file name, function name, and class name mentioned in the summary below. For each one, state whether it appeared in the source files that were actually provided in this conversation.

Format: A table — Name | Mentioned in provided files? (yes/no) | If no, flag as likely invented.

[paste the summary]

What Should You Actually Paste Into a Code-Explanation Prompt?

Paste directory structure and interfaces before you paste implementation, and paste a function's contract, not just the function, before you paste an entire file. What you paste determines what the model can verify and what it has to guess.

Whole files are the default instinct and usually the wrong one: most of a file's contents are irrelevant to whatever specific question you're asking, and pasting it burns context window that could hold the actual callers or types instead. A single isolated function is the opposite problem: it loses its contract entirely, so the model can't see what it's promised to return, what calls it, or what it depends on, and fills that gap with a plausible guess.

The middle ground that works for most questions: the function or module in question, its type signatures or interface definitions, and one or two real call sites. That's usually under a hundred lines and it's enough for the model to reason about behavior instead of inventing it.

Role: You are extracting only the public contract of a module for someone who needs to call it without reading its internals.

Task: From the file below, extract every exported function, its parameters, its return type, and a one-line description of what it does — nothing about internal implementation.

Format: A markdown table — Function | Parameters | Returns | One-line purpose.

[paste the file]

When Should You Use MCP or an Agent Instead of Pasting Code at All?

Switch from pasting to a repo-connected agent once your questions span more files than you can reasonably copy in by hand, or once you're asking the same kind of question repeatedly across a whole codebase. Pasting doesn't stop working at some hard line. It just stops being the fastest way to get an answer.

Model Context Protocol (MCP) is the open standard Anthropic released in November 2024 for connecting an AI model directly to external tools and data, including a filesystem or a git repository, instead of you copying content into the chat by hand. Tools like Claude Code, Cursor, and GitHub Copilot's agent mode can open a repository, follow an import across files, and run a search themselves, which is a meaningfully different workflow from pasting: you describe the question, the tool decides what to read.

Native context windows have also grown enough that this matters less as a hard constraint than it used to. As of August 2026, Claude Sonnet 5 and Opus 4.7 and later run a 1-million-token window by default on Anthropic's own API (docs.anthropic.com), and Gemini 3 offers a comparable 1-million-token input window (ai.google.dev). That's large in raw terms, but a bigger window doesn't fix the verification problem from the previous section. A model with more room to read still needs to be checked on what it claims, and an agent reading files directly still benefits from you asking it to cite what it found rather than trusting a summary.

The practical split: use the five-phase paste method for a specific module, a specific bug, or a focused review where you already know which files matter. Reach for an agent with direct repo access when you're onboarding to something large enough that you don't yet know which files matter — which is exactly when manually deciding what to paste becomes the bottleneck. How to use MCP inside Cursor and Claude Desktop covers the connection setup if you haven't wired one up yet.

Role: You are briefing an AI agent that has direct read access to this repository.

Task: Before writing any code, do the following: (1) list the entry point files, (2) summarize the three most important modules and how they connect, (3) trace how [specific feature] works end to end, citing the actual files and line ranges you read. Do not describe anything you did not open.

Format: Three headed sections matching the three tasks, each with file paths and line references.

Role: You are an agent with repository access, asked to scope a change before making it.

Task: Find every file that references [function/class/module name], using an actual search rather than assumption. Report each reference with file path and line number before proposing any change.

Format: A list of file:line references, followed by a one-paragraph summary of what would need to change and why.

Whichever method you use, the discipline doesn't change: name the specific question, hand over the specific evidence, and check the specific claims. That's the whole difference between a prompt that produces a plausible paragraph and one that produces a working understanding of code you didn't write. Prompt Architects' generator builds prompts to this same Role/Task/Format/Constraints/Tone structure automatically if you'd rather not write the scaffolding by hand each time. See what prompt engineering actually is for the underlying mechanics, or the code review prompt generator for a fill-in-the-blanks version built specifically for reviewing code once you understand it.