Prompts that work the first time

What you’ll be able to do

Write prompts that consistently get the right change on the first or second try, and know what to do when they don’t.

The four parts of a good task prompt

Part	Question it answers	Example
Goal	What should be true afterwards?	“Users can reset their password by email.”
Context	Where, and what’s relevant?	“Auth lives in @src/auth. Email is sent via @src/lib/mailer.ts.”
Constraints	What must it not do?	“No new dependencies. Keep the existing API shape.”
Done means	How do we know it worked?	“Add tests, run npm test, and show me the diff.”

You don’t need all four every time, but when a result disappoints, one of them is usually missing.

Before and after

Vague:

add caching

Specific:

The /products endpoint in @src/routes/products.ts hits the database on every
request. Add an in-memory cache with a 60-second TTL keyed by the query string.
No new dependencies. Add a test proving the second call within 60s doesn't hit
the DB (mock the repository). Run the tests.

The second prompt takes 30 seconds longer to write and saves a round of back-and-forth.

Ways to give context

• @path/to/file or @folder/ to point at code
• Paste an error or stack trace verbatim. Don’t paraphrase it.
• Drag in a screenshot of a UI bug, or paste it (Ctrl+V, or Alt+V on Windows)
• Point at an example: “Follow the same pattern as @src/routes/orders.ts”
• Pipe it in: cat error.log | claude -p "what's the root cause?"

Exercise: rewrite three prompts

In any project, take these vague prompts and rewrite each one using the four parts. Then run your rewritten versions:

1. “write some tests”
2. “the README is bad”
3. “speed this up” (pick any slow-looking function)

For each one, compare the result with what you’d have got from the vague version. Try a vague version too, then /clear before the next one.

When the result is wrong

Don’t start over. Give feedback the way you would to a colleague:

• “That works, but use the existing logger instead of console.log.”
• “Revert the change to config.ts, which is out of scope.”
• “The test passes but it doesn’t test the edge case where the list is empty.”

If you’ve corrected the same thing twice, it belongs in CLAUDE.md. That’s next.

Verify it worked

• You rewrote all three vague prompts with goal, context, constraints and a definition of done
• At least one prompt used @ to reference files
• You corrected a result with specific feedback instead of starting over