Claude Code Prompt Engineering Guide

Claude Code is Anthropic's CLI-based agentic coding assistant powered by Claude. Unlike traditional autocomplete tools, Claude Code can autonomously execute multi-step tasks: reading files, running commands, making edits across your codebase, and even running tests to verify its work.

This guide will help you write prompts that leverage Claude Code's agentic capabilities for maximum productivity.

Claude Code can:

• Read and navigate your entire codebase
• Edit files with precise, targeted changes
• Run commands like npm install, git commit, tests
• Search using grep, glob patterns, and semantic understanding
• Plan and execute multi-step tasks autonomously
• Debug by running code and analyzing errors

Claude Code maintains context about your project and can work across multiple files in a single task. It thinks step-by-step and verifies its work.

1. State the Goal Clearly

Start with what you want to achieve:

Add user authentication using NextAuth.js with Google OAuth. Users should be redirected to /dashboard after login.

2. Provide Context When Helpful

Give context about your project:

This is a Next.js 14 app using App Router and PostgreSQL with Prisma. Add a /api/users/[id] route that returns user profile data.

3. Specify Acceptance Criteria

Define what "done" looks like:

Implement email validation for the signup form:
- Check format with a regex
- Verify domain has MX records
- Show inline error if invalid
- The existing tests should still pass

4. Request Verification

Ask Claude Code to verify its work:

After making the changes, run the test suite and fix any failures.

5. Constrain the Scope

Prevent over-engineering:

Fix the null pointer error in calculateTotal. Don't refactor other parts of the file.

Feature Implementation

Add a dark mode toggle to the app:
1. Create a ThemeProvider using next-themes
2. Add a toggle button in the header
3. Update the Tailwind config for dark mode
4. Test that the toggle persists across page reloads

Use the existing button component styles for consistency.

Bug Investigation

The checkout flow is failing with "Cannot read property 'id' of undefined" for some users.

1. Find where this error originates
2. Identify what conditions cause it
3. Fix the root cause
4. Add a test case to prevent regression

Refactoring

Extract the API request logic from the individual route handlers into a shared utility.

Requirements:
- Handle errors consistently
- Add request/response logging
- Support authentication headers
- Migrate existing routes to use the new utility
- Ensure all existing tests pass

Performance Optimization

The products page loads slowly. Profile the page and identify the bottlenecks.

Focus on:
- Database query optimization (check for N+1 queries)
- Unnecessary re-renders
- Large bundle size

Make fixes and measure the improvement.

Testing

Add comprehensive tests for the checkout module:
- Unit tests for the price calculation functions
- Integration tests for the checkout API endpoint
- Edge cases: empty cart, invalid coupon, out-of-stock items

Target 90% code coverage for this module.

Plan Mode for Complex Tasks

For large changes, use plan mode:

/plan Migrate the authentication system from custom JWT to NextAuth.js while maintaining backward compatibility with existing sessions.

Iterative Development

Break large features into phases:

Phase 1: Set up the database schema for the new feature
Phase 2: Implement the API endpoints
Phase 3: Build the UI components
Phase 4: Add tests and documentation

Start with Phase 1.

Exploration and Analysis

Ask Claude Code to analyze before acting:

Before making changes, analyze the current authentication flow:
- How does login work?
- Where are sessions stored?
- What middleware protects routes?

Then suggest improvements for security.

Code Review Assistance

Ask for review of specific changes:

Review the changes in the last 3 commits:
- Check for security issues
- Look for performance problems
- Verify error handling is adequate
- Suggest improvements

Too Vague

Bad: "Fix the app"

Good: "Fix the login form - it's not showing validation errors when fields are empty"

No Success Criteria

Bad: "Add caching"

Good: "Add Redis caching to the products API. Cache for 5 minutes. Invalidate when products are updated. Verify with the load test script."

Scope Too Large

Bad: "Rebuild the entire frontend"

Good: "Migrate the Header component from CSS modules to Tailwind. Keep the same visual appearance."

Not Using Claude Code's Strengths

Bad: Asking Claude Code to only give advice without making changes

Good: Ask Claude Code to actually implement, test, and commit the changes