Using LLMs to Understand an Unfamiliar Codebase

Understanding code that someone else wrote remains one of the most time-consuming recurring tasks in software development, and the availability of large language models has not changed that fact in any fundamental way. Code Compass, a study out of UC Berkeley on navigating unfamiliar codebases, found that developers spend around 58% of their time on program comprehension activities. Unfamiliar code appears in a new hire's first weeks on a team, in an incident responder tracing a production failure through a service nobody on the call wrote, in an auditor reviewing a contractor's repository, and in a contributor trying to send a useful patch to an open-source project. The task recurs because software changes hands constantly, and each handoff resets the clock on comprehension. Code Compass also found a specific failure mode behind the slowdown: developers struggle to use documentation alongside code exploration, and the tools available to them do not bridge that gap. Solving the problem is possible, but it requires a deliberate approach, since the obvious move, pasting code into a chat window and asking questions, does not supply the structure the task actually demands.

Structural unreliability of LLMs for codebase-level reasoning without guidance

The CodeMap research presented at ICPC 2026 cites prior studies showing that LLMs often fail to help users understand code structure or to provide assistance that adapts to the user and the situation in real-world settings. That failure points to a methodology gap in how the tooling is used. The underlying tension is straightforward: real codebases outscale what any context window can hold, and making the window bigger does not solve this on its own. Chroma's Context Rot research tested a range of models and found that performance grows less reliable as input length grows, meaning a developer who dumps an entire repository into a prompt is not giving the model more to work with so much as burying the signal in noise. A model asked to reason over thousands of tokens of loosely related code has to do its own filtering before it can do any actual analysis, and that filtering step is exactly where unguided prompting breaks down. Pasting more text is not a substitute for pasting the right text. Structured, targeted context beats indiscriminate volume, and the mechanism is simple: a model reasoning over a focused, coherent slice of a codebase has a much easier time staying grounded than one asked to make sense of an undifferentiated wall of source.

How comprehension debt accumulates when developers skip deliberate understanding

The real cost of leaning on LLMs for code comprehension is that the developer's own understanding of the system shrinks, a shortfall that compounds quietly until it surfaces as a seemingly unrelated problem months later. An Anthropic research study found that participants who relied heavily on automation scored measurably lower on comprehension tests than those who worked through the code by hand, with the steepest drop in their ability to debug and reason about complex systems. Margaret-Anne Storey of the University of Victoria gave this phenomenon a name in March 2026, describing it as a Triple Debt Model: technical debt sitting in the code itself, cognitive debt accumulating in the people responsible for it, and intent debt, the missing externalized rationale that both human engineers and AI agents need in order to work with the system safely. These debts compound together. A developer who never built a working mental model of a module cannot maintain it confidently later, an incident responder without that model takes longer to isolate a root cause, and a team accumulating intent debt leaves nothing behind for the next person, human or AI, who has to pick the work back up. The question facing developers is how to use LLMs during onboarding and investigation so that comprehension builds up rather than eroding.

How professional code auditors learn an unfamiliar codebase fast

Code auditors onboard a new system weekly, and their working methods translate directly into a better way to use an LLM. The CodeMap research team interviewed eight code auditing practitioners specifically to find out how they build comprehension quickly, and distilled what they found into four design principles: supporting cognitive alignment through automated extraction of information about the codebase, decomposing the codebase into navigable units, representing that decomposition hierarchically in a way that matches how humans actually build mental models, and reducing manual effort and conversational distraction through deliberate interaction design. The principle that matters most for a developer working with an LLM is the order of operations. Auditors never start with a specific line of code. They start by building the map, and only once the map exists do they navigate to a particular piece of territory. That sequence, orient, decompose, zoom in, is a cognitive flow, not a feature of any particular tool, and it is the structure that an LLM-assisted workflow needs to mirror if it wants the same result auditors get: fast, reliable comprehension of a system nobody on the team built.

The structured workflow: moving from high-level orientation to targeted module questions

Effective LLM-assisted codebase reading follows three ordered phases, orientation at the top level, decomposition into navigable units, and targeted investigation at the module and function level. Skipping a phase or working through them out of order produces the unreliable, hallucination-prone output developers tend to blame on the model, when the prompting sequence is the actual cause.

Phase 1 is orientation at the codebase level. Before any code gets pasted in, the task is to give the model the map rather than the territory: feed it the README, the package manifest, and the top-level file tree, and ask it to explain the project's purpose and identify where it actually starts running. A usable prompt here reads: "Given this directory structure and README, explain the purpose of this codebase, identify the main entry points, and list the top five modules a new developer should understand first." The output from this phase is meant to produce a reading order, a prioritized list of what to look at next, treated as a map.

Phase 2 is decomposition at the module level. Each high-priority module surfaced in Phase 1 gets its own pass, one at a time rather than all at once: what is this module's single responsibility, what does it expose to the rest of the system, and what does it depend on. Keeping each prompt scoped to one module keeps the model's reasoning coherent, since a module-level question gives it a focused, bounded unit to reason about.

Phase 3 is targeted investigation at the function or file level, and it only starts once the module's role is already established. At this point a developer can bring in a specific function and ask something precise: "In the context of [module role explained above], explain what this function does step by step, identify any side effects, and flag anything that looks like it could fail silently." Anchoring this kind of question to the context already built in Phases 1 and 2 sharply reduces the risk of hallucination, because the model now has a coherent frame to reason within instead of having to guess at the surrounding system from the function alone.

Context management techniques that keep LLM responses accurate as you go deeper

The quality of what a model produces degrades as a conversation grows longer, and that degradation does not correct itself without active management from the developer running the investigation. One of the simplest corrections is an explicit reset: when the work shifts from one module to the next, starting a new conversation serves the task better, since context accumulated while studying an earlier module tends to introduce noise into the next. A second technique is the running summary, prompting the model at the end of each phase to produce something compact, such as "Summarize what we now know about this module's responsibilities and dependencies in three bullet points," and then carrying that summary forward as a compressed anchor rather than re-pasting the full history of the conversation. A third is scoped pasting: a function or a class should go into the prompt where a function or class answers the question, and a whole file should not, because handing the model more than it needs shifts the burden of figuring out what matters onto the model itself, a task it performs poorly once the input grows large. A fourth is the verification prompt, asking the model directly what it is least confident about and what it would need in order to verify its own explanation, which catches hallucination risk before it compounds into a wrong mental model the developer then builds on. A related discipline comes from a study by Sankaranarayanan, which proposed an "Explanation Gate": requiring a developer to explain AI-generated code back in their own words before integrating it. Applied to codebase comprehension, that gate works as a self-check rather than a gatekeeping step, and the same research found that groups skipping this check had markedly higher failure rates on maintenance tasks that came later.

What code tours offer as a structured alternative

Code tours, sequential walkthroughs that link explanation to specific steps through a codebase, offer a legitimate way to accelerate Phase 1 orientation when an LLM generates them. Balfroid and colleagues studied this directly in a 2026 paper, building a pipeline that generated and evaluated code tours from real, reproducible bugs and running a study with 26 developers of varying backgrounds. The study produced 26 code tours authored from real Java bugs mined from 2025 GitHub commits, with each tour independently judged by two different LLMs, yielding 52 evaluated configurations, and developers thought aloud as they worked through each one. The resulting picture is one of a genuinely useful orientation aid that still carries real trust and quality problems, the kind that make a generated tour a reasonable place to start rather than a substitute for the investigation that follows. The practical upshot for a developer is to treat an LLM-generated tour as what Phase 1 calls for, a scaffold for orientation, and then run the Phase 2 and Phase 3 workflow against it to confirm what the tour got right and fill in what it missed or got wrong.

Tooling choices and structural context

The tool used to feed code into a model determines, in large part, what kind of context the model is actually working with when it answers a question. Many tools built for code search and retrieval are tuned to find text that resembles the query, which is a different task from finding code that is architecturally related to it. A function can be semantically similar to another, sharing vocabulary and structure, without either one calling, depending on, or otherwise interacting with the other, and a tool that only measures textual similarity will hand the model that irrelevant match with just as much confidence as a genuinely connected piece of code. The gap between semantic similarity and architectural relationship is where most tools built for this purpose fall down, because a developer following the three-phase workflow needs a tool that can surface a module's actual dependencies and callers, not merely text that reads alike. Matching the tool to the phase matters as a result: an orientation pass benefits from a tool that can summarize directory structure and entry points cleanly, while targeted investigation at the function level needs a tool that can trace real call paths and data dependencies rather than one that only ranks files by how closely their wording matches the question asked of them.