Prompt Engineering for Claude Code

“Fix the bug” produces wildly different results than “The WebSocket reconnection in src/realtime/socket.ts fails after the third retry because the backoff timer resets on partial connections. Fix the retry logic to use exponential backoff with jitter, and add a test that simulates three failed reconnection attempts.”

The difference is not about being verbose. It is about giving Claude the right constraints, context, and verification criteria to produce exactly what you need on the first try.

What You Will Walk Away With

• A structured prompt framework that works for any task
• Plan mode and thinking keywords for complex multi-file changes
• Context priming techniques that reduce hallucination
• Prompts for the ten most common development tasks

The Prompt Framework

Every effective Claude Code prompt answers four questions:

1. What specifically needs to change?
2. Where in the codebase?
3. Why (the constraint or requirement driving the change)?
4. How should Claude verify the result?

What: Add rate limiting to the /api/users endpoint
Where: src/api/routes/users.ts and src/middleware/rate-limit.ts
Why: We are getting 10k requests/minute from a single IP and the DB is overloaded
How: The existing test suite should pass, and add a new test that verifies 429 responses after 100 requests/minute

Tip

Copy-paste prompt template for any code change:

[WHAT]: [describe the specific change]
[WHERE]: [list specific files or directories]
[WHY]: [explain the constraint or problem]
[VERIFY]: [how to confirm the change works]

Additional context:
- [any relevant architecture decisions]
- [related files Claude should read first]
- [patterns to follow from existing code]

Plan Mode

Press Shift+Tab to toggle plan mode. In plan mode, Claude analyzes the codebase and creates a plan before making any changes. This is essential for:

• Changes spanning more than three files
• Refactoring where the order of changes matters
• Tasks where you are unsure of the approach

[Shift+Tab to enable plan mode]

Refactor the authentication system from session-based to JWT. The current implementation
uses express-session with Redis storage across 12 route files. I need:

1. A migration plan that does not break existing sessions during deployment
2. Backward compatibility for the mobile app (version 2.3 and below uses session cookies)
3. Token refresh logic that handles concurrent requests

Read the current auth implementation in src/auth/ first, then create the plan.
Do not start implementing until I approve the plan.

Note

Plan mode is different from asking Claude to “plan first.” Plan mode is a behavioral toggle that restricts Claude from making changes until you approve. Simply asking Claude to plan first is a suggestion it may or may not follow.

Thinking Keywords

Claude Code supports extended thinking when you use specific keywords. These trigger deeper reasoning for complex problems:

• “think” — Standard extended thinking
• “think hard” — More extended thinking budget
• “think harder” — Even more thinking budget
• “ultrathink” — Maximum thinking budget

ultrathink about the race condition in our payment processing pipeline. Three services
(OrderService, PaymentService, InventoryService) communicate via Redis pub/sub, and we are
seeing duplicate charges when two payment confirmations arrive within 50ms of each other.
Analyze the timing diagram and propose a solution using distributed locks.

Use thinking keywords when the problem requires multi-step reasoning, when you are seeing incorrect or shallow analysis, or when the task involves concurrent systems, security analysis, or architectural decisions.

Tip

Copy-paste prompt for deep architectural analysis:

ultrathink about the best approach for migrating our monolith's user service into
a standalone microservice. Current state:
- 47 files reference the User model directly
- 12 API endpoints depend on the users table
- Auth middleware reads from users table on every request
- Test suite has 200+ tests that use user fixtures

Constraints:
- Zero downtime migration
- Must support rollback within 5 minutes
- Mobile app (v2.x) cannot be updated simultaneously

Context Priming

Before asking Claude to make changes, prime its context with the right information:

The Read-Then-Act Pattern

Read src/auth/middleware.ts, src/auth/jwt.ts, and src/auth/session.ts.
Then read the test files for each.
Now tell me: what would break if I changed the token expiry from 1 hour to 15 minutes?

This is more effective than asking the question directly because Claude has the actual code in context, not its assumptions about what the code might look like.

The Show-By-Example Pattern

Look at how error handling works in src/api/routes/orders.ts.
Now apply the same error handling pattern to src/api/routes/products.ts.
Every endpoint should have the same try/catch structure, the same error response
format, and the same logging calls.

The Constraint-First Pattern

CONSTRAINTS:
- Do not modify any file in src/core/ (these are generated)
- Keep backward compatibility with the v1 API
- All new code must have 80%+ test coverage
- Use the existing Logger, not console.log

TASK: Add a new /api/v2/analytics endpoint that aggregates user activity data
from the events table.

Tip

Copy-paste prompt for constraint-driven development:

Before you start, confirm you understand these constraints:
1. Do not add new dependencies to package.json
2. Follow the existing patterns in src/api/ for route structure
3. Use Zod for input validation (see existing routes for examples)
4. All database queries must go through the Prisma client in src/lib/db.ts
5. Error responses must follow our RFC 7807 format

Now: [your actual task here]

Prompts for Common Tasks

Bug Fix

The /api/users/:id endpoint returns 500 when the user ID contains special characters.
Steps to reproduce: GET /api/users/abc%20def
Expected: 400 with validation error
Actual: 500 with unhandled Prisma error

Fix the input validation in src/api/routes/users.ts and add a test case for special characters in IDs.

Code Review

Review the changes in the current git diff (git diff HEAD). For each finding:
1. Explain the issue
2. Rate severity: CRITICAL / HIGH / MEDIUM / LOW
3. Suggest a specific fix with code

Focus on: error handling, type safety, and performance.
Skip: style issues (our formatter handles those).

Test Generation

Read src/services/payment.service.ts and generate a comprehensive test file.
Follow the patterns in src/services/__tests__/order.service.test.ts for:
- Test structure (describe/it blocks)
- Mocking approach (jest.mock for external services)
- Assertion style (expect().toEqual for objects, toBe for primitives)

Cover: happy path, validation errors, external service failures, and edge cases
(empty arrays, null values, maximum limits).

When This Breaks

Claude ignores constraints: Put constraints at the beginning of your prompt, not the end. When context gets long, the end of the prompt gets less attention. Also consider adding critical constraints to your CLAUDE.md file.

Plan mode still makes changes: Make sure you toggled plan mode with Shift+Tab (not just asked Claude to plan). Check the status indicator in the REPL to confirm plan mode is active.

Extended thinking does not improve results: Not every problem benefits from extended thinking. Simple file edits, formatting changes, and straightforward bug fixes do not need ultrathink. Reserve it for problems with multiple interacting components or subtle correctness requirements.

Claude misunderstands the codebase: Prime context by having Claude read the relevant files first. If it misunderstands, correct it with “No, look at line 45 of src/auth.ts — the token is stored in Redis, not in the session.”

What is Next

• Batch Operations — Apply your prompting skills to large-scale changes
• Debugging Workflows — Prompts specifically designed for finding root causes
• CLAUDE.md Optimization — Encode your prompting patterns into persistent memory