Step-by-step guide to writing Claude Code prompts that produce specific, actionable output. Pattern + worked examples + common mistakes + how to debug a bad response.
Writing a good Claude Code prompt is a craft skill — not a trick. The same five elements appear in every prompt that works. Once you internalise them, you can write a usable prompt in 60 seconds.
Vague (bad):
Review this code and tell me what's wrong with it.What you get: Five paragraphs of prose covering "consider adding type hints", "you might want to extract that into a function", "this could be more pythonic". Nothing you can ship.
Good:
Review the diff in this branch as a skeptical senior engineer.
For each issue:
- file:line
- severity 1 (nit) to 5 (production-breaking)
- category: correctness | security | performance | readability | testing
- one-line minimal fix
Output as a markdown table sorted by severity descending.
Constraints:
- Max 12 issues — pick the highest-value
- Do NOT propose new features
- Do NOT recommend refactors larger than 10 lines
- If the diff is fine, say so in one sentence and stop
Read: git diff main...HEADWhat you get: A 12-row table you can work through line by line.
Vague (bad):
Refactor src/api/users.py to be cleaner.Failure mode: Claude renames variables, reformats imports, splits a 30-line function into four files, and updates 12 unrelated tests. Now your diff is unreviewable.
Good:
In src/api/users.py, the function create_user() has cyclomatic complexity
12. Reduce it to under 10.
Constraints:
- No renames (functions, variables, anything)
- No formatting changes (no reordering imports, no quote style changes)
- No new files
- No new dependencies
- No changes to files other than src/api/users.py
- Preserve exact behaviour — same inputs produce same outputs/raises
Approach order:
1. Early returns / guard clauses
2. Extract one helper function (in same file) for the validation block
3. Only if 1+2 doesn't suffice, split into multiple functions
After: run `pytest tests/test_users.py -x` and confirm green.
Show me the diff before applying.Vague (bad):
I want to add real-time notifications to this app. Build it.Failure mode: Claude builds the wrong thing. Or the right thing on the wrong stack. Or both.
Good:
I want to add real-time notifications to this app. Before any code,
propose 3 approaches:
1. Polling — clients poll an endpoint every N seconds
2. Server-Sent Events
3. WebSockets
For each:
- 3-sentence description of how it works in THIS codebase
- Files that would change (list with file:line ranges)
- Infrastructure changes needed (Redis? a queue? a sticky-session LB?)
- The biggest risk
- A rough estimate of work in T-shirt sizes (S/M/L)
Then recommend one with a one-paragraph justification.
Do NOT write code yet. Wait for "go with approach N".Most "prompt engineering" advice focuses on positive instructions. The bigger lift in Claude Code is negative constraints — Claude is biased toward doing more than asked. Add these as needed:
| Failure mode | Constraint that prevents it |
|---|---|
| Sneaky reformatting | "No formatting changes. No import reordering. No quote-style changes." |
| "Helpful" renames | "No renames. Preserve all existing function/variable/file names." |
| Suggesting refactors during a bugfix | "Fix the bug only. No 'while I'm here' refactors." |
| Adding dependencies | "No new dependencies. Use only what's already in package.json/pyproject.toml." |
| Splitting into too many files | "All changes in [FILE]. No new files." |
| Skipping tests | "After changes, run [TEST COMMAND]. Confirm green before reporting done." |
| Implementing before planning | "Output the plan. Do NOT write code. Wait for go-ahead." |
| Padding with low-value findings | "Max N findings. Pick the highest-value." |
When the response isn't what you wanted, ask: which of the five elements was missing or weak?
When a prompt produces the right output three sessions in a row without manual edits, it's ready to live in CLAUDE.md. Below three uses, it's still a draft — keep refining the bracketed slots.
You don't have to invent these prompts from scratch. The Claude Code Power Prompts PDF has 30 production-tested prompts across six workflows. Each has been through the three-session test. Paste them into CLAUDE.md and they become part of your standard kit. £3 tonight (first 10 buyers), £5 standard, instant PDF after Stripe checkout.