On this page
- Why Claude Code prompts differ from chat prompts
- 1. Explore before you change anything
- 2. Plan first, then implement
- 3. Fix a bug from a reproduction
- 4. Refactor with a safety net
- 5. Write tests that test something
- 6. Review a diff like a skeptical colleague
- CLAUDE.md: the system prompt your repo carries around
- Keep your best prompts, version them, and share them
- Mistakes that waste the most time
- Adapting these to your stack
- Next step
The best Claude Code prompts state the goal, point at the files that matter, set one or two hard constraints, and say how to check the work. Everything else is optional. Below are six prompts we reuse for exploring a codebase, planning, fixing bugs, refactoring, writing tests, and reviewing a diff, plus a CLAUDE.md starter that acts as the standing system prompt for your repo.
Copy them as written, replace the [placeholders], and trim anything that doesn't fit your project.
Why Claude Code prompts differ from chat prompts
In a chat window, you paste code and get text back. Claude Code works inside your repo. It reads files, runs commands, edits code, and can run your tests. That changes what a good prompt looks like.
You don't need to paste code. You need to say where to look. You also need to say what counts as done, because an agent that can run commands will keep going until it believes it's finished, and its belief is only as good as your definition.
Three habits matter more than any clever phrasing:
Give it a way to verify. A test command, a type check, a lint run, or a reproduction script. Without one, you are the only check.
Name boundaries. Which directories are off limits, which dependencies it may not add, which public APIs must not change.
Separate thinking from doing. Ask for a plan or an investigation first on anything bigger than a small edit. Reviewing a plan takes a minute. Reviewing a wrong 600-line diff takes much longer.
If you want the general theory behind this, our post on writing goals instead of rulebooks covers why short, goal-first instructions beat long lists of rules. It applies directly here.
1. Explore before you change anything
Use this at the start of a session in an unfamiliar repo, or before touching an area you haven't worked in for months. It stops Claude from guessing at structure and gives you a map you can correct.
I'm about to work on [feature or area, e.g. the invoice export flow]. Don't edit any files yet.
Investigate the repo and report:
1. Which files and modules are involved, with paths.
2. How data moves through them, in 5-8 plain sentences.
3. Existing tests that cover this area, and how to run them.
4. Anything surprising: dead code, duplicated logic, unusual patterns, TODOs.
If you're unsure about something, say so and name the file you'd need to read to confirm. Do not guess.The last line earns its place. Without it, Claude tends to fill gaps with plausible-sounding structure. With it, you get an honest list of unknowns, which is more useful than a confident summary.
2. Plan first, then implement
For any change touching more than two or three files, ask for a plan and approve it. Claude Code has a plan mode for exactly this, but the prompt matters more than the mode.
Task: [describe the change in 1-3 sentences]. Before writing code, produce a plan: - Files you expect to change and why. - The order of changes, in small steps that each leave the project in a working state. - Risks and anything that could break existing behaviour. - How you will verify each step: [test command, e.g. npm test -- invoices]. - Questions you need answered before starting. Constraints: [e.g. no new dependencies; do not change the public API in /src/api; keep the existing code style]. Stop after the plan and wait for my approval.
The questions line is where the value is. Half the time Claude asks something you hadn't considered, like whether old exports should keep working. Answer, then tell it to proceed one step at a time.
3. Fix a bug from a reproduction
Vague bug prompts like 'the export is broken' send Claude on a hunt. Give it the symptom, the expected behaviour, and a way to see the failure.
There's a bug in [area]. Actual behaviour: [what happens, including the exact error message or wrong output]. Expected behaviour: [what should happen]. How to reproduce: [command, test name, or steps]. Do this in order: 1. Reproduce the failure and show me the output. 2. Find the root cause. Tell me what it is before you fix it, and name the file and line. 3. Write a failing test that captures the bug, if one doesn't exist. 4. Make the smallest fix that passes the test. 5. Run [full test command] and report anything else that fails. Do not refactor unrelated code or change formatting outside the lines you need to touch.
Step 3 is the one people skip and then regret. A regression test turns a one-off fix into something that stays fixed. The final line keeps the diff small enough to read.
4. Refactor with a safety net
Refactors go wrong when behaviour changes quietly. Anchor the work to tests that already pass.
Refactor [module or function] to [goal, e.g. remove the duplicated validation and split it into small pure functions]. Rules: - Behaviour must not change. Existing tests must pass before and after. - First run [test command] and confirm the baseline is green. If it isn't, stop and tell me. - Work in small commits-worth of steps. After each step, run the tests. - If coverage of this code is thin, propose characterization tests first and wait for my go-ahead. - Do not rename public exports or touch files outside [directory]. When done, summarise what moved where, in a short list I can check against the diff.
If you're working with a model that tends to over-edit, tighten the scope line. Name the directory. Naming it beats a general instruction to be careful.
5. Write tests that test something
Generated tests often assert what the code already does, bugs included. Ask for tests based on intended behaviour.
Write tests for [function, module or file]. Base the cases on what the code is meant to do, using the docs, types, naming and call sites as evidence, not just on what the current implementation returns. If the implementation seems to contradict the intent, flag it instead of encoding the bug in a test. Cover: the normal path, boundary values, empty and invalid input, and one case for each error the code can raise. Match the style of the existing tests in [path to a test file]. Use [test framework]. Run the tests and show me the result. Do not modify the source file.
6. Review a diff like a skeptical colleague
Claude is a decent first-pass reviewer when you tell it what to look for. Without direction, you get praise and style nitpicks.
Review the changes on this branch compared to [main branch name]. Use git diff.
Look for, in this priority order:
1. Bugs and logic errors, including edge cases and off-by-one mistakes.
2. Security problems: unvalidated input, secrets, unsafe queries, missing auth checks.
3. Behaviour changes that tests don't cover.
4. Anything that will be hard to maintain.
For each issue give the file and line, what's wrong, and a suggested fix. Separate must-fix from nice-to-have. Skip pure style comments unless they hide a real problem. If you find nothing serious, say so plainly instead of inventing issues.The 'say so plainly' line matters. Reviewers, human or not, feel pressure to produce findings. Permission to find nothing keeps the list honest.
CLAUDE.md: the system prompt your repo carries around
People searching for Claude Code system prompts are usually after this. You can't rewrite the underlying system prompt, but Claude Code reads a CLAUDE.md file from your project and treats it as standing context for every session. It's the right place for things you'd otherwise repeat in each prompt.
Keep it short. Every line costs context on every run, and a bloated file gets ignored in practice. Put in commands, conventions, and gotchas, not a tutorial.
# Project: [name] ## Commands - Install: [command] - Run tests: [command] - Run a single test: [command] - Lint and type check: [command] ## Structure - [directory]: [what lives there] - [directory]: [what lives there] ## Conventions - [language/style rule that isn't enforced by the linter] - [naming or error-handling convention] - Prefer small, pure functions. Don't add dependencies without asking. ## Gotchas - [thing that has bitten people, e.g. the staging DB resets nightly] - Never edit files in [generated directory]; they are built from [source]. ## Done means - Tests pass, lint is clean, and the diff contains only what the task needed.
The 'Done means' section does quiet work. It gives Claude a default definition of finished, so you don't have to restate it.
One rule of thumb for what belongs where: if it's true for every task in the repo, it goes in CLAUDE.md. If it's true for this task only, it goes in the prompt. Our post on system prompts versus user prompts goes through the same split in more detail.
Keep your best prompts, version them, and share them
A good prompt that lives in one terminal's history is lost the next time you clear it. This is where a prompt library earns its place.
Here is the workflow we use:
Run a prompt on a real task. Note what Claude got wrong: it edited too widely, skipped tests, or asked nothing.
Tighten the prompt with one change aimed at that failure. Don't rewrite the whole thing.
Save it to your PromptPal library with a clear name like 'Bug fix from repro', and keep the
[placeholders]in place so it's reusable.Let the version history record each change, so when a tweak makes results worse, you can see what you changed and go back. That's what prompt version control is for.
Put the set in a shared workspace so the team starts from the same review prompt and the same bug-fix routine.
If your prompts and project context should reach agents at runtime rather than being pasted by hand, delivering governed prompts to agents through MCP is the route for that. For choosing between CLAUDE.md-style files, skills and MCP, see AGENTS.md, Skills or MCP?.
Mistakes that waste the most time
Pasting a wall of rules. Fifty instructions get partly followed. Five clear constraints get followed. Move permanent ones to CLAUDE.md and keep the prompt about the task.
Asking for everything in one go. 'Add the feature, write tests, update docs and refactor the helpers' produces a diff nobody wants to review. Split it. One prompt, one reviewable change.
Skipping verification. If the prompt doesn't include a command that proves the work, the result is a claim, not a fact. Always include the test or lint command.
Letting the session run long. Long sessions pile up context, and early instructions get less attention. When Claude starts forgetting constraints, start a fresh session with the plan and CLAUDE.md rather than repeating yourself louder.
Not reading the plan. The plan prompt only helps if you read the plan. Spend the two minutes. It's the cheapest review you'll do all day.
Adapting these to your stack
The prompts above are deliberately framework-neutral. Adjust three things for your project. First, the verify command: a Python repo might use pytest and mypy, a TypeScript one might use a test runner and tsc. Second, the boundaries: list the directories that are generated, vendored, or owned by another team. Third, the review priorities: a payments service should rank security first; an internal script can rank maintainability higher.
How strictly Claude follows these instructions varies by model version and by how much else is in the session, so treat your first few runs as tests of the prompt, not of the model. If a prompt fails twice in the same way, the fix is almost always a clearer constraint or a missing verification step, not a longer prompt.
Next step
Browse the public prompt library for coding and developer templates, save the ones you want to a collection in PromptPal, and adapt them to your repo from there.
Stay Updated
Get the latest blog posts and AI prompt engineering tips delivered to your inbox.




