NOTES / PROMPTING AND CONTEXT ENGINEERING
Prompt design
Writing instructions a model can follow: separate the parts of a prompt, pitch rules at the right altitude, explain the why, and test with a cold reader.
From prompts to context
Anthropic describes prompt engineering as the methods for writing and organising instructions to get good results, and context engineering as the wider job of curating the whole set of tokens the model sees at inference time, including tools, retrieved data and message history1. A good prompt is still the foundation. This note covers the single prompt; the rest of the section covers everything around it.
Diagram: my own. A common way to organise a prompt, not a required template.
Separate the parts
When a prompt mixes instructions, background, examples and variable input, the model has to work out which is which. Anthropic’s guide recommends wrapping each kind of content in its own descriptive XML tag, such as instructions, context and input, to reduce misreading2. The same idea appears in Anthropic’s engineering advice to organise a system prompt into clearly delineated sections1. Tag names are not magic; consistency is the point.
Pitch it at the right altitude
Anthropic’s context engineering post warns about two failure modes. One is hard-coding brittle if-then logic into the prompt, which is fragile and hard to maintain. The other is vague guidance that assumes the model shares your context1. The target is specific enough to steer behaviour and flexible enough to give the model strong heuristics to apply.
Diagram: my own, illustrating the trade-off described in 1.
Habits that help
- Be clear and direct. State the task, the audience and what good output looks like. Anthropic’s guide treats clarity as the first lever2.
- Give the reason behind a rule. A model can generalise from “do X because Y” better than from a bare command. This is guidance I am summarising from the docs’ emphasis on explaining context2.
- Set a role in one line. The guide notes that even a single sentence of role in the system prompt focuses tone and behaviour2.
- Put examples in tags. See Few-shot examples.
- Say what to do, not only what to avoid. My own rule of thumb from practice.
- Test with a cold reader. If a colleague with no context would be confused by your prompt, the model probably will be too. This heuristic is widely attributed to Anthropic’s guide; I have not verified the exact wording, so I give it as paraphrase.
Treat prompts like code
Prompts change behaviour as surely as code does. Keep them in version control, change one thing at a time, and run an eval set before and after. Anthropic’s overview also cautions that not every failing eval is best fixed by prompting; sometimes the answer is a different model, better tools or fine-tuning2.
Next: Few-shot examples.
Sources
- [1]Effective context engineering for AI agents — Anthropic Engineering · 2025PARAPHRASED
- [2]Prompting best practices — Anthropic, Claude Platform docsPARAPHRASED