Get oriented in a new codebase
Ask Claude Code to map an unfamiliar repository: its architecture, key directories, how the parts connect, and where to start for your task.
Task: Get oriented in a new codebase · Other tasks
Fill in the details
One sentence is enough. Claude uses it to decide which parts of the project deserve the most detail.
Optional. Name a directory, service or feature if you already know where your work will happen.
Copy your prompt
This site doesn't run Claude or show model output. Results depend on your input and the model you use.
You've edited the prompt, so changes to the fields aren't applied.
Replace what you've entered for this task with the example? This can't be undone.
What you type is kept in this tab's session storage so a reload doesn't lose it. Use "Clear this task" to remove it. Browsers can restore session data when they reopen tabs, so closing a tab isn't a guaranteed way to erase it.
When to use this template
- You have just joined a project or opened a repository you have never worked in, and you need a mental map before you change anything.
- You know what you need to build but not where it belongs, and you want Claude to point at the files you will most likely touch.
- You are about to review or plan work in an area you have not seen in months and want a quick refresher on how it fits together.
When not to use it
- You already know the codebase and need one specific answer, such as where a setting is read. Ask that question directly; a full overview is slower.
- The repository is very large or a monorepo. Point the focus field at one service or package, or start Claude Code in that folder, so the overview does not try to cover everything.
- You are not using Claude Code or another tool that can read your files. In a plain chat, Claude cannot see the repository and would have to guess.
Why this structure
- The prompt describes what you want to know and deliberately names no files. Claude Code explores the project on its own, so you get its reading of the whole repository instead of only the files you happened to mention.
- The required goal line turns a generic tour into a targeted one. Step 5 then asks where to start for that goal, which is usually the part you act on first.
- The six numbered sections fix the shape of the answer, from the big picture down to conventions and vocabulary, so the overview is easy to scan and compare across projects.
- The read-only line keeps the first session safe. Exploring a new codebase should not leave edits behind that you then have to find and undo.
- Asking Claude to mark what it inferred and to list open questions separates facts read from the code from educated guesses, which matters most in a project you cannot yet judge yourself.
Example input (fictional)
- What you need to do in this codebase
Add a second payment provider next to the existing one
- Areas to look at closely
the checkout service and the payment adapters
- Length
Brief, about one screen
Follow-ups to send Claude
- Trace one real request through the code, from the entry point to the database, and name each file it passes through.
- Add the build, test and style conventions you found to CLAUDE.md, briefly, so later sessions start with them.
- Which parts of this codebase look fragile or under-tested? Show me the evidence for each.
Common mistakes
- Listing the files you think matter. That narrows the exploration to your current guess, which is exactly what you are trying to improve on.
- Skipping the goal. Without it the overview spends as much space on code you will never touch as on the code you need.
- Treating the overview as the final word. Spot-check two or three claims, such as how tests are run, before you rely on it.
Related templates
- Plan a code change before editing: Have Claude Code read the relevant code and propose a file-by-file plan for a multi-file change, without editing anything until you approve it.
- Explain a concept: Get a concept explained at your level, in the format that helps you most, with a quick self-check and the common misconceptions.
- Write a spec by interview: Let Claude Code interview you about a feature, covering implementation, UX, edge cases and tradeoffs, then write a self-contained spec to a file.
Sources
- Claude Code docs: Prompt library (Anthropic documentation)
- Claude Code docs: Common workflows, get a quick codebase overview (Anthropic documentation)
- Claude Code best practices: Explore first, then plan, then code (Anthropic documentation)