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 debugging prompt that makes the agent reproduce the bug and prove the cause before it touches any code.
By Matthews WongUpdated
Key takeaway
Paste this with a bug report and the agent works in a fixed order: reproduce the failure with one repeatable command or test, gather evidence, state the cause with that evidence, make the smallest fix, re-run the same reproduction, and keep it as a regression test. If it cannot reproduce the bug, it stops and asks for what is missing. It does not guess a fix.
Exactly what the download contains. Read it first, then copy or download.
Help me debug this. Do not change any code until you have reproduced the bug and can show what is wrong with evidence.
The bug: [WHAT HAPPENS, AND WHAT SHOULD HAPPEN INSTEAD]
How I trigger it: [STEPS, COMMAND, INPUT OR FAILING TEST, OR "UNKNOWN"]
What I already have: [ERROR MESSAGE, STACK TRACE, LOGS, OR "NOTHING YET"]
## Work in this order
1. **Reproduce.** Trigger the failure yourself with one concrete, repeatable command, input or test. Show me the command and its real output. A failing test is the best reproduction.
2. **Gather evidence.** Read the stack trace, logs, console output or network traffic. If they do not show the cause, add temporary logging or run with debug output. List every temporary line you add.
3. **State the cause.** In two or three sentences: what is wrong, where (file and line), and why it produces this symptom. Quote the evidence that proves it. If two causes fit the evidence, say so and name the check that would tell them apart.
4. **Fix.** Only now, make the smallest change that removes the cause. Do not refactor, rename or tidy nearby code.
5. **Re-run.** Run the exact reproduction from step 1 and show the output. Then run the existing test suite with the project's own command.
6. **Keep it.** Turn the reproduction into a regression test that fails without the fix and passes with it. Remove all temporary logging.
## If you cannot reproduce it
Stop. Do not guess a fix. Tell me what you tried and what happened, then ask for exactly what is missing: the steps, the input data, the logs, the version or the environment.
## Do not
- Do not edit code before step 3 is written down.
- Do not say "this should fix it". Say what you ran and what it printed.
- Do not silence the error: no empty catch blocks, no skipped or deleted tests, no loosened assertions.
- Do not fix other problems you notice. List them at the end.
## Report at the end
- **Reproduction:** the command
- **Cause:** one paragraph, with the evidence
- **Fix:** the files changed, and why
- **Proof:** the output before and after
- **Regression test:** its path and name
- **Noticed but not touched:** a list, or "nothing"
If you cannot run commands here, say so at the start. Then give me one command at a time and wait for the output I paste back before you move to the next step.
Describe what happens and what should happen, how you trigger it, and what you already have: the error message, the stack trace or the logs. Writing unknown is allowed; the agent then has to find the trigger first.
The first thing you should see is a command and its real output showing the failure. If the agent goes straight to an edit, stop it and point at step 1. No reproduction means there is no way to tell whether a fix worked.
The agent states what is wrong, the file and line, and why it produces the symptom, with the evidence quoted. Check that the evidence supports the claim. If two causes fit, it names the check that separates them.
After the fix, the agent re-runs the exact reproduction and the existing test suite, and shows both outputs. The closing report lists the reproduction, cause, fix, proof and the regression test's path.
Review the diff, confirm the temporary logging is gone, and commit the fix and its regression test together. The list of things noticed but not touched becomes your next tickets.
The prompt blocks code changes until the cause is stated with evidence. An agent left alone reads the error, pattern-matches a likely fix and edits. That often changes the symptom and leaves the bug.
A command or a failing test can be run again after the fix, by the agent and by you. Manual steps described in prose cannot, and they drift a little each time someone repeats them.
If the failure does not appear, the agent reports what it tried and asks for the missing steps, data, logs, version or environment. Without this rule, an agent that cannot see the bug still ships a plausible patch.
No empty catch blocks, no skipped or deleted tests, no loosened assertions. Each of these makes the failure disappear from the output while the defect stays in the code.
The test must fail without the fix and pass with it. That is the proof the fix addresses this bug, and it is what stops the same bug from returning unnoticed.
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 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 review prompt that reports bugs with file, line, a failure scenario, severity and a fix, and skips style nitpicks.
1 file2.3 KB.md