ChatGPT Prompt to Explain a Codebase

The Scenario

You just joined a project, inherited a repo, or were handed an unfamiliar service. The code runs, but you have no map. Reading every file top to bottom is slow, and asking a teammate to “explain it” is unfair on day one. You need a structured orientation, not a dump of the README.

ChatGPT can act as a patient guide if you feed it the right slices of the codebase. The prompt below asks for a layered explanation: what the project is, how it is organized, the risk areas, and concrete next steps. It is not a replacement for reading the code, but it gives you a reading order.

For comparing good vs bad code asks, see Code vs Architecture Prompts.

How to Feed Code Without Drowning the Model

The quality of the explanation depends as much on what you paste as on the prompt. A common error is dumping the entire repository into one message. Context windows are large but not infinite, and once the model is buried in thousands of lines, its per-file summaries get vague and its risk calls get lazy. The better approach is layered: start with the entry point or main file, read the explanation, then follow the suggested reading order, pasting one or two related files at a time.

Trim before you paste. Remove long auto-generated sections, vendored dependencies, and giant fixture files; they add tokens without adding understanding. Keep function signatures, the import lines, and the control flow. If a file is huge, paste the part you actually care about and say “this is lines 40-120 of auth.py.” Naming the file in your message also helps the model keep track when you spread a single module across multiple turns.

Treat the explanation as a map, not the territory. The model can misread a conditional or invent a function that is not there. Use its output to decide what to read next, then confirm by reading the real code. The goal is to cut your onboarding time, not to replace reading entirely.

The Prompt

You are a senior engineer onboarding me to an unfamiliar codebase. I will paste files or snippets. Explain in layers.

For each file or section I paste, give:
1. PURPOSE: what this file/function is responsible for, in one sentence.
2. KEY ENTRIES: the main functions, classes, or routes and what triggers them.
3. DEPENDENCIES: what it imports or calls, and what depends on it.
4. RISK: anything fragile, surprising, or likely to break (hardcoded values, missing tests, unclear flow).
5. QUESTIONS: what I should read next to understand the system.

After I paste the repo's main files, also give:
- A one-paragraph summary of what the whole system does.
- A suggested reading order (easiest to hardest).
- The top 3 things a new contributor should NOT change without asking.

Context about the project: [language, framework, what it does, your experience level]

Variables You Need to Fill

Keep each paste focused. Pasting 20 files at once clouds the explanation. Feed the entry point first, then follow the reading order it suggests.

Expected Output

For each file you get a tight PURPOSE / KEY ENTRIES / DEPENDENCIES / RISK / QUESTIONS breakdown, then a system summary, a reading order, and a “do not touch” list. Example for a routes file:

routes.py
1. PURPOSE: Exposes HTTP endpoints for subscription changes.
2. KEY ENTRIES: /upgrade (POST), /cancel (POST), guarded by auth middleware.
3. DEPENDENCIES: imports models.Subscription, services.billing; called by the frontend app.
4. RISK: /cancel has no idempotency guard - double-click could double-refund. No test covers the race.
5. QUESTIONS: Read services/billing.py next to see how charges post.

System summary: A small FastAPI service that manages plan upgrades and cancellations against a Stripe-like billing backend.

Reading order: models.py -> routes.py -> services/billing.py -> config.

Do NOT change without asking: auth middleware, the refund path, env-based API keys.

If the RISK section is empty, push it: “What are the silent failure modes here?” Models are optimistic by default and need prodding to find fragility.

Pitfalls to Watch

Even with a good prompt, a few things go wrong. The model is optimistic about code it only half understands, so its RISK section is often thinner than reality. Push it with a direct question like “what are the silent failure modes” to get past the cheerful default. It can also confidently describe functions or imports that do not exist, especially in loosely typed code, so never treat the dependency map as authoritative until you have grepped the repo yourself.

Another trap is context loss across a long session. If you paste ten files over twenty messages, the model may forget an earlier constraint. When the explanation starts contradicting something from two turns ago, open a fresh chat and re-paste just the relevant files with the same prompt. Finally, do not ask it to “explain the whole thing at once” on a large service; you will get a plausible but shallow summary. Smaller, targeted passes produce explanations you can actually trust and act on.

Variation Tips

• Diagram mode: “Describe the call flow as a numbered sequence from request to response.”
• Test gap mode: “List every function above without a test and rank by blast radius.”
• Newbie mode: “Explain like I have never used [framework]; define any jargon.”
• Security pass: “From the files so far, list possible injection, auth, or secret-leak issues.”
• Pair with settings: tune the model via ChatGPT Coding Settings for cleaner explanations.

When you move from understanding to fixing, the workflow in Debug Code with ChatGPT picks up where this leaves off.

Sources & Notes

Prompt template is original to this guide, designed around layered code reading (purpose, entries, dependencies, risk). Tuned for ChatGPT GPT-4o and newer; effective on Claude and Gemini. Tested October 2026. Always verify the model’s claims against the real code, especially RISK and dependency claims, since LLMs can misread or invent details. No single external source; the layering mirrors standard code-review practice.