You ask Claude Code to fix a checkout error. It changes the right file and reports that the tests pass. But the tests never covered the expired coupon that caused the error, so you still don’t know whether the fix works.
A useful prompt gives Claude Code enough information to address that gap: the behavior you expect, the relevant files, any limits on the change, and evidence you can review. For a bug fix, that might mean reproducing the failure before changing the code. For a codebase question, it might mean citing the files and functions behind the answer.
The 25 Claude Code prompts below cover planning, debugging, code review, migrations, and other recurring tasks. Each gives you a starting point to adapt to your repository, with guidance on what to provide and how to assess the result.
TL;DR: Give Claude Code a defined task, relevant repository context, and clear limits on what can change. For code changes, specify tests or other checks; for research and planning, request cited findings or a reviewable plan. Adapt the 25 templates to your project’s requirements and permissions, then review the evidence before accepting the work.
What Makes a Claude Code Prompt Different From a Chat Prompt?
A Claude Code prompt can authorize work in your repository, rather than simply request an explanation. Depending on its tools and permissions, Claude can inspect files, run commands, edit code, and check the results. Your instructions therefore need to define both the task and the boundaries of the work.
Chat assistants can also use tools and take actions, so the distinction is not “chat replies, Claude Code acts.” The practical difference is the environment and access you give the assistant. Asking for a suggested fix in a chat leaves you to apply it; asking Claude Code to implement that fix can change your working files.
That changes the consequences of an unclear request. “Fix checkout” leaves decisions about scope, expected behavior, and acceptable changes unresolved. Claude may produce a plausible implementation that you then have to inspect or undo. A more useful request identifies the failing case, what must remain unchanged, and whether Claude should investigate, plan, or edit.
Anthropic’s analysis of 500,000 coding-related interactions illustrates this difference in use. Using data from April 2025, it classified 79% of Claude Code conversations as automation, compared with 49% of Claude.ai conversations. These figures describe observed usage patterns, not fixed limits on either product.
The same study classified 35.8% of Claude Code interactions as feedback loops, where people validated the work and supplied further input, such as error messages. Giving Claude a relevant test command can help it investigate failures directly. You still need to assess whether those checks cover the behavior you requested.
For Claude Code, a prompt should make the intended level of action clear: explain the code, propose a change, or implement it within a defined scope. Configure permissions separately, then review the evidence appropriate to that task.
The Anatomy of a Good Claude Code Prompt
A strong Claude Code prompt explains the result you want, the context needed to produce it, and how you’ll assess the work. A question about one function may need only a file reference and a requested explanation. A change across several files needs clearer scope and constraints.
Include these six details where they apply:
- What: The expected behavior, such as showing an invalid-coupon message instead of returning a checkout error
- Where: The files, folders, or services in scope, referenced with @ when you know them
- Pattern: An existing implementation Claude should follow, such as your project’s API client or error-handling conventions
- Verification: A test or build command for code changes, or file references and commit IDs for research
- Limits: What must remain untouched, such as public APIs, database schemas, or unrelated modules
- Approach: Whether Claude should explain, propose a plan for review, or implement the change
Here’s how those details improve three common requests.
Fix a specific bug
Instead of: “Fix the checkout bug.”
Customers using an expired coupon receive a 500 error at checkout. Inspect @src/checkout/coupons.ts and its tests. The expected behavior is an invalid-coupon message without creating an order. Write a failing test that reproduces the error, then fix it without changing valid-coupon behavior. Run [checkout test command] and show the results before and after. If you cannot reproduce the error, report what you checked before changing the implementation.
Customers using an expired coupon receive a 500 error at checkout. Inspect @src/checkout/coupons.ts and its tests. The expected behavior is an invalid-coupon message without creating an order. Write a failing test that reproduces the error, then fix it without changing valid-coupon behavior. Run [checkout test command] and show the results before and after. If you cannot reproduce the error, report what you checked before changing the implementation.
Add a feature using an existing pattern
Instead of: “Add a date picker.”
Add a date picker to [booking form path]. Follow the component and validation conventions in @src/components/TimeSelect.tsx. Users must be able to select [allowed dates], while [unavailable dates] remain disabled. Don’t add libraries. Run [component test command] and [type-check command], and report any criteria those checks do not cover.
Add a date picker to [booking form path]. Follow the component and validation conventions in @src/components/TimeSelect.tsx. Users must be able to select [allowed dates], while [unavailable dates] remain disabled. Don’t add libraries. Run [component test command] and [type-check command], and report any criteria those checks do not cover.
Refactor without changing behavior
Instead of: “Clean up this file.”
Split @src/reports/export.py into smaller functions while preserving its inputs, output format, and error behavior. Run [export test command] before editing and report any existing failures. After refactoring, rerun the tests and show both results. Don’t change the public interface or unrelated files.
Split @src/reports/export.py into smaller functions while preserving its inputs, output format, and error behavior. Run [export test command] before editing and report any existing failures. After refactoring, rerun the tests and show both results. Don’t change the public interface or unrelated files.
Replace the example paths and commands with values from your repository. Passing tests provide evidence for the cases they cover; review the diff and confirm those cases match the requirement.
These examples adapt the scoped-request approach in Anthropic’s Claude Code best practices. For guidance beyond coding, see these AI agent prompting best practices.
Why the Check Matters More Than the Wording
A detailed prompt can still produce code that solves the wrong problem. You might specify the files, coding style, and desired output, yet leave out the condition that determines whether the change is useful. For an expired-coupon bug, “the checkout tests pass” is incomplete evidence unless those tests cover the failing coupon and confirm that no order was created.
Wording helps Claude understand the request. Verification lets you assess whether its implementation meets it. That distinction matters when Claude can edit files and run commands: a convincing explanation of the change is not evidence that the behavior is correct.
Anthropic’s Claude Code best-practices guide recommends giving Claude a way to verify its work through tests, screenshots, or expected outputs. The check should reflect the requirement. A build checks whether the project compiles; a focused test checks a particular behavior; a screenshot comparison helps assess the rendered interface. Each answers a different question.
Boris Cherny, the creator of Claude Code, describes using a browser-based feedback loop in his own workflow:
“Claude tests every single change I land to claude.ai/code using the Claude Chrome extension. It opens a browser, tests the UI, and iterates until the code works and the UX feels good.”
“Claude tests every single change I land to using the Claude Chrome extension. It opens a browser, tests the UI, and iterates until the code works and the UX feels good.”
InfoQ’s account of Cherny’s workflow reports his view that verification can improve result quality by a factor of two to three. That is an attributed assessment of his workflow, not a controlled measurement or a guaranteed improvement.
Keep responsibility for requirements and acceptance criteria
Delegating implementation still leaves you responsible for deciding what the software should do. Claude can suggest tests, but those tests need to reflect your business rules, including exceptions that may not be obvious from the code.
In its study of about 400,000 Claude Code sessions, Anthropic found that people made about 70% of planning decisions but only about 20% of execution decisions. The study also associated higher apparent task-specific expertise with higher verified-success rates: about 15% for sessions rated novice, compared with 28% to 33% for intermediate or expert sessions.
Those figures need context. Expertise was assessed from transcripts, and “verified success” required evidence of success within the session. Anthropic did not observe users’ real-world outcomes. Sessions without that signal were not necessarily failures, and the study does not establish that changing prompt wording alone improves results.
The practical implication is to contribute the knowledge Claude cannot safely infer. An accountant reconciling invoices must specify how partial payments, refunds, and rounding should work. A developer changing checkout behavior must identify which existing behaviors must remain intact. Those decisions determine whether the resulting tests check the right thing.
Before accepting a change, review the requirement, the implementation, and the evidence together. Ask which cases were tested, which checks failed or were skipped, and what remains uncertain. This gives you a basis for accepting the work beyond Claude’s statement that it is finished.
25 Claude Code Prompts You Can Copy and Adapt
Choose a prompt based on the task you need to complete, then replace the bracketed details with your repository’s paths, requirements, and commands. For code changes, specify a test or build command. For research and planning, ask for source references and a clearly defined deliverable.
These templates describe the work you want Claude to do. Configure Claude Code’s permissions separately; an instruction such as “don’t edit files” is not a substitute for access controls.
Prompts for understanding a codebase
Before changing unfamiliar code, establish where the relevant behavior lives and how it works. These prompts focus on reading files and history without making edits.
1. Get an overview of an unfamiliar repository
Use this when joining a project or working in a repository for the first time. Start with the README, project configuration, and directory structure rather than asking Claude to read every file.
Inspect the README, project configuration, and top-level directory structure of this repository. Follow references only as needed to explain:What the application doesIts main entry points and major componentsWhere tests live and which commands the repository defines for running themCite the file paths supporting your explanation. Distinguish documented behavior from your own inferences, and flag anything you cannot determine. Don’t read secrets or environment files, inspect installed dependencies, or change any files. End with the three files I should read first and why.
Inspect the README, project configuration, and top-level directory structure of this repository. Follow references only as needed to explain:What the application doesIts main entry points and major componentsWhere tests live and which commands the repository defines for running themCite the file paths supporting your explanation. Distinguish documented behavior from your own inferences, and flag anything you cannot determine. Don’t read secrets or environment files, inspect installed dependencies, or change any files. End with the three files I should read first and why.
2. Understand why an implementation changed
Use Git history to investigate a design decision before replacing it. Ask for recorded evidence rather than assuming the current code reveals the original author’s intent.
Review the Git history of [file, function, or class], focusing on [behavior or design question]. Identify the commits that introduced or substantially changed this behavior.For each relevant commit, provide its hash, summarize the change, and explain any rationale documented in the commit message or linked discussion you can access. Label inferred reasons as inferences. If the history does not explain a decision, say so. Don’t modify files or Git history.
Review the Git history of [file, function, or class], focusing on [behavior or design question]. Identify the commits that introduced or substantially changed this behavior.For each relevant commit, provide its hash, summarize the change, and explain any rationale documented in the commit message or linked discussion you can access. Label inferred reasons as inferences. If the history does not explain a decision, say so. Don’t modify files or Git history.
3. Trace a specific application flow
Use this before touching behavior that crosses multiple components, such as authentication, checkout, or notifications.
Trace what happens when [user action or system event], starting in [known route, handler, or folder]. Follow the relevant calls through validation, business logic, and any database writes or external requests.List the files and functions in execution order, with line references where available. Explain the main failure paths and identify existing tests covering the flow. Flag any connection you cannot confirm from the code. Don’t execute the flow, call external services, or edit files.
Trace what happens when [user action or system event], starting in [known route, handler, or folder]. Follow the relevant calls through validation, business logic, and any database writes or external requests.List the files and functions in execution order, with line references where available. Explain the main failure paths and identify existing tests covering the flow. Flag any connection you cannot confirm from the code. Don’t execute the flow, call external services, or edit files.
Prompts for planning before you build
For changes that span several files or leave important requirements unresolved, review a plan before implementation. These prompts help you define the work, clarify decisions, and identify affected code.
4. Plan a feature before changing code
Use this when you know the desired behavior but need to understand the implementation. Start in Plan mode so Claude can inspect the repository before proposing changes.
Plan how to implement [feature] in [repository area]. The expected behavior is [requirements], and these areas must remain unchanged: [constraints].Inspect the relevant code and existing tests. Identify the files that need to change, the implementation order, and any compatibility or data-migration risks. Map each requirement to a proposed test or other verification step.List unresolved questions and assumptions separately. Don’t implement the feature yet. Return the plan for my review.
Plan how to implement [feature] in [repository area]. The expected behavior is [requirements], and these areas must remain unchanged: [constraints].Inspect the relevant code and existing tests. Identify the files that need to change, the implementation order, and any compatibility or data-migration risks. Map each requirement to a proposed test or other verification step.List unresolved questions and assumptions separately. Don’t implement the feature yet. Return the plan for my review.
5. Clarify requirements before writing a specification
Use this when the feature request leaves decisions about user behavior, data, or edge cases unanswered. The resulting specification should give a later implementation session enough context to proceed.
I want to build [short description] for [users and use case]. Read [relevant files or requirements] first, then use AskUserQuestion to clarify decisions that would materially affect the implementation.Focus on edge cases, data handling, permissions, expected UI behavior, and trade-offs. Don’t ask questions the supplied context already answers.Once the key decisions are resolved, draft a specification covering requirements, acceptance criteria, constraints, and what is out of scope. Mark any remaining assumptions. Show me the specification before saving it to [specification path], and don’t overwrite an existing file without approval.
I want to build [short description] for [users and use case]. Read [relevant files or requirements] first, then use AskUserQuestion to clarify decisions that would materially affect the implementation.Focus on edge cases, data handling, permissions, expected UI behavior, and trade-offs. Don’t ask questions the supplied context already answers.Once the key decisions are resolved, draft a specification covering requirements, acceptance criteria, constraints, and what is out of scope. Mark any remaining assumptions. Show me the specification before saving it to [specification path], and don’t overwrite an existing file without approval.
After reviewing and saving the specification, reference it in the implementation session. Include the relevant repository paths so Claude can check the specification against the existing code.
6. Identify what a shared-code change could affect
Use this before changing a shared function, component, or interface. A caller inventory helps you assess the scope, but it may not reveal consumers outside the repository.
Assess the impact of changing [function, component, or interface] from [current behavior] to [proposed behavior].Search [repository or directory scope] for its definition, direct callers, imports, and related tests. List the files likely to need changes and explain how each could be affected, with file and line references where available.Flag dynamically resolved calls, external consumers, or other dependencies you cannot verify. Identify any compatibility questions that need an answer before implementation. Don’t change files; return the impact assessment and wait for my review.
Assess the impact of changing [function, component, or interface] from [current behavior] to [proposed behavior].Search [repository or directory scope] for its definition, direct callers, imports, and related tests. List the files likely to need changes and explain how each could be affected, with file and line references where available.Flag dynamically resolved calls, external consumers, or other dependencies you cannot verify. Identify any compatibility questions that need an answer before implementation. Don’t change files; return the impact assessment and wait for my review.
Prompts for building features
Feature-building prompts should describe the expected behavior and connect it to the code already in your project. Include relevant examples, constraints, and checks so Claude can implement the change without making unrelated decisions.
7. Build a feature using an existing pattern
Use this when a similar feature already exists in your repository. Point Claude to the implementation you want it to follow, including data access, error handling, and tests.
Add [feature] to [file or page] with this behavior: [acceptance criteria].Inspect [existing implementation] and follow its conventions for fetching data, handling errors, and organizing components. Use only libraries already installed in the project. Keep changes within [scope] and preserve [existing behavior or public interface].Add or update tests for the acceptance criteria. Run [test command] and [type-check or lint command], then report the changed files, results, and any checks you could not complete. If the existing pattern conflicts with a requirement, explain the conflict before proceeding.
Add [feature] to [file or page] with this behavior: [acceptance criteria].Inspect [existing implementation] and follow its conventions for fetching data, handling errors, and organizing components. Use only libraries already installed in the project. Keep changes within [scope] and preserve [existing behavior or public interface].Add or update tests for the acceptance criteria. Run [test command] and [type-check or lint command], then report the changed files, results, and any checks you could not complete. If the existing pattern conflicts with a requirement, explain the conflict before proceeding.
8. Write tests before implementing a function
Use this for behavior you can express through defined inputs and outputs. The initial test failure should demonstrate missing behavior, rather than a broken test setup.
Implement [function name] in [file] to satisfy [requirements]. Cover [normal case], [edge case], and [invalid-input behavior].Run [relevant test command] first and report any existing failures. Write tests for the requested behavior, then run them before implementation. Confirm that the new tests fail for the expected reason.Implement the function and rerun the tests. Don’t weaken assertions, skip tests, or change the expected behavior to make them pass. If the requirements conflict with existing tests, stop and explain the conflict. Show the before-and-after results.
Implement [function name] in [file] to satisfy [requirements]. Cover [normal case], [edge case], and [invalid-input behavior].Run [relevant test command] first and report any existing failures. Write tests for the requested behavior, then run them before implementation. Confirm that the new tests fail for the expected reason.Implement the function and rerun the tests. Don’t weaken assertions, skip tests, or change the expected behavior to make them pass. If the requirements conflict with existing tests, stop and explain the conflict. Show the before-and-after results.
9. Implement a UI from a reference image
Use this when you have a design screenshot and a working way to capture the implementation. Supply the route, viewport, and UI state so Claude compares equivalent screens.
Implement the attached design in [component or page], using the project’s existing components and styles. Preserve [required behavior] and avoid changes outside [scope].Use [configured browser or screenshot tool] to capture [local route] at [viewport dimensions] with [test data and UI state]. If the tool or application is unavailable, report what is needed rather than claiming a visual check.Compare the capture with the reference, focusing on [layout, spacing, typography, or other acceptance criteria]. Make up to [number] correction passes, then report the remaining differences. Don’t alter the reference image.Run [relevant component tests] and [type-check or build command]. Include the captured screenshot and actual check results in your summary.
Implement the attached design in [component or page], using the project’s existing components and styles. Preserve [required behavior] and avoid changes outside [scope].Use [configured browser or screenshot tool] to capture [local route] at [viewport dimensions] with [test data and UI state]. If the tool or application is unavailable, report what is needed rather than claiming a visual check.Compare the capture with the reference, focusing on [layout, spacing, typography, or other acceptance criteria]. Make up to [number] correction passes, then report the remaining differences. Don’t alter the reference image.Run [relevant component tests] and [type-check or build command]. Include the captured screenshot and actual check results in your summary.
Prompts for debugging and fixing
10. Reproduce a bug before fixing it
12. Narrow down a bug through questions
