Claude Code prompt guide

How to prompt Claude Code

1. Give Claude a check it can run itself (tests, build, lint, screenshot diff) and tell it to iterate until the check passes.
2. Scope the task: the specific file, the scenario and what 'done' looks like.
3. For multi-file or unclear work, explore and plan in plan mode first, then implement; skip the plan if the diff fits in one sentence.
4. Reference files with @path rather than describing where code lives.
5. Point to an existing pattern in the codebase to copy.
6. For bugs, give the symptom, the likely location and the error text, and ask for a failing test before the fix.
7. Ask it to fix the root cause rather than suppress the error.
8. For big features, have Claude interview you and write SPEC.md, then implement in a fresh session.
9. Use subagents for wide investigations to keep the main context clean.
10. Keep a short CLAUDE.md (run /init) with commands, style differences and gotchas, and nothing it can work out from the code.
11. Ask for evidence: commands run, test output, screenshots.
12. Run /clear between unrelated tasks, and after two failed corrections, rewrite the prompt.

The shape of a good prompt

[Task and why] [Context: @files, pattern to follow, constraints] [Requirements / edge cases] [Verification: command or test to run, iterate until pass] [Process: plan first? subagents?] [Deliverable: commit/PR, show evidence]

Avoid

• Unscoped 'investigate X' prompts that read hundreds of files
• Tasks with no way for Claude to check its own work
• A long CLAUDE.md full of things Claude can infer from the code
• Mixing unrelated tasks in one session
• Using 'think hard' and expecting extra reasoning (only 'ultrathink' works)

Example

Request add rate limiting to our API

Add per-IP rate limiting to the public API.

Context: middleware lives in @src/middleware/; follow the structure of @src/middleware/requestLogger.ts. Routes are registered in @src/app.ts.

Requirements:
- 100 requests/minute per IP on /api/*; /health exempt
- Return 429 with a Retry-After header and our standard JSON error shape
- Use the existing Redis client in src/lib/redis.ts; no new dependencies

First explore and give me a short plan of files to change. After I approve: implement, add tests covering under-limit, at-limit, over-limit and the /health exemption, run `npm test` and `npm run typecheck`, and iterate until both pass. Show me the test output.