Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Select an option

  • Save rafaelcalleja/9a14d83f583128806f2d75d2d68771c5 to your computer and use it in GitHub Desktop.

Select an option

Save rafaelcalleja/9a14d83f583128806f2d75d2d68771c5 to your computer and use it in GitHub Desktop.
Best practices for prompt engineering - Article from Claude Blog with expanded resources

Best practices for prompt engineering

Get better AI results with prompt engineering techniques from the team behind Claude.

Source: Claude Blog
Date: November 10, 2025
Reading time: 5 min


Introduction

Context engineering has emerged as an increasingly important part of working with LLMs, with prompt engineering as its essential building block.

Prompt engineering is the craft of structuring instructions to get better outputs from AI models. It's how you phrase queries, specify style, provide context, and guide the model's behavior to achieve your goals.

How to use prompt engineering

At its most basic level, prompt engineering is just modifying the query you pass your LLM. Often it's simply adding information to the query before you make your actual requestbut knowing which information is the right information to share is the secret to engineering a great and effective prompt.

Core techniques

Be explicit and clear

Modern AI models respond exceptionally well to clear, explicit instructions. Don't assume the model will infer what you wantstate it directly.

Example: Creating an analytics dashboard

  • Vague: "Create an analytics dashboard"
  • Explicit: "Create an analytics dashboard. Include as many relevant features and interactions as possible. Go beyond the basics to create a fully-featured implementation."

Best practices:

  • Lead with direct action verbs: "Write," "Analyze," "Generate," "Create"
  • Skip preambles and get straight to the request
  • State what you want the output to include, not just what to work on
  • Be specific about quality and depth expectations

Provide context and motivation

Explaining why something matters helps AI models better understand your goals and deliver more targeted responses.

Example: Formatting preferences

  • Less effective: "NEVER use bullet points"
  • More effective: "I prefer responses in natural paragraph form rather than bullet points because I find flowing prose easier to read and more conversational."

Be specific

Specificity in prompt engineering means structuring your instructions with explicit guidelines and requirements.

Include:

  • Clear constraints (word count, format, timeline)
  • Relevant context (who's the audience, what's the goal)
  • Desired output structure (table, list, paragraph)
  • Any requirements or restrictions

Use examples

Examples shine when explaining concepts or demonstrating specific formats. Also known as one-shot or few-shot prompting.

Pro tip: Start with one example (one-shot). Only add more examples (few-shot) if the output still doesn't match your needs.

Give permission to express uncertainty

Give the AI explicit permission to express uncertainty rather than guessing. This reduces hallucinations and increases reliability.

Example: "Analyze this financial data and identify trends. If the data is insufficient to draw conclusions, say so rather than speculating."

Advanced prompt engineering techniques

Prefill the AI's response

Prefilling lets you start the AI's response for it, guiding format, tone, or structure.

Chain of thought prompting

Chain of thought (CoT) prompting involves requesting step-by-step reasoning before answering.

Modern approach: Claude offers an extended thinking feature that automates structured reasoning.

Three implementations:

  1. Basic: Simply add "Think step-by-step" to your instructions
  2. Guided: Structure your prompt to provide specific reasoning stages
  3. Structured: Use tags to separate reasoning from the final answer

Control the output format

  1. Tell the AI what TO do instead of what NOT to do
  2. Match your prompt style to the desired output
  3. Be explicit about formatting preferences

Prompt chaining

Chaining breaks down complex tasks into smaller sequential steps with separate prompts. Each prompt handles one stage, and the output feeds into the next instruction.

Techniques you might have heard about

XML tags for structure

While modern models are better at understanding structure without XML tags, they can still be useful in specific situations.

Role prompting

Role prompting defines expert personas and perspectives. Modern alternative: Being explicit about what perspective you want is often more effective.

Troubleshooting common prompt issues

Problem Solution
Response is too generic Add specificity, examples, or explicit requests for comprehensive output
Response is off-topic Be more explicit about your actual goal. Provide context
Response format is inconsistent Add examples (few-shot) or use prefilling
Task is too complex Break into multiple prompts (chaining)
AI includes unnecessary preambles Use prefilling or explicitly request to skip
AI makes up information Give permission to say "I don't know" when uncertain

Common mistakes to avoid

  • Don't over-engineer: Longer, more complex prompts are NOT always better
  • Don't ignore the basics: Advanced techniques won't help if your core prompt is unclear
  • Don't assume the AI reads minds: Be specific about what you want
  • Don't use every technique at once: Select techniques that address your specific challenge
  • Don't forget to iterate: The first prompt rarely works perfectly
  • Don't rely on outdated techniques: XML tags and heavy role prompting are less necessary with modern models

What does a good prompt look like?

To really hone your prompt engineering skills, you'll need to objectively measure the effectiveness of your prompts. Check out the prompt engineering course.


Additional resources

Effective context engineering for AI agents

Building with language models is becoming less about finding the right words and phrases for your prompts, and more about answering the broader question of "what configuration of context is most likely to generate our model's desired behavior?"

Source: Anthropic Engineering Blog


Introduction

Context refers to the set of tokens included when sampling from a large-language model (LLM). The engineering problem at hand is optimizing the utility of those tokens against the inherent constraints of LLMs in order to consistently achieve a desired outcome.

Context engineering vs. prompt engineering

  • Prompt engineering: Methods for writing and organizing LLM instructions for optimal outcomes
  • Context engineering: Strategies for curating and maintaining the optimal set of tokens (information) during LLM inference

As we move towards engineering more capable agents that operate over multiple turns of inference and longer time horizons, we need strategies for managing the entire context state (system instructions, tools, MCP, external data, message history, etc).

Why context engineering is important

LLMs, like humans, lose focus or experience confusion at a certain point. Studies have uncovered the concept of context rot: as the number of tokens in the context window increases, the model's ability to accurately recall information decreases.

Context must be treated as a finite resource with diminishing marginal returns. LLMs have an "attention budget" that they draw on when parsing large volumes of context.

The anatomy of effective context

Good context engineering means finding the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome.

System Prompts

Should be extremely clear and use simple, direct language at the right altitude for the agent - the Goldilocks zone between:

  • Too rigid: Hardcoding complex, brittle logic
  • Too vague: High-level guidance that fails to give concrete signals

Tools

Tools define the contract between agents and their information/action space. They should:

  • Be self-contained and robust to error
  • Have minimal overlap in functionality
  • Have descriptive, unambiguous input parameters

Examples (Few-shot prompting)

Curate a set of diverse, canonical examples that effectively portray the expected behavior. For an LLM, examples are the "pictures" worth a thousand words.

Context retrieval and agentic search

"Just in time" context strategies

Rather than pre-processing all relevant data up front, agents maintain lightweight identifiers (file paths, stored queries, web links) and use these references to dynamically load data into context at runtime using tools.

Progressive disclosure

Allows agents to incrementally discover relevant context through exploration. Each interaction yields context that informs the next decision.

Context engineering for long-horizon tasks

For tasks that span tens of minutes to multiple hours, agents require specialized techniques:

1. Compaction

Taking a conversation nearing the context window limit, summarizing its contents, and reinitiating a new context window with the summary.

2. Structured note-taking

The agent regularly writes notes persisted to memory outside of the context window. These notes get pulled back into the context window at later times.

3. Sub-agent architectures

Specialized sub-agents handle focused tasks with clean context windows. The main agent coordinates with a high-level plan while subagents perform deep technical work.

Conclusion

The guiding principle: find the smallest set of high-signal tokens that maximize the likelihood of your desired outcome.

Even as capabilities scale, treating context as a precious, finite resource will remain central to building reliable, effective agents.

Prompting best practices for Claude 4.x

Specific prompt engineering techniques for Claude 4.x models (Sonnet 4.5, Haiku 4.5, Opus 4.5)

Source: Claude Docs


General Principles

Be Explicit with Your Instructions

Claude 4.x models respond well to clear, explicit instructions. Being specific about your desired output can help enhance results.

Example: Instead of "Create an analytics dashboard", use "Create an analytics dashboard. Include as many relevant features and interactions as possible. Go beyond the basics to create a fully-featured implementation."

Add Context to Improve Performance

Providing context or motivation behind your instructions helps Claude 4.x models better understand your goals.

Be Vigilant with Examples & Details

Claude 4.x models pay close attention to details and examples. Ensure your examples align with the behaviors you want to encourage.


Long-horizon Reasoning and State Tracking

Claude 4.5 models excel at long-horizon reasoning tasks with exceptional state tracking capabilities. It maintains orientation across extended sessions by focusing on incremental progress.

Context Awareness

Claude 4.5 models can track remaining context window throughout a conversation. This enables Claude to execute tasks and manage context more effectively.

Multi-context Window Workflows

  • Use the first context window to set up a framework (write tests, create setup scripts)
  • Have the model write tests in a structured format
  • Set up quality of life tools (setup scripts like init.sh)
  • Consider starting fresh vs compacting

State Management Best Practices

  • Use structured formats (JSON) for state data
  • Use unstructured text for progress notes
  • Use git for state tracking
  • Emphasize incremental progress

Communication Style

Claude 4.5 models have a more concise and natural communication style:

  • More direct and grounded
  • More conversational
  • Less verbose

Tool Usage Patterns

Claude 4.5 models benefit from explicit direction to use specific tools.

For proactive action:

By default, implement changes rather than only suggesting them.

For conservative action:

Do not jump into implementation unless clearly instructed to make changes.

Output Formatting

Control the Format of Responses

  1. Tell Claude what to do instead of what not to do
  2. Use XML format indicators
  3. Match your prompt style to the desired output
  4. Use detailed prompts for specific formatting preferences

Research and Information Gathering

For optimal research results:

  • Provide clear success criteria
  • Encourage source verification
  • Use a structured approach for complex research

Subagent Orchestration

Claude 4.5 models can recognize when tasks benefit from delegating work to specialized subagents and do so proactively.


Extended Thinking

Claude 4.x models offer thinking capabilities for tasks involving reflection after tool use or complex multi-step reasoning.

Note: When extended thinking is disabled, Claude Opus 4.5 is sensitive to the word "think" - use alternatives like "consider," "believe," or "evaluate."


Document Creation & Vision

  • Excel at creating presentations, animations, and visual documents
  • Improved vision capabilities for image processing and data extraction
  • Can analyze videos by breaking them into frames

Parallel Tool Calling

Claude 4.x models excel at parallel tool execution:

  • Run multiple speculative searches during research
  • Read several files at once to build context faster
  • Execute bash commands in parallel

Frontend Design

To avoid "AI slop" aesthetics, focus on:

  • Typography: Choose distinctive fonts
  • Color & Theme: Commit to a cohesive aesthetic
  • Motion: Use animations for effects
  • Backgrounds: Create atmosphere and depth

Migration Considerations

When migrating to Claude 4.5 models:

  • Be specific about desired behavior
  • Frame instructions with modifiers
  • Request specific features explicitly

Claude's Extended Thinking

With extended thinking mode, Claude can think more deeply about trickier questions. Developers can set a "thinking budget" to control how long Claude spends on a problem.

Source: Anthropic Announcements
Date: February 24, 2025


What is Extended Thinking?

Extended thinking mode isn't an option that switches to a different model with a separate strategy. Instead, it's allowing the very same model to give itself more time, and expend more effort, in coming to an answer.

Just like humans can choose to apply more or less cognitive effort depending on the task, Claude now has that same flexibility.


The Visible Thought Process

Benefits

  1. Trust: Being able to observe the way Claude thinks makes it easier to understand and check its answers
  2. Alignment: Contradictions between what the model inwardly thinks and what it outwardly says can help identify concerning behaviors like deception
  3. Interest: Claude's thought process is often similar to human reasoning - exploring different angles, double- and triple-checking answers

Considerations

  • The revealed thinking may be more detached and less personal-sounding than Claude's default outputs
  • Faithfulness: We don't know for certain that what's in the thought process truly represents what's going on in the model's mind
  • Security concerns: Malicious actors might use the visible thought process to build jailbreak strategies

Improved Capabilities

Claude as an Agent

Claude 3.7 Sonnet benefits from "action scaling" - an improved capability that allows it to iteratively call functions, respond to environmental changes, and continue until an open-ended task is complete.

Computer Use

Claude can issue virtual mouse clicks and keyboard presses to solve tasks on a user's behalf. Claude 3.7 Sonnet can allocate more turnsand more time and computational powerto computer use tasks.


Test-Time Compute Scaling

Serial Scaling

When using extended thinking, Claude uses multiple, sequential reasoning steps before producing its final output. Performance improves logarithmically with the number of "thinking tokens" allowed.

Parallel Scaling

Sampling multiple independent thought processes and selecting the best one:

  • Majority voting: Selecting the answer that appears most commonly
  • Scoring model: Using another language model to check work

Safety Mechanisms

AI Safety Level

Claude 3.7 Sonnet confirmed appropriate for ASL-2 (AI Safety Level 2) standard. The model showed increased sophistication but critical failures in CBRN-related tasks.

Visible Thought Process Safety

In rare cases, Claude's thought process might include potentially harmful content. In such cases, the thought process is encrypted and users see: "the rest of the thought process is not available for this response"

Computer Use Safety

Enhanced defenses against "prompt injection" attacks:

  • New training to resist prompt injection
  • New system prompt with instructions to ignore attacks
  • Classifier that triggers on potential prompt injection
  • Result: 88% prevention rate (up from 74%)

How to Use Extended Thinking

Available for Claude Pro, Team, Enterprise, and API users at Claude.ai or through the API.

Prompt Engineering Overview

Official Anthropic documentation on prompt engineering for Claude models.

Source: Claude Docs - Prompt Engineering


Before Prompt Engineering

This guide assumes that you have:

  • A clear definition of the success criteria for your use case
  • Some ways to empirically test against those criteria
  • A first draft prompt you want to improve

Tip: Try the prompt generator in the Claude Console if you don't have a first draft!


When to Prompt Engineer

This guide focuses on success criteria that are controllable through prompt engineering. Not every success criteria or failing eval is best solved by prompt engineering.

For example, latency and cost can sometimes be more easily improved by selecting a different model.


How to Prompt Engineer

The prompt engineering techniques are organized from most broadly effective to more specialized techniques. Try these in order when troubleshooting performance:

1. Prompt Generator

Use Claude Console's prompt generator for initial drafts.

2. Be Clear and Direct

State exactly what you want clearly and explicitly.

3. Use Examples (Multishot)

Provide examples to demonstrate the desired format and style.

4. Let Claude Think (Chain of Thought)

Allow Claude to reason step-by-step through complex problems.

5. Use XML Tags

Structure your prompts with XML tags for clarity.

6. Give Claude a Role (System Prompts)

Define a persona or role for Claude to adopt.

7. Prefill Claude's Response

Start Claude's response to guide the output format.

8. Chain Complex Prompts

Break down complex tasks into multiple prompts.

9. Long Context Tips

Optimize for working with large amounts of context.


Interactive Tutorials

GitHub Prompting Tutorial

An example-filled tutorial covering prompt engineering concepts from the docs. Interactive prompt engineering tutorial

Google Sheets Prompting Tutorial

A lighter weight version via an interactive spreadsheet.


Key Concepts

Technique When to Use
Be Clear and Direct Always - foundational technique
Examples When format/style matters
Chain of Thought Complex reasoning tasks
XML Tags Structured inputs/outputs
Role/System Prompts Consistent persona needed
Prefilling Specific output format
Chaining Multi-step complex tasks

Prompting vs. Finetuning

  • Prompting: Quick iteration, no training required, flexible
  • Finetuning: Better for specific, repetitive tasks at scale

Start with prompt engineering and consider finetuning only when needed.

Building with the Claude API - Anthropic Academy Course

Comprehensive course covering the full spectrum of working with Anthropic models using the Claude API.

Source: Anthropic Skilljar
Price: FREE
Duration: 84 lectures, 8.1 hours of video, 10 quizzes
Certificate: Certificate of completion available


About This Course

This course provides comprehensive coverage of the Claude API, from basic usage through advanced agent architectures. You'll learn to integrate Claude into applications, implement tool calling, build RAG pipelines, and design both deterministic workflows and flexible agent systems.


Learning Objectives

By the end of this course, you'll be able to:

  • Make API requests to Claude models and handle responses
  • Implement multi-turn conversations, streaming, and structured output generation
  • Build and evaluate prompts systematically using automated testing pipelines
  • Create custom tools and integrate Claude with external services
  • Design and implement RAG systems with hybrid search and reranking
  • Use MCP (Model Context Protocol) to connect Claude to various data sources
  • Understand common workflows and agent architectures

Prerequisites

  • Proficiency in Python programming
  • Basic knowledge of handling JSON data

Course Topics

Fundamentals

  • API basics and authentication
  • Making your first API request
  • Understanding model parameters

Prompt Engineering

  • Building effective prompts
  • Testing and evaluation frameworks
  • Iterative prompt improvement

Advanced Features

  • Tool calling and function integration
  • Streaming responses
  • Structured output generation

RAG (Retrieval-Augmented Generation)

  • Building RAG pipelines
  • Hybrid search strategies
  • Reranking techniques

Agent Development

  • Deterministic workflows
  • Flexible agent systems
  • MCP (Model Context Protocol) integration

How to Enroll

  1. Visit Anthropic Academy
  2. Click "Enroll in Course"
  3. Create an account or sign in
  4. Start learning!

Related Resources

Anthropic's Interactive Prompt Engineering Tutorial

A comprehensive step-by-step course to understand how to engineer optimal prompts within Claude.

Source: GitHub Repository
Alternative: Google Sheets version (more user-friendly)


Course Goals

After completing this course, you will be able to:

  • Master the basic structure of a good prompt
  • Recognize common failure modes and learn the '80/20' techniques to address them
  • Understand Claude's strengths and weaknesses
  • Build strong prompts from scratch for common use cases

Course Structure

The course is broken up into 9 chapters with accompanying exercises, plus an appendix of advanced methods. Each lesson has an "Example Playground" area for experimentation.

Note: This tutorial uses Claude 3 Haiku (smallest, fastest, cheapest model).


Table of Contents

Beginner

Chapter Topic
1 Basic Prompt Structure
2 Being Clear and Direct
3 Assigning Roles

Intermediate

Chapter Topic
4 Separating Data from Instructions
5 Formatting Output & Speaking for Claude
6 Precognition (Thinking Step by Step)
7 Using Examples

Advanced

Chapter Topic
8 Avoiding Hallucinations
9 Building Complex Prompts (Industry Use Cases)

Industry Use Cases (Chapter 9)

  • Complex Prompts from Scratch - Chatbot
  • Complex Prompts for Legal Services
  • Exercise: Complex Prompts for Financial Services
  • Exercise: Complex Prompts for Coding

Appendix: Beyond Standard Prompting

Chaining Prompts

Breaking down complex tasks into multiple prompts.

Tool Use

Integrating external tools and functions with Claude.

Search & Retrieval

Implementing RAG (Retrieval-Augmented Generation) patterns.


How to Use This Tutorial

  1. Clone or download the repository from GitHub
  2. Work through chapters in order (1-9)
  3. Use the Example Playground to experiment with prompts
  4. Complete exercises to practice concepts
  5. Check the answer key if needed

Key Concepts Covered

Basic Concepts

  • Prompt structure fundamentals
  • Clear and direct communication
  • Role assignment

Intermediate Techniques

  • Data/instruction separation
  • Output formatting
  • Chain of thought prompting
  • Few-shot examples

Advanced Skills

  • Hallucination prevention
  • Complex multi-step prompts
  • Industry-specific applications

Related Resources

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment