Claude Code can inspect a repository, read files, edit code, run commands, execute tests, investigate bugs, and work through multi-step development tasks.
But getting useful results is not simply about telling Claude what you want.
The quality of a Claude Code task often depends on whether you provide enough context, a clear goal, useful constraints, and a way to verify the result.
Compare these two prompts:
Fix the login bug.
with:
Users are being logged out after a session timeout. Investigate the authentication flow, especially token refresh and session restoration. First identify the root cause. Then: - reproduce the issue with a test - make the smallest appropriate fix - run the relevant authentication tests - explain the root cause and files changed Do not modify unrelated authentication behavior.
The second prompt gives Claude a much clearer problem to solve.
Anthropic's current prompting guidance recommends clear and direct instructions, useful context, examples, structured prompts, and explicit action when you want Claude to actually make changes rather than merely suggest them.
For Claude Code specifically, Anthropic also recommends a workflow that separates exploration, planning, implementation, and verification when the task is complex.
What Makes a Good Claude Code Prompt?
A useful Claude Code prompt usually answers four questions:
- What is the goal?
- What context does Claude need?
- What constraints or existing patterns matter?
- How will you know the task is complete?
A simple structure is:
Context Task Constraints Verification
For example:
Context: This is a Next.js application using Prisma and PostgreSQL. The authentication code is in src/auth/. Task: Add password reset functionality. Constraints: Use the existing email service. Follow the same error-handling pattern as the login endpoint. Do not change the existing authentication architecture. Verification: Add tests for token creation, expiration, and successful reset. Run the relevant tests before finishing.
This is not a rigid formula. Simple tasks may need only one or two sentences. Complex tasks need more structure.
Anthropic's context-engineering guidance makes an important distinction: minimal context does not necessarily mean short context. The goal is to provide the minimum information needed for reliable behavior without stuffing the prompt with irrelevant instructions.
The 4-Part Claude Code Prompt Framework
1. Context
Tell Claude what it needs to know.
This is a Next.js app using: - TypeScript - PostgreSQL - Prisma - Vitest Authentication is handled in src/auth/.
2. Task
Clearly state what you want done.
Add password reset functionality.
3. Constraints
Define important boundaries.
Use the existing email service. Do not change the public authentication API. Follow the project's existing validation pattern.
4. Verification
Define how the result should be checked.
Add regression tests. Run the relevant test suite. Make sure TypeScript compilation still passes.
Combined:
Context: This is a Next.js app using TypeScript, PostgreSQL, Prisma, and Vitest. Authentication is handled in src/auth/. Task: Add password reset functionality. Constraints: Use the existing email service. Do not change the public authentication API. Follow the project's existing validation pattern. Verification: Add regression tests. Run the relevant test suite. Make sure TypeScript compilation passes.
This structure works because Claude doesn't have to guess what the project is, what you want, or what counts as finished.
1. Be Clear and Direct
Anthropic's current guidance describes Claude as highly capable but lacking knowledge of your particular project norms and workflows. Their practical rule is simple: if a colleague with minimal context would be confused by your prompt, Claude probably will be too.
Weak
Make the dashboard better.
Better
Improve the dashboard's loading performance. Focus on: - unnecessary API requests - duplicate data fetching - large client-side components Do not change the visual design. Run the existing dashboard tests after making changes.
The second prompt defines the area of work and its boundaries.
2. Give Claude the Context It Cannot Infer
Claude can inspect your repository, but you shouldn't assume it already knows your project's conventions.
For example:
The application uses: - React - TypeScript - TanStack Query - Vitest The existing API client is in src/api/client.ts. Follow the patterns already used there.
Context is particularly useful when:
- a project has unusual conventions
- multiple implementations exist
- a specific architecture must be preserved
- business rules aren't obvious from the code
- you need a particular testing strategy
Anthropic recommends providing context or motivation when it helps Claude understand why an instruction matters.
For example:
Less useful
Never use ellipses.
Better
The response will be converted to speech by a text-to-speech system, so avoid ellipses because the speech system does not pronounce them correctly.
The second version explains the reason behind the constraint.
That gives Claude something it can generalize from rather than an isolated rule.
3. Use the "Context → Task → Constraints" Pattern
A very practical pattern for Claude Code is:
Context: [What Claude needs to know] Task: [What you want Claude to do] Constraints: [What must or must not change]
For example:
Context: We have a Node.js API using Express and PostgreSQL. The order routes are in src/routes/orders.ts. Task: Add an endpoint for cancelling an order. Constraints: Follow the existing route structure. Only allow cancellation before shipment. Reuse the existing authentication middleware. Do not modify the database schema.
This pattern is also reflected in independent Claude Code guidance, where context, task, and constraints are treated as the basic anatomy of a coding prompt.
4. Tell Claude to Read First When the Problem Is Unclear
One of the most useful Claude Code prompting patterns is:
Read first, then do.
Instead of immediately asking Claude to modify unfamiliar code:
Fix the payment system.
try:
Read src/services/payment.ts and the related tests. Explain how the current refund flow works. Then identify what would need to change to support partial refunds. Do not modify files yet.
After Claude explains the architecture, you can ask:
Implement the partial refund support using the approach you described. Add the necessary tests and run them.
Claude Code's official workflow guidance recommends separating exploration and planning from implementation for complex tasks because jumping straight into coding can result in solving the wrong problem.
5. Tell Claude to Follow an Existing Pattern
You often don't need to explain your entire coding style.
Show Claude a nearby implementation.
For example:
Add a PATCH endpoint for products. Follow the same implementation pattern used by: src/routes/users.ts
This is powerful because Claude can inspect the existing code and follow its conventions.
Claude Code's current best-practices documentation explicitly recommends pointing Claude toward existing patterns in the repository.
Another example
Create a new notification component. Look at: src/components/Toast.tsx Follow its: - component structure - styling approach - accessibility pattern - testing conventions
This is often better than writing a long explanation of how your project works.
6. Use @ References to Give Claude the Right Files
Claude Code supports direct file references with @.
Instead of:
The authentication file is somewhere inside src/auth...
you can use:
Review @src/auth/login.ts and @tests/auth/login.test.ts. Find why the login test fails after the recent session change. Do not modify files yet.
Claude Code documentation also describes several other ways to provide rich context, including images, URLs, piped data, and letting Claude retrieve information through tools.
For example:
cat error.log | claude
can provide log content directly.
This is useful when the information is too large or inconvenient to paste manually.
7. Don't Give Claude Every Implementation Detail
A common prompting mistake is trying to control every line Claude should write.
For example:
Open file A. Find function B. Create variable C. Call method D. Move this line. Add this exact condition. Then create another helper...
If you already know exactly what code should be written, that can work.
But for many tasks, a better approach is to describe the desired outcome, constraints, and verification while allowing Claude to determine reasonable implementation details.
For example:
Add caching to the product API. Use the project's existing caching approach. Keep the API response unchanged. Cache repeated product-list requests. Invalidate the cache when products are created or updated. Add tests for cache hits, misses, and invalidation.
Anthropic's context-engineering guidance recommends finding the right “altitude”: specific enough to guide the agent, but not so brittle that every implementation decision has been hardcoded into the prompt.
8. But Be Specific About Things Claude Cannot Infer
There is an important balance here.
Don't prescribe every implementation detail unnecessarily.
But do specify requirements that matter.
For example:
The endpoint must return: 200 for valid requests 400 for invalid input 404 when the product does not exist
That is much better than:
Make the endpoint handle errors properly.
Similarly:
Keep the existing method signatures unchanged.
is valuable if changing those signatures could break callers.
A useful rule is:
Give Claude freedom over implementation details, but not over requirements that affect correctness.
9. Define the Blast Radius
For coding agents, one of the most useful constraints is telling Claude what not to touch.
Example:
Fix the checkout bug. You may modify: - src/checkout/ - tests/checkout/ Do not: - change authentication - change the database schema - upgrade dependencies - refactor unrelated code
This creates a clear boundary.
Independent Claude Code guidance similarly emphasizes bounding the “blast radius” by specifying what should and should not change.
10. Use Positive Instructions
Instead of only telling Claude what not to do, tell it what you want.
Less useful
Don't write a long explanation. Don't use lots of bullets. Don't modify unrelated files.
Better
Keep the explanation concise. Use bullets only when they make discrete items easier to scan. Limit code changes to the authentication module.
Anthropic's current prompting guidance specifically recommends telling Claude what to do rather than relying only on negative instructions.
11. Give the Reason When a Rule Matters
If a constraint has an important reason, include it.
Instead of:
Don't change the database schema.
you might say:
Do not change the database schema because this migration will be deployed separately by the database team.
Or:
Keep the response format unchanged because an existing mobile client depends on the current JSON structure.
The reason gives Claude more information about the underlying goal.
12. Use Examples to Control Output
Examples are one of Anthropic's strongest general prompting techniques.
They can help Claude understand:
- output structure
- tone
- coding conventions
- expected behavior
- edge cases
Anthropic recommends examples that are relevant, diverse, and structured, and its current guidance says 3–5 examples can work well when examples are needed.
For example:
Review the code and report issues using this format: Issue: File: Why it matters: Recommended fix: Example: Issue: Missing input validation. File: src/api/users.ts Why it matters: Invalid input can reach the database layer. Recommended fix: Validate the request body before calling the database.
If the output format is important, examples can communicate it faster than a long explanation.
13. Don't Stuff Your Prompt With Every Edge Case
More instructions don't automatically mean better results.
Anthropic's context-engineering guidance specifically warns against turning prompts into huge lists of every imaginable edge case. Instead, it recommends selecting a smaller set of diverse, representative examples.
Instead of:
If A happens do X. If B happens do Y. If C happens do Z. If D happens...
when possible, give Claude representative examples and the underlying rule.
For example:
Use the existing API error format. Examples: - validation failure → 400 - missing resource → 404 - unexpected server failure → 500
Then let Claude apply the pattern.
14. Use XML Tags for Complex Prompts
XML tags are useful when a prompt mixes several kinds of information.
For example:
<context> This is a Next.js application using PostgreSQL and Prisma. </context> <task> Add password reset functionality. </task> <requirements> - Generate secure reset tokens. - Tokens must expire. - A token can only be used once. </requirements> <constraints> - Use the existing email service. - Do not change authentication architecture. </constraints> <verification> Add tests and run the relevant test suite. </verification>
Anthropic recommends descriptive XML tags for separating instructions, context, examples, and inputs in complex prompts.
You do not need XML for every Claude Code prompt.
For:
Rename this variable from `usr` to `user`.
XML would be unnecessary.
15. Use Plan Mode for Complex Tasks
For larger tasks, Claude Code's Plan Mode can separate exploration and implementation.
Claude Code's current documentation recommends an:
Explore → Plan → Implement → Commit
workflow for complex changes.
Claude Academy also describes Plan Mode as useful for complex changes and safe code review because Claude can analyze the codebase and create a plan before modifying files.
Example:
I need to add Google OAuth. First inspect the existing authentication, session, and environment-variable setup. Identify the files that need to change and create an implementation plan. Do not modify files yet.
After reviewing the plan:
Implement the approved plan. Add tests for the OAuth callback and run the relevant test suite. Fix failures before finishing.
When not to use Plan Mode
Planning has overhead.
Claude Code's documentation specifically says that for small, obvious changes—such as a typo, a log line, or a simple variable rename—you can skip planning and ask Claude to make the change directly.
A useful rule:
Small and obvious → act directly.
Large, unfamiliar, or multi-file → explore and plan first.
16. Use "Options With Tradeoffs" for Design Decisions
Sometimes you know the problem but don't know the best implementation.
Don't immediately ask Claude to pick one solution.
Ask for alternatives first:
I need to add caching to the product catalog. Review the existing architecture and give me three implementation approaches. For each option explain: - how it works - advantages - disadvantages - implementation complexity - likely maintenance cost Do not modify the code yet.
This gives you a design discussion before implementation.
An independent Claude Code guide identifies this “options with tradeoffs” pattern as useful when you want alternatives before committing to an implementation.
17. Ask "What Would You Change?" Before Editing
For code you aren't ready to modify:
Review @src/components/Dashboard.tsx. What would you improve? Focus on: - maintainability - performance - accessibility - obvious bugs Do not modify the file.
This is different from:
Improve Dashboard.tsx.
The first asks for analysis.
The second asks for action.
Being explicit about that distinction matters because current Claude models are trained to follow tool/action instructions closely. Anthropic's documentation shows that wording such as “suggest changes” can lead to suggestions, while “make these edits” explicitly requests implementation.
18. Tell Claude Whether You Want Analysis or Action
This is a small change that can make a big difference.
Analysis
Investigate the authentication bug. Do not modify files. Explain the root cause and recommend a fix.
Action
Investigate the authentication bug. Implement the smallest appropriate fix, add a regression test, and run the relevant tests.
Don't make Claude guess whether you want advice or actual changes.
19. Give Claude a Measurable Definition of Done
“Make it better” isn't measurable.
“Run tests” is better, but you can be even more precise.
For example:
The endpoint should: - return 200 for valid input - return 400 for invalid input - return 404 when the product does not exist - preserve the existing response schema Run the product API tests and confirm all pass.
Or:
The page should load without console errors and the existing Playwright tests must pass.
The more measurable the result, the easier it is for Claude—and you—to determine whether the task is actually finished.
Claude Code's current documentation recommends having Claude show evidence of successful verification, such as test output, commands and their results, or screenshots.
20. Don't Just Ask Claude to "Check Its Work"
Instead of:
Check your work.
say:
Run the relevant unit tests. Then run TypeScript type checking. If either fails, investigate and fix failures directly related to this change. At the end, report the commands you ran and their results.
This is much more actionable.
The official Claude Code guidance recommends asking for evidence rather than simply accepting an assertion that the work succeeded.
21. Use Context Engineering, Not Just Prompt Engineering
This is one of the most important ideas for modern Claude Code users.
Prompt engineering is about writing better instructions.
Context engineering is broader. It is about deciding what information Claude should have access to while it works.
That can include:
- files
- repository structure
- documentation
- logs
- tool results
- URLs
- project instructions
- examples
- previous decisions
Anthropic describes a “just-in-time” approach where agents maintain references such as file paths and links and retrieve relevant information when needed rather than loading everything into context at once. Claude Code uses this kind of approach when working across large codebases.
Bad approach
Here are 200 files from my project...
Better approach
Investigate the authentication issue. Start with: @src/auth/ @tests/auth/ Read the relevant files and trace the session flow. Only inspect unrelated areas if the evidence points there.
This keeps the context focused.
22. Long Context: Put the Important Question in the Right Place
When working with very large documents or data-heavy prompts, Anthropic's current prompting guidance recommends placing long-form input near the beginning and putting the query/instructions after it. Their documentation reports improved performance in tests for complex multi-document inputs when the query appears at the end.
A structured approach looks like:
<documents>
<document index="1">
<source>architecture.md</source>
<document_content>
...
</document_content>
</document>
<document index="2">
<source>api-spec.md</source>
<document_content>
...
</document_content>
</document>
</documents>
Analyze these documents and identify the changes
required to implement the new API.
For large-document tasks, Anthropic also recommends grounding responses in relevant excerpts before performing the larger task.
23. Move Repeated Instructions Out of Your Prompts
Suppose you repeatedly write:
Use TypeScript. Use Vitest. Use functional components. Run type checking. Follow our API error format.
If you need these rules in almost every session, they probably don't belong in every individual prompt.
Claude Code supports persistent project instructions through CLAUDE.md.
The current Claude Code documentation recommends keeping CLAUDE.md concise and using it for things Claude cannot reliably infer from the codebase, such as project-specific commands, code style differences, testing instructions, architecture decisions, and non-obvious gotchas.
For example:
# Code Style - Use ES modules. - Use TypeScript interfaces for public props. # Workflow - Run type checking after significant code changes. - Prefer targeted tests before the full suite. # Architecture - API handlers live in src/api/. - Business logic belongs in src/services/.
But don't turn CLAUDE.md into a giant project manual.
Claude Code's documentation warns that bloated CLAUDE.md files can cause important instructions to get lost.
A useful rule:
One-time instruction → prompt
Project-wide rule → CLAUDE.md
Reusable specialized workflow → skill
24. Use Skills for Repeated Specialized Workflows
If you repeatedly need the same specialized instructions, a Skill can be more appropriate than repeating a huge prompt.
For example, suppose you regularly ask Claude to:
- review API security
- generate tests
- analyze SEO
- review database migrations
Instead of pasting the same instructions every time, you can package the workflow into a reusable Skill.
This keeps individual prompts focused on the task itself.
Claude Code's current documentation distinguishes persistent project context in CLAUDE.md from specialized workflows that can be loaded when relevant.
25. Use a Single Task Instead of a Giant Request
A common mistake is:
Add authentication, build the dashboard, create the admin panel, optimize the database, write tests, deploy everything, and update the docs.
That's several projects combined into one instruction.
A better approach is:
First implement JWT authentication. Follow the existing Express architecture. Use AUTH_SECRET from the environment. Add authentication tests. Do not modify the dashboard yet.
Then move to the next task.
This makes failures easier to identify and reduces unnecessary scope.
Independent Claude Code research also identifies multiple unrelated tasks in one prompt as a common source of poor results.
26. Specify the Location When It Matters
Instead of:
Create a date utility.
say:
Create `formatDate` in: src/utils/date.ts Format dates like: Apr 11, 2026
This prevents ambiguity about where the implementation belongs.
If you don't know the correct location, let Claude investigate:
Find where date formatting utilities belong in this repository. Follow the existing project structure and add the new utility there.
27. Use Baselines and Targets for Performance Tasks
“Make it faster” isn't a useful performance requirement.
Instead:
The GET /api/products endpoint currently takes about 3 seconds for 1,000 records. Investigate the cause first. Target: P99 response time below 200ms. Look for: - N+1 queries - missing indexes - unnecessary database tracking Propose the changes before modifying the implementation.
A baseline and measurable target make performance work much easier to evaluate.
The same principle applies to other tasks:
Current: Build takes approximately 90 seconds. Target: Reduce it below 45 seconds without changing the build output.
28. Prompt for Specific Code Review Categories
Don't simply say:
Review my code for bugs.
That is too broad.
Instead:
Review @src/orders/ for: 1. Missing input validation 2. N+1 database queries 3. Incorrect error handling 4. Missing cancellation propagation 5. Missing tests For every finding provide: - file - line - issue - why it matters - recommended fix Do not modify the code.
Specific categories give Claude a checklist to work through.
29. Claude Code Prompt Examples
Example 1: Understand a Codebase
Explain how authentication works in this repository. Trace the flow from login request through authentication and session creation. Identify the relevant files. Do not modify anything. Give me: 1. Authentication flow 2. Important files 3. Error-handling approach 4. Areas that may deserve further investigation
Example 2: Fix a Bug
Users are being logged out after a session timeout. Investigate the authentication flow, especially token refresh and session restoration. First reproduce the problem or trace the failure. Then: - identify the root cause - add a regression test - make the smallest appropriate fix - run the relevant authentication tests Do not modify unrelated authentication behavior.
Example 3: Add a Feature
Add password reset functionality. Requirements: - users request a reset using their email - reset tokens expire - tokens can only be used once - do not reveal whether an email exists First inspect the existing authentication architecture. Use the existing email service. Follow the project's existing validation and error-handling patterns. Add appropriate tests and run them before finishing.
Example 4: Refactor Code
Refactor @src/services/OrderService.ts. Goals: - reduce duplicated logic - improve readability - preserve existing behavior Constraints: - keep public method signatures unchanged - do not change business rules - do not introduce new dependencies - do not refactor unrelated services Run the existing tests after the refactor.
Example 5: Write Tests
Read @src/services/OrderService.ts first. Write tests for CreateOrder. Cover: - successful order - insufficient stock - invalid product - concurrency conflict Follow the existing test structure. Do not modify the production implementation. Run the new tests when finished.
Specifying the actual scenarios is particularly useful because otherwise an agent may generate mostly generic happy-path tests.
Example 6: Code Review
Review @src/orders/. Focus on: - security issues - missing validation - error handling - database performance - race conditions - missing tests For every finding provide: Severity: File: Problem: Why it matters: Suggested fix: Do not modify any files.
Example 7: Investigate Before Changing
Investigate why the dashboard is loading slowly. Read the relevant components and API calls. Do not modify files. Identify: - the likely bottleneck - supporting evidence - possible solutions - which solution you would implement and why
Example 8: Give Me Options
I need to add caching to the product catalog. Inspect the existing architecture first. Give me three implementation approaches. For each include: - implementation complexity - advantages - disadvantages - maintenance implications Do not modify the code yet.
Example 9: Large Feature
<context> This is a Next.js application using TypeScript, PostgreSQL, Prisma, and an existing email service. The authentication system is in src/auth/. </context> <task> Implement team invitations. </task> <requirements> - Users can invite team members by email. - Invitations expire. - Invitations can only be accepted once. - Existing team permissions must remain unchanged. </requirements> <constraints> - Reuse the existing email infrastructure. - Follow the existing authentication patterns. - Do not change unrelated permissions. - Do not add unnecessary dependencies. </constraints> <verification> Add tests for invitation creation, expiration, acceptance, duplicate use, and invalid tokens. Run the relevant test suite. </verification>
30. A Reusable Claude Code Prompt Template
Save this template for recurring tasks:
<context> [Relevant project context] [Relevant files] [Existing patterns] [Important technical or business rules] </context> <task> [What should Claude accomplish?] </task> <requirements> - [Requirement 1] - [Requirement 2] - [Requirement 3] </requirements> <constraints> - [What must remain unchanged?] - [What should Claude avoid?] - [Existing patterns to follow] </constraints> <verification> - [Test] - [Build] - [Lint] - [Expected behavior] </verification> <final_response> Summarize: - what changed - files changed - tests/checks run - any remaining issues </final_response>
For a tiny task, however, don't force this entire structure.
This can be enough:
Rename `usr` to `user` in @src/auth/login.ts. Keep behavior unchanged and run the relevant tests.
The goal is not to create the longest possible prompt.
The goal is to provide the minimum sufficient context and instructions for reliable execution. Anthropic's context-engineering guidance explicitly recommends starting with a minimal prompt and adding instructions or examples based on observed failure modes.
31. A Better Mental Model: Treat Claude Like a New Developer
Imagine a talented developer joining your project today.
If you say:
Fix the checkout.
they would probably ask questions.
But:
Users report that checkout fails when an expired card is submitted. Trace the payment flow and identify the root cause. The payment API is in @src/payments/. Existing payment tests are in @tests/payments/. Add a regression test, make the smallest appropriate fix, and run the payment tests. Do not change the public payment API.
gives that developer something actionable.
Claude Code benefits from the same kind of communication.
32. The Explore → Plan → Implement → Verify Workflow
For larger tasks, use a workflow rather than one giant prompt.
Phase 1: Explore
Inspect the authentication system. Identify the relevant files, dependencies, database tables, and existing tests. Do not modify anything.
Phase 2: Plan
Based on your investigation, create an implementation plan. List: - files that need changes - database changes - tests required - potential risks
Phase 3: Implement
Implement the approved plan. Follow the existing project patterns.
Phase 4: Verify
Run the relevant tests and type checking. If something fails, investigate failures caused by this change and fix them. Report the commands and results.
Phase 5: Review
Review the final diff. Check for: - unintended changes - missing tests - security issues - unnecessary complexity
Claude Code's official documentation presents this exploration/planning/implementation/commit workflow as a practical approach for complex work.
33. When a Short Prompt Is Better
Not every task needs a detailed prompt.
For example:
Rename `usr` to `user` in @src/auth/login.ts.
or:
Add a log statement before the payment request.
or:
Run the tests for the files changed in this session.
Adding 300 words of instructions would make these prompts worse, not better.
Use structure when the task has ambiguity, risk, multiple requirements, or important constraints.
34. When a Detailed Prompt Is Better
Use more detail when:
- multiple files are involved
- the codebase is unfamiliar
- requirements are complex
- security matters
- there are important constraints
- you need a specific output format
- there are multiple valid approaches
- verification is important
- the task can easily expand beyond its intended scope
A simple way to think about it:
Simple task → short prompt
Unclear task → investigation prompt
Complex task → explore + plan + implement
High-risk task → explicit constraints + verification
35. Common Claude Code Prompting Mistakes
Mistake 1: Too vague
Fix my code.
Better:
The POST /orders endpoint returns 500 when the cart is empty. Investigate @src/routes/orders.ts. Expected behavior: Return 400 with the project's standard validation error. Add a regression test and run the relevant tests.
Mistake 2: Too many unrelated tasks
Add authentication, redesign the dashboard, optimize the database, build an admin panel, and deploy the application.
Break the work into separate tasks.
Mistake 3: Ignoring existing patterns
Create a user service.
Better:
Create the user service following the same pattern used in @src/services/product.ts.
Mistake 4: No scope
Improve the application.
Better:
Improve the checkout validation. Limit changes to the checkout module. Do not modify authentication or payment processing.
Mistake 5: No definition of done
Add caching.
Better:
Add caching to product-list requests. Verify that repeated requests use the cache and that product creation invalidates affected entries. Add tests for cache hits, misses, and invalidation.
Mistake 6: Asking for suggestions when you want action
Can you suggest changes to this function?
If you actually want Claude to edit it:
Improve this function's performance. Make the changes directly and run the relevant tests.
Anthropic's current guidance specifically notes this distinction between suggestion-oriented wording and explicit action instructions.
Mistake 7: Repeating project rules in every prompt
If you constantly write:
Use TypeScript. Use Vitest. Follow our API conventions. Run type checking.
consider moving stable project-wide rules into CLAUDE.md or a reusable Skill instead.
36. The "Colleague Test"
Before sending a complex prompt, use this simple test:
Could a developer who knows almost nothing about this task understand exactly what I want from this prompt?
If the answer is no, add the missing context.
This is closely aligned with Anthropic's current “new employee” framing for prompting Claude.
You don't need to explain things Claude can discover from the repository.
But you do need to explain:
- project-specific rules
- business requirements
- important constraints
- expected behavior
- things that aren't obvious from the code
37. The "Minimum Sufficient Prompt" Rule
A common misconception is:
Better Claude prompts are longer Claude prompts.
That's not necessarily true.
A better rule is:
Use the smallest prompt that gives Claude enough information to make the correct decision.
For example:
Fix the typo in @README.md.
is already sufficient.
But:
Fix the authentication bug.
isn't sufficient if there are several authentication paths and no description of the failure.
Add information until ambiguity disappears.
Don't add information just to make the prompt longer.
Anthropic's context-engineering guidance explicitly recommends keeping context informative but tight and adding instructions or examples based on observed failures.
38. Advanced Pattern: Show Evidence
For debugging and research tasks, don't ask Claude to simply tell you what it thinks.
Ask it to show the evidence.
For example:
Investigate why the API returns intermittent 500 errors. Find the relevant logs and source code. For each possible cause: - show the relevant evidence - explain how it supports the hypothesis - identify what would confirm or reject it Do not make changes yet.
This makes the investigation easier to review.
The official Claude Code documentation similarly recommends showing evidence such as test output, commands and their results, or screenshots rather than simply asserting that verification succeeded.
39. Advanced Pattern: Use a Verification Gate
For risky changes, explicitly separate proposal from implementation.
Investigate the database performance problem. Measure the current behavior. Identify the root cause. Propose the smallest fix and explain the expected impact. Do not modify the code until the proposal is complete.
After reviewing:
Implement the approved fix. Run the benchmark and relevant tests. Compare the result with the original baseline.
This is especially useful for:
- database changes
- authentication
- infrastructure
- migrations
- major refactors
- performance optimization
40. Advanced Pattern: Ask Claude to Review Its Final Diff
After a complex change:
Review the final diff as a separate code-review pass. Look for: - unintended changes - missing edge cases - unnecessary complexity - security problems - missing tests Do not modify anything during this review. Report findings separately from the implementation summary.
For higher-assurance workflows, Claude Code's documentation also describes using a second verification agent or deterministic checks such as hooks to validate work.
41. 15 Practical Claude Code Prompt Patterns
Here are the patterns worth remembering:
1. Context + Task + Constraints
Context: ... Task: ... Constraints: ...
2. Read First, Then Do
Read the relevant files and explain the current behavior. Then implement the requested change.
3. Like This One
Follow the same pattern used in @src/example.ts.
4. Investigate First
Find the root cause before making changes.
5. Plan First
Inspect the codebase and create an implementation plan. Do not modify files yet.
6. Options With Tradeoffs
Give me three approaches with pros, cons, complexity, and maintenance implications.
7. Define Done
The task is complete when...
8. Give a Baseline
Current response time: ~3 seconds. Target: below 500ms.
9. Bound the Blast Radius
Only modify the checkout module. Do not change authentication or database schema.
10. Show Evidence
Report the commands you ran and their results.
11. Use Existing Tests
Follow the existing testing pattern in @tests/.
12. Use Rich Context
Inspect @src/auth/, the related tests, and the error log.
13. Ask for Analysis
Review this code and explain what you would change. Do not modify it.
14. Ask for Action
Make the changes directly and verify them.
15. Separate Persistent Rules
Move project-wide instructions into CLAUDE.md instead of repeating them in every prompt.
42. A Complete Real-World Example
Suppose you want Claude Code to fix a slow product API.
Weak prompt
Make the product API faster.
Better prompt
The GET /api/products endpoint takes approximately 3 seconds when returning 1,000 products. Investigate the cause before modifying the code. Focus on: - N+1 queries - missing database indexes - unnecessary ORM tracking - repeated API calls Inspect the existing implementation and tests. Target: P99 response time below 500ms. Constraints: - preserve the existing API response format - do not rewrite unrelated services - do not add dependencies unless necessary First propose the likely cause and recommended fix. Do not modify files yet.
After approval:
Implement the approved performance fix. Add or update the relevant tests. Run: - product API tests - type checking - the available performance check Compare the result with the original ~3-second baseline. Report: - root cause - files changed - commands run - verification results
This is much more powerful because it gives Claude:
context + problem + investigation + target + constraints + approval gate + verification.
43. Your Claude Code Prompt Checklist
Before sending a complex prompt, ask:
Goal
- Did I clearly state what I want?
Context
- Does Claude know the relevant project context?
- Did I reference important files?
Existing patterns
- Is there an existing implementation Claude should follow?
Scope
- Did I define what Claude should change?
- Did I define what should remain untouched?
Action
- Do I want analysis, suggestions, or actual implementation?
Verification
- How will we know the task succeeded?
Complexity
- Should Claude investigate first?
- Would Plan Mode help?
Repetition
- Am I repeating instructions that belong in CLAUDE.md or a Skill?
Context
- Did I provide useful information without dumping irrelevant data?
Examples
- Would an example make the expected output clearer?
44. Final Claude Code Prompt Template
Use this when you need a general-purpose template:
<context> Project: [Technology and relevant architecture] Relevant files: [Files or directories] Existing patterns: [Patterns Claude should follow] Important constraints: [Business or technical rules] </context> <task> [Clearly describe what you want Claude to accomplish] </task> <requirements> - [Requirement] - [Requirement] - [Requirement] </requirements> <constraints> - [What must remain unchanged] - [What Claude should avoid] - [Dependencies or architectural restrictions] </constraints> <workflow> [Explore first / plan first / implement directly] </workflow> <verification> [Tests] [Build] [Lint] [Expected behavior] [Performance target if applicable] </verification> <final_response> Report: - what changed - files changed - verification performed - remaining issues </final_response>
Again, this is a template—not a requirement.
For:
Rename @src/utils/usr.ts to @src/utils/user.ts and update imports.
you don't need a giant XML prompt.
45. Final Takeaway
The best Claude Code prompts are not necessarily the longest ones.
They are the ones that remove the right ambiguity.
For a simple task, Claude may only need:
Task + relevant file
For a more complicated task:
Context + Task + Requirements + Constraints + Verification
For a large or unfamiliar change:
Explore → Plan → Implement → Verify → Review
And for a large codebase, prompting is only part of the equation.
Good context engineering matters too. Give Claude access to the right files, documentation, examples, logs, and project instructions instead of trying to paste the entire world into one prompt.
The most practical rule to remember is:
Tell Claude what you want, give it the context it cannot infer, point it toward existing patterns, define the boundaries, and give it a concrete way to verify the result.
That is usually more useful than trying to write a “perfect” prompt.