Effective Prompting

Getting good results from Claude Code is less about magic words and more about clear communication — the same skills that make you effective when pairing with another engineer.

Be specific about intent

Vague prompts force Claude to guess what you want. Specific prompts tell Claude exactly what to build, what to avoid, and what 'done' looks like. You don't need to write an essay — just answer the implicit questions: what file, what behavior, what constraints?

Weak: 'add tests for foo.py' — Claude picks whatever it thinks is worth testing
Strong: 'write a test for foo.py covering the edge case where the user is logged out. avoid mocks.' — scope, scenario, and constraints all present
Weak: 'fix the login bug' — Claude has to guess what's broken
Strong: 'users report login fails after session timeout. check src/auth/, especially token refresh. write a failing test that reproduces it, then fix it' — symptom, location, and success condition

When vague is fine

Open-ended prompts like 'what would you improve in this file?' are useful when you're exploring and want Claude to surface things you haven't thought to ask about. Save specificity for when you know what you want.

Give context, not just commands

Claude can read your files and run commands — but it can't read your mind. Point it at the right sources and paste the right details, and you'll get a much more accurate result on the first try.

Use @ to reference files directly: 'look at @src/auth/session.ts and explain how tokens are refreshed'
Paste error output inline rather than describing it: share the actual stack trace, not 'I got a weird error'
Point to existing patterns: 'look at HotDogWidget.php as a reference — follow the same pattern for a new CalendarWidget'
Pipe data in from the shell: cat error.log | claude sends file contents without copying manually

text

# Weak
add a calendar widget

# Strong
look at how existing widgets work in HotDogWidget.php.
follow that pattern to build a CalendarWidget that lets the
user pick a month and paginate forwards/backwards by year.
no new libraries beyond what's already used.

Iterate in small steps

Claude works best in tight feedback loops. Rather than describing an entire feature in one prompt and waiting, ask for one piece at a time. Review it, redirect if needed, then continue. Smaller steps mean mistakes stay small and are easier to catch.

Ask Claude to implement one function, run the tests, then move on
After each change, check the output before asking for the next step
If something looks off, stop with Esc and redirect — don't let a wrong direction run for 10 more steps

Correcting more than twice? Start fresh

If you've corrected Claude on the same issue two or more times in a row, the conversation context has accumulated failed approaches that are actively confusing things. Run /clear and write a new, more specific prompt using what you learned. A clean session with a better prompt almost always beats a long session with accumulated corrections.

Plan before big changes

When a change touches multiple files or you're not sure of the right approach, use plan mode. Claude reads your code and proposes a plan without touching anything on disk. You review it, edit it if needed, then approve. This separates 'figure out what to do' from 'actually do it' — and avoids implementing the wrong solution.

text

# Step 1 — Enter plan mode (Shift+Tab or --permission-mode plan)
# Ask Claude to explore first:
read /src/auth and understand how sessions and login work.
also look at how we store secrets.

# Step 2 — Ask for a plan:
I want to add Google OAuth. What files need to change?
What's the session flow? Create a detailed plan.

# Step 3 — Switch out of plan mode, then implement:
implement the OAuth flow from your plan. write tests for the
callback handler, run them, and fix any failures.

Skip planning for small tasks

Plan mode adds overhead. If you can describe the change in one sentence — 'fix the typo on line 42' — just ask Claude to do it directly.

Course-correct early

Claude occasionally solves problems on the first try, but more often you'll need to steer it. The earlier you redirect, the less you have to undo. Watch what Claude is doing and step in as soon as something looks wrong — don't wait until it's finished to point out a problem.

Press Esc to stop Claude mid-action — your context is preserved so you can redirect immediately
Press Esc twice (or run /rewind) to roll back to a previous checkpoint and try a different approach
Say 'undo that' to have Claude revert its last changes
Run /clear between unrelated tasks so old context doesn't bleed into new work

Key takeaways

Effective prompting comes down to a few habits: be specific about what you want and what done looks like, point Claude at real files and real error output instead of describing them, work in small reviewable steps, use plan mode when the approach is uncertain, and redirect early rather than letting a wrong direction run. For the full reference on these patterns and more, see code.claude.com/docs/en/best-practices.