Writing Prompts That Land on the First Try
After using Claude Code for a while, you’ll notice most failed sessions trace back to your prompt, not the model. Claude can infer intent, but you can’t expect it to read your mind.
Lock down the scope
“Optimize this code” — what comes out is a lottery. Optimize for what? Performance? Readability? Removing dead code?
A good prompt names the file, the scenario, and how to verify:
Write an edge-case test for logged-out users in src/auth.ts. No mocks.
The tighter the scope, the more predictable the output. Vague prompts only make sense when you actually want the agent’s opinion — “what would you improve in this file” is fine, but keep it scoped so it doesn’t wander into hundreds of files.
Point at an existing example
Claude learns conventions faster from real code than from description.
Don’t explain “our project uses camelCase and interface names start with I”. Just say:
Follow the pattern in src/services/user.ts to implement the new interface.
One sentence beats a hundred words of description.
Bug reports need structure
I use this format for debugging and it rarely fails:
Symptom: User gets a 404 after login
Location: src/router/index.ts lines 42-56, route guard logic
Fix criteria: Redirect to the URL in the redirect param, or go to home
Then add: “Write a failing test first, then fix it.” This keeps the agent from pretending it fixed something when it didn’t.
Use /btw for quick side questions
Mid-task, you might need to check something unrelated — “what’s the API signature of this package?” If you ask in the main session, it pollutes context. Use /btw what's the API signature of this package instead. The answer appears in an overlay and never enters conversation history. Zero context cost.
Don’t paraphrase code yourself
You don’t need to read code to Claude. Feed it directly:
@filereferences to project files- Pipe command output:
cat package.json | claude -p "check deps" - Paste screenshots if you’re on the desktop version
Paraphrasing is tiring and you’ll miss details.
One thing at a time
Split this component into three, fix its performance issue, and add a loading state.
This prompt asks three things at once. Split them:
- “Split into three child components, keep the existing API”
- “Optimize list rendering with virtual scroll”
- “Add a loading state”
Each one gets its own session, its own review, its own commit. Sounds slower, but it’s faster than having Claude fix things in circles.
Let Claude interview you for big features
For larger features with many unknowns, there’s a useful pattern from the official docs: start with a minimal description and have Claude interview you using AskUserQuestion.
I want to add a user invitation feature. Interview me using AskUserQuestion.
Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs.
Don't ask obvious questions, dig into the hard parts I might not have considered.
Keep going until we've covered everything, then write a complete spec to SPEC.md.
Claude goes back and forth until it has a complete picture, then produces a spec. Start a fresh session to execute it — clean context, written document to reference.