---
description: Use when creating or editing prompts, system messages, or LLM calls in application code.
alwaysApply: false
---

# Prompts as code

- Prompts live in dedicated files (`prompts/<name>.md` or `prompts/<name>.ts`), not inline string literals scattered in handlers. Each has a name and version.
- Structure system prompts in clear sections: role and goal, context, rules/constraints, output format, examples. Put stable instructions first and variable data last (better for prompt caching).
- Insert variables with a template function and clear delimiters (XML-style tags like `<document>...</document>`), and escape or strip delimiter look-alikes from user input.
- Be specific and positive: say what to do ("Answer in 3 bullet points citing [doc-id]") rather than only what to avoid. State what to do when information is missing.
- For machine-read output, use the provider's structured output / tool schema and validate with zod/Pydantic; don't regex free text.
- Few-shot examples should cover edge cases and be realistic; keep them short and consistent with the required format.
- Untrusted content (user input, retrieved docs, web pages) goes in delimited sections with an instruction that it's data, not instructions.
- Model, temperature, and max tokens come from config next to the prompt.
- Every prompt change updates or adds eval cases (inputs + expected properties) and reports before/after results.
- Log prompt version with each call for debugging.

## Don't
- Don't tell the model to "be accurate" as a substitute for giving it the needed context or tools.