effective-prompting

Effective Prompting for Claude Code

Write prompts that Claude Code understands and executes correctly the first time.

Quick Reference

@ Mentions (Context Injection)

@ mentions pull specific context into your prompt. Use them liberally.

Types

File Patterns

@src/api/*.ts           # All TS files in api folder
@src/**/*.test.ts       # All test files recursively
@package.json           # Specific file
@src/components/        # Entire folder

Best Practices

• Be specific: @src/api/users.ts > @src/
• Include tests: @src/auth.ts @src/auth.test.ts
• Add related files: @types/user.ts @src/api/users.ts
• Limit scope: 3-5 relevant files > entire codebase

Thinking Keywords

Trigger deeper reasoning with specific keywords.

When to Use Extended Thinking

• Architecture decisions
• Security-sensitive code
• Performance optimization
• Complex debugging
• Multi-system integration
• Breaking changes analysis

Example

ultrathink about how to refactor the authentication system
to support OAuth2 while maintaining backward compatibility
with our existing session-based auth @src/auth/

Task Framing

Structure prompts for clarity and precision.

The WHAT-WHY-HOW Pattern

WHAT: [Specific task]
WHY: [Context/motivation]
HOW: [Constraints/approach]

Example:

WHAT: Add rate limiting to the /api/upload endpoint
WHY: Users are uploading large files too frequently, causing server strain
HOW: Use a sliding window approach, 10 requests per minute per user

Success Criteria

Always define "done":

Add user search to the dashboard.

Done when:
- Search input filters users in real-time
- Debounced to 300ms
- Shows "No results" for empty matches
- Tests cover happy path and edge cases

Constraints Pattern

Specify boundaries:

Implement caching for API responses.

Constraints:
- Use Redis (already configured in docker-compose)
- TTL of 5 minutes for user data
- No caching for POST/PUT/DELETE
- Must work with existing middleware

Multi-Step Tasks

For complex work, structure as steps.

Sequential Steps

Implement user authentication:

1. First, add the User model with email/password fields
2. Then, create login/register API endpoints
3. Next, add JWT token generation and validation
4. Finally, protect routes with auth middleware

Run tests after each step.

Parallel Work Indicators

These can be done in parallel:
- Add UserCard component
- Add UserList component
- Add UserSearch component

Then combine them in the UserDashboard page.

Checkpoints

Refactor the payment module.

Checkpoint 1: Extract PaymentService class
- Run tests, commit if green

Checkpoint 2: Add Stripe integration
- Run tests, commit if green

Checkpoint 3: Add webhook handling
- Run tests, commit if green

Iterative Refinement

Build complex features incrementally.

Start Simple

# Round 1
Add a basic todo list component with hardcoded items.

# Round 2
Now add the ability to add new todos.

# Round 3
Add delete functionality and persist to localStorage.

Feedback Loop

# Initial
Add pagination to the user list.

# After seeing result
Good, but the page buttons are too small on mobile.
Make them at least 44px tap targets.

# After fix
Perfect. Now add keyboard navigation (arrow keys).

Session Management

Using /compact

When context grows large:

/compact

Continue with: We're implementing user auth.
Done: User model, login endpoint.
Next: JWT middleware.

Context Reset

Let's start fresh on the auth system.
Ignore previous attempts.
Here's the new approach: [approach]

Common Prompt Patterns

Reference Files

Validation Checklist

Before sending a complex prompt:

• Included relevant context with @ mentions
• Stated the goal clearly
• Defined success criteria
• Specified constraints
• Used thinking keywords if needed
• Broke down multi-step tasks
• Provided examples if pattern is unclear