Reading an unfamiliar codebase with an LLM (a 4-step process)

You've inherited a codebase. Maybe it's a new job, maybe you're on-call for a service you've never touched, maybe it's an open-source project you want to contribute to. Reading code by hand from scratch takes days. With an LLM, structured right, it takes hours.

This post is the 4-step process that works.

The wrong way (don't do this)

The most common AI codebase prompt:

"Explain this codebase to me."

What happens: the LLM produces a generic essay. "This is a web application using TypeScript. There are folders for components, utilities, and tests." Useless. You learned nothing actionable.

The reason it fails: too broad. The LLM tries to summarize everything and lands on platitudes.

The 4-step process

The right approach is structured progression — start abstract, end concrete.

Step 1: Surface map (15 minutes)

Goal: know where things live without yet knowing what they do.

Prompt:

Read the top-level directory structure of this codebase. For each top-level folder, give me one sentence on what's in it. Cite specific files when you reference them. List the build/test commands you can find from package.json/Makefile/Cargo.toml/etc.

Output you want:

src/auth/        — Authentication module. CookieAuth.ts is legacy; JwtAuth.ts is new.
src/users/       — User management. CRUD endpoints in users-controller.ts.
src/lib/         — Shared utilities. Notably error-handling.ts and tracing.ts.
tests/           — Jest tests, mirrors src/.
docs/            — Architecture decision records (ADRs).

Build: npm run build
Test: npm test
Dev: npm run dev (uses nodemon)

This is the surface map. You don't yet know how anything works, but you know where it is.

Step 2: Hot files (15 minutes)

Goal: identify the 5-10 files where most of the action lives.

Prompt:

Based on the structure, what are the 5-10 files in this codebase that I should read first to understand how it works? Rank by importance. For each, give 2-3 lines on what it does. Prefer real entry points, controllers, and core domain models over test files or config.

Output:

1. src/server.ts — Express app initialization, middleware chain.
2. src/auth/JwtAuth.ts — Token generation/validation. The new auth path.
3. src/users/users-service.ts — User CRUD logic, calls users-repo.ts for persistence.
4. src/lib/error-handling.ts — Centralized error → HTTP response mapping.
5. src/lib/tracing.ts — OpenTelemetry setup, applied as middleware.
6. ...

This is your reading list. 5-10 files in priority order.

In your file manager, open these files in tabs (mq-dir's per-tab navigation makes this easy).

Step 3: Cross-cutting concerns (30 minutes)

Goal: understand the patterns that recur across files — how this codebase does things.

Prompt:

Looking at the hot files, what are the recurring patterns in this codebase? Specifically:

1. How is data persisted? (DB, ORM, query builder, raw SQL?)
2. How is the request lifecycle structured? (Middleware order, error path, response shape?)
3. What's the error-handling strategy?
4. How are tests organized?
5. What conventions does the team follow that aren't explicit?

Cite specific files and line ranges.

Output:

1. Persistence: Postgres via knex query builder. All queries go through repo files
   in src/users/users-repo.ts, src/auth/auth-repo.ts. No raw SQL in services.

2. Request lifecycle: Express middleware in this order:
   a. tracing (lib/tracing.ts:42)
   b. auth (auth/middleware.ts:15)
   c. controller-specific
   d. error handler (lib/error-handling.ts:28)

3. Error handling: AppError class in lib/error-handling.ts. Throw AppError variants
   from services; the global handler maps to HTTP. Don't throw raw Error.

4. Tests: per-file (users-service.test.ts beside users-service.ts). Jest with custom
   db setup in test/setup-integration.ts.

5. Implicit convention: services don't await DB calls inline; they use Promise.all
   for parallelism even when only one query is in flight (preparing for future
   parallel fetches).

Now you know the grammar of the codebase, not just the vocabulary.

Step 4: Specific dive (per-task)

Goal: when you're ready to actually do work, drill into the specific area.

Prompt:

I need to add a new endpoint POST /api/users/:id/avatar that uploads an avatar image. Walk me through the files I'd touch, in order, following this codebase's conventions.

Output:

1. src/users/users-controller.ts — add the route + handler.
2. src/users/users-service.ts — add uploadAvatar method.
3. src/users/users-repo.ts — add updateAvatarUrl query.
4. tests/users/users-service.test.ts — add unit tests.
5. tests/integration/users.integration.test.ts — add integration test.

Conventions to follow:
- File upload: use the existing multer setup at lib/upload.ts:12.
- Validation: Zod schema at users-schemas.ts (add UploadAvatarSchema).
- Storage: existing s3 client at lib/storage.ts:45.
- Error handling: throw AppError.NotFound if user not found; the global handler maps.

Now you have a concrete plan grounded in the codebase's actual conventions, not generic best practices.

File-manager setup for this workflow

mq-dir's quad-pane setup is naturally suited:

• Pane 1: top-level directory listing of the codebase (for navigation overview).
• Pane 2: the "hot files" pane — the 5-10 files from Step 2 as tabs.
• Pane 3: notes pane — your notes.md capturing what you learn from the LLM.
• Pane 4: cmux session running the LLM (Claude Code or similar).

In one screen you see the structure, the key files, your evolving notes, and the agent's responses. No alt-tabbing.

Anti-patterns

Asking "explain this code"

Too broad. Always ask for specific extraction (architecture, patterns, hot files).

Trusting without spot-check

The LLM can hallucinate file references. Open the cited files yourself and verify the first 3-5 claims. Calibration converges fast.

Reading the docs first

Counterintuitively, docs can mislead — they're often outdated. Read the code first; consult docs as a complement, not a primary source.

Diving into Step 4 without Steps 1-3

Skipping the abstract steps means the LLM doesn't have the codebase context for Step 4. It'll give generic advice, not codebase-specific.

Treating the LLM as omniscient

It only knows what's in the files. If the codebase has external dependencies you haven't shown it, its model is incomplete. Make sure you've put the relevant files in scope.

What this gives you

After 90 minutes:

• You can navigate the codebase without getting lost.
• You know the canonical patterns — how to add a feature in this codebase's style.
• You have a notes.md you can refer back to.
• You're ready to make changes confidently.

By hand, this would take 1-2 days of reading. With LLM, ~90 minutes for a medium-size codebase.

Where this is most useful

• New job onboarding: replace the typical "shadow a senior dev for a week" with a faster self-paced approach.
• On-call for unfamiliar services: ramp up before incidents.
• Open-source contribution: understand a project before your first PR.
• Acquisition due diligence: read an acquired codebase fast.

Variations

Large monorepos (500k+ lines)

Step 1 expands. Have the LLM produce surface maps for each significant subsystem. Treat each as a mini-codebase.

Microservices

Step 1 produces a service catalog (each service's purpose). Steps 2-4 apply per service.

Documentation-heavy codebases

Steps 1-3 still come from code. Use docs as Step 5 for "the team's stated intentions vs. the code's actual behavior" comparison.

Legacy codebases without tests

Steps 1-3 are critical (you have no other source of truth). Step 4's confidence comes from extra spot-checking.

Verdict

Reading an unfamiliar codebase is dramatically faster with an LLM if you progress structured (surface → hot files → patterns → specific) rather than generic ("explain this"). 90 minutes gets you a working mental model on a medium codebase.

The file-manager setup matters: hot files in tabs, notes pane visible, agent in cmux. mq-dir's quad-pane is suited for this; Forklift or Marta dual-pane works too.

This is one of the highest-leverage AI workflows. Worth practicing on a codebase you already know — you'll see the LLM's accuracy, calibrate trust, and have the muscle memory ready when you genuinely need it.