Prompt Engineering

# Prompt Engineering — System Prompts, Examples, Reasoning, Structured Output & Safety

Patterns for the *single LLM call* — designing, constraining, and hardening the
instruction-plus-context payload a model sees. Vendor-neutral; provider features
(prompt caching, constrained decoding, "thinking" modes) appear as **capability
classes**, not API names, because the names move faster than the ideas. For
multi-step orchestration see the sibling `agentic-workflows.md`; for retrieval
mechanics see `rag-patterns.md` (this file does **not** re-teach RAG).

The governing rule: **a prompt is code.** It has a contract, inputs, edge cases,
versions, and tests. Treat "tweak the wording" with the same suspicion you'd treat
"tweak the regex" — unmeasured, it's a guess.

---

## System-Prompt Design

A durable system prompt has the same skeleton regardless of model or task. Order
matters — put the stable, identity-defining material first (it anchors behaviour
*and* caches well; see §Context Engineering).

| Block | Answers | Notes |
|---|---|---|
| **Role / persona** | "Who are you acting as?" | One line. Sets vocabulary and default assumptions. |
| **Objective** | "What is the single goal of this call?" | One task per prompt. Multiple goals → split or chain. |
| **Constraints** | "What must always / never happen?" | Scope, tone, length, forbidden actions, data boundaries. |
| **Context / inputs** | "What does the model get to work from?" | Delimited; mark provenance (trusted vs. untrusted). |
| **Output contract** | "What exactly must come back?" | Format, schema, required fields, what to do when unsure. |
| **Definition of done** | "How does the model know it's finished?" | Explicit success criteria + the "no answer" escape hatch. |

### Principles that survive model upgrades

- **Be explicit, not clever.** Most prompt failures are ambiguity, not model
  weakness. Spell out the requirement; don't hint at it.
- **Positive instructions beat negatives.** "Respond in formal English" outperforms
  "don't be casual." A negative names the bad behaviour without describing the good
  one, and models latch onto named tokens. When you must forbid something, also
  state the replacement: *"Do not invent values; if a field is unknown, emit `null`."*
- **One task per prompt.** A prompt doing classification *and* extraction *and*
  formatting will do all three worse. Decompose (see `agentic-workflows.md`).
- **Spell out the definition of done**, including the failure path. The single most
  valuable instruction in a grounded system is the escape hatch: *"If the context
  does not contain the answer, reply exactly `INSUFFICIENT_CONTEXT` — do not guess."*
- **Instruction ordering: lead with identity, end with the immediate task.** Models
  attend most strongly to the start and end of context (primacy/recency); bury
  nothing critical in the middle of a long prompt.

### Minimal skeleton