Skip to content

Prompting Best Practices

A prompt is a brief. The same way a vague brief produces a vague design, a vague prompt produces a vague result. The good news: the skills that make a good brief for a human make a good prompt for a model. This page covers the fundamentals everyone should share, whether you are shipping AI inside a product (via the API) or using an AI assistant to write code.

Why this matters — Limitation #1 (Limited memory). A model has a finite context window, and its attention degrades as that window fills. Every irrelevant sentence you add competes with the instructions that actually matter. A precise, well-scoped prompt is not just polite — it directly protects the model's ability to focus on the right thing.

The core idea

Tell the model five things, every time:

  1. The context — are we talking botanic or software engineering? (contract and smart contract refer to different things)
  2. The goal — what outcome you want and why you want it (if it can help).
  3. The constraints — what it must respect (language, libraries, style, performance, what to leave untouched).
  4. The output format — prose, a table, a diff, JSON, a bulleted plan.
  5. The additional context it needs — and nothing more — the specific files, examples, or facts required to do the job. Nothing more.

If you give it those five, you have already beaten most prompts.

Leverage md files: because rewriting the same things over and over quickly becomes annoying, use markdown files to create solid foundations, then reference these files at the beginning of every new session, see Markdown files as external memory.

Be specific about goal, constraints, and output

Models do not read minds; they pattern-match on what you give them. "Make this better" forces the model to guess what "better" means. "Reduce this function from three loops to one without changing its public signature" leaves nothing to guess.

  • State the goal as an outcome, not a vibe. "Fast" → "responds in under 200 ms for 1,000 rows."
  • Name the constraints explicitly. Which framework, which style guide, which files are off-limits.
  • Ask for the shape of the answer. "Give me a markdown table with columns X, Y, Z" gets you a table. Silence gets you whatever the model felt like.

Give context and examples

A short, relevant example is worth a paragraph of description. If you want output in a particular style or structure, show one. (This scales into a formal technique — see Advanced Prompting on few-shot examples.)

But context is a budget, not a free resource. Paste the one function that matters, not the whole file. Point at the two relevant files, not the entire directory. This is the discipline that Context Management is built around.

Show, don't just tell — screenshots and images as input

Modern models are multimodal: they can see, not just read. When something is faster to show than to describe, paste an image straight into the prompt. A screenshot carries the layout, spacing, colors, and exact error text that would take a paragraph to spell out — and that you'd probably get slightly wrong.

Where it earns its keep:

  • A visual bug. Paste a screenshot of the broken UI — "this button overflows its container on mobile" — instead of describing the misalignment in words.
  • A design or mockup to build. Hand over a Figma export, a wireframe, or even a hand-drawn sketch and ask the model to implement the layout.
  • An error or stack trace you're looking at in another tool — a screenshot is faster than retyping and preserves the exact wording.
  • A diagram or chart — an architecture sketch, a schema diagram, or a graph whose trend you want explained.

The rest of this page still applies: pair the image with a clear goal and constraints ("match this mockup, but use our existing Button component"). The picture replaces the description, not the brief.

How you attach one depends on the tool. Most chat surfaces take a paste or drag-and-drop; terminal agents like Claude Code accept an image path or a pasted image. Agents can also capture their own screenshots — for example, driving a browser to reproduce a UI bug (see MCP and Config).

For non-developers: this isn't a coding-only trick. Screenshot a spreadsheet, a slide, or a page from a PDF report and ask the model to pull out the numbers, critique the layout, or summarize it.

Separate instructions from the data

When a prompt mixes your instructions with the material the model should act on — a document to summarize, code to review, text to classify — mark the boundary explicitly. Wrapping the data in XML-style tags (<document>…</document>, <code>…</code>) or clear delimiters tells the model which part is the command and which part is the content, so it won't mistake pasted text for an instruction. It's a small habit that sharply reduces confusion on anything longer than a sentence.

Ask for a plan before code

For anything non-trivial, ask the model to describe its approach before it writes the implementation. This is cheap to read, easy to correct, and catches wrong assumptions before they become 300 lines you have to review. "Before you write any code, outline the steps and the files you'll touch" is one of the highest-return sentences you can add to a prompt. This grows into a whole practice — see Plan and Design First.

State non-goals (what NOT to do)

Telling the model what to avoid is as powerful as telling it what to do. Models tend to be eager: they refactor things you didn't ask about, add abstractions you don't want, and "improve" code that was fine. Head it off:

  • "Do not change the public API."
  • "Do not add new dependencies."
  • "Only touch the file I gave you."
  • "Don't write tests yet — just the function."

Specify a role where it helps

Giving the model a role ("You are a senior security reviewer") nudges its tone, priorities, and vocabulary. It is genuinely useful when the task has a clear professional lens — a security review, a copy edit, an API design critique. It is noise when the task is concrete and unambiguous. Use it as a tool, not a ritual.

Let the model sharpen your prompt

The model is a capable prompt engineer too. When you are not sure how to ask, hand it your rough draft and ask it to improve the prompt before answering it: "Rewrite this prompt to be clearer and more specific, and ask me about anything ambiguous first." You get back a tighter brief — and often a few clarifying questions that surface gaps you hadn't noticed.

This pays off most for a prompt you will reuse — a saved slash command, a system prompt, a template — where the up-front polish earns its cost on every run. It also pairs with the section below: use the model to sharpen the prompt before you send it, then iterate on the output after. (This is a light form of the self-critique technique in Advanced Prompting.)

Iterate

Your first prompt is a draft. Read the output, see where it went wrong, and add the one sentence that would have prevented it. Treat prompting as a short conversation, not a single shot — each correction teaches the model about this task (though, per Limitation #2, it learns nothing for next time; that is what project memory in Memory and Project Rules is for).

Good vs. bad examples

For non-developers: the examples below are about prompting in general — read the left/right contrast, not the code details.

Example 1 — a code change

Prompt
Bad "Fix the login."
Good "Users with expired sessions see a blank page instead of being redirected to /login. In auth/session.ts, the validateSession function returns null on expiry but the caller doesn't handle null. Fix the caller to redirect. Don't change validateSession itself. Show me a diff."

The good version names the symptom, the suspected location, the constraint, and the output format. The model can act instead of guess.

Example 2 — a product/analysis task (non-technical)

Prompt
Bad "Summarize this customer feedback."
Good "Summarize the attached 40 feedback items into a markdown table with three columns: theme, how many items mention it, and a representative quote. Group into at most 6 themes. Don't include feedback about pricing — that's out of scope for this review."

The good version defines the format, the grouping, the size limit, and an explicit non-goal.

Example 3 — generating content with a role and format

Prompt
Bad "Write release notes for version 2.0."
Good "You are writing user-facing release notes for a non-technical audience. Turn the attached changelog into 4–6 bullets, each one sentence, leading with the user benefit, not the implementation. Skip internal refactors. Output as a markdown bullet list."

Don't bloat the prompt

This is the thread that ties back to Limitation #1. More context is not better context. Dumping a whole repository, an entire chat history, or five tangential documents into a prompt makes the model slower, more expensive, and less accurate, because the signal you care about is now buried in noise. The model can get "lost in the middle" of a large context and miss the one instruction that mattered.

The rule of thumb: include exactly what the task needs to succeed, and nothing you'd be embarrassed to defend. If you're not sure a paragraph earns its place, cut it.

Quick checklist

  • Goal stated as a concrete outcome
  • Constraints named explicitly
  • Output format requested
  • Only the relevant context included
  • A screenshot or image attached where showing beats describing
  • Non-goals stated where the model might overreach
  • A plan requested first, for anything non-trivial
  • Role assigned only if it adds a useful lens

Sources