Produces the orientation doc a new engineer actually needs: the three things that will confuse them, the load-bearing files, and the conventions nobody wrote down.
I am joining this codebase on Monday and my first task is: {{ROLE}}. Write the orientation I wish someone would give me over coffee. STRUCTURE: {{TREE}} KEY FILES: {{ENTRY}} Cover these, in order: 1. **What this system does**, in three sentences, in terms of what a user experiences — not architecture. 2. **The shape of it.** The 4–6 pieces that matter and how a request flows through them. One paragraph, no diagrams-in-text. 3. **Where I'll actually work.** Given my first task, the specific files I'll touch and the order I should read them. 4. **Three things that will confuse me.** Non-obvious conventions, naming that means something different here, places where the code disagrees with itself. Be specific and cite files. 5. **The load-bearing files.** What breaks everything if edited carelessly. 6. **What I should not touch yet**, and why. 7. **Five questions to ask the team**, ones the code cannot answer — history, intent, or plans. Rules: - Mark inference explicitly: write `[inferred]` when reasoning from structure rather than from code you were shown. - Do not summarise files one by one. Synthesise. - Prefer "this is unusual" over "this follows best practice" — the unusual parts are what I need warned about.
Tools for this prompt
Where the input below comes from. The ones marked needed change the output a lot — fallbacks for each are further down.
This prompt is only as good as what you feed it. Web search covers anything public — these are the inputs it can't reach.
Packs the repo into one context-sized file, which beats pasting a file tree by hand.
Don't have it: Ask for a file tree plus two or three key files.
`git log --format='%s' -n 50` shows where the churn is, which sharpens the 'what will confuse me' section.
Don't have it: Ask the user to paste the diff or file directly.
Only tools that web search cannot replace are listed. Anything public — reviews, job ads, papers, salary data — an agent can already fetch, so it is not listed here. No paid placements or affiliate links; if that changes, this line will say so.
A prompt is a skill with the serial numbers filed off. Install it once and your agent reaches for it on its own.
Paste this into ChatGPT, Claude Code, Codex, Cursor, or whatever you use:
Install the explain-this-codebase-to-me skill globally from https://promptsbuddy.com/prompts/explain-this-codebase-to-me/skill.md.claude/skills/explain-this-codebase-to-me/SKILL.md
---
name: explain-this-codebase-to-me
description: "Produces the orientation doc a new engineer actually needs: the three things that will confuse them, the load-bearing files, and the conventions nobody wrote down. Use when the user asks for help with engineering tasks like onboarding, engineering, documentation."
license: CC-BY-4.0
metadata:
source: https://promptsbuddy.com/prompts/explain-this-codebase-to-me
author: "Meghna"
version: "1.5"
---
# Explain this codebase like I start on Monday
Produces the orientation doc a new engineer actually needs: the three things that will confuse them, the load-bearing files, and the conventions nobody wrote down.
## Inputs to collect first
Ask the user for anything below that they have not already given you. Do not
invent values for these.
- `TREE` — Output of `tree -L 3 -I node_modules` or similar. (e.g. app/
api/
(marketing)/
lib/
components/)
- `ENTRY` — Two or three key files, pasted in full. (e.g. app/layout.tsx, lib/db.ts, package.json)
- `ROLE` — What the reader will be doing first. (e.g. Adding a new API route and its tests.)
## Tools this works with
Do not require any of these. If one is unavailable, use the stated fallback and
say which input is missing rather than inventing it.
- **Repomix** — Packs the repo into one context-sized file, which beats pasting a file tree by hand.
- Without it: Ask for a file tree plus two or three key files.
- https://repomix.com/
- **GitHub** — `git log --format='%s' -n 50` shows where the churn is, which sharpens the 'what will confuse me' section. If its MCP server is connected, fetch this yourself.
- Without it: Ask the user to paste the diff or file directly.
- https://github.com/
## Instructions
I am joining this codebase on Monday and my first task is: {{ROLE}}.
Write the orientation I wish someone would give me over coffee.
STRUCTURE:
{{TREE}}
KEY FILES:
{{ENTRY}}
Cover these, in order:
1. **What this system does**, in three sentences, in terms of what a user
experiences — not architecture.
2. **The shape of it.** The 4–6 pieces that matter and how a request flows
through them. One paragraph, no diagrams-in-text.
3. **Where I'll actually work.** Given my first task, the specific files I'll
touch and the order I should read them.
4. **Three things that will confuse me.** Non-obvious conventions, naming that
means something different here, places where the code disagrees with itself.
Be specific and cite files.
5. **The load-bearing files.** What breaks everything if edited carelessly.
6. **What I should not touch yet**, and why.
7. **Five questions to ask the team**, ones the code cannot answer — history,
intent, or plans.
Rules:
- Mark inference explicitly: write `[inferred]` when reasoning from structure
rather than from code you were shown.
- Do not summarise files one by one. Synthesise.
- Prefer "this is unusual" over "this follows best practice" — the unusual parts
are what I need warned about.
## Notes from people who use this
- Section 7 is the highest-value output. Take those five questions to your team lead in week one.
- Run it again after two weeks with your own corrections pasted in. The delta shows you what you actually learned.
- Add `git log --format='%s' -n 50` to the context and the model picks up on where the churn is.
---
Explain this codebase like I start on Monday · by Meghna · v1.5
From PromptsBuddy — https://promptsbuddy.com/prompts/explain-this-codebase-to-me
Licensed CC BY 4.0.
Every prompt is also available at /prompts/explain-this-codebase-to-me/skill.md — see all install options.
Ask a model about a codebase and it will walk the file tree, describing each
directory. That's an index, and you already have one. The value is in the
sentence a teammate says offhand — "ignore everything in legacy/, it's read
only by the billing cron" — and this prompt is built to extract that class of
statement.
Any codebase orientation from partial context is partly guesswork. Requiring
[inferred] tags turns that from a hazard into a map: the tagged claims are
exactly the ones worth verifying first, and the untagged ones you can lean on.
For anything past a few hundred files, feed the tree plus a handful of entry points rather than the whole repository. More context here reliably makes the output worse — the model starts describing instead of synthesising.
Reviews a diff at three altitudes — design, correctness, style — and explains the reasoning behind each note so the author learns something instead of just applying a patch.
Meghna