One Claude Code Tip a Day: Explain the Codebase with Evidence

This post is part of the “One Claude Code Tip a Day” series — a daily guide to using Claude Code more effectively.

The real failure: a confident tour of the wrong system

The most dangerous explanation of an unfamiliar codebase is the one that sounds complete after five minutes. You ask Claude Code, “How does authentication work here?” It returns a clean story: login form, API route, session cookie, middleware, redirect.

Today’s habit is simple: when using Claude Code to explain an unfamiliar codebase, require evidence.

Start with a read-only evidence brief

Open Claude Code from the repository root, then make the first prompt explicitly read-only:

`I need to understand how authentication works in this repo. Do not edit files. First inspect the project structure, then produce an evidence brief: entry points, main files, data flow, runtime checks, and tests. For every claim, cite the exact file path and function/component name that supports it.`

That prompt changes the task from “summarize the repo” to “build a case.”

Force Claude to separate map from trace

A repo map tells you what is present. A trace tells you what happens.

After the evidence brief, ask:

`Now trace the real login path from the browser form to the persisted session. Ignore test helpers and deprecated files unless they are imported by the active path. Return a numbered flow. Each step must include: file path, symbol name, what data enters, what data exits, and how you know this step is active.`

This is where the session becomes practical. The trace prompt forces a decision: which one is imported by the route? Which one is executed in production? Which one only appears in tests?

When Claude cannot prove a step is active, ask it to say so. Uncertainty is better than a polished lie.

Use shell checks as the lie detector

Explanations improve when they touch the ground. Ask Claude Code to run small checks before you trust the story:

`Use shell commands to verify the import path for the login route. Search for the symbols you named, show the import chain, and run the smallest relevant auth test if one exists. Do not modify files.`

The checks might be as simple as `rg "createSession|validateSession|middleware" apps packages` and `pnpm test auth/session.test.ts`.

I also like this follow-up:

`Compare your explanation against the command output. List any claims that were confirmed, weakened, or disproven.`

That sentence prevents Claude from treating command output as decoration. It must update the explanation.

Inspect the shape of the first answer

A good codebase explanation has a few recognizable properties.

A weak explanation uses architecture words without file-level anchors: “the service layer validates the token,” “middleware handles auth,” “the client stores state globally.” Those may be true, but they are not yet useful. Push back:

`Rewrite the explanation with fewer abstractions. Replace every generic phrase like service layer, middleware, or global state with the exact file and symbol. If you cannot find the symbol, mark the claim as unverified.`

This is not pedantry. It is how you avoid editing the wrong subsystem tomorrow.

Failure modes

The first failure mode is asking too broad a question: “Explain this repo.” Claude will produce a museum tour. Ask about one behavior: login, checkout, background sync, image upload, billing webhook, release build.

The second failure mode is accepting filename-based inference. A file named `useAuth.ts` may be unused. A folder named `new-auth` may be experimental. Always ask how Claude knows a path is active.

The third failure mode is skipping runtime evidence. Static reading is valuable, but logs, tests, route commands, and import searches catch the places where the architecture has drifted.

Second-pass correction

The best explanation often arrives after the first one fails. Suppose Claude says sessions are stored in Redis, but `rg REDIS_URL` only finds a queue worker. Give the contradiction back:

`Your first explanation said auth sessions are stored in Redis, but the search output only shows Redis in queue workers. Re-check the auth path. Correct the explanation, cite the storage mechanism, and list which earlier claims changed.`

This is the same debugging loop you would use with code: hypothesis, evidence, contradiction, correction. Claude Code becomes much more reliable when you make it revise its own model in public.

Rule of thumb

Use Claude Code to explain unfamiliar codebases the way a senior engineer explains a production incident: with file paths, traces, command output, uncertainty, and corrections. If the answer cannot point to evidence, it is not an explanation yet. It is a guess wearing a nice outline.