AI Prompts to Understand a Codebase

Give it something to read first

If your assistant has no access to the repository, it is not reading your project. It is describing what a project with that name, language, and description usually looks like. That produces answers which are structurally plausible and specifically wrong — the hardest kind to catch.

Four files cover purpose, stack, structure, and starting point in very few tokens:

• The README, for what the project claims to do
• The dependency manifest, for what it is actually built on
• The top-level directory listing, for the shape of the project
• The entry-point file, for where execution begins

Add more as questions get specific. Pasting large amounts of code up front is the most common mistake: it fills the context window with material the assistant has no reason to prioritise, and the answers get vaguer rather than sharper.

1. Orientation

Start wide. You are trying to establish the vocabulary of the project so that your later questions can be precise.

Here are the README, dependency manifest, and top-level directory listing for a project I have not seen before. In plain terms: what does it do, who is it for, what is it built on, and where does execution start? Then list the three files you would read first to understand its core logic, and say why each one.

The last part matters more than the summary. A reading list forces the assistant to commit to a structural claim you can immediately check, and it hands you your next set of files.

2. Trace one real path

This is the highest-value prompt in the sequence. A summary of every folder teaches you very little; one operation followed end to end teaches you the project's conventions, its layering, and where its real complexity sits.

Trace what happens when [a user submits the form / the CLI runs with the default command / a request hits the main endpoint], from entry point to output. Name every file and function involved in order, and tell me where the important decisions are made. If you cannot see a step in the files I gave you, say so instead of filling the gap.

That final sentence changes the quality of the answer noticeably. Without an explicit exit, the natural behaviour is to produce a complete-looking chain and quietly invent the missing links.

3. Conventions before code

Before changing anything, find out what the project expects of you. Most rejected pull requests fail on convention rather than logic.

Based on these files, what are this project's conventions? Cover naming, file organisation, error handling, logging, configuration, and how tests are structured. Point to a specific example of each. Where the codebase is inconsistent, say which pattern appears to be the current one.

The inconsistency question is the useful one. Nearly every codebase of any age contains two or three generations of style, and knowing which is current tells you which parts are actively maintained.

4. Fragility and risk

Ask what would break. The answers tend to point at the same places an experienced reviewer would look first.

Which parts of this codebase would be riskiest to change, and why? Consider: code with no test coverage, functions with many callers, implicit assumptions about input, shared mutable state, and anything doing hand-rolled work that a library usually handles. Rank them and explain the failure mode for each.

Giving the assistant the categories to consider produces far better output than asking whether the code is good. Open quality questions invite flattery; specific failure modes invite analysis.

5. Planning a change

Ask for the plan before any code. It is much cheaper to reject a wrong plan than a wrong implementation.

I want to add [feature] to this project. Before writing any code: list the files you would change and the files you would create, describe the approach in a few sentences, name what could break, and tell me what you would need to see that I have not shown you. Do not write the implementation yet.

The request to name missing context is the part that earns its place. It surfaces the assistant's blind spots while they are still cheap, and the list is usually a good guide to what you should have read yourself.

6. Running it locally

Setup instructions rot faster than any other part of a README, because they are written once by someone whose machine was already configured.

From the manifest, configuration files, CI workflow, and any container files here, work out how to run this project locally: the runtime versions, the install command, required environment variables and services, and the command to start it. Where the README and the CI configuration disagree, trust the CI and tell me where they diverge.

Preferring CI over the README is deliberate. The CI workflow is executable and runs constantly, so it is the one description of the project that cannot silently go stale.

Prompts that waste your time

• “Explain this repository.” Too broad to be checkable. You will get a fluent paragraph that would fit hundreds of projects.
• “Is this code good?” Invites agreement rather than analysis. Ask what would break instead.
• “Find the bugs.” Without runtime context this mostly produces a list of theoretical edge cases, each plausible and unranked.
• “Is this repository safe?” An assistant cannot verify what a dependency does at install time, and a confident yes is worse than no answer at all. That question needs its own checklist.

How to tell when the answer is invented

Fabrications are fluent, so read for structure rather than tone. The reliable signals are specific and easy to check:

• File paths you have not provided. If it cites a file you never gave it and cannot confirm exists, the surrounding explanation is guesswork.
• Suspiciously conventional structure. Descriptions matching the framework's tutorial layout more closely than your actual tree usually mean it fell back on the common case.
• No uncertainty anywhere. A genuine reading of a partial codebase produces hedges. Total confidence across an entire unfamiliar project is itself the warning.
• Answers that do not change when the question narrows. Ask for the line number. Invented claims tend to dissolve or shift under that pressure.

The cheapest habit is to ask for file paths and line references throughout, which makes verification a five-second check rather than a judgement call.

When the repository is too big for the context window

Large projects will not fit, and stuffing the window degrades the answers rather than improving them. Work in layers instead: establish the map first from the README, manifest, and directory listing, then load only the subsystem you actually care about.

Ask the assistant which files it needs to answer a specific question and provide those, rather than deciding in advance. It is reasonably good at naming what it is missing, and it keeps each session narrow enough that the answers stay concrete.

Common questions

These prompts work best once you already know roughly what you are looking at. If the project is completely unfamiliar, start with the reading order for an unfamiliar repository and come back to the assistant with better questions.

Get a briefing and prompt set for any public repo