18 Claude Code Prompts for Planning, Debugging and Code Review

I'm new to this repository and need a working mental model of it before I change anything. Explore the codebase and explain it to me.

Read the actual files rather than inferring from names: the README, package or build manifests, config, entry points, and a representative sample of the core modules and tests. If something is still unclear after reading, say so instead of filling the gap.

Give me:
1. What this project does, in two or three sentences.
2. Stack: language, framework, package manager, database, notable libraries.
3. How to run it: install, dev server, tests, build. Quote the exact commands from the repo.
4. Architecture map: the 5 to 10 directories that matter, one line each, and how a typical request or job flows through them from entry point to storage.
5. Conventions to follow: naming, error handling, where tests live, how config and secrets are loaded. Point to one exemplary file for each.
6. Risky or fragile areas: complex code, missing tests, TODOs, surprising coupling.
7. Open questions you couldn't answer from the code.

This is read-only: leave every file unchanged. Keep it under 600 words and cite a file path for every claim.

The area I'll be working on: [AREA OR FEATURE, OR "GENERAL OVERVIEW"]

I want to [DESCRIBE THE CHANGE]. Plan it before writing any code.

1. Explore first. Open the files involved and trace how the relevant code works today. Base the plan only on code you have actually opened.
2. Restate the goal in one sentence and list your assumptions. If a requirement is ambiguous, ask me up to 3 questions now rather than picking an interpretation silently.
3. Propose a numbered, step-by-step plan. For each step give: the files to create or edit, what changes in each, and how we'll verify that step (a test, a command, or a manual check).
4. List what you will deliberately leave unchanged, and the risks: migrations, breaking API changes, performance, security.
5. If there's more than one reasonable approach, show the top two with their trade-offs and recommend one.

Aim for the smallest change that fully solves the goal. Stop after presenting the plan and wait for my approval before editing any file.

<task>
Implement [FEATURE] so that [WHO] can [OUTCOME].
</task>

<done_when>
- [OBSERVABLE CRITERION, E.G. POST /INVITES RETURNS 201 AND SENDS EXACTLY ONE EMAIL]
- [SECOND CRITERION]
- [AN ERROR OR EMPTY CASE, E.G. INVITING AN EXISTING MEMBER RETURNS 409]
</done_when>

<constraints>
- Follow this repo's existing patterns. Before writing, find the closest existing feature and model yours on it.
- Keep scope to the done criteria. If you spot unrelated problems, list them at the end and leave them alone.
- Ask me before adding any new dependency.
</constraints>

Work in this order: read the relevant code, write or update a test for each done criterion, implement, then run the test suite, linter and type checker and fix anything you broke.

When finished, report: files changed with a one-line reason each, the commands you ran and their results, any done criterion you couldn't meet and why, and follow-ups you noticed. Call it done only when every check you ran passes.

Before writing any code for this task, walk down this ladder and stop at the first rung that works:

1. Does this need to exist at all? Could a config change, deleting code, or doing nothing solve it?
2. Does the language's standard library already do it?
3. Does the framework or platform have a built-in feature for it?
4. Does a dependency we already have handle it? Check the manifest before proposing anything new.
5. Can it be one line, or a few lines inside an existing function?
6. Only then write new code: as little as possible, following the patterns already in this file.

Before showing the change, tell me in one or two sentences which rung you stopped at and why.

For the change itself: add new files, classes, interfaces or config options only when the task can't be done without them. Build for today's requirement, not imagined future ones. Leave neighbouring code as it is. Small and boring beats clever, because every extra line is something I have to review and maintain.

The task: [DESCRIBE THE TASK]

Fix this bug.

<error>
[PASTE THE ERROR MESSAGE AND FULL STACK TRACE]
</error>

<context>
How to trigger it: [STEPS, REQUEST OR COMMAND]
Expected: [WHAT SHOULD HAPPEN]
When it started, if known: [E.G. AFTER THE LAST DEPLOY, OR UNKNOWN]
</context>

Work through it in this order:
1. Reproduce it. Run the failing path, or write the smallest script or test that triggers it. If you can't reproduce it, stop and tell me what you tried.
2. Find the root cause. Trace back from the top stack frame to where the bad value or state was first introduced, and explain why it happens. The line that crashes is often not the line that's wrong.
3. Write a test that fails because of this bug, and show me it fails for the right reason.
4. Make the smallest fix that makes that test pass. Keep unrelated cleanup out of this change.
5. Run the full test suite to confirm nothing else broke.
6. Search for the same pattern elsewhere in the codebase and list any other places it could occur, without fixing them yet.

Finish with: the root cause in one sentence, the fix, and the test results.

Review my changes before I push. Look at the commits not yet on the upstream branch plus any uncommitted work (git diff @{upstream} and git status), and read the surrounding code for every changed hunk, not just the changed lines.

Check for:
1. Behaviour changes: anything that now works differently for users or callers, intended or not.
2. Contract breaks: changed function signatures, API request or response shapes, database schemas, events, config keys, CLI flags. Find the callers and say whether they break.
3. Edge cases: empty, null, zero, very large, duplicate, concurrent, unicode, time zones, permission denied.
4. Bugs: wrong conditions, off-by-one, unhandled errors, resource leaks, race conditions.
5. Data and state: migrations, caches, persisted data, and whether existing records still work.
6. Test gaps: changed behaviour with no test that would fail if it regressed.
7. Leftovers: debug logging, commented-out code, secrets, unrelated changes.

Rank each finding as Blocker, Should fix, or Nit, with file:line, a concrete scenario where it goes wrong, and the suggested fix. If you're unsure whether something is a bug, say what would confirm it. Report only; I'll decide what to change. If nothing blocks the push, say so plainly.

Review the pull request on this branch against main.

PR description: [PASTE IT, OR "NONE"]

First understand the intent: run git log main..HEAD and git diff main...HEAD, read the description above, and summarise in two sentences what the PR is trying to do. Flag it if the code does more or less than that.

Then review for:
- Correctness: does it do what it claims, including error and edge cases?
- Design fit: does it follow the existing architecture, or add a second way of doing something the codebase already does?
- Compatibility: public APIs, schemas, migrations, feature flags, and existing data and clients.
- Security: input validation, an authorisation check on every new path, secrets, injection.
- Tests: do they exercise real behaviour, and would they fail if the feature broke?
- Maintainability: naming and structure a teammate can work with.

Open any file you need for context. Output:
1. Verdict: approve, approve with changes, or request changes, with one sentence why.
2. Findings ranked Blocker, Major, Minor, Nit, each with file:line, the problem and a suggested fix.
3. Questions for the author.
4. What's done well, briefly.

Report only; leave the code and the PR untouched.

Write tests for [FILE, FUNCTION OR FEATURE].

1. Read the code under test and its callers so you understand what it's supposed to do, not just what it currently does. Find the existing test setup and match its framework, file naming, fixtures and style.
2. Before writing, list the behaviours you plan to test: main success paths, boundaries, invalid input, error handling, and state changes or side effects. Include cases you suspect will fail.
3. Write the tests. One behaviour per test, with a name that states it, e.g. "returns 404 when the invoice belongs to another account". Assert on outputs and observable effects rather than private implementation details. Mock only true external boundaries such as network, time and randomness.
4. Run them.

If a test fails because the code is wrong, keep the test honest: leave the expected value as the correct behaviour, and leave the code without special cases added just to pass. Stop and report it as a likely bug with the input, expected result and actual result. A test that passes because it was written to match the code proves nothing.

Report the behaviours covered, any bugs found, and gaps you deliberately left.

I want to refactor [CODE OR AREA] so that [GOAL, E.G. THE 900-LINE ORDER SERVICE IS SPLIT BY RESPONSIBILITY]. Behaviour must stay exactly the same.

1. Read the code and everything that calls it, and tell me how well it's covered by tests today. If coverage is thin on the parts you'll touch, first write characterisation tests that pin down current behaviour, quirks included, and get them passing.
2. Propose a sequence of small refactoring steps (rename, extract function, move, inline, and so on). Each step must leave the code building and all tests passing. Show me the list and wait for my OK.
3. Then do one step at a time: make the change, run the tests, type checker and linter, and continue only when everything is green. If a step goes red, revert that step rather than patching forward.
4. Keep behaviour, public interfaces and bugs exactly as they are. If you find a bug, note it and leave it, because mixing fixes into a refactor makes both harder to review.

At the end, summarise each step, the before and after structure, and any bugs or follow-ups you noted.

Do a security review of [THE WHOLE REPO / THE CURRENT DIFF AGAINST MAIN / THIS DIRECTORY].

Start by mapping the attack surface: entry points (HTTP routes, webhooks, CLI arguments, file uploads, queue consumers), where user-controlled data comes in, where it's stored, and where authentication is enforced. Then trace untrusted input from each entry point to where it's used.

Look for:
- Broken access control: missing auth checks, IDs from the request used without checking ownership, data leaking between tenants.
- Injection: SQL, shell commands, templates, path traversal, SSRF, unsafe deserialisation, XSS.
- Secrets in code, logs, client-side bundles or config committed to the repo.
- Auth and sessions: password storage, token expiry, CSRF, cookie flags, rate limits on login and password reset.
- Known-vulnerable dependencies, using the project's audit tool if there is one.
- Sensitive data exposed in logs or error responses.

Report only what you can tie to specific code. For each finding: severity (Critical, High, Medium, Low), file:line, a concrete attack scenario, and the fix. Keep confirmed issues separate from things worth checking that you couldn't verify. This is read-only, so leave files unchanged. Finish with the three fixes to make first.

Create a CLAUDE.md for this repository, or improve the existing one. It's loaded into every session, so every line costs context: keep it under about 100 lines and include only what can't easily be worked out from the code.

Investigate first: read the manifests, scripts, CI config, linter and formatter config, README, and a few representative source and test files. Check that each command exists before listing it.

Include:
1. A one-paragraph project summary.
2. Commands: install, dev, test, run a single test, lint, typecheck, build, migrate. Exact commands, with any required flags or environment variables.
3. Conventions the tooling doesn't enforce: naming, error handling, where tests live, how config and secrets are read. Point to one exemplary file for each.
4. Architecture: the directories that matter, one line each, and the boundaries between them.
5. Gotchas: what a newcomer would get wrong, fragile areas, and things that need discussion before they change.

Move longer detail (API conventions, deployment, design system) into separate docs and reference them with @path/to/file imports rather than inlining it. Write each rule as a direct instruction, with a short reason where the reason isn't obvious.

If a CLAUDE.md already exists, show me what you'd change and why before writing, and remove anything stale or contradicted by the code.

Set up a lessons log for this repo so mistakes from our sessions don't repeat.

1. Create MISTAKES.md in the repo root with a one-line note on its purpose, then entries in this format:

## [YYYY-MM-DD] Short title of the mistake
- What happened: one or two concrete sentences.
- Root cause: why it happened, e.g. assumed the function had no side effects, missed the existing helper.
- Prevention: one imperative rule that would have avoided it, written so it applies next time.

2. Add this single line to CLAUDE.md: "Before starting a task, read MISTAKES.md and follow its prevention rules. When I correct you, or you discover an error you made, add an entry."

3. Add the first entries now: [DESCRIBE WHAT WENT WRONG, OR "REVIEW THIS SESSION AND ADD ANY REAL MISTAKES"].

Keep each entry under 60 words. If a new mistake repeats an existing rule, sharpen that entry instead of adding a duplicate. When a prevention rule has become a permanent project convention, suggest moving it into CLAUDE.md and deleting the entry, so the log stays short enough to actually be read.

Write a commit message for my staged changes. Run git diff --staged and read all of it, plus surrounding code if you need context.

Use the Conventional Commits format:

type(optional scope): summary

body

footer

- type: feat, fix, refactor, perf, test, docs, build, ci, chore or style. Pick the one that matches the main intent.
- summary: imperative mood ("add", not "added"), under 72 characters, no full stop, specific enough to find in git log a year from now.
- body: wrap at 72 characters. Explain why the change was made and how behaviour changes; the diff already shows the how. Mention anything a reviewer could miss, such as migrations, config changes or removed features.
- footer: if a public API or contract breaks, add "BREAKING CHANGE:" followed by what callers must do. Reference [ISSUE OR TICKET ID, IF ANY].

Extra context on why: [OPTIONAL: THE BUG REPORT, REQUEST OR INCIDENT BEHIND THIS CHANGE]

If the staged changes do two unrelated things, tell me and suggest how to split them into separate commits instead. Show the message and wait for my confirmation before committing.

I'm going to continue this work in a fresh session that has none of this context. Write a handoff document that lets it pick up exactly where we are.

Check the real state rather than relying on memory: look at git status and git diff, and re-run the tests so the status you report is current.

Use these sections:
1. Goal: what we're trying to achieve overall, in two sentences.
2. Done: what's finished, and how it was verified.
3. In progress: what's partly done and its exact state.
4. Decisions: choices we made and why, including approaches we tried and rejected, so they don't get retried.
5. Open issues: known bugs, failing tests and unanswered questions, with error messages quoted exactly.
6. Next steps: an ordered list, the first one specific enough to start on immediately.
7. Files touched: paths, with a few words on what changed in each.
8. Commands: how to run, test and reproduce anything relevant.

Be concrete: file paths, function names, exact errors. Leave out the story of how we got here. Save it to [HANDOFF.md OR ANOTHER PATH] and show me the content. I'll start the next session with: "Read [HANDOFF.md] and continue from Next steps."

I have a question about this codebase: [YOUR QUESTION, E.G. WHAT HAPPENS TO A USER'S DATA WHEN THEY DELETE THEIR ACCOUNT?]

Answer only from code you have opened in this session. Before answering:
1. Search for the relevant symbols, routes, config and tests, and open the files. Follow calls across files to the end of the path, including background jobs, event handlers, scheduled tasks and database triggers.
2. If the answer depends on runtime config, environment variables or external services you can't see, say so explicitly.

Then answer in this format:
- Short answer: two or three sentences.
- Evidence: the path through the code as a numbered list, each step with file:line and a short quote of the relevant line.
- Inferred: anything you concluded without reading it directly, labelled as such.
- Not found: what you looked for and couldn't find, and where you looked.

"I don't know" and "the code doesn't show this" are good answers when they're true. I'd much rather see a gap than get a confident answer built on a guess, because I'm going to act on what you tell me.

Upgrade [PACKAGE OR FRAMEWORK] from [CURRENT VERSION] to [TARGET VERSION].

1. Confirm the installed version from the lockfile and find everywhere it's used: imports, config, plugins, and other dependencies that depend on it or pin it.
2. Read the official changelog, release notes and migration guide for every major version between current and target. If you can't access them, tell me and I'll paste them in; breaking changes need a source, not memory.
3. Before changing anything, give me an impact report: each breaking or deprecated change that affects our code, the files it touches, and any peer dependency conflicts. Recommend going straight to the target or stepping through intermediate versions.
4. After I approve: run the test suite to record a baseline, then upgrade, apply the code changes, update the lockfile with the project's package manager, and run tests, type checks, lint and the build.
5. Compare against the baseline. Treat any new failure as caused by the upgrade until proven otherwise.

Report what changed, what you verified, what needs a manual check and how to do it, and how to roll back.

[WHAT IS SLOW, E.G. THE REPORTS PAGE TAKES 6 SECONDS TO LOAD WITH 10,000 ROWS]. Target: [E.G. UNDER 500 MS AT P95]. Find out why and fix it, using measurements rather than intuition.

1. Reproduce and measure. Build a repeatable benchmark or timing for the slow path with realistic data volume, and record the baseline. If you need data or access I haven't given you, ask.
2. Profile. Use the right tool for the stack (a profiler, EXPLAIN on queries, request timing, a bundle analyser) to find where the time actually goes. Show me the evidence: the top costs and their share of the total.
3. Propose fixes for the biggest cost first, with expected impact and trade-offs such as memory, complexity or stale data from caching. If there's more than one sensible option, wait for my pick.
4. Apply one fix at a time, re-run the same benchmark, and keep a change only if it measurably helps. Run the tests to confirm behaviour is unchanged.

Report a before and after table from the same benchmark, what you changed, and what you tried that didn't help. Spend effort only where the profile shows time is going.

This task is too big for one context: [DESCRIBE THE LARGE TASK].

Act as the coordinator and use subagents.

1. Explore in parallel. Launch one read-only explorer subagent per area: [AREAS, E.G. API LAYER, DATABASE, FRONTEND]. Each returns a short summary: the relevant files, how the code works, and risks for this task. Summaries only, not whole files.
2. Plan. From their summaries, break the work into units with clear file ownership, so no two implementers edit the same file. Mark which units depend on others. Show me the plan and wait for approval.
3. Implement. Launch an implementer subagent per unit, in parallel where there are no dependencies. Give each a self-contained brief: goal, files it owns, interfaces it must match, done criteria and the test command to run.
4. Review. When the units are done, launch a reviewer subagent with fresh context to check the combined diff for bugs, mismatches between units and missing tests.
5. Integrate. Fix the review findings, run the full test suite, and report what each subagent did and the final results.

Write every brief as if to a capable colleague who hasn't seen this conversation, because subagents start without it.