Writing good prompts

There is no magic prompt. There are no secret incantations. "You are an expert ten-times engineer who never makes mistakes" does not unlock a hidden mode. The reason some people get great results from Claude Code and others struggle comes down to clarity, not phrasing — being specific about what you want, what you don't want, and what counts as done.

The four ingredients of a clear request

Almost every prompt that goes well contains four pieces, in some order:

1. Context. What part of the project is this about? Which file or feature? What were you trying to do?
2. Goal. What should be true when this is done?
3. Constraints. What approaches or libraries to use or avoid? What style to match?
4. Done criteria. How will we know it worked?

You don't need all four every time. For tiny tasks, the goal alone is fine. For anything non-trivial, give all four — it's five extra seconds of typing that saves five minutes of back-and-forth.

Before and after

Vague:

Add a contact form.

Sharper:

On the landing page (src/app/page.tsx), add a contact form below the hero section. Fields: name, email, message. On submit, post to /api/contact(don't implement the endpoint yet — leave a comment). Style it to match the existing buttons. Done when the form renders and console-logs the submitted data on submit.

Same task, dramatically better odds. You've named the file you want changed. You've described the fields. You've scoped what's in and out of this task (no backend yet). You've said how to know it worked.

Provide examples when you can

Sometimes the easiest way to describe what you want is to point at something similar that already exists:

Add an "archive" action to the email list, modelled on how the existing "delete" action works in src/EmailRow.tsx. Same button style, same keyboard shortcut pattern. Use the existing updateEmailStatus helper.

Pointing at an existing pattern ("like X") is much higher-bandwidth than describing the same thing in prose. Claude opens the example, learns the convention, and applies it.

Be explicit about what NOT to do

Negative constraints are underrated. They're often more useful than positive ones, because they prevent the most common drift:

• Don't install new dependencies — use only what's already in package.json.
• Don't refactor the existing function; just add the new behaviour alongside.
• Don't change the database schema — work with what exists.
• Don't add tests yet; we'll write those in a separate pass.

Each "don't" removes a path the agent might otherwise take. That focusing effect compounds across a long task.

Ask for plans, not just edits

For anything non-trivial, ask Claude to think before it touches files. You can do this casually:

Walk me through how you'd approach this before you change anything.

Or formally, by entering plan mode (next lesson). Either way, you get a chance to redirect before any code moves. A two-minute plan prevents a thirty-minute wrong turn.

Following up on a half-right answer

When Claude does most of what you wanted but not quite, resist starting over. Instead, point at the specific gap:

That's most of it. Two things to change: the submit button should be styled with the same outline-and-shadow as the others on this page, and the error message position should be above the form, not below it.

Specific corrections compound. Generic dissatisfaction ("this isn't quite right") tends to produce a slightly different but also wrong attempt.

Phrases that consistently help

A few patterns that tend to improve results in practice:

• "Look at how X is implemented first." Forces Claude to read existing code before writing new code.
• "Don't implement yet — what's the plan?" Pulls back from premature edits.
• "Be specific about what you're unsure about." Surfaces the assumptions early.
• "Check that this still works by running X." Closes the loop with a real verification step.
• "Keep the change minimal."Tells Claude not to opportunistically refactor while it's in the file.

What doesn't help

• Long preambles flattering the model ("you are a brilliant AI..."). Wastes context for no benefit.
• Repeating the same instruction five different ways. The first time is enough; the rest dilutes.
• Pretending you know less than you do (or more). Be honest about your level — Claude calibrates.