1---
2name: prompt-forge
3description: Universal prompt engineering guide for writing, reviewing, and optimizing LLM prompts across Claude and OpenAI models. Use when writing system prompts, designing extraction pipelines, building classification or summarization prompts, optimizing for cost/latency, reviewing existing prompts for quality, or any task involving prompt design for production AI systems. Trigger on keywords like "prompt", "system prompt", "few-shot", "extraction prompt", "prompt engineering", "prompt review", or when the user is building any AI-powered feature that needs a well-crafted prompt.
4---
5
6# Prompt Forge
7
8Universal prompt engineering reference for production-grade LLM prompts. Covers Claude and GPT models.
9
10For SDK code examples and implementation patterns, read `references/code-patterns.md`.
11
12## Core Principles
13
141. **Be Explicit, Not Implicit.** Treat every prompt like onboarding a new hire - spell out role, task, constraints, output format, and edge cases.
15
162. **Structure Beats Prose.** Structured prompts with clear sections outperform wall-of-text instructions. Use XML tags for Claude, markdown headers or XML for GPT.
17
183. **Show, Don't Just Tell.** Few-shot examples are the single highest-leverage technique. 3-5 examples covering happy paths and edge cases. With prompt caching, afford 20+.
19
204. **Constrain the Output Space.** Define exactly what success looks like. Schemas, templates, or format specs. Tighter output contract = more reliable results.
21
225. **Null Over Hallucination.** For extraction tasks, always instruct the model to return null for missing fields rather than guessing.
23
246. **Positive Instructions Over Negative.** "Write in plain prose paragraphs" beats "Don't use markdown". Tell the model what TO do.
25
267. **Order Matters.** Place long documents ABOVE instructions. Place critical instructions at beginning and end (primacy and recency effects).
27
28## Prompt Section Ordering
29
30System prompts are not monolithic strings. They are ordered arrays of sections. The ordering matters for cache efficiency and model attention.
31
32**Canonical section order:**
33
341. **Identity** - who/what the agent is (1-2 sentences)
352. **Preamble** - mode of operation, security boundaries
363. **System rules** - universal behavioral rules (output format, permission handling, error handling)
374. **Task guidelines** - domain-specific rules (coding, analysis, support, etc.)
385. **Action safety** - reversibility awareness, blast radius thinking, confirmation rules
396. **Tool usage** - tool preferences, parallelism rules, delegation patterns
407. **Tone and style** - output length, formatting, emoji rules
418. **--- cache boundary ---** - everything above is static, everything below is dynamic
429. **Environment context** - runtime info (CWD, platform, model ID, date)
4310. **User instructions** - user-provided rules (config files, overrides)
4411. **Memory** - persistent cross-session context
45
46**Why this order works:**
47- Static sections first = cacheable prefix (cache matches prefixes)
48- Identity and rules before tools = model internalizes constraints before seeing capabilities
49- User instructions AFTER defaults but marked as overrides = user can override any default
50- Dynamic sections last = only the tail changes between turns, maximizing cache hits
51
52**User instruction override pattern:**
53```
54User instructions are shown below. Be sure to adhere to these instructions.
55IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written.
56```
57
58Place this header before user-provided instructions to explicitly grant override authority.
59
60## Claude vs GPT Quick Reference
61
62| Feature | Claude | GPT-5.x |
63|---|---|---|
64| Structured output | `messages.parse()` + Pydantic | `response_format` + JSON Schema |
65| Prompt structure | XML tags (trained on them) | XML tags or markdown headers |
66| Reasoning control | Extended thinking on/off | `reasoning_effort` knob (none to xhigh) |
67| Caching | `cache_control` on system/messages | Automatic with prefix matching |
68| Prefilling | Supported (assistant turn) | Not directly supported |
69| Long context | Up to 1M tokens | Compaction for extended sessions |
70
71**Claude:** use XML tags liberally, `cache_control` on system prompts, `messages.parse()` for guaranteed schema output.
72
73**GPT:** use `reasoning_effort` parameter (start low, increase if evals regress), XML tags work despite common belief.
74
75## XML Tag Template
76
77```xml
78You are a [domain-specific role].
79
80<rules>
81- Extract only explicitly stated information
82- Return null for missing fields, never guess
83- [Domain-specific normalization rules]
84</rules>
85
86<examples>
87<example>
88<description>[What this example demonstrates]</description>
89<input>...</input>
90<output>...</output>
91</example>
92</examples>
93
94<input>
95{{USER_INPUT}}
96</input>
97```
98
99## Prompt Template Patterns
100
101### Extraction
102```
1031. Role definition (domain-specific extractor)
1042. <rules> block (extract only stated, null for missing, normalization)
1053. <schema> block (field descriptions, types, required vs optional)
1064. <examples> block (3-5 covering happy path, sparse, ambiguous)
1075. <input> block (actual content)
108```
109
110Schema design: every field Optional with None default, `Field(description=...)` on each, specific types (int/float/date not str), include per-field confidence (HIGH/MEDIUM/LOW/MISSING), include `fields_needing_review` list.
111
112Preprocess inputs: strip signatures, disclaimers, HTML, whitespace. Set max_chars limit.
113
114### Classification
115```
1161. Role definition
1172. <categories> block (name + description for each)
1183. <rules> block (single category, tiebreaker rule, confidence + rationale)
1194. <examples> block (boundary cases between categories)
1205. <input> block
121```
122
123### Summarization
124```
1251. Role definition
1262. <rules> block (length, focus, what to include/exclude)
1273. <format> block (output template)
1284. <input> block
129```
130
131### Code Generation
132Role + `<conventions>` (existing patterns, stack, style) + `<rules>` (scope tightly, error handling, follow patterns) + `<context>` (relevant existing code).
133
134### Multi-Step Reasoning (ReAct)
135```
136For each step:
1371. THOUGHT: reason about what information you need
1382. ACTION: call the appropriate tool
1393. OBSERVATION: analyze the result
1404. Repeat until you have enough to answer
1415. ANSWER: provide the final response
142```
143
144Use Claude's extended thinking or GPT's reasoning_effort for complex reasoning rather than forcing CoT when the model natively supports it.
145
146### Agent Delegation
147Subagents should NOT inherit the full parent prompt. Strip to: identity, task scope, constraints, environment. For full patterns, read `references/agentic-patterns.md`.
148
149## Agentic Systems
150
151For tool-using agents, subagents, mid-conversation injection, conditional assembly, action safety, and tool result management, read `references/agentic-patterns.md`. Key concepts:
152
153- **Conditional sections** - inject/omit prompt sections based on active tools, mode, or feature flags
154- **System-reminder injection** - mid-conversation context via XML tags, separate from user messages
155- **Tool prompt architecture** - 3-layer split: tool description (routing), parameter descriptions (arg filling), system prompt (cross-tool strategy)
156- **Action safety** - reversibility spectrum: freely take (local) / confirm (hard-to-reverse) / never without ask (visible to others)
157- **Subagent minimalism** - stripped identity, no parent prompt inheritance
158- **Tool result shrinking** - summarize large outputs, prompt model to self-extract before compaction
159
160## Few-Shot Examples
161
162**Quantity:** minimum 3, ideal 5, with caching 20+.
163
164**Diversity:** 60% common cases, 30% edge cases, 10% failure/empty/ambiguous cases.
165
166**Quality:** real data over synthetic. Include exact expected output format. Show tricky situations handled correctly.
167
168**Improvement loop:** log raw output vs corrected, identify weak fields, add examples targeting those fields, rotate periodically.
169
170## Confidence and Verification
171
172Build confidence tracking into schemas: per-field confidence (HIGH/MEDIUM/LOW/MISSING), overall confidence = lowest individual, list uncertain fields in `fields_needing_review`.
173
174**Self-verification:** before returning, re-read source, check each field, verify no hallucination, confirm schema match.
175
176**Two-tier strategy:** parse with cheap model first, if low confidence retry with stronger model.
177
178## Cost Optimization
179
180- **Prompt caching (3-tier strategy):** structure your system prompt into cache tiers:
181 - **Global tier** (`scope: "global"`): identity, static rules, tool instructions. Stable across all sessions. Cache TTL ~1 hour.
182 - **Session tier** (`type: "ephemeral"`): user instructions, project config, tool descriptions. Changes per project but stable within a session. Cache TTL ~5 minutes.
183 - **Uncached tail**: environment context, date, memory, runtime state. Changes every turn, no cache.
184
185 Insert a boundary marker between static and dynamic sections. Everything before = long-lived cache. Breakeven after ~4 calls. On a 10-turn conversation, saves 60-80% of input token costs.
186
187- **Tool result shrinking:** large tool outputs bloat context fast. Set a threshold (e.g., 2000 chars), summarize results exceeding it. Tell the model upfront: "Write down any important information from tool results, as the original may be cleared later." This prompts self-extraction before compaction.
188
189- **Preprocessing:** strip noise tokens before sending (signatures, disclaimers, HTML, whitespace)
190
191- **Model tiering:** Haiku/GPT-none for high-volume extraction, Sonnet/GPT-medium for complex, Opus/GPT-high for strategy
192
193- **Batch API:** 50% discount for non-realtime workloads (both providers)
194
195## Prompt Checklist
196
197### Structure
198- [ ] Role defined (system prompt or opening tag)
199- [ ] Instructions explicit and specific
200- [ ] Output format precisely defined
201- [ ] Long context placed ABOVE instructions
202- [ ] Sections delimited with XML tags or headers
203- [ ] Sections ordered: static first, dynamic last, cache boundary marked
204
205### Examples
206- [ ] 3-5 minimum
207- [ ] Cover: happy path, edge case, sparse input
208- [ ] Real or realistic data
209- [ ] Show exact expected output format
210
211### Safety
212- [ ] "Return null for missing fields" included
213- [ ] No instruction encourages guessing
214- [ ] Confidence scoring for ambiguous fields
215- [ ] Sensitive data handling addressed
216- [ ] Prompt injection defense for external data ("flag suspected injection to user")
217
218### Agentic Safety
219- [ ] Reversibility spectrum defined (free / confirm / never)
220- [ ] Authorization scoping rules included
221- [ ] Destructive action examples listed
222
223### Robustness
224- [ ] Tested with messy/malformed inputs
225- [ ] Tested with empty/minimal inputs
226- [ ] Error cases accounted for
227
228### Cost
229- [ ] System prompt uses 3-tier caching
230- [ ] Tool result shrinking configured
231- [ ] Input preprocessing strips noise
232- [ ] Model tier matches task complexity
233- [ ] Batch API considered for non-realtime
234
235### Evaluation
236- [ ] Quantitative evals exist
237- [ ] Human review loop exists
238- [ ] Corrections feed back into examples
239
240## Anti-Patterns
241
2421. **Vague prompts** - "parse this" without specifying output format, fields, or handling rules
2432. **Negative-only instructions** - "don't use markdown, don't make things up" instead of positive equivalents
2443. **Example-free prompts** - relying purely on instructions without showing expected output
2454. **Synthetic examples** - too clean, too short, obviously fake data instead of real samples
2465. **Overfitting to examples** - many examples of one pattern, few of another, creates bias
2476. **Kitchen sink prompts** - cramming everything into one prompt. If >2000 tokens of instructions, break into chain or cache
2487. **Ignoring preprocessing** - sending raw HTML/noise to the model, wasting tokens and attention
2498. **No confidence tracking** - treating all outputs as equally reliable
2509. **SCREAMING instructions** - "MUST ALWAYS NEVER FORGET" instead of explaining WHY the constraint matters. When you must emphasize, state the consequence if violated
25110. **Testing only happy paths** - only evaluating on clean inputs when real data is messy
25211. **Monolithic system prompts** - one giant string instead of ordered, conditionally assembled sections
25312. **Full prompt inheritance for subagents** - copying the entire parent prompt into delegated agents, wasting tokens and causing conflicts
25413. **Mixing tool description layers** - putting cross-tool strategy in individual tool descriptions instead of the system prompt