Skip to main content

6.2 Prompt engineering

Instruction clarity​

WeakStrong
"Summarise this well""Three bullets, max 20 words each, covering decision, owner, and deadline"
"Be careful with dates""Dates as YYYY-MM-DD. If a date is ambiguous or absent, return null — never infer one"
"Escalate if needed""Escalate when: the policy has no rule for the case, the customer asks for a human, or you cannot progress after two tool failures"
"Don't hallucinate""Answer only from the supplied document. If the answer is not in it, say not found in source"
"Review this code""Flag only: unhandled errors, missing input validation, and N+1 queries. Ignore style"

The pattern: replace an adjective with a testable criterion. A criterion you cannot evaluate is a criterion the model cannot satisfy reliably — and it is also an eval you cannot write.

Positive framing beats prohibition. "Return null for a missing field" works better than "do not make up values", because it names the action to take.

System versus user placement​

ChannelHoldsLifetime
systemRole, standing rules, output contract, tool-use policy, safety boundariesEvery request — put it in the cached prefix
messages (user)The specific task, the data, the questionThis turn
Mid-conversation system messageAn operator instruction that arrives later (mode switch, injected state)From that point on, without invalidating the cached prefix; model-gated
Tool descriptionWhen and when not to use a capabilityEvery request that includes the tool
CLAUDE.md / rulesRepo-wide or path-scoped conventions for Claude CodeEvery session / matching paths

Placement rules that decide items:

  • Standing behaviour goes in system; per-request specifics go in messages. Putting the standing rules in every user turn wastes tokens and breaks the cache.
  • Do not put an operator instruction in a user message where untrusted content also lives — the model cannot distinguish authority you did not mark.
  • Do not edit the top-level system mid-conversation for a new instruction; append a mid-conversation system message so the cached prefix survives.
  • Instructions about choosing a tool belong in the tool description, not the system prompt.

Output constraints​

RequirementMechanism
Exact JSON shapeoutput_config.format (structured outputs), or a tool with strict: true
A closed set of valuesenum in the schema — not a prose instruction
LengthAn explicit numeric bound ("max 40 words"), plus a sane max_tokens
No preambleSay so in system, and prefer a schema that has nowhere to put prose
Uncertainty expressibleA nullable field, or an explicit "unknown" enum member

Constrain shape with the schema, judgment with criteria and examples. Trying to get shape reliability from prose alone is the most common self-inflicted wound in this domain.

Few-shot examples​

  • 2–5, diverse, boundary-covering. Include the near-miss and the negative case.
  • Same format as the real input and output, so the model is not transferring across formats.
  • In the cached prefix, because they are input tokens on every request.
  • Stop when accuracy plateaus — more examples then just cost money.
  • Few-shot fixes fuzzy judgment. It does not fix compliance (use a gate) or tool selection (fix the description).

Iterative refinement​

A loop, not a rewrite:

  1. Build the eval set first — real inputs, expected outputs, including the cases that already failed.
  2. Measure the current prompt as a rate.
  3. Read the failures and classify them: ambiguous instruction, missing criterion, wrong placement, schema too strict, context missing, or a genuine capability limit.
  4. Change one thing.
  5. Re-measure on the whole set, watching for regressions on cases that used to pass.
  6. Commit the prompt with its score.
The refinement anti-patterns

Piling on emphasis ("IMPORTANT!! ALWAYS!!") instead of adding a criterion · changing several things at once so nothing is attributable · tuning on the one input a stakeholder complained about · keeping instructions written for an older model — over-prescriptive scaffolding actively degrades newer models, so delete as part of refinement, not just add.

Input sanitization​

Untrusted input is data, not instruction. Before it enters the prompt:

StepDetail
Delimit and labelWrap it in a named tag and state that its contents are data to analyse
Strip or neutralise control contentZero-width and bidirectional characters, HTML comments, hidden elements — the classic carriers of hidden text
NormaliseOne encoding, bounded length, known media types
Never concatenate into systemAuthority is exactly what you are withholding
Scope the turn's toolsRead-only tools while processing untrusted content
Validate on the way out tooOutput derived from untrusted input is still untrusted for downstream systems

Sanitization reduces exposure; it does not eliminate injection. The enforceable control is on the action side — see 7.1.

Quiz​

  1. Question 1

    Which instruction is most likely to reduce fabricated dates in extraction output?

  2. Question 2

    Halfway through a long, cached conversation the application must switch the assistant into a terse mode. Which change preserves the cached prefix?