Skip to content

1. Writing clear instructions

Beginner · 12 min read

Most bad outputs come from missing information, not from a weak model. The model can't ask "who is this for?" or "how long should it be?"; it guesses. Clear instructions remove the guessing. This page builds on the anatomy of a prompt and goes further: context, the reason behind rules, success criteria, ordering and prefill.

1.1 The new-colleague test

Before sending a prompt, imagine handing it to a smart colleague on their first day. They know English, coding and the world, but nothing about your company, your users or this task. Could they do the job from the prompt alone?

A new colleague would ask… Put it in the prompt
Who is this for? The audience: "for a customer on a phone", "for the on-call engineer"
What is it for? The goal: "so the agent can decide whether to escalate"
What does good look like? Success criteria, length, format, an example
What if the input is weird? Edge cases: empty input, wrong language, missing data
What must I never do? Hard rules, with the reason behind them

1.2 Give the reason, not only the rule

A rule with a reason generalises. The model applies the reason to cases your rule didn't mention.

❌  Never use bullet points.

✅  Your reply is read aloud by a text-to-speech voice on a phone call, so write in short spoken sentences.
    Avoid bullet points, tables, URLs and symbols, because they sound wrong when read aloud.

With the reason, the model also avoids things you forgot to list: emoji, markdown headings, "see below".

1.3 Define success

Say what a good answer contains and how it will be used. Vague quality words ("good", "detailed", "professional") mean different things to different people, and to models.

Write a product description for the store page.
A good description:
- opens with the main benefit in one sentence, for an Indian student preparing for interviews;
- lists 3–5 concrete things inside the product (not adjectives);
- is 60–90 words, with no exclamation marks and no claims we can't prove ("best", "guaranteed").

1.4 Say what to do, in numbers where you can

Weak Strong
Be concise Answer in at most 3 sentences
Don't be too technical Explain it for a first-year student; define any term you use
Don't make things up If the documents don't contain the answer, reply exactly "I don't know"
Use a friendly tone Write like a helpful shop assistant: warm, short sentences, no slang

1.5 Order matters in long prompts

With long inputs (contracts, transcripts, many retrieved chunks), put the documents first and the instructions and question last. Models attend most reliably to the start and the end of the context, and the question at the end is fresh when the answer begins.

def long_doc_prompt(document: str, question: str) -> str:
    return (
        f"<document>\n{document}\n</document>\n\n"          # long data first
        "Answer the question using only the document above.\n"
        "Quote the sentence you relied on, then give the answer.\n\n"
        f"<question>{question}</question>"                   # instructions + question last
    )

doc = "Clause 4. Either party may end this agreement with 30 days' written notice.\n" * 2
print(long_doc_prompt(doc.strip(), "How much notice is needed to end the agreement?"))
Output
<document>
Clause 4. Either party may end this agreement with 30 days' written notice.
Clause 4. Either party may end this agreement with 30 days' written notice.
</document>

Answer the question using only the document above.
Quote the sentence you relied on, then give the answer.

<question>How much notice is needed to end the agreement?</question>

For a system prompt that stays the same on every call, keep it first and unchanged: that also makes it cacheable (see prompt caching).

1.6 Prefill: start the answer for the model

Some APIs let you write the beginning of the assistant's reply. The model continues from there, which is a strong way to force a format:

# no-run
messages = [
    {"role": "user", "content": "Extract the invoice number and total from this text: ..."},
    {"role": "assistant", "content": "{"},          # prefill: the reply must continue as JSON
]

Prefill is supported by some providers (for example Anthropic's Messages API) and not others; where it isn't, use structured output instead.

1.7 Lint your prompts

A simple check in code catches prompts that are missing a key part before they ever reach a model:

import re

CHECKS = {
    "audience or purpose": r"\b(for (a|an|the)\b|so that|so the)\b",
    "output format":       r"\b(json|bullets?|table|sentences?|words|format|reply with)\b",
    "unsure behaviour":    r"\b(if (you|the) .*(not|n't|unsure|missing)|i don't know)\b",
    "length limit":        r"\b(at most|no more than|up to|under) \d+",
}

def lint(prompt: str) -> list[str]:
    text = prompt.lower()
    return [name for name, pattern in CHECKS.items() if not re.search(pattern, text)]

weak = "Summarise this ticket."
strong = ("Summarise this ticket for the on-call engineer in at most 3 bullets. "
          "If the ticket doesn't say when the problem started, write 'start time unknown'.")
print("weak  :", lint(weak))
print("strong:", lint(strong))
Output
weak  : ['audience or purpose', 'output format', 'unsure behaviour', 'length limit']
strong: []

It's a rough heuristic, not a quality score, but it's a cheap pre-commit check for a team's prompt library.

1.8 Common mistakes

  • Contradictions: "be brief" in the system prompt and "explain in detail" in the user template. The model picks one at random. Read the whole assembled prompt, not each part separately.
  • Hidden assumptions: "use our usual format". The model has never seen it; show it.
  • SHOUTING: "YOU MUST ALWAYS…" in capitals makes modern models over-apply the rule. Calm, specific wording with a reason works better.
  • Rules for problems you don't have: every extra rule costs tokens and attention. Add rules when an eval shows a failure, not just in case.

Interview questions

Why explain the reason behind an instruction?

A bare rule covers only the cases it names. With the reason ("this is read aloud on a phone"), the model can infer the right behaviour for cases you didn't list, such as avoiding emoji or URLs. It also reduces over-application of rules in situations where they don't make sense.

Where should the question go in a prompt with a long document?

After the document. Put long data first, wrapped in clear tags, and the instructions and question at the end. Models use the start and end of the context most reliably, and keeping the stable part first also helps caching.

What is prefilling, and when is it useful?

Writing the first tokens of the assistant's reply so the model continues from them, for example { to force JSON or <answer> to skip preamble. It's a strong format control on APIs that support it; elsewhere use structured output features.

Practice

  • Take a one-line prompt from your project and run the new-colleague test on it. Add audience, goal, success criteria and an unsure rule.
  • Add a "language" check to lint that passes when the prompt names a reply language.

Next: 2. Few-shot examples in depth Back to: Prompt Engineering overview · Notes overview