# 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.

Paste into: **Claude Code**, started in your project folder

## Prompt template

How the builder on the page fills in this template, so you can do the same:

- `{{key}}` becomes the text entered for that field, exactly as typed. Empty text, or text that is only whitespace (spaces, tabs or line breaks), counts as empty: a required field then becomes `[fill in: <label>]` with its label, and an optional field becomes nothing.
- For a choice field, `{{key}}` becomes the text of the chosen option, or of the default when none is chosen.
- Text between `{{#key}}` and `{{/key}}` stays only when that field is not empty; a choice field always counts as filled. The markers themselves are removed, and a marker that stands alone on its line takes its line break with it.
- Each value is inserted once, as it is: `{{…}}` inside a value stays as typed.

```text
Give me an overview of this codebase: its architecture, the key directories, and how the pieces connect.

My goal: {{goal}}
{{#focus}}
Look closely at: {{focus}}
{{/focus}}
Length: {{depth}}

Explore the project yourself; I have not named files on purpose. Only read. Do not change, create or delete any files.

Structure the overview like this:
1. What the project does and its main parts, in a few sentences.
2. The key directories and entry points, one line each.
3. How a typical request or job moves through the code, from entry point to result.
4. Conventions to follow: naming, error handling, and how tests are organized and run.
5. Where to start for my goal: the files I will most likely change, and anything risky nearby.
6. Project terms I am likely to meet, with a one-line meaning each.

Mark anything you inferred rather than read in the code. If something is unclear, list it as an open question instead of guessing.
```

## Fields

- `{{goal}}` (required): What you need to do in this codebase. One sentence is enough. Claude uses it to decide which parts of the project deserve the most detail.
- `{{focus}}`: Areas to look at closely. Optional. Name a directory, service or feature if you already know where your work will happen.
- `{{depth}}`: Length. Choose one:
  - Brief, about one screen (default)
  - Detailed, a full walkthrough with file paths

This site doesn't run Claude or show model output. Results depend on your input and the model you use.

## 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](https://awesomeclaudeprompts.com/prompts/plan-code-change/): 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](https://awesomeclaudeprompts.com/prompts/explain-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](https://awesomeclaudeprompts.com/prompts/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](https://code.claude.com/docs/en/prompt-library) (Anthropic documentation)
- [Claude Code docs: Common workflows, get a quick codebase overview](https://code.claude.com/docs/en/common-workflows#get-a-quick-codebase-overview) (Anthropic documentation)
- [Claude Code best practices: Explore first, then plan, then code](https://code.claude.com/docs/en/best-practices#explore-first-then-plan-then-code) (Anthropic documentation)

---

Awesome Claude Prompts is an independent project. It is not affiliated with, endorsed by, or sponsored by Anthropic. Claude is a trademark of Anthropic, PBC.