pavel-molyanov/prompt-master

Prompt Engineering for Reasoning Models

Based on Anthropic and OpenAI guidelines (2025-2026). Every principle here has a motivation — when you understand WHY something works, you follow it more reliably.

Core Principles

The model is already smart

Add only what the model lacks: domain context, constraints, success criteria. Every sentence should justify its token cost. The context window is a shared resource — prompts compete for attention with conversation history, tool outputs, and the model's own reasoning.

Clarity over cleverness

Most prompt failures stem from ambiguity, not model limitations. Test: show the prompt to a colleague with no context. If they're confused about what to do, the model will be too.

Motivation over emphasis

Explain WHY a rule matters. One motivated sentence outperforms ten capitalized words.

When every instruction screams for attention (ALL CAPS, "CRITICAL", "NEVER", "ALWAYS", "MUST"), nothing stands out. Emphasis words signal a poorly written instruction — rewrite it instead of raising the volume. Over-thorough language ("Be THOROUGH", "Make sure you have the FULL picture") also hurts — it inflates token cost without adding signal.

Before:
  CRITICAL: You MUST ALWAYS validate input. NEVER skip validation.
  IMPORTANT: ALWAYS check for edge cases. This is MANDATORY.

After:
  Validate all input before processing.
  Reason: unvalidated input causes pipeline crashes in production.

Positive framing

Default to stating what you want, not what to avoid. Models follow positive instructions more reliably. Long prohibition lists get ignored — they add tokens without adding clarity.

Rewrite when positive form is sufficient:
  Before: Don't use bullet points. Never include code examples.
  After:  Write in prose paragraphs, 2-3 sentences each.

Keep negatives for hard boundaries where positive rewrite loses the prohibition:
  "Return data as JSON. Do not include markdown fences around it."
  — positive alone ("Return raw JSON") may not prevent the common mistake.

Test: does the positive rewrite fully convey the prohibition?
  Yes → rewrite positively.
  No  → keep negative + add reason why it matters.

Examples over rules

1-3 canonical examples transfer knowledge more efficiently than paragraphs of description. Show the desired output — let the model generalize from the pattern.

Compress

Remove filler ("could you please", "I would like you to", "make sure to"). Shorter prompts often perform equally well or better — less noise means stronger signal per token.

Degrees of freedom

Match specificity to the task's fragility. Over-specifying creative tasks stifles the model's reasoning. Under-specifying fragile tasks leads to format errors and broken parsing.

Fragile tasks (parsing specific formats, following exact protocols): prescribe steps. Creative tasks (writing, analysis, design): give constraints and let the model find its path.

High-level guidance

Provide constraints and success criteria rather than step-by-step micro-instructions. The model's own reasoning often exceeds prescriptive procedures. Describe WHAT success looks like — the model figures out HOW.

Techniques That Work

Context over decoration

Provide concrete context (audience, use case, constraints) instead of decorative phrasing. The model gains nothing from flattery.

Before:
  You are an incredibly brilliant and talented expert programmer
  who writes the most amazing code in the world. Please write
  a function that validates emails.

After:
  Write an email validation function.
  Context: TypeScript, used in a signup form, must handle
  international domains. Return {valid: boolean, reason: string}.

Structure with XML tags

Separate instructions, data, and examples with XML tags. This prevents the model from confusing context with instructions. Consistent tag names make handoffs between chained prompts clean.

Before:
  Here's some customer feedback. Also, the format should be
  JSON. And please analyze sentiment. The feedback is:
  "Great product but shipping was slow."

After:
  <instructions>
  Analyze sentiment. Output JSON: {text, sentiment, confidence}.
  </instructions>
  <data>
  Great product but shipping was slow.
  </data>

Examples over explanations

Instead of describing the desired output format in paragraphs, show 1-3 examples. The model generalizes from patterns faster than from rules.

Before:
  When summarizing articles, create a summary that includes
  the main topic as a short phrase, then 2-3 key points as
  bullet items, then a one-sentence practical takeaway.

After:
  Summarize articles in this format:

  <example>
  Topic: Remote work productivity
  - Async communication reduces meetings by 40%
  - Written documentation improves onboarding speed
  Takeaway: Teams that default to async work ship faster.
  </example>

Prompt chaining over mega-prompts

Break complex tasks into focused steps. Each step gets the model's full attention. A chain of 3 focused prompts outperforms one overloaded prompt — empirically shown to reduce error rates.

Before (single mega-prompt):
  Analyze this contract for risks, then draft an email
  to the vendor with concerns, then review for tone.

After (3-step chain):
  Step 1: Analyze <contract> for risks. Output in <risks> tags.
  Step 2: Using <risks>, draft vendor email with proposed changes.
  Step 3: Review <email> for tone. Grade A-F with suggestions.

Define success criteria

Tell the model what good output looks like — not just what to do. Include format, length, audience, and evaluation criteria.

Before:
  Write a good product description.

After:
  Write a product description for noise-canceling headphones.
  Audience: Tech-savvy millennials on a comparison shopping site.
  Format: 80-120 words, no superlatives, focus on specs and
  use cases. End with one differentiating fact vs. competitors.

Refinement

How to improve a prompt that isn't working well:

1. Draft a first version focused on context and success criteria
2. Test against 3-5 representative inputs (include edge cases)
3. Observe the output — collect specific problems, not vague impressions
4. Diagnose each problem: is it ambiguity? missing context? conflicting instructions? wrong format?
5. Plan changes: map each problem to a specific edit (what failed → why → what to change)
6. Refine with targeted edits — change one thing at a time, test each separately
7. Metaprompt: show the model a problematic output and ask "What in this prompt causes this behavior? Suggest a revision."

When to add instructions vs. examples

| Problem | Fix | |---------|-----| | Model misunderstands the task | Add context (audience, use case, constraints) | | Output missing required sections | Add an example showing all sections | | Wrong format or style | Add 1-2 output examples | | Model uses wrong context | Restructure with XML tags to separate data from instructions | | Contradictory behavior | Audit prompt for conflicting rules and resolve them |

Quick Reference

| Instead of | Do this | Why | |------------|---------|-----| | Emphasis words (CAPS, "NEVER", "ALWAYS") | One sentence explaining motivation | When everything screams, nothing stands out | | Lists of prohibitions | State desired behavior; keep negatives only for hard boundaries + motivation | Positive framing is followed more reliably | | "Act as a world-class expert..." | Provide context + success criteria | Flattery adds tokens without adding signal | | One mega-prompt with many tasks | Chain of 3-4 focused prompts | Each step gets full model attention | | Filler ("please", "make sure", "I want you to") | Direct instruction | Fewer tokens = less noise | | Paragraphs describing format | 1-3 examples of desired output | Models generalize from examples faster than from rules | | Step-by-step micro-instructions | Constraints + success criteria | Model's own reasoning exceeds prescriptive procedures |