How to Prompt Claude Code Effectively

Most of the difference between a Claude Code session that lands a clean, verified change and one that produces confident-looking code you have to unwind comes down to the prompt. Not cleverness — structure. A good prompt tells the agent what "done" means, where to look, and how to prove it worked. A vague one leaves all three to guessing, and guessing is where the rework comes from.

This is a guide to the parts of a prompt that actually move the outcome, each with a before/after so you can see the shape. None of it is about magic phrasing. It's about giving the agent the same brief you'd give a fast, capable engineer who has never seen your repo.

State the intent and the acceptance criteria

The single biggest upgrade is telling Claude what success looks like before it starts. An agent that knows the acceptance criteria writes toward them and can check its own work against them. An agent that only knows the surface request will happily satisfy the letter of it and miss the point.

Before:

Add pagination to the orders endpoint.

After:

Add pagination to GET /api/orders. Accept limit (default 20, max 100) and a cursor query param. Return { items, nextCursor }, where nextCursor is null on the last page. Keep the existing response shape for each item unchanged. Done means: a request with no params returns the first 20, and following nextCursor walks the full set without gaps or repeats.

The second version isn't longer for the sake of it — every clause removes a decision Claude would otherwise make for you, probably differently than you intended. The bounds (max 100), the null-on-last-page contract, the "don't change the item shape" constraint: those are exactly the things a bare request leaves ambiguous, and ambiguity is what you end up reviewing and correcting.

You don't need a spec document. One or two sentences of "done means…" is usually enough to change the whole trajectory.

Point at the right files

Claude does its sharpest work when its context is small and relevant. If you make it discover the codebase by grepping around, it fills the window with noise and reasons over a blurry picture. If you name the files, it reads the right ones and matches what's already there.

Before:

We have a bug where discounts sometimes come out negative. Can you fix it?

After:

Discounts sometimes come out negative. The math lives in services/pricing.ts (applyDiscount), and the endpoint that calls it is routes/coupons.ts. Look at those two first. Match the error-handling style already in that service.

Pointing at files does two jobs at once: it narrows the search so the reasoning stays crisp, and it anchors Claude to your existing patterns instead of a plausible-but-foreign approach. If you genuinely don't know where the logic lives, say that — "find where discount math happens, then show me before changing anything" — which turns the discovery into an explicit, reviewable step rather than a silent detour.

The related habit: when you switch to an unrelated task, clear the context (/clear) so the previous task's files aren't still hanging around, quietly polluting the next answer.

Ask it to plan before it edits

For anything non-trivial, get a plan before any file changes. This is where you catch the wrong data model or the missed concurrency case while the fix is still a sentence, not a rewrite. Claude Code's plan mode is built for exactly this — it explores and proposes without touching files until you approve — but you can also just ask.

Before:

Refactor the auth middleware to support API keys as well as sessions.

After:

Before editing anything, outline how you'd add API-key auth alongside the existing session auth in the middleware. Tell me which files change, how you'll tell the two credential types apart, and the riskiest assumption in your approach. Wait for my go-ahead.

The payoff is the "riskiest assumption" line. That's where you find out Claude was about to trust an unvalidated header, or run the key check after the session check in a way that lets one bypass the other. Reading a three-line plan costs thirty seconds; finding the same problem in a finished 200-line diff costs the whole detour. For genuinely hard problems, nudging it to reason longer ("think through the edge cases first") before it commits earns its keep here too.

Demand verification — real evidence, not "it compiles"

A typecheck or a green build is not verification. It tells you the code is well-formed, not that it's correct — different claims. If a change has a runtime surface, insist the agent actually exercise it and paste what came back, both the happy path and the failure path.

Before:

Great, does it work?

After:

Verify it end to end. Call the endpoint with a valid coupon and show me the response, then call it a second time with the same coupon and show me the "already redeemed" path. Paste the actual output, not a description of it.

What honest verification looks like:

$ curl -s -X POST localhost:3000/api/coupons/redeem -d '{"code":"SAVE10","cartId":"c_1"}'
{"discount":10,"total":90}          # happy path ✓
$ curl -s -X POST localhost:3000/api/coupons/redeem -d '{"code":"SAVE10","cartId":"c_1"}'
{"error":"coupon already redeemed"} # failure path ✓ — the guard fires

If you don't see evidence like that — an actual response body, a log line, a test that ran — the change wasn't verified, however confidently it's described. Ask for it. (And if there's genuinely nothing to run, like a types-only change, the honest answer is "no runtime surface to exercise," not a fake pass.) For Claude to run your checks at all, it has to know the commands, which is the strongest argument for keeping them in CLAUDE.md — more on that next.

Stop re-typing: encode repeated instructions

Here's the tell that you're prompting inefficiently: you're typing the same instructions every session. "Match our error format." "Scope every query by account_id." "Run these four checks before you call it done." Those don't belong in your prompt — they belong in a file the agent reads automatically.

Standing project rules go in CLAUDE.md, the project-memory file Claude Code loads at the start of every session. Put your exact build, test, and lint commands there, plus the conventions and gotchas that aren't obvious from the code. Now "run the checks" is implicit — the commands are already in context.

Repeatable procedures go in a skill: a Markdown file (conventionally a SKILL.md under a .claude/skills/ directory) that Claude pulls into context when its description matches the task. Write that description for the trigger, not for a human — name the exact situations and keywords, because the name and description are essentially all Claude has to go on when deciding whether to fire.

---
name: ship
description: >
  Use before committing any change. Runs Plan, Implement, Verify,
  and Self-review gates. Trigger on "commit", "ship", "ready to merge".
---
# Ship
1. Plan: state what changes, which files, and the riskiest assumption.
2. Implement: match the surrounding code's patterns and error shape.
3. Verify: exercise the change — paste real output, not "it compiles."
4. Self-review: re-read the diff; flag scope gaps instead of burying them.

With that skill installed, the whole intent-plan-verify discipline this article describes becomes a habit the agent applies on its own, instead of a paragraph you retype. (Exact frontmatter fields and directory conventions are worth confirming against the official docs, since the tooling evolves — but the concept is stable.) If you'd rather start from working examples than a blank file, the free claude-code-starter repo ships a ship skill, a CLAUDE.md template, and an adversarial-review subagent you can read and adapt.

The through-line

Every technique here does the same job from a different angle: it removes a decision the agent would otherwise make silently. Acceptance criteria remove "what does done mean." Naming files removes "where do I look." Planning removes "is this even the right approach." Verification removes "did it actually work." And moving repeated instructions into CLAUDE.md and skills removes the decision entirely — once, and for the whole team.

The model is already capable. Effective prompting is mostly about being specific up front so that capability lands the first time — and about noticing when a good prompt has become a good file.

Related guides

• Safe Refactoring With Claude Code
• Custom Slash Commands in Claude Code
• Claude Code Subagents: A Practical Guide