6.2 Prompt engineering
Instruction clarity
| Weak | Strong |
|---|---|
| "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
| Channel | Holds | Lifetime |
|---|---|---|
system | Role, standing rules, output contract, tool-use policy, safety boundaries | Every request — put it in the cached prefix |
messages (user) | The specific task, the data, the question | This turn |
Mid-conversation system message | An operator instruction that arrives later (mode switch, injected state) | From that point on, without invalidating the cached prefix; model-gated |
Tool description | When and when not to use a capability | Every request that includes the tool |
CLAUDE.md / rules | Repo-wide or path-scoped conventions for Claude Code | Every session / matching paths |
Placement rules that decide items:
- Standing behaviour goes in
system; per-request specifics go inmessages. 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
systemmid-conversation for a new instruction; append a mid-conversationsystemmessage so the cached prefix survives. - Instructions about choosing a tool belong in the tool description, not the system prompt.
Output constraints
| Requirement | Mechanism |
|---|---|
| Exact JSON shape | output_config.format (structured outputs), or a tool with strict: true |
| A closed set of values | enum in the schema — not a prose instruction |
| Length | An explicit numeric bound ("max 40 words"), plus a sane max_tokens |
| No preamble | Say so in system, and prefer a schema that has nowhere to put prose |
| Uncertainty expressible | A 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:
- Build the eval set first — real inputs, expected outputs, including the cases that already failed.
- Measure the current prompt as a rate.
- Read the failures and classify them: ambiguous instruction, missing criterion, wrong placement, schema too strict, context missing, or a genuine capability limit.
- Change one thing.
- Re-measure on the whole set, watching for regressions on cases that used to pass.
- Commit the prompt with its score.
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:
| Step | Detail |
|---|---|
| Delimit and label | Wrap it in a named tag and state that its contents are data to analyse |
| Strip or neutralise control content | Zero-width and bidirectional characters, HTML comments, hidden elements — the classic carriers of hidden text |
| Normalise | One encoding, bounded length, known media types |
Never concatenate into system | Authority is exactly what you are withholding |
| Scope the turn's tools | Read-only tools while processing untrusted content |
| Validate on the way out too | Output 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
- Question 1
Which instruction is most likely to reduce fabricated dates in extraction output?
- Question 2
Halfway through a long, cached conversation the application must switch the assistant into a terse mode. Which change preserves the cached prefix?
Links
- https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview
- https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/be-clear-and-direct
- https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/multishot-prompting
- https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/system-prompts
- https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/use-xml-tags
- https://platform.claude.com/docs/en/build-with-claude/structured-outputs