How to write prompts that get the result you want (with Claude Code)

The quality of what you get from an AI tool depends heavily on what you ask for. The model is capable; it just can't read your mind. Most bad outcomes come from prompts that leave out the things a human developer would ask about before starting. These habits work in Claude Code, in Claude chat and in most AI tools.

Give it the context a new hire would need

Say who the app is for, what it does and why this change matters. "Add a filter" is a guess waiting to happen. "Trainers have 40+ clients and can't find people quickly. Add a search box to the client list that filters by name as you type" gives the assistant the goal, not just the task, so it can make sensible decisions about details you didn't mention.

Define what "done" looks like

Describe the finished result the way you'd check it: "When I type 'sam' the list shows only clients whose name contains 'sam', ignoring capitals. Clearing the box shows everyone again. It works on a phone." Clear acceptance criteria are the biggest single improvement most people can make.

Set the constraints

Tell it what not to do as well as what to do: "Don't add new libraries", "Keep the existing design", "Only change the client list page", "Don't touch the database". Constraints stop helpful-but-unwanted changes, the most common source of "it fixed one thing and broke another".

Ask for a plan before code

For anything bigger than a small fix, ask for the plan first, or use plan mode in Claude Code. Then read it. You'll catch misunderstandings in thirty seconds that would otherwise take an hour to untangle. Try "Before you start, ask me any questions you need answered", too. It often surfaces decisions you hadn't thought about.

One thing at a time

"Build my whole app" produces something large, generic and hard to check. "Build the sign-up page" produces something you can test in five minutes. Work in small steps, check each one, commit it, then move on. Small steps are also easy to undo.

Show, don't describe

• Errors: paste the exact error message and what you did just before it, not "it's broken".
• Design: share a screenshot or a link to a page you like and say which parts you like.
• Data: give two or three real examples of the input and the output you expect.
• Docs: link the official documentation for the service you're connecting, so it works from the current version.

Ask it to check its own work

End bigger requests with how to verify: "Run the app and confirm the page loads", "Add a test for the empty-search case", "Check no secret keys are exposed to the browser". Then check the important things yourself as well. You're the product owner; it's your app.

Keep standing rules in one place

Rules you'd otherwise repeat in every prompt belong in your project's CLAUDE.md: your stack, your style, "explain things in plain English", "every database change is a migration". See getting started with Claude Code.

Before and after

Vague:

Add payments.

Clear:

Goal: trainers pay $29/month for the Pro plan, which unlocks unlimited
clients. Free accounts are limited to 5 clients.

Please:
1. Add a Pricing page with Free and Pro, using our existing card styles.
2. Use Stripe Checkout in subscription mode (price ID is STRIPE_PRICE_PRO).
3. Mark the user as Pro only from a verified Stripe webhook.
4. Show an upgrade prompt when a free user adds a 6th client.

Constraints: no new UI libraries; keys come from .env; don't change
existing tables except adding columns to profiles via a migration.

Done when: a test card payment upgrades my account, and cancelling in
the customer portal downgrades it. Show me the plan before writing code.

The second prompt is longer, but it saves hours: it states the goal, the steps, the limits and how to know it worked.

When it goes off track

• Stop early. If it's heading the wrong way, interrupt and redirect rather than letting it finish.
• Rewind instead of patching. If a change made things worse, go back to before it and ask again with a clearer prompt.
• Start fresh for a new task. Long conversations drift; a new session with a clear prompt is often faster.
• Ask why. "Explain why you did it this way" teaches you the codebase and exposes wrong assumptions.

Next in the series: add a database and user logins with Supabase.