Welcome to my digital garden. 🌱

Tim Le

How to write better AI prompts

A practical way to write prompts for AI assistants and coding agents: the five parts every good prompt has, examples, a debugging loop for prompts that fail, and the templates I reuse every day.

How to write better AI prompts

Most of my day is spent talking to AI models. Claude Code runs next to my editor, a chat assistant helps with research and writing, and a few small features I build call a model through an API. After a lot of hours doing this, I am convinced of one thing: the quality of the answer is mostly decided before the model starts writing. It is decided by the prompt.

"Prompt engineering" sounds like a bag of magic phrases. It isn't. Writing a good prompt is the same skill as writing a good ticket for a teammate who is very fast, very well read, and has never seen your project. If a smart new colleague would need to ask you three questions before starting, the model needs those answers too. It just won't ask; it will guess.

This post is the practical version: what a good prompt contains, how to fix one that doesn't work, and the small templates I reuse.

Why vague prompts fail

A model fills every gap in your prompt with the most likely interpretation. "Most likely" means "most common on the internet", not "what you meant". Ask for "a function to validate emails" and you get a generic regex, maybe in a language you don't use, with an explanation you didn't want.

What I usually see when an answer is disappointing:

  • The goal was implied, not stated. I knew why I wanted it; the model didn't.
  • The context was in my head. The framework version, the existing helper, the constraint from the last meeting.
  • "Done" was undefined. So the model stopped too early, or kept polishing things I didn't ask about.
  • The format was left to chance. I wanted a diff and got an essay.

Every one of these is a gap I left, not a weakness of the model. That is good news, because gaps are easy to close.

The five parts of a good prompt

When I look at the prompts that work well for me, they almost always contain the same five parts. Not always in this order, and not always more than a sentence each, but all five are there.

The five parts of a good prompt: goal, context, constraints, done criteria and output format

1. Goal: what and why. One or two sentences on the outcome you want and the reason behind it. The "why" matters more than people think. "Make this page load faster because users on mobile drop off before the form appears" leads to very different work than just "make it faster".

2. Context: what the model can't know. Paths, names, versions, the relevant snippet, the error message verbatim, what you already tried. Give the facts the model would otherwise have to guess or go looking for. Leave out the rest; a wall of loosely related text makes the answer worse, not better.

3. Constraints: the rules of the road. What must stay the same, what libraries are allowed, what style to follow, what not to touch. Agents in particular love to "helpfully" refactor nearby code. One line like "don't change the public API" prevents a lot of review time.

4. Done criteria: how we both know it worked. A test that should pass, a command that should succeed, a behavior to check. This turns an open-ended request into a finishable task, and it gives an agent something to verify against instead of declaring victory.

5. Output format: what to give back. A diff, a JSON object, five bullets, a table, a commit message. If you will paste the answer somewhere, say what shape it must have.

Here is what that looks like in practice for a coding agent:

Goal: users report that the cart total
is wrong after removing a coupon. Fix it.

Context:
- Cart logic: app/composables/useCart.ts
- Coupon removal: removeCoupon() there
- Repro: add 2 items, apply SAVE10,
  remove it -> total stays discounted

Constraints:
- Keep the useCart() return shape
- No new dependencies

Done when:
- New test in tests/cart.spec.ts covers
  the repro and passes
- `pnpm test cart` is green

Output: the change as a diff and one
sentence on the root cause.

That took me about a minute to write. Compare it with "the cart total is broken after coupons, can you fix it": the agent would first have to find the cart code, guess the repro, decide on its own what "fixed" means, and probably explain everything at length.

Before and after

The difference is easiest to see side by side. The same request, written two ways:

A vague prompt compared with a specific prompt for the same task, with the gaps highlighted

The specific prompt is not longer because it is wordy. It is longer because it contains information. A useful self-check: read every sentence and ask "would the answer be different without this?" If not, delete it.

Techniques that actually help

Beyond the five parts, a handful of techniques consistently make a difference for me. None of them are tricks; they all come down to giving the model clearer information.

Show an example. If you want a specific format or tone, one good example beats a paragraph of description. For structured output, paste one sample object. For writing, paste a short passage in the voice you want. Two or three varied examples work even better than one, because the model generalizes from the pattern instead of copying a single case.

Separate instructions from material. When the prompt includes a document, a log or code to work on, mark clearly where it starts and ends. Simple tags work well:

Summarize the incident below for a
non-technical audience in 5 bullets.

<log>
...pasted log lines...
</log>

Without the boundary, the model can mistake text inside the material for instructions, or the other way around.

Say what to do, not only what to avoid. "Don't use jargon" is weaker than "write for a product manager who doesn't code". A positive description gives the model a target; a list of don'ts only gives it fences.

Ask for a plan first on big tasks. For anything bigger than a small fix, I ask the agent to read the relevant code and propose a plan before writing anything. Reviewing a ten-line plan is much cheaper than reviewing a 400-line diff that went in the wrong direction. In Claude Code, plan mode is built for exactly this.

Give it room to think on hard problems. For debugging, tricky logic or a decision with trade-offs, asking the model to reason through the options before answering usually improves the result. For simple lookups it just adds noise, so I use it selectively.

Assign a role only when it adds information. "You are a senior engineer" on its own does little. "Review this as a security engineer looking for injection and auth issues" is useful, because the role tells the model what to look for.

When a prompt doesn't work: debug it

When an answer is wrong, the instinct is to reply "no, that's wrong, try again". That rarely works well, because the model still has the same missing information. I treat a bad answer as a bug report about my prompt.

The prompt debugging loop: run, read the output, find the gap, fix the prompt, run again

The loop I follow:

  1. Read the output carefully. Where exactly did it go off course? The first wrong assumption is the interesting part, not everything after it.
  2. Name the gap. Was it a missing fact (context), a misread goal, a broken rule (constraint), stopping too early (done criteria), or the wrong shape (format)?
  3. Fix the prompt, not the answer. Add the missing sentence. If I'm in a long chat, I often edit the original message or start a fresh conversation with the improved prompt, instead of stacking corrections on top of a confused thread.
  4. Run it again and compare.

Mapping failures to the five parts makes this fast:

SymptomUsually missing
Solves a different problemGoal (the why)
Invents files, APIs or namesContext
Rewrites code you didn't ask aboutConstraints
Stops halfway or over-polishesDone criteria
Right content, unusable shapeOutput format

When the same correction keeps coming up across sessions ("we use pnpm, not npm", "tests live next to the file"), it doesn't belong in the prompt anymore. It belongs in the project instructions file the agent reads every time, like CLAUDE.md.

Prompts for agents vs. chat

The five parts apply everywhere, but the emphasis shifts with the tool.

In a chat, the model only knows what you paste. Context is everything: include the snippet, the error, the versions. Format matters a lot, because you are the one copying the answer out.

With a coding agent, the model can read files and run commands, so you don't need to paste whole files. Instead, point it to the right places (paths, function names, the failing test) so it doesn't burn time exploring. Done criteria matter most here, because an agent works in a loop and needs a clear signal to stop. "Run the tests and fix failures until they pass" is a complete instruction to an agent; it is meaningless to a chat model.

In code that calls an API, the prompt is part of your product. It deserves the same care as any other code: keep it in version control, put user input inside clear delimiters, ask for structured output you can validate, and test changes against a handful of real examples before shipping. A prompt that works on the three inputs you tried may break on the fourth.

Templates I reuse

I don't write every prompt from scratch. A few short templates cover most of my day. I keep them in a snippets file and fill in the blanks.

Bug fix:

Bug: <what happens vs what should>
Repro: <steps or failing test>
Where: <file paths / functions>
Constraints: <what must not change>
Done: <test/command that must pass>
Return: diff + one-line root cause

Code review:

Review this diff for bugs, security
issues and missing tests. Ignore style.
For each finding: file:line, the
problem, a concrete fix. Max 10 items,
most severe first.

Explain unfamiliar code:

Explain how <feature> works in this
repo. Start from <entry file>. Give me
the call flow as a short numbered list
with file paths, then the 2-3 things
most likely to surprise a newcomer.

Writing:

Rewrite the text below for <audience>.
Goal: <what they should do after>.
Keep: <facts/terms that must stay>.
Length: <limit>. Tone: <example>.

<text>...</text>

They are deliberately short. The structure reminds me to include the five parts; the content is always specific to the task.

Common mistakes

A few patterns I still catch myself doing:

  • Over-prompting. Pages of rules "just in case". The important instructions get diluted, and the model follows the noise. Shorter and precise beats long and exhaustive.
  • Shouting. ALL CAPS and "VERY IMPORTANT" everywhere. Modern models follow calm, clear instructions well; if everything is critical, nothing is.
  • Hidden assumptions. "Use the usual approach." The model doesn't know your usual.
  • Fixing by arguing. Ten rounds of "no, not like that" in one thread. Start over with a better prompt instead.
  • Never checking. Trusting a confident answer without running it. A good prompt raises the hit rate; it doesn't replace verification.

Conclusion

Better prompts come from clearer thinking, not magic words. Before I send anything non-trivial, I run a quick mental check: does this say what I want and why, give the facts the model can't know, state the rules, define done, and ask for a usable shape? When the answer is still off, I treat it as a missing sentence in my prompt and go find it.

The nice side effect is that this habit makes me better at writing tickets, specs and messages for humans too. A prompt that a model can act on without guessing is usually one a colleague could act on as well.