swarm-zap/memory/references/openai-prompting-best-practices.md

OpenAI — Prompt Engineering Best Practices

Source: https://platform.openai.com/docs/guides/prompt-engineering Source: https://platform.openai.com/docs/guides/optimizing-llm-accuracy Fetched: 2026-03-05 Applies to: GPT-4.1, GPT-5, GPT-5 mini, o-series (reasoning models)

---

Model Types and When to Use Each

Model Type	Speed	Cost	Best For	Prompting Style
Reasoning (o3, o4-mini)	Slow	High	Complex multi-step, math, planning	Less instruction-heavy — model reasons internally
Large GPT (gpt-5.2, gpt-4.1)	Medium	Medium	General tasks, coding, analysis	Explicit instructions work well
Small GPT (gpt-5-mini, gpt-4.1-nano)	Fast	Low	Simple tasks, formatting, classification	More explicit instructions needed

When in doubt: gpt-4.1 is the recommended balance of intelligence, speed, and cost.

Important: Reasoning models and GPT models need to be prompted differently:

• Reasoning models: Don't over-specify step-by-step reasoning — model handles this internally.
• GPT models: Benefit from explicit step-by-step instructions ("think through this step by step").

---

Message Roles and Priority

Role	Priority	Purpose
developer	Highest	System rules, business logic, application-level instructions
user	Medium	End-user inputs and requests
assistant	—	Model-generated responses

Note: instructions parameter in Responses API = top-level developer message, takes priority over input.

Important: instructions is per-request only — not carried over in conversation continuations (use message array for persistent instructions in multi-turn).

---

Core Prompt Engineering Techniques

1. Write Clear Instructions

• Be explicit about desired format, length, tone, and constraints.
• Provide context — WHY the instruction matters.
• Specify what to do rather than only what not to do.
• Use numbered steps when sequence matters.

2. Split Complex Tasks into Subtasks

• Complex tasks are error-prone as single prompts.
• Chain simpler prompts: classification → generation → verification.
• Intent classification → routing to specialized prompts.
• Summarize long conversations before sending to model.

3. Give the Model Time to "Think" (GPT models)

• Ask the model to reason before answering: "Before answering, think through the problem step by step."
• Ask the model to check its own reasoning: "Review your answer and identify any errors."
• Ask for a chain of thought in a scratchpad before final output.

4. Provide Reference Text

• Include documents, examples, or facts the model should use.
• Instruct the model to answer ONLY based on provided context.
• Ask it to quote from reference material when answering.

5. Use External Tools

• Retrieval (RAG): when model lacks current or proprietary knowledge.
• Code execution: for precise math, data analysis.
• Function calling: for structured external actions.

6. Test Changes Systematically

• Define eval criteria before changing prompts.
• Test on diverse samples including edge cases.
• Track performance metrics, don't rely on vibes.
• Pin to specific model snapshots (e.g., gpt-4.1-2025-04-14) for production.

---

Prompt Structure Best Practices

Recommended order in developer message:

1. Identity: Purpose, communication style, high-level goals.
2. Instructions: Rules, what to do and not do, output format.
3. Examples: Few-shot examples (in <example> blocks or as messages).
4. Context/documents: Reference material (with XML tags for clarity).
5. Delimiters: Use markdown headers AND XML tags to delineate sections.

Use XML tags to separate document content from instructions:

<document>
  <source>filename.txt</source>
  <content>
    ...
  </content>
</document>

---

LLM Optimization Framework (from Optimizing LLM Accuracy guide)

Two Axes of Optimization

Context optimization (right information in context):

• Model lacks factual/domain knowledge → add RAG
• Knowledge is outdated → use retrieval
• Needs proprietary data → inject context

LLM optimization (consistent behavior):

• Inconsistent output format → add examples (few-shot)
• Wrong tone/style → adjust system prompt
• Reasoning not followed → fine-tune

Optimization Ladder

1. Start: Simple prompt + evaluation set
2. Add static few-shot examples → improves consistency
3. Add dynamic few-shot (RAG) → improves accuracy for diverse inputs
4. Fine-tuning → for high-volume tasks needing consistent style/format
5. Fact-checking step → for accuracy on high-stakes tasks

Evaluation Best Practices

• Build eval set of 20+ Q&A pairs before advanced optimization.
• Metrics: ROUGE (quick), BERTScore (semantic similarity), GPT-4 as evaluator (human-like judgment).
• Separate evaluation on high-stakes "tail" queries from aggregate metrics.
• Use evals to monitor prompt performance across model upgrades.

---

Structured Outputs

• Use response_format: json_schema to enforce JSON output schemas.
• Eliminates format retries entirely.
• Reduces output tokens (structured output is more concise than prose).
• Works with: GPT-4.1+, GPT-5, GPT-5 mini, o-series.

---

Relevance for Our Subagent Prompts

For GPT models (copilot-gpt-* subagents)

• Use developer role for system/role instructions.
• Include few-shot examples for structured output tasks.
• Use response_format: json_schema for any scored/structured council output.
• For simple advisory tasks: gpt-5-mini or gpt-4.1 is appropriate.
• Reserve gpt-5.2+ for complex reasoning tasks.

For reasoning models (o3, o4-mini)

• Don't over-specify reasoning steps — model handles internally.
• Use for tasks requiring deep analysis or multi-step planning.
• Much slower and more expensive — use sparingly.

Subagent model selection cheat sheet

Task	Recommended Model
Council advisors (opinion/brainstorm)	zai/glm-4.7 (free) or copilot-gpt-5-mini
Council referee / synthesis	copilot-claude-sonnet-4.6
Code generation / review	copilot-claude-sonnet-4.6 or copilot-gpt-5.2
Simple formatting / classification	zai/glm-4.7-flash or copilot-gpt-5-nano
Deep reasoning / architecture review	copilot-claude-opus-4.6 or o3