How to Write Better Prompts for Claude Code

The difference between frustrating sessions and productive ones often comes down to how you ask. These techniques will dramatically improve your results.

Write better Claude Code prompts by being specific about what you want, providing context upfront, and asking Claude to verify before acting. These three principles — specificity, context, and verification — are the difference between frustrating back-and-forth and getting the right result on the first try.

This guide breaks down each principle with real before-and-after examples you can learn from immediately. The techniques work with all current Claude Code models: Opus 4.6, Sonnet 4.5, and Haiku 4.5.

The Three Principles

Before and After Examples

File Organization

Organize my Downloads folder

Organize files in ~/Downloads by type:
- Images (jpg, png, gif) → Images folder
- Documents (pdf, doc) → Documents folder
- Archives (zip, rar) → Archives folder
- Everything else → Other folder

First, show me how many files of each type.
Only move after I approve.

Data Processing

Clean up the CSV file

Clean ~/data/contacts.csv:
1. Remove rows with duplicate emails
2. Standardize phone numbers to (XXX) XXX-XXXX
3. Capitalize first letter of names
4. Delete rows where email is empty

Before saving:
- Show me 5 sample rows
- Tell me how many rows were removed

Save as contacts_clean.csv

Website Building

Make me a landing page

Create a landing page for a productivity app:
- Hero: headline, subheadline, email signup
- 3 feature sections with icons
- Testimonials from 2 users
- Pricing: Free and Pro tiers
- FAQ with 4 questions

Style: Clean, minimal, blue accent, lots of white space.
Mobile responsive.

Reference Files Directly with @

Instead of describing where code lives, use @ to reference files directly. Claude reads the file before responding, which eliminates ambiguity and saves you from writing lengthy descriptions.

Look at @src/auth/login.ts and fix the token validation on line 45

Refactor @components/Dashboard.tsx to use the same pattern as @components/Settings.tsx

You can also paste screenshots and images directly into the prompt, or pipe data in from the command line.

Using CLAUDE.md for Persistent Context

If you find yourself repeating the same context every session, you're doing it wrong.

Create a CLAUDE.md file in your project. Claude reads it automatically at the start of every conversation. Put your preferences there once:

# Project Context

## Code Style
- Use 2-space indentation
- Single quotes for strings
- Always add semicolons

## File Organization
- Keep original files, create copies
- Use YYYY-MM-DD date format
- Lowercase with hyphens for names

## When Processing Data
- Always backup before modifying
- Show sample output before full run
- Count records before and after

Now every prompt benefits from this context without you typing it. Keep your CLAUDE.md concise -- Claude can reliably follow around 150-200 instructions, so every line should earn its place.

The Verification Pattern

For anything that modifies files, add verification instructions:

Examples:

Before moving any files, list what you'll move and where.

Before updating the database, show me the SQL you'll run.

Before deleting anything, show me what matches the criteria.

After the transformation, verify by showing the first 5 rows
and comparing row counts before vs after.

Breaking Down Complex Tasks

For multi-step work, don't dump everything at once. Use phases:

Phase 1: Analyze
Look at ~/data/sales.csv and tell me:
- Column names and types
- Row count
- Any obvious data quality issues

Phase 2: Clean (after I review your analysis)
Fix the issues you found...

Phase 3: Transform (after cleaning is done)
Create the final report...

This gives you checkpoints to course-correct before Claude goes too far in the wrong direction.

Prompt Patterns That Work

The "First Show, Then Do" Pattern

First, show me [what you'll do].
After I approve, [do it].

The "Before and After" Pattern

[Do the task].
After finishing, verify by showing:
- [Metric before]
- [Metric after]
- [Sample of result]

The "If This, Then That" Pattern

If [condition], then [action A].
Otherwise, [action B].
If you're unsure, ask me.

The "Explore Then Execute" Pattern

First, explore [location] and tell me what's there.
Based on what you find, recommend an approach.
Don't make changes yet.

Common Mistakes

1. Too much at once: Long prompts with many requirements often miss important details. Break complex work into phases.
2. Assuming Claude remembers: Claude's context is limited. For long sessions, important context can get pushed out. Repeat critical constraints.
3. Not specifying paths: "Organize my files" vs "Organize files in ~/Downloads" — absolute paths prevent confusion.
4. Skipping verification: For destructive operations, always ask Claude to show its plan first.
5. Ignoring CLAUDE.md: If you're repeating context every session, you should be using a CLAUDE.md file instead.

When Claude Gets It Wrong

If Claude misunderstands, don't just say "that's wrong." Explain what's wrong and what you actually wanted:

No, that's not right.

That sorted by date, but I wanted
alphabetical by filename. Please
redo sorting A-Z by the filename,
ignoring case.

Be specific about what went wrong and what "right" looks like.

Mode-Specific Prompting

Use Plan Mode (Shift+Tab twice) for exploration:

Explore this codebase and explain the architecture.
Don't make any changes, just analyze.

Use Normal Mode for execution with safety checks:

Refactor the authentication module.
Ask me before each file modification.

Use Auto-Accept Mode (Shift+Tab once) when you trust the direction:

Apply the changes we discussed.
Go ahead without asking for each one.

Use Structured Formatting for Complex Prompts

For complex instructions, structured formatting helps Claude process your request more accurately. XML tags work especially well -- Claude processes structured data up to 40% more accurately than freeform text.

<task>
Refactor the payment processing module
</task>

<constraints>
- Do not change the public API interface
- Keep backward compatibility with v2 clients
- All new functions need TypeScript types
</constraints>

<verification>
Run npm test after each file change.
Show me test results before moving to next file.
</verification>

You can also use clear section headings like INSTRUCTIONS, CONTEXT, TASK, and OUTPUT FORMAT to achieve a similar effect.

Skills and Reusable Prompts

If you find yourself writing the same complex prompt repeatedly, turn it into a skill. Skills live in .claude/skills/ folders and can be invoked automatically when Claude detects a matching task, or manually with a slash command.

# .claude/skills/code-review/SKILL.md
---
description: Review code for quality, security, and performance issues
trigger: user asks for code review
---

Review the specified code for:
1. Security vulnerabilities (injection, auth issues)
2. Performance bottlenecks
3. Error handling gaps
4. Naming and readability

Format as a prioritized list: Critical > Warning > Suggestion.

Skills replaced the older .claude/commands/ system. They support additional features like supporting files and lazy-loading (the full content only loads when needed, saving tokens).

FAQ

How detailed should my prompts be?

Detailed enough that someone else could understand exactly what you want. If you'd need to clarify something for a human colleague, clarify it for Claude too.

Should I include examples in my prompts?

Yes, especially for formatting. "Format like this: 'Name - Title (Year)'" is clearer than describing the format in words.

How do I make Claude follow a specific style?

Either include style instructions in your prompt or—better—put them in your CLAUDE.md so they apply to every prompt automatically.

What if my prompt is getting too long?

Break it into phases. Or create a skill that encapsulates your complex instructions so Claude can apply them automatically when relevant. You can also use /compact mid-session to compress conversation history, freeing up token space for new instructions.

Related Guides

• How to Use CLAUDE.md Files — persistent context
• Claude Code Prompts & Examples — ready-to-use prompts
• How to Use Plan Mode — safe exploration