How do you use an AI assistant to understand a large or unfamiliar codebase you just inherited?

Question

Accepted Answer

An AI is great for **orientation** in unfamiliar code — but only if you keep it **grounded in the real files** rather than letting it describe a generic version of what the system probably does. Point it at actual paths and ask it to read before it explains.

## Strategies, from broad to specific

- **Ask for a high-level map and entry points** — "Where does a request start? What are the main modules and how do they relate?" This gives you the lay of the land before you dive in.
- **Trace a single feature end-to-end** — pick one real feature (e.g. "user login") and have the AI follow it from the route, through the controller and service, to the database. Tracing beats abstract overviews.
- **Summarize one module at a time** — "Summarize what `src/billing/` is responsible for," not the whole repo at once.
- **Explain unfamiliar code** — paste a gnarly function and ask what it does and why, line by line.
- **Generate a dependency overview** — what imports what, which modules are central, where the coupling is.

## Keep it grounded

```text
❌ UNGROUNDED: "How does authentication usually work in a Node app?"
   → generic textbook answer; may not match THIS codebase at all

✅ GROUNDED: "Read src/auth/login.js and src/middleware/session.js.
             Trace what happens when POST /login is called, step by step,
             citing the functions involved."
   → the AI must read the actual files → its explanation maps to YOUR system
```

The grounded version forces the AI to base its answer on your code, so you can verify each step against the real files instead of trusting a plausible generality.

## Why it matters

Inheriting a large codebase is mostly a **reading and mapping problem**, and that's exactly where an AI accelerates you — it can summarize a module, trace a flow, or explain a cryptic function in seconds, turning days of cold reading into guided exploration. The risk is that an ungrounded prompt gets you a confident, generic answer that doesn't match the actual code. Anchoring every question to **real file paths** and verifying its trace against those files keeps the AI's speed without inheriting its hallucinations — you build an accurate mental model faster, and you can trust it because you checked it against the source.