Plan Before Code Prompt
A planning prompt that covers business, domain, tech design and steps, then lists the decisions it needs from you.
- Claude Code
- Cursor
- Claude.ai
1 file2.3 KB.md
A read-only prompt that maps an unfamiliar repository: what it does, how to run it, how a request flows, what is risky.
By Matthews WongUpdated
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.
Exactly what the download contains. Read it first, then copy or download.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Short answers before you download it.
Free lessons and articles on this site that explain the ideas behind it.
A planning prompt that covers business, domain, tech design and steps, then lists the decisions it needs from you.
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