# GPT-5 Official Prompting Guide

Source: https://cookbook.openai.com/examples/gpt-5/gpt-5_prompting_guide

This reference summarizes key insights from OpenAI's official GPT-5 prompting guide for building high-quality instruction files.

## Key Principles

### 1. Avoid Contradictory Instructions

**CRITICAL:** GPT-5 follows instructions with surgical precision. Contradictory or vague instructions are more damaging to GPT-5 than other models, as it expends reasoning tokens trying to reconcile contradictions.

**Example of problematic instructions:**
```
Never schedule without explicit consent
[Later in same prompt]
For urgent cases, auto-assign slots without contacting patient
```

**Fix:** Establish clear instruction hierarchy and resolve conflicts:
```
Never schedule without explicit consent
Exception: For urgent cases, auto-assign and then inform patient
```

### 2. When to Ask Clarifying Questions

GPT-5 can be calibrated between autonomy and asking for guidance:

**For maximum autonomy (fewer clarifying questions):**
```markdown
You are an agent - keep going until the query is completely resolved.
Never stop or hand back when you encounter uncertainty.
Research or deduce the most reasonable approach and continue.
Do not ask for confirmation - decide the most reasonable assumption,
proceed, and document it for reference.
```

**For more user interaction (ask when uncertain):**
```markdown
If you need more information to investigate, update the user with 
your latest findings and open questions. Proceed only if user confirms.

For high-stakes actions (payments, deletions), always get explicit
confirmation before proceeding.
```

**Best practice:** Calibrate based on action consequence:
- Low-risk actions (search, read): High autonomy, rarely ask
- Medium-risk (create, modify): Ask if ambiguous
- High-risk (delete, payment): Always confirm

### 3. Tool Preambles for User Experience

For agentic tasks, provide clear upfront plans and progress updates:

```markdown
Tool Preamble Guidelines:
- Always begin by rephrasing the user's goal clearly and concisely
- Outline a structured plan detailing each logical step
- As you execute, narrate each step succinctly and sequentially
- Finish by summarizing completed work distinctly from upfront plan
```

This dramatically improves user experience during multi-step tasks.

### 4. Self-Reflection for Quality

Use GPT-5's self-reflection capabilities for higher quality:

```markdown
Self-Reflection Process:
- First, create a rubric with 5-7 quality categories
- Think deeply about what makes excellent output in each category
- Use the rubric to internally iterate on your response
- If not hitting top marks across all categories, start again
- Do not show rubric to user - for internal use only
```

### 5. Verbosity Control

Use natural language verbosity overrides for specific contexts:

```markdown
Global default: Use concise responses

Context-specific overrides:
- For code: Use high verbosity with clear variable names and comments
- For status updates: Keep brief and to-the-point
- For final summaries: Comprehensive but scannable
```

### 6. Planning for Complex Tasks

Encourage upfront planning:

```markdown
Planning Protocol:
- Decompose the query into all required sub-requests
- Confirm each sub-request is completed before moving to next
- Plan extensively before making tool calls
- Reflect on outcomes of each action
- Only finish when all sub-requests are resolved
```

### 7. Markdown Formatting

GPT-5 does not format in Markdown by default. To enable:

```markdown
Use Markdown **only where semantically correct**:
- `inline code` for file/function names
- ```code fences``` for code blocks
- Lists, tables when appropriate
- \( \) for inline math, \[ \] for block math
```

### 8. Instruction Adherence Best Practices

**Do:**
- Use clear, unambiguous language
- Establish single source of truth for each rule
- Use structured formats like XML tags: `<rule_name>...</rule_name>`
- Be explicit about priority and hierarchy

**Don't:**
- Include contradictory instructions
- Use vague requirements ("be thorough", "be careful")
- Overuse "ALWAYS" and "NEVER" without clear scope
- Mix informal and formal language inconsistently

### 9. Minimal Reasoning Effort (for latency-sensitive apps)

When using minimal reasoning effort:
- Request brief explanations at start of response
- Use thorough tool-calling preambles
- Be maximally explicit in tool instructions
- Include prompted planning sections
- Disambiguate instructions completely

### 10. Meta-Prompting

Use GPT-5 to improve your own prompts:

```markdown
Meta-Prompt Template:
"When asked to optimize prompts, explain what specific phrases 
could be added or removed to elicit desired behavior.

Here's a prompt: [PROMPT]

The desired behavior is [X], but instead it does [Y].

What minimal edits would you make to encourage more consistent 
behavior while keeping existing prompt intact?"
```

## Application to Instructions Files

When creating instructions.md files:

1. **Review for contradictions** - Check entire file for conflicting rules
2. **Calibrate autonomy** - Decide when assistant should ask vs. proceed
3. **Add tool preambles** - If multi-step workflows, request progress updates
4. **Consider self-reflection** - For quality-critical outputs, add rubric creation
5. **Specify verbosity** - Different contexts may need different verbosity levels
6. **Avoid vague imperatives** - Replace "be thorough" with specific behaviors
7. **Use structured XML** - `<section_name>` tags improve instruction adherence
8. **Test for contradictions** - Have GPT-5 review your instructions for conflicts

## Common Patterns from Guide

### Persistence Pattern
```markdown
<persistence>
You are an agent - keep going until query is completely resolved.
Only terminate when problem is solved.
Never stop at uncertainty - research or deduce and continue.
Do not ask for confirmation - document assumptions and proceed.
</persistence>
```

### Exploration Pattern
```markdown
<exploration>
If unsure about information, use tools to gather it - don't guess.

Before responding:
- Decompose request into explicit requirements
- Map scope of codebase/data involved
- Check dependencies and constraints
- Resolve ambiguity proactively
- Define exact deliverables
- Formulate execution plan
</exploration>
```

### Verification Pattern
```markdown
<verification>
Routinely verify your work as you progress.
Don't hand back until certain problem is solved.
Test each step before moving to next.
</verification>
```

### Context Gathering Pattern
```markdown
<context_gathering>
Goal: Get enough context fast.

Method:
- Start broad, then fan out to focused queries
- Parallelize discovery
- Deduplicate and cache
- Stop as soon as you can act

Early stop criteria:
- You can name exact content to change
- Top results converge on one area

Depth:
- Trace only what you'll modify
- Avoid transitive expansion unless necessary
</context_gathering>
```

## Key Takeaways for Instruction Files

1. **Be unambiguous** - GPT-5 will try to follow every instruction precisely
2. **Resolve conflicts** - Any contradictions will impair reasoning
3. **Calibrate autonomy** - Explicitly state when to ask vs. proceed
4. **Structure with XML** - Tags improve instruction adherence
5. **Consider consequences** - Match autonomy level to action risk
6. **Plan for progress** - Multi-step tasks need progress updates
7. **Test for contradictions** - Review carefully or use meta-prompting

# Writing Great Prompts: The Genius Intern Framework

## Imagine This

A genius alien with PhDs in every field just landed on Earth and is now your intern. They can figure out anything... but they have NO idea what "good" looks like in your business context, what your priorities are, or which of the infinite possible approaches you'd prefer.

This framework is your guide to communicating with that genius alien intern.

---

## The Three Types of Prompts

Most prompts fail because they're either over-specified (mechanically prescriptive, treating AI like it can't think) or under-specified (vague and ambiguous, forcing the AI to hedge or guess). The key is **matching your prompt's complexity to the judgment required**.

Every prompt falls into one of three categories:

### Type 1: Do This (Task Prompts)
Execute this specific thing now. Single-use, context-specific requests.

**Examples:**
- "Write a competitive analysis for our board meeting tomorrow"
- "Debug this authentication bug in the login flow"
- "Create a presentation about Q3 results for executives"

**When to use:** You need something done once, with quality tailored to this specific context.

### Type 2: Know How To Do This (Capability Prompts)
Learn this tool, system, or workflow for repeated future use.

**Examples:**
- "Here's how to use the TodoWrite tool"
- "This is our deployment workflow"
- "This tool asks users questions during execution"

**When to use:** You're teaching a reusable capability, not executing right now. The AI needs to know when and how to apply this skill across different contexts.

### Type 3: Learn This Domain First, Then Do This (Learning Journey Prompts)
Acquire domain knowledge before execution.

**Examples:**
- "Learn our MCP protocol, then build an MCP server"
- "Study this medical coding system, then process these claims"
- "Understand our data schema, then write integration code"

**When to use:**
- The concept is outside the AI's training data (new frameworks, emerging tech)
- Company-specific knowledge (internal tools, proprietary systems)
- Specialized domains requiring deep understanding (legal frameworks, medical protocols)

**Most prompts should be Type 1.** Only escalate to Type 2 when you need reusability, and Type 3 when domain knowledge is genuinely missing or complex.

---

## Universal Principles

These apply regardless of prompt type:

### 1. Be Decisively Opinionated

Don't hedge when you should be directive.

<example type="bad">
Maybe make it more concise... if you think that's good? Try to keep it relatively brief unless you need more detail?
</example>

<example type="good">
Keep this under 500 words. Brevity is critical here—executives won't read past page one.
</example>

AIs are good at inference, but they're even better when you just state your preferences. It's not condescending—it's decisive.

### 2. Prompt at the Right Altitude

Don't micromanage (too low) or be vague (too high). Give enough context for smart decisions without prescribing implementation.

<example>
❌ Low: "Use font-family: 'Inter'; color: #6B21A8; font-size: 18px"
❌ High: "Make typography more interesting"
✅ Right: "Never use Inter, Roboto, Arial. Good: JetBrains Mono, Playfair Display. High contrast pairings: display + monospace. Weight extremes: 100/200 vs 800/900"
</example>

Right altitude = decisive constraints + concrete alternatives + principles to apply. Anthropic's frontend skill bans "purple gradients" but doesn't specify hex codes.

### 3. Show Good and Bad, Explain Why

If you have examples of desired output (or common failures), include them with reasoning.

<example type="positive">
"Stripe processed $640B in 2022, up 15% YoY despite economic headwinds. Their competitive moat: developer experience and ecosystem lock-in through 100+ integrations."

<reasoning>
Quantitative metrics + strategic insight + clear defensibility. This is what good competitive analysis looks like.
</reasoning>
</example>

<example type="negative">
"Stripe is a payment processor that helps businesses. They are growing and have many customers."

<reasoning>
No numbers, no strategic thinking, no actionable insight. Pure fluff.
</reasoning>
</example>

**Two rules:**
1. Don't fabricate examples if you don't have real ones—just skip examples entirely
2. Don't paste entire documents as examples—excerpt the relevant parts that make your point

### 4. Embed Decision Frameworks Where They're Relevant

Instead of front-loading all criteria, place decision logic exactly where it matters.

<example>
**Bad structure:** "Here are all the rules upfront: use scripts for X, references for Y, validation for Z..."

**Good structure:**
```
## Scripts
When to include: Same code being rewritten repeatedly
Examples: rotate_pdf.py for PDF rotation tasks
Benefits: Token efficient, deterministic

## References  
When to include: Documentation needed while working
Examples: schema.md for database structure
Benefits: Keeps main instructions lean
```
</example>

This way, when the AI is thinking "should I use a script?" the decision criteria is right there.

### 5. Proactively Address Common Mistakes

Flag predictable failure modes upfront.

<common_mistakes>
- Don't list competitor features—analyze strategic positioning
- Don't use secondary sources as primary—go to earnings calls and company blogs  
- Don't hedge recommendations—be decisive
- Don't exceed 3 pages—executives won't read it
</common_mistakes>

### 6. Use Structure Strategically

AIs benefit from structural markup that would annoy humans. Use XML-style tags to create clear boundaries:

```xml
<example type="good">...</example>
<reasoning>...</reasoning>
<context>...</context>
<common_mistakes>...</common_mistakes>
```

This helps AI parse what's a rule vs. an example vs. meta-commentary. Use it when structure matters, not as decoration.

### 7. Beware Overfitting

When showing examples, write prompts that generalize beyond them. The prompt needs to work on real-world data you haven't seen yet. Teach principles, not pattern matching.

---

## Writing Task Prompts (Type 1)

For single-execution requests, build conceptual understanding before mechanics.

### Core Structure

**Purpose & Context** - What problem are you solving and why does it matter?

<example>
Bad: "Write a competitive analysis."

Good: "I'm presenting to our board tomorrow to convince them we should invest in feature X. I need a persuasive analysis showing market opportunity and competitive gaps."
</example>

The second tells the AI it's writing for decision-makers, needs to be persuasive (not just informative), and should emphasize opportunity.

**Success Criteria** - What must be true for this to be excellent?

<example>
"Must include 3+ quantitative metrics per competitor. Must make a clear recommendation. Should be scannable in 5 minutes by executives who won't read every word."
</example>

Clear quality bar (3+ metrics), deliverable (recommendation), and audience constraint (executive scanning pattern).

**Add only if it helps:**
- Examples with reasoning (if you have real ones)
- Common mistakes to avoid (if failure modes are predictable)
- Constraints or boundaries (budget, timeline, technical limits)

---

## Writing Capability Prompts (Type 2)

For teaching reusable tools, systems, or workflows. These prompts don't execute tasks—they teach the AI how to think about a domain or use a capability across different contexts.

**Important:** Good capability prompts amplify human judgment, they don't replace it. A frontend design skill still requires you to say "use a dark theme" or "make it feel editorial"—the skill just makes that steering more effective by preventing convergence to generic patterns.

### Core Structure

**Purpose** - One sentence. What does this capability enable?

<example>
"Use this tool when you need to ask the user questions during execution."
</example>

**When To Use / When NOT To Use** - Capabilities need clear boundaries.

<example>
**TodoWrite Tool**

When to use: Multi-step tasks (3+ steps), user requests todo list, or scope expands
When NOT to use: Single straightforward tasks, trivial changes, purely conversational requests

User: "Add dark mode toggle. Make sure tests pass!"
→ Uses TodoWrite (multi-step: UI, state, styling, tests)

User: "Add a comment to calculateTotal function."
→ Skips TodoWrite (single-step change, no organizational benefit)
</example>

Without clear boundaries, the AI will either overuse or underuse capabilities. 

**Contrast: Domain thinking vs. tool usage**

TodoWrite teaches "when to use this tool." Anthropic's frontend skill teaches "how to think about design":

```
<frontend_aesthetics>
You tend to converge toward generic outputs. In frontend design, this creates 
"AI slop" aesthetic. Avoid this: make distinctive frontends.

Typography: Choose beautiful, unique fonts. Never use Inter, Roboto, Arial.
Good: JetBrains Mono, Playfair Display, IBM Plex. High contrast pairings: 
display + monospace. Weight extremes: 100/200 vs 800/900.

Avoid: Overused fonts, purple gradients on white, cookie-cutter layouts.
</frontend_aesthetics>
```

This is a capability prompt that prevents convergence to generic patterns while still requiring you to steer ("use dark theme," "editorial feel").

---

## Writing Learning Journey Prompts (Type 3)

Use this structure only when domain knowledge is genuinely missing or requires deep understanding before execution.

### Five-Phase Pattern

**Phase 1: Foundation Learning** - Build conceptual understanding first.
- Core concepts and principles
- Why things work this way
- High-level mental models
- Load foundational documentation

**Phase 2: Detailed Study** - Load specific technical details.
- API documentation and specs
- Edge cases and constraints
- Best practices

**Progressive Context Loading Pattern:**
Don't load everything upfront. Specify just-in-time knowledge delivery:

```
**Load these resources as needed:**
- Phase 1: [📋 MCP Overview](./overview.md)
- Phase 2: For Python, fetch `https://github.com/.../python-sdk/README.md`
- Phase 2: For TypeScript, fetch `https://github.com/.../typescript-sdk/README.md`
- Phase 4: [✅ Evaluation Guide](./eval.md)
```

**Phase 3: Synthesis and Planning** - Apply learned knowledge.
- Create implementation plan
- Design architecture from first principles
- Identify tools and resources needed
- Anticipate challenges

**Phase 4: Execution** - Implement using learned patterns.
- Step-by-step implementation
- Reference learned principles as you go
- Branch for different paths (e.g., Python vs. TypeScript)

**Phase 5: Validation** - Check against learned standards.
- Quality checklist
- Test against principles
- Evaluation criteria

### Resource Map

Provide a consolidated view of ALL resources with clear loading instructions:

```markdown
# Reference Files

Load these resources as indicated during each phase:

## Core Documentation (Phase 1)
- **Protocol Spec**: Fetch from `https://protocol-spec.com`
- [📋 Best Practices](./reference/best_practices.md)

## SDK Documentation (Phase 2)  
- **Python SDK**: Fetch from `https://github.com/python-sdk/README.md`
- **TypeScript SDK**: Fetch from `https://github.com/ts-sdk/README.md`

## Implementation Guides (Phase 2-3)
- [🐍 Python Guide](./reference/python.md) - Complete examples
- [⚡ TypeScript Guide](./reference/typescript.md) - Complete examples

## Evaluation Guide (Phase 5)
- [✅ Testing Guide](./reference/eval.md) - Validation criteria
```

---

## Quick Reference

**Which type do I need?**

```
Do I just need this done once?
→ Type 1: Task Prompt
└─ Purpose + Success Criteria + Examples (if helpful)

Will the AI need to do this repeatedly in different contexts?  
→ Type 2: Capability Prompt
└─ Purpose + When/When Not + Examples with reasoning + Common mistakes

Does the AI lack the domain knowledge to do this well?
→ Type 3: Learning Journey Prompt  
└─ Five phases: Foundation → Study → Plan → Execute → Validate
```

**Default to Type 1.** Only escalate when reusability or domain knowledge genuinely requires it.

---

## The Core Philosophy

Treat AI like a genius remote teammate. That means:
- Assume high intelligence—don't micromanage
- Prompt at the right altitude—not too detailed, not too vague
- Give context for decisions, not just instructions
- Be decisively clear, not hedge-filled
- Show examples with reasoning when helpful
- Match prompt complexity to judgment required
- Trust questions over guesswork

Most prompts should be short. The complexity should match the stakes.

# Writing for AI Teammates

"Prompt engineering" is dead.

Not because AI got worse—because it got better. Today's AI models like Claude Sonnet 4.5 have both high intelligence and high emotional intelligence. They don't need tricks. They need what any smart remote teammate needs: clear, context-rich written communication.

The challenge isn't finding magic words to make AI understand. The challenge is the same one facing any async-first remote company: how do you communicate clearly in writing when you can't tap someone on the shoulder for clarification?

---

## The 37signals Parallel

Companies like 37signals (makers of Basecamp) have spent decades perfecting async remote culture. Their survival depends on one thing: great writing. When your teammate is in a different timezone, every piece of communication needs to work without real-time clarification.

The same is true for AI.

When you write instructions for AI, you're doing exactly what a 37signals employee does when they write a project brief or document a process: you're communicating with someone smart who isn't physically present. The principles are identical:

**Assume high intelligence.** Don't explain what a function is if you're asking someone to write code. Don't define basic terms. Trust them to figure out HOW once they understand WHAT and WHY. Micromanagement wastes everyone's time.

**Give a reason** Don't just say WHAT to do—explain WHY it matters. Who's the audience? What does success look like? What constraints exist? Smart people (and smart AIs) need context to make good decisions, not just step-by-step instructions.

**Be decisively clear.** Hedging wastes time in async communication. "Make it concise if you want" becomes "Keep it under 500 words." Have opinions. State them. Your remote teammate (or AI) needs to make decisions in your absence—give them the clarity to do so.

**Match your length to the stakes.** A quick status update shouldn't be an essay. A major architectural decision shouldn't be a one-liner. The size of your communication should reflect its importance. Writing too much for simple things wastes time. Writing too little for complex things wastes even more time in back-and-forth clarification

**Ask clarifying questions early.** If something isn't clear, ask before you start working. Making assumptions and going through the feedback cycle wastes everyone's time. Better to spend two minutes clarifying upfront than two hours redoing work based on wrong assumptions. This applies equally whether you're writing instructions or receiving them.

Bad remote culture has two failure modes: either everyone lives in Slack asking endless clarifying questions, or work takes twice as long because everything gets done wrong the first time and needs redoing. Then people conclude "remote work doesn't work." But teams like 37signals with strong written communication make remote work a competitive advantage—they can hire great writers anywhere in the world. The difference isn't remote versus in-person. The difference is clear writing versus unclear writing.

The same applies to AI.

---

## The Brevity-Clarity Balance

Here's where it gets hard: great async writing requires balancing brevity with comprehensive clarity.

Making ordered lists isn't enough. It's easy to write eight subheadings with four sub-bullets each. But these are all-or-nothing — if you stop reading at bullet three, you've missed potentially critical information in bullets four through eight.

Great writing doesn't work that way.

Great writing reveals information gradually, like a progressive image loading. At every point you stop reading, you have a complete picture—just at different levels of detail. The first sentence gives you the core idea. The first paragraph adds key insight. Each section adds resolution. But at no point are you left with an incomplete or misleading understanding.

This is the inverted pyramid from journalism. This is what Nassim Taleb means by *via negativa*—you're not adding fluff, you're strategically revealing depth.

Consider the U.S. Constitution: about 4,400 words. It established an entire system of government. Brevity isn't about being terse—it's about respecting your reader's time while giving them everything they need.

At every stopping point, it should be complete.

---

## The Zen of Writing for AI Teammates

Context is better than commands.

Clarity is better than brevity.

Brevity with clarity is better than both.

Assume intelligence.

Explicit is better than implicit.

Unless you're being explicit about the obvious.

Examples are better than explanations.

Show good. Show bad.

Hedging helps no one.

Questions are cheap. Rework is expensive.

If you can't skim it, you wrote it wrong.

Match your length to the stakes.

Trust, but clarify early.

As models get smarter, communication matters more, prompting matters less.

There is no prompt engineering—only clear writing.

<caveat>Although sometimes there are hacks</caveat>

But hacks have a half-life.