# Codebase Onboarding Prompt for Claude Code: Free Copy-Paste

> Free codebase onboarding prompt for Claude Code, Cursor and ChatGPT. It maps an unfamiliar repository, read-only, with a file path behind every claim.

URL: https://www.matthewswong.com/en/toolkit/codebase-onboarding-prompt/

- Author: Matthews Wong (https://www.matthewswong.com/en/about/)
- Updated: 13 November 2026

> **Key takeaway:** Paste this before you ask an agent to change a repository it has never seen. It reads the instructions, manifests, entry points, one feature end to end, the tests and recent commits, then writes one report: what the system does, how to run and test it, the module map, how a request flows, conventions, risky areas and open questions. It edits nothing.

- Type: Prompt
- Works with: Claude Code, Cursor, Claude.ai, ChatGPT
- Download: [codebase-onboarding-prompt.md](https://www.matthewswong.com/downloads/toolkit/codebase-onboarding-prompt/codebase-onboarding-prompt.md) (2.3 KB)
- License: Free to use, change and share, at work too.

## The file

Exactly what the download contains. Read it first, then copy or download.

### codebase-onboarding-prompt.md

```markdown
You are onboarding onto a repository you have never seen. Your job is to map it, not to change it.

Repository: [REPOSITORY PATH OR URL]
What I plan to work on next: [THE AREA OR TASK I CARE ABOUT, OR "NOT DECIDED YET"]

## Rules

- Read-only. Do not create, edit, move or delete any file. Do not install dependencies, run migrations, commit or push.
- You may run commands that only read: listing files, searching, printing git history. Ask before running anything else, including the test suite.
- Report only what you saw in a file, and give the path for every claim. If you inferred something, label it "inferred".
- If you cannot open the repository, say so and ask me to paste the file tree, the README and the manifest files. Do not describe a codebase you have not read.

## Read in this order

1. README, CONTRIBUTING, and any agent instruction files (CLAUDE.md, AGENTS.md, editor rules).
2. Manifests and build files: package.json, pyproject.toml, pom.xml, go.mod, Makefile, Dockerfile, CI workflows.
3. The entry points: where the process starts, and where routes, commands or jobs are registered.
4. One complete feature, followed end to end from the entry point to the data store and back.
5. The tests: where they live, how they are run, what they cover.
6. The last 20 commits: what changes often, and how commits are written.

## Output

Write one Markdown report with these sections, in this order:

1. **What the system does**: three to five sentences on who uses it and for what.
2. **Run and test**: the exact commands to install, run, test, lint and build, each with the file that declares it. Mark any you did not find.
3. **Module map**: a table of the main directories or modules, with one line each on what it owns.
4. **How a request flows**: the feature you traced, as numbered steps with file paths.
5. **Conventions to follow**: naming, folder layout, error handling, test style and commit style, each with one example file.
6. **Risky areas**: code with no tests, very large files, shared state, authentication, migrations, anything a small change could break.
7. **Open questions**: what the code could not tell you, phrased as questions for me.

If I named an area or task above, end with the five files I should read first for it, and why.

Stop after the report. Do not propose a refactor and do not start the task.
```

## Use it when

- You joined a project and need to know how it runs before your first change.
- You inherited a repository with a thin README and nobody left to ask.
- You are about to hand an agent a task in code it has not read yet.
- You review a pull request in a service you do not work in.

## From download to working

1. **Open the agent at the repository root.** Start Claude Code or Cursor in the project folder so the agent can read files itself. In a chat window with no access to the code, attach or paste the file tree, the README and the manifest files; the prompt tells the agent to ask for them.
2. **Fill the two placeholders.** Give the repository path or URL, and the area or task you care about. If you have not decided, write that. Naming a task adds a closing list of the five files to read first.
3. **Check the report against the code.** Every claim carries a file path. Open three of them and run the install and test commands the report lists. A wrong command here is cheaper to find now than in the middle of a task.
4. **Answer the open questions, then keep the report.** The last section lists what the code could not tell the agent. Answer those, then save the corrected report in the repository or move its commands and conventions into your CLAUDE.md, so the next session starts from it.

## Why it is written this way

- **Read-only is the first rule.** The prompt forbids creating, editing or deleting files, installing dependencies, running migrations and committing. An agent that starts fixing things while it explores leaves you with a diff you did not ask for and a map you cannot trust.
- **A fixed reading order.** Instructions, manifests, entry points, one feature end to end, tests, then the last 20 commits. Without an order, an agent reads whatever file it opens first and describes that corner as if it were the whole system.
- **Every claim needs a path.** The agent reports only what it saw in a file and labels anything else as inferred. That is what lets you spot-check the report in a few minutes, and it keeps the agent from describing an architecture the code does not have.
- **One traced request, not a list of folders.** The report follows one feature from the entry point to the data store and back, as numbered steps with file paths. A folder list tells you where files are. A traced request tells you where your change has to go.
- **Risky areas and open questions.** The last two sections name the code a small change could break and the things the code could not answer. They are the parts a README usually leaves out, and the ones you need before you estimate a task.

## What goes wrong

- The report is a map, not proof. An agent can misread a flow, so run the commands it lists and open a few of the paths before you rely on it.
- On a large monorepo one pass stays shallow. Point the repository placeholder at one service or package and run the prompt once per area.
- In a chat window with no file access, the agent only knows what you paste. A report built from a README alone repeats the README.
- It does not run the application or the tests unless you allow it, so a command it lists may be declared in a file and still be broken.

## FAQ

### What prompt should I use to understand a new codebase with AI?

Use one that sets a reading order, asks for a fixed report and forbids edits. This prompt reads instructions, manifests, entry points, one feature end to end, tests and recent commits, then reports what the system does, how to run it, the module map, a traced request, conventions, risky areas and open questions.

### Will this prompt change my files?

It tells the agent not to create, edit, move or delete files, install dependencies, run migrations, commit or push, and to ask before running anything beyond read-only commands. A prompt is an instruction, not a lock, so keep your agent's own approval prompts on if you want a hard guarantee.

### Does it work in ChatGPT or Claude.ai without access to the repository?

Yes, with less depth. The prompt tells the agent to say it cannot open the repository and to ask for the file tree, the README and the manifest files. The report then covers only what you pasted, so add the entry point and one feature's files to get a useful request flow.

### How is this different from asking the agent to explain the project?

An open question gets a summary of the README and the folder names. This prompt asks for commands with the file that declares them, one request traced through real files, and a list of what the code could not answer. Those are the parts you can check and act on.

## Learn what this file packages

- Free lesson: [CLAUDE.md File Example: Global, Project and Local Layers](https://www.matthewswong.com/en/learn/claude-code-tips/claude-md-file-example/)
- Free lesson: [Where to Put Instructions in Claude Code: A Decision Guide](https://www.matthewswong.com/en/learn/claude-code-tips/where-to-put-instructions-claude-code/)
- Free lesson: [Claude Code Tips to Save Tokens: Context, Compaction, Scope](https://www.matthewswong.com/en/learn/claude-code-tips/save-tokens-claude-code/)
- [Onboarding an AI Coding Agent to an Unfamiliar Codebase](https://www.matthewswong.com/en/blog/ai-agent-onboarding-unfamiliar-codebase/)
- [Context Engineering for AI Coding Agents in a Monorepo](https://www.matthewswong.com/en/blog/context-engineering-monorepo-ai-agents/)
- [How Claude Code Works: Agentic Coding Explained](https://www.matthewswong.com/en/blog/how-claude-code-works-agentic-coding/)
- [How to Write a CLAUDE.md That Improves AI Output](https://www.matthewswong.com/en/blog/writing-claude-md-memory-guide/)

[All toolkit items](https://www.matthewswong.com/en/toolkit/)

---

- HTML version: https://www.matthewswong.com/en/toolkit/codebase-onboarding-prompt/
- Bahasa Indonesia: https://www.matthewswong.com/id/toolkit/codebase-onboarding-prompt/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
