Codebase Onboarding Prompt
A read-only prompt that maps an unfamiliar repository: what it does, how to run it, how a request flows, what is risky.
- Claude Code
- Cursor
- Claude.ai
1 file2.3 KB.md
A planning prompt that covers business, domain, tech design and steps, then lists the decisions it needs from you.
By Matthews WongUpdated
Key takeaway
Paste this before a non-trivial change. The agent reads the code the change touches, then plans it from four points of view: business, domain, tech design verified in the real code, and numbered steps with a check for each. It lists every assumption and every decision that is yours, and it writes no code until you reply approved.
Exactly what the download contains. Read it first, then copy or download.
Plan this change with me before any code is written. Do not create or edit files until I reply "approved".
The change: [WHAT I WANT BUILT OR CHANGED]
Who it is for: [THE USERS, OR THE TEAM THAT ASKED FOR IT]
Constraints: [DEADLINE, STACK, THINGS THAT MUST NOT CHANGE, OR "NONE"]
## First, read
Read the code this change touches: the files, their callers, their tests, and one existing feature of the same kind so you can follow its patterns. Read any project instruction file (CLAUDE.md, AGENTS.md, README). Name the files you read.
## Then write the plan from four points of view
Keep each one short. Write only what this task needs.
1. **Business.** Who the users are, the journey they take, what they need at each step, and the screens or outputs they expect. End with acceptance criteria I can check.
2. **Domain.** How this domain works in general, independent of this system: the usual process, roles and terms. For a warehouse that is goods receipt, putaway, picking, packing and goods issue. Mark anything you are unsure about.
3. **Tech design.** The components, data and interfaces this change adds or alters, and how it fits the code that exists. Verify every claim in the real code and cite the file. Name the one alternative you rejected, and why.
4. **Instructions.** Numbered steps. Each step says what to do, where (file path or tool), and how to verify it: the command to run and the result to expect. Order them so each step can be tested and committed on its own.
## Then list what you need from me
- **Assumptions:** every assumption you made, numbered, each with what changes if it is wrong.
- **Decisions:** every decision that is mine to make, each with the options and the one you recommend.
- **Out of scope:** what this plan deliberately leaves out.
## Rules
- When a view is missing and the code cannot answer it, do not guess. Ask whether I have that context or want you to draft it.
- Do not invent requirements, business rules, table names or APIs. If you did not read it, write "not verified".
- Plan only what was asked. No speculative features.
- No code in this reply, beyond a short signature or schema sketch where it makes the design clear.
Stop after the plan and wait. Once I approve, work one step at a time, run each step's check, show the real output, and tell me as soon as the work contradicts the plan.
Write the change you want, who it is for, and the constraints: a deadline, the stack, or things that must not change. Paste the ticket text if you have one. Write none where there is no constraint.
The plan starts by naming the files the agent read. If the list misses the module you know is involved, say so before you read further. A plan built on the wrong files is wrong in every section.
Go through the numbered assumptions and correct the wrong ones. Pick an option for each decision. This list is the main output: every item is something the agent would otherwise have decided silently.
Reply approved once the plan is right. The agent then works through the numbered steps, runs each step's check and shows the real output. It is told to speak up as soon as the work contradicts the plan.
Business, domain, tech design and instructions. Most plans an agent writes are only the last two. Without the first two it designs a clean solution to a problem nobody has. The prompt asks for only what the task needs, so the plan stays readable.
It asks how the domain works in general: the usual process, roles and terms. A feature that ignores how goods receipt or an approval chain really works compiles, passes its tests and is still rejected by the people who use it.
Every design claim cites a file, and anything unread is marked not verified. This is the guard against a plan that calls a function, table or endpoint the project does not have.
A step says what to do, where, and which command proves it worked. Steps are ordered so each can be tested and committed alone, which keeps a failure small and easy to locate.
When a view is missing and the code cannot answer it, the agent asks whether you have that context or want it drafted. Assumptions, decisions and out of scope are listed apart, so nothing is settled without you seeing it.
Short answers before you download it.
Free lessons and articles on this site that explain the ideas behind it.
A read-only prompt that maps an unfamiliar repository: what it does, how to run it, how a request flows, what is risky.
1 file2.3 KB.md
A debugging prompt that makes the agent reproduce the bug and prove the cause before it touches any code.
1 file2.3 KB.md
A review prompt that reports bugs with file, line, a failure scenario, severity and a fix, and skips style nitpicks.
1 file2.3 KB.md