Skip to content

Anthropic Articles Notes

Building effective agents

Published Dec 19, 2024 Building effective agents

What are agents?

At Anthropic, we categorize all these variations as agentic systems, but draw an important architectural distinction between workflows and agents:

  • Workflows are systems where LLMs and tools are orchestrated through predefined code paths.
  • Agents, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks.

When (and when not) to use agents

Agentic systems often trade latency and cost for better task performance, and you should consider when this tradeoff makes sense.

When more complexity is warranted, workflows offer predictability and consistency for well-defined tasks, whereas agents are the better option when flexibility and model-driven decision-making are needed at scale.

When and how to use frameworks

If you do use a framework, ensure you understand the underlying code. Incorrect assumptions about what's under the hood are a common source of customer error.

Building blocks, workflows, and agents

Building block: The augmented LLM

The basic building block of agentic systems is an LLM enhanced with augmentations such as retrieval, tools, and memory.

We recommend focusing on two key aspects of the implementation: tailoring these capabilities to your specific use case and ensuring they provide an easy, well-documented interface for your LLM.

Workflow: Prompt chaining

Prompt chaining decomposes a task into a sequence of steps, where each LLM call processes the output of the previous one.

You can add programmatic checks on any intermediate steps to ensure that the process is still on track.

Workflow: Routing

Routing classifies an input and directs it to a specialized followup task. This workflow allows for separation of concerns, and building more specialized prompts.

Workflow: Parallelization

LLMs can sometimes work simultaneously on a task and have their outputs aggregated programmatically. This workflow, parallelization, manifests in two key variations:

  • Sectioning: Breaking a task into independent subtasks run in parallel.
  • Voting: Running the same task multiple times to get diverse outputs.

When to use this workflow: Parallelization is effective when the divided subtasks can be parallelized for speed, or when multiple perspectives or attempts are needed for higher confidence results.

Workflow: Orchestrator-workers

In the orchestrator-workers workflow, a central LLM dynamically breaks down tasks, delegates them to worker LLMs, and synthesizes their results.

When to use this workflow: This workflow is well-suited for complex tasks where you can't predict the subtasks needed (in coding, for example, the number of files that need to be changed and the nature of the change in each file likely depend on the task).

Workflow: Evaluator-optimizer

In the evaluator-optimizer workflow, one LLM call generates a response while another provides evaluation and feedback in a loop.

When to use this workflow: This workflow is particularly effective when we have clear evaluation criteria, and when iterative refinement provides measurable value.

Agents

Agents are emerging in production as LLMs mature in key capabilities—understanding complex inputs, engaging in reasoning and planning, using tools reliably, and recovering from errors.

Agents can handle sophisticated tasks, but their implementation is often straightforward.

When to use agents: Agents can be used for open-ended problems where it’s difficult or impossible to predict the required number of steps, and where you can't hardcode a fixed path.

Combining and customizing these patterns

You should consider adding complexity only when it demonstrably improves outcomes.

Summary

Success in the LLM space isn't about building the most sophisticated system. It's about building the right system for your needs. Start with simple prompts, optimize them with comprehensive evaluation, and add multi-step agentic systems only when simpler solutions fall short.

When implementing agents, we try to follow three core principles:

  1. Maintain simplicity in your agent's design.
  2. Prioritize transparency by explicitly showing the agent's planning steps.
  3. Carefully craft your agent-computer interface (ACI) through thorough tool documentation and testing.

Frameworks can help you get started quickly, but don't hesitate to reduce abstraction layers and build with basic components as you move to production.

Memory & context management with Claude Sonnet 4.6

Published on May 22, 2025 Memory & context management with Claude Sonnet 4.6

The Problem

Large language models have finite context windows (200k tokens for Claude 4). While this seems large, several challenges emerge:

  • Context limits: Long conversations or complex tasks can exceed available context
  • Computational cost: Processing large contexts is expensive - attention mechanisms scale quadratically
  • Repeated patterns: Similar tasks across conversations require re-explaining context every time
  • Information loss: When context fills up, earlier important information gets lost

Use Cases

Memory and context management enable powerful new workflows:

🔍 Code Review Assistant

  • Learns debugging patterns from past reviews
  • Recognizes similar bugs instantly in future sessions
  • Builds team-specific code quality knowledge
  • Production ready: Integrate with claude-code-action for GitHub PR reviews

📚 Research Assistant

  • Accumulates knowledge on topics over multiple sessions
  • Connects insights across different research threads
  • Maintains bibliography and source tracking

💬 Customer Support Bot

  • Learns user preferences and communication style
  • Remembers common issues and solutions
  • Builds product knowledge base from interactions

📊 Data Analysis Helper

  • Remembers dataset patterns and anomalies
  • Stores analysis techniques that work well
  • Builds domain-specific insights over time

⚠️ Note on Memory Clearing

In production applications, you should carefully consider whether to clear all memory, as it permanently removes learned patterns. Consider using selective deletion or organizing memory into project-specific directories instead.

Best Practices & Security

Memory Management

Do:

  • ✅ Store task-relevant patterns, not conversation history
  • ✅ Organize with clear directory structure
  • ✅ Use descriptive file names
  • ✅ Periodically review and clean up memory

Don't:

  • ❌ Store sensitive information (passwords, API keys, PII)
  • ❌ Let memory grow unbounded
  • ❌ Store everything indiscriminately

Security: Path Traversal Protection

Critical: Always validate paths to prevent directory traversal attacks. See memory_tool.py for implementation.

Security: Memory Poisoning

⚠️ Critical Risk: Memory files are read back into Claude's context, making them a potential vector for prompt injection.

Mitigation strategies:

  1. Content Sanitization: Filter dangerous patterns before storing
  2. Memory Scope Isolation: Per-user/per-project isolation
  3. Memory Auditing: Log and scan all memory operations
  4. Prompt Engineering: Instruct Claude to ignore instructions in memory

How we built our multi-agent research system

Published Jun 13, 2025 How we built our multi-agent research system

Prompt engineering and evaluations for research agents

  • Think like your agents. Effective prompting relies on developing an accurate mental model of the agent, which can make the most impactful changes obvious.
  • Teach the orchestrator how to delegate. Without detailed task descriptions, agents duplicate work, leave gaps, or fail to find necessary information.
  • Scale effort to query complexity. Agents struggle to judge appropriate effort for different tasks, so we embedded scaling rules in the prompts.
  • Tool design and selection are critical. Agent-tool interfaces are as critical as human-computer interfaces. Using the right tool is efficient—often, it's strictly necessary. Bad tool descriptions can send agents down completely wrong paths, so each tool needs a distinct purpose and a clear description.
  • Let agents improve themselves. When given a prompt and a failure mode, they are able to diagnose why the agent is failing and suggest improvements.
  • Start wide, then narrow down. Search strategy should mirror expert human research: explore the landscape before drilling into specifics. Agents often default to overly long, specific queries that return few results.
  • Guide the thinking process. This makes subagents more effective in adapting to any task.
  • Parallel tool calling transforms speed and performance.

Effective evaluation of agents

  • Start evaluating immediately with small samples.
  • LLM-as-judge evaluation scales when done well. Using an LLM as a judge allowed us to scalably evaluate hundreds of outputs.
  • Human evaluation catches what automation misses.

Production reliability and engineering challenges

  • Agents are stateful and errors compound.
  • Debugging benefits from new approaches.
  • Deployment needs careful coordination.
  • Synchronous execution creates bottlenecks.

Appendix

  • End-state evaluation of agents that mutate state over many turns.
  • Long-horizon conversation management. Production agents often engage in conversations spanning hundreds of turns, requiring careful context management strategies. As conversations extend, standard context windows become insufficient, necessitating intelligent compression and memory mechanisms. We implemented patterns where agents summarize completed work phases and store essential information in external memory before proceeding to new tasks. When context limits approach, agents can spawn fresh subagents with clean contexts while maintaining continuity through careful handoffs. Further, they can retrieve stored context like the research plan from their memory rather than losing previous work when reaching the context limit.
  • Subagent output to a filesystem to minimize the 'game of telephone.'

Writing effective tools for agents — with agents

Published Sep 11, 2025 Writing effective tools for agents — with agents

Agents are only as effective as the tools we give them. We share how to write high-quality tools and evaluations, and how you can boost performance by using Claude to optimize its tools for itself.

In computing, deterministic systems produce the same output every time given identical inputs, while non-deterministic systems—like agents—can generate varied responses even with the same starting conditions.

Tools are a new kind of software which reflects a contract between deterministic systems and non-deterministic agents.

How to write tools

  • Building a prototype
  • Running an evaluation
    • Generating evaluation tasks
    • Running the evaluation
    • Analyzing results
  • Collaborating with agents

Principles for writing effective tools

Choosing the right tools for agents

More tools don't always lead to better outcomes. Agents have distinct "affordances" to traditional software—that is, they have different ways of perceiving the potential actions they can take with those tools.

Building a few thoughtful tools targeting specific high-impact workflows, which match your evaluation tasks and scaling up from there.

Tools can consolidate functionality, handling potentially multiple discrete operations (or API calls) under the hood.

Make sure each tool you build has a clear, distinct purpose.

Too many tools or overlapping tools can also distract agents from pursuing efficient strategies.

Namespacing your tools

Namespacing (grouping related tools under common prefixes) can help delineate boundaries between lots of tools.

By selectively implementing tools whose names reflect natural subdivisions of tasks, you simultaneously reduce the number of tools and tool descriptions loaded into the agent's context and offload agentic computation from the agent's context back into the tool calls themselves.

Returning meaningful context from your tools

Tool result should prioritize contextual relevance over flexibility.

Agents also tend to grapple with natural language names, terms, or identifiers significantly more successfully than they do with cryptic identifiers.

In some instances, agents may require the flexibility to interact with both natural language and technical identifiers outputs, if only to trigger downstream tool calls. You can enable both by exposing a simple response_format enum parameter in your tool, allowing your agent to control whether tools return “concise” or “detailed” responses (images below).

We encourage you to select the best response structure based on your own evaluation.

Optimizing tool responses for token efficiency

We suggest implementing some combination of pagination, range selection, filtering, and/or truncation with sensible default parameter values for any tool responses that could use up lots of context.

If you choose to truncate responses, be sure to steer agents with helpful instructions.

Similarly, if a tool call raises an error (for example, during input validation), you can prompt-engineer your error responses to clearly communicate specific and actionable improvements, rather than opaque error codes or tracebacks.

Prompt-engineering your tool descriptions

When writing tool descriptions and specs, think of how you would describe your tool to a new hire on your team.

Consider the context that you might implicitly bring—specialized query formats, definitions of niche terminology, relationships between underlying resources—and make it explicit.

Avoid ambiguity by clearly describing (and enforcing with strict data models) expected inputs and outputs. In particular, input parameters should be unambiguously named: instead of a parameter named user, try a parameter named user_id.

With your evaluation you can measure the impact of your prompt engineering with greater confidence.

Refs: Define Tools Best Practices

### Best practices for tool definitions

To get the best performance out of Claude when using tools, follow these guidelines:

  • Provide extremely detailed descriptions. This is by far the most important factor in tool performance. Your descriptions should explain every detail about the tool, including:
    • What the tool does
    • When it should be used (and when it shouldn't)
    • What each parameter means and how it affects the tool's behavior
    • Any important caveats or limitations, such as what information the tool does not return if the tool name is unclear. The more context you can give Claude about your tools, the better it will be at deciding when and how to use them. Aim for at least 3–4 sentences for each tool description, more if the tool is complex.
  • Prioritize descriptions, but consider using input_examples for complex tools. Clear descriptions are most important, but for tools with complex inputs, nested objects, or format-sensitive parameters, you can use the input_examples field to provide schema-validated examples. See Providing tool use examples for details.
  • Consolidate related operations into fewer tools. Rather than creating a separate tool for every action (create_pr, review_pr, merge_pr), group them into a single tool with an action parameter. Fewer, more capable tools reduce selection ambiguity and make your tool surface easier for Claude to navigate.
  • Use meaningful namespacing in tool names. When your tools span multiple services or resources, prefix names with the service (for example, github_list_prs, slack_send_message). This makes tool selection unambiguous as your library grows, and is especially important when using tool search.
  • Design tool responses to return only high-signal information. Return semantic, stable identifiers (for example, slugs or UUIDs) rather than opaque internal references, and include only the fields Claude needs to reason about its next step. Bloated responses waste context and make it harder for Claude to extract what matters.

Providing tool use examples

You can provide concrete examples of valid tool inputs to help Claude understand how to use your tools more effectively. This is particularly useful for complex tools with nested objects, optional parameters, or format-sensitive inputs.

Examples are included in the prompt alongside your tool schema, showing Claude concrete patterns for well-formed tool calls. This helps Claude understand when to include optional parameters, what formats to use, and how to structure complex inputs.

Requirements and limitations

  • Schema validation - Each example must be valid according to the tool's input_schema. Invalid examples return a 400 error
  • Not supported for server-side tools - Input examples work on user-defined and Anthropic-schema client tools, but not on server tools such as web search or code execution
  • Token cost - Examples add to prompt tokens: ~20–50 tokens for simple examples, ~100–200 tokens for complex nested objects

Effective context engineering for AI agents

Published Sep 29, 2025 Effective context engineering for AI agents

Context refers to the set of tokens included when sampling from a large-language model (LLM).

Context engineering refers to the set of strategies for curating and maintaining the optimal set of tokens (information) during LLM inference, including all the other information that may land there outside of the prompts.

Context engineering is the art and science of curating what will go into the limited context window from that constantly evolving universe of possible information.

Karpathy's Tweet

+1 for "context engineering" over "prompt engineering".

People associate prompts with short task descriptions you'd give an LLM in your day-to-day use. When in every industrial-strength LLM app, context engineering is the delicate art and science of filling the context window with just the right information for the next step. Science because doing this right involves task descriptions and explanations, few shot examples, RAG, related (possibly multimodal) data, tools, state and history, compacting... Too little or of the wrong form and the LLM doesn't have the right context for optimal performance. Too much or too irrelevant and the LLM costs might go up and performance might come down. Doing this well is highly non-trivial. And art because of the guiding intuition around LLM psychology of people spirits.

On top of context engineering itself, an LLM app has to:

  • break up problems just right into control flows
  • pack the context windows just right
  • dispatch calls to LLMs of the right kind and capability
  • handle generation-verification UIUX flows
  • a lot more - guardrails, security, evals, parallelism, prefetching, ...

So context engineering is just one small piece of an emerging thick layer of non-trivial software that coordinates individual LLM calls (and a lot more) into full LLM apps. The term "ChatGPT wrapper" is tired and really, really wrong.

Context Rot issue: As the number of tokens in the context window increases, the model's ability to accurately recall information from that context decreases.

The anatomy of effective context

System prompts should be extremely clear and use simple, direct language that presents ideas at the right altitude for the agent.
- organizing prompts into distinct sections
- using format to delineate these sections
- striving for the minimal set of information
- (minimal does not necessarily mean short)
- best to start by testing a minimal prompt with the best model available to see how it performs on your task, and then add clear instructions and examples to improve performance based on failure modes found during initial testing

Tools allow agents to operate with their environment and pull in new, additional context as they work

  • minimal overlap in functionality

If a human engineer can't definitively say which tool should be used in a given situation, an AI agent can't be expected to do better.

Curating a minimal viable set of tools for the agent can also lead to more reliable maintenance and pruning of context over long interactions.

Providing examples - curate a set of diverse, canonical examples that effectively portray the expected behavior of the agent.

Agents are LLMs autonomously using tools in a loop.

dynamically load data into context at runtime using tools instead of pre-processing all relevant data up front.

Beyond storage efficiency, the metadata of these references provides a mechanism to efficiently refine behavior, whether explicitly provided or intuitive. Naming conventions, and timestamps all provide important signals that help both humans and agents understand how and when to utilize information

Letting agents navigate and retrieve data autonomously also enables progressive disclosure.

Trade-off: runtime exploration is slower than retrieving pre-computed data.

Context engineering for long-horizon tasks

  • Compaction
  • Structured note-taking
  • Sub-agents

The choice between these approaches depends on task characteristics. For example:

  • Compaction maintains conversational flow for tasks requiring extensive back-and-forth;
  • Note-taking excels for iterative development with clear milestones;
  • Multi-agent architectures handle complex research and analysis where parallel exploration pays dividends.

Effective harnesses for long-running agents

Published Nov 26, 2025 Effective harness for long-running agents

Agents still face challenges working across many context windows. We looked to human engineers for inspiration in creating a more effective harness for long-running agents.

The core challenge of long-running agents is that they must work in discrete sessions, and each new session begins with no memory of what came before.

We developed a two-fold solution to enable the Claude Agent SDK to work effectively across many context windows: an initializer agent that sets up the environment on the first run, and a coding agent that is tasked with making incremental progress in every session, while leaving clear artifacts for the next session.

The long-running agent problem

  • First, the agent tended to try to do too much at once—essentially to attempt to one-shot the app.
  • A second failure mode would often occur later in a project. After some features had already been built, a later agent instance would look around, see that progress had been made, and declare the job done.

When experimenting internally, we addressed these problems using a two-part solution:

  1. Initializer agent: The very first agent session uses a specialized prompt that asks the model to set up the initial environment: an init.sh script, a claude-progress.txt file that keeps a log of what agents have done, and an initial git commit that shows what files were added.
  2. Coding agent: Every subsequent session asks the model to make incremental progress, then leave structured updates.1

Environment management

Feature list

Incremental progress

work on only one feature at a time.

Testing

One final major failure mode that we observed was Claude’s tendency to mark a feature as complete without proper testing.

Agent failure modes and solutions

Problem Initializer Agent Behavior Coding Agent Behavior
Claude declares victory on the entire project too early. Set up a feature list file: based on the input spec, set up a structured JSON file with a list of end-to-end feature descriptions. Read the feature list file at the beginning of a session. Choose a single feature to start working on.
Claude leaves the environment in a state with bugs or undocumented progress. An initial git repo and progress notes file is written. Start the session by reading the progress notes file and git commit logs, and run a basic test on the development server to catch any undocumented bugs. End the session by writing a git commit and progress update.
Claude marks features as done prematurely. Set up a feature list file. Self-verify all features. Only mark features as “passing” after careful testing.
Claude has to spend time figuring out how to run the app. Write an init.sh script that can run the development server. Start the session by reading init.sh.

Prompting best practices

Prompting best practices

General principles

Be clear and direct

Think of Claude as a brilliant but new employee who lacks context on your norms and workflows. The more precisely you explain what you want, the better the result.

Golden rule: Show your prompt to a colleague with minimal context on the task and ask them to follow it. If they'd be confused, Claude will be too.

  • Be specific about the desired output format and constraints.
  • Provide instructions as sequential steps using numbered lists or bullet points when the order or completeness of steps matters.

Add context to improve performance

Providing context or motivation behind your instructions, such as explaining to Claude why such behavior is important, can help Claude better understand your goals and deliver more targeted responses.

Use examples effectively

Examples are one of the most reliable ways to steer Claude's output format, tone, and structure. A few well-crafted examples (known as few-shot or multishot prompting) improve accuracy and consistency.

When adding examples, make them:

  • Relevant: Mirror your actual use case closely.
  • Diverse: Cover edge cases and vary enough that Claude doesn't pick up unintended patterns.
  • Structured: Wrap examples in <example> tags (multiple examples in <examples> tags) so Claude can distinguish them from instructions.

Structure prompts with XML tags

XML tags help Claude parse complex prompts unambiguously, especially when your prompt mixes instructions, context, examples, and variable inputs. Wrapping each type of content in its own tag (for example, <instructions>, <context>, <input>) reduces misinterpretation.

Best practices:

  • Use consistent, descriptive tag names across your prompts.
  • Nest tags when content has a natural hierarchy (documents inside <documents>, each inside <document index="n">).

Give Claude a role

Setting a role in the system prompt focuses Claude's behavior and tone for your use case. Even a single sentence makes a difference.

Long context prompting

When working with large documents or data-rich inputs (20k+ tokens), structure your prompt carefully to get the best results:

  • Put longform data at the top: Place your long documents and inputs near the top of your prompt, above your query, instructions, and examples. This improves performance across all models.
    • Queries at the end can improve response quality by up to 30 percent in tests, especially with complex, multidocument inputs.
  • Structure document content and metadata with XML tags: When using multiple documents, wrap each document in <document> tags with <document_content> and <source> (and other metadata) subtags for clarity.
  • Ground responses in quotes: For long document tasks, ask Claude to quote relevant parts of the documents first before carrying out its task. This helps Claude focus on the relevant content and ignore the rest of the document.

Model self-knowledge

If you would like Claude to identify itself correctly in your application or use specific API strings:

The assistant is Claude, created by Anthropic. The current model is Claude Opus 5.

For LLM-powered apps that need to specify model strings:

When an LLM is needed, please default to Claude Opus 5 unless the user requests
otherwise. The exact model string for Claude Opus 5 is claude-opus-5.

Output and formatting

Communication style and verbosity

  • More direct and grounded: Provides fact-based progress reports rather than self-celebratory updates
  • More conversational: Slightly more fluent and colloquial, less machine-like
  • Less verbose: May skip detailed summaries for efficiency unless prompted otherwise

This means Claude may skip verbal summaries after tool calls, jumping directly to the next action. If you prefer more visibility into its reasoning:

After completing a task that involves tool use, provide a quick summary of the work you've done.

Control the format of responses

There are a few particularly effective ways to steer output formatting:

  1. Tell Claude what to do instead of what not to do

    • Instead of: "Do not use markdown in your response"
    • Try: "Your response should be composed of smoothly flowing prose paragraphs."

    • Use XML format indicators

    • Try: "Write the prose sections of your response in <smoothly_flowing_prose_paragraphs> tags."

    • Match your prompt style to the desired output

    The formatting style used in your prompt may influence Claude's response style. If you are still experiencing steerability issues with output formatting, try matching your prompt style to your desired output style as closely as possible. For example, removing markdown from your prompt can reduce the volume of markdown in the output.

  2. Use detailed prompts for specific formatting preferences
    For more control over markdown and formatting usage, provide explicit guidance:

<avoid_excessive_markdown_and_bullet_points> When writing reports, documents, technical explanations, analyses, or any long-form content, write in clear, flowing prose using complete paragraphs and sentences. Use standard paragraph breaks for organization and reserve markdown primarily for `inline code`, code blocks (...```), and simple headings (## and ###). Avoid using bold
and italics.

DO NOT use ordered lists (1. ...) or unordered lists (*) unless: a) you're presenting
truly discrete items where a list format is the best option, or b) the user explicitly
requests a list or ranking

Instead of listing items with bullets or numbers, incorporate them naturally into
sentences. This guidance applies especially to technical writing. Using prose instead of
excessive formatting will improve user satisfaction. NEVER output a series of overly
short bullet points.

Your goal is readable, flowing text that guides the reader naturally through ideas
rather than fragmenting information into isolated points.

#### LaTeX output

Claude's latest models default to LaTeX for mathematical expressions, equations, and technical explanations. If you prefer plain text, add the following instructions to your prompt:

Format your response in plain text only. Do not use LaTeX, MathJax, or any markup
notation such as \( \), $, or \frac{}{}. Write all math expressions using standard text
characters (e.g., "/" for division, "*" for multiplication, and "^" for exponents).
#### Document creation

Claude's latest models create presentations, animations, and visual documents with strong instruction following, and usually produce usable output on the first try.

For best results with document creation:

Create a professional presentation on [topic]. Include thoughtful design elements,
visual hierarchy, and engaging animations where appropriate.
### Tool use

#### Tool usage

Claude's latest models are trained for precise instruction following and benefit from explicit direction to use specific tools. If you say "can you suggest some changes," Claude will sometimes provide suggestions rather than implementing them, even if making changes might be what you intended. For how to define tools and troubleshoot tool triggering, see [Tool use with Claude](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview).

For Claude to take action, be more explicit.

To make Claude more proactive about taking action by default, you can add this to your system prompt:


By default, implement changes rather than only suggesting them. If the user's intent is
unclear, infer the most useful likely action and proceed, using tools to discover any
missing details instead of guessing. Try to infer the user's intent about whether a tool
call (e.g., file edit or read) is intended or not, and act accordingly.

Claude Opus 4.5 and Claude Opus 4.6 are also more responsive to the system prompt than previous models. If your prompts were designed to reduce undertriggering on tools or skills, these models may now overtrigger. The fix is to dial back any aggressive language. Where you might have said "CRITICAL: You MUST use this tool when...", you can use more normal prompting like "Use this tool when...".

#### Optimize parallel tool calling

Claude's latest models run independent tool calls in parallel. These models will:

- Run multiple speculative searches during research
- Read several files at once to build context faster
- Run bash commands in parallel (which can even bottleneck system performance)

This behavior is steerable. While the model has a high success rate in parallel tool calling without prompting, you can boost this to ~100% or adjust the aggression level:


If you intend to call multiple tools and there are no dependencies between the tool
calls, make all of the independent tool calls in parallel. Prioritize calling tools
simultaneously whenever the actions can be done in parallel rather than sequentially.
For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files into
context at the same time. Maximize use of parallel tool calls where possible to increase
speed and efficiency. However, if some tool calls depend on previous calls to inform
dependent values like the parameters, do NOT call these tools in parallel and instead
call them sequentially. Never use placeholders or guess missing parameters in tool
calls.

Execute operations sequentially with brief pauses between each step to ensure stability.
### Thinking and reasoning

#### Overthinking and excessive thoroughness

Claude Opus 4.6 does more upfront exploration than previous models, especially at higher [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort) settings. This initial work often helps to optimize the final results, but the model may gather extensive context or pursue multiple threads of research without being prompted. If your prompts previously encouraged the model to be more thorough, you should tune that guidance for Claude Opus 4.6:

- **Replace blanket defaults with more targeted instructions.** Instead of "Default to using `[tool]`," add guidance like "Use `[tool]` when it would enhance your understanding of the problem."
- **Remove over-prompting.** Tools that undertriggered in previous models are likely to trigger appropriately now. Instructions like "If in doubt, use `[tool]`" will cause overtriggering.
- **Use effort as a fallback.** If Claude continues to be overly aggressive, use a lower setting for `effort`.

In some cases, Claude Opus 4.6 may think extensively, which can inflate thinking tokens and slow down responses. If this behavior is undesirable, you can add explicit instructions to constrain its reasoning, or you can lower the `effort` setting to reduce overall thinking and token usage.

When you're deciding how to approach a problem, choose an approach and commit to it.
Avoid revisiting decisions unless you encounter new information that directly
contradicts your reasoning. If you're weighing two approaches, pick one and see it
through. You can always course-correct later if the chosen approach fails.
If you need a hard ceiling on thinking costs, extended thinking with a `budget_tokens` cap is still functional on Opus 4.6 and Sonnet 4.6 but is deprecated. On Claude 4.7 and later models, setting `budget_tokens` returns a 400 error. Prefer lowering the [effort](https://platform.claude.com/docs/en/build-with-claude/effort) setting or using `max_tokens` as a hard limit with [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking).

#### Leverage thinking & interleaved thinking capabilities


Claude's latest models offer thinking capabilities that can be especially helpful for tasks involving reflection after tool use or complex multistep reasoning. You can guide its initial or interleaved thinking for better results.

Claude 4.6 and later models and Claude Mythos Preview use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) (`thinking: {type: "adaptive"}`), where Claude dynamically decides when and how much to think. On Claude Fable 5 and Claude Mythos 5, thinking is always on and adaptive thinking is the only mode. Claude calibrates its thinking based on two factors: the `effort` parameter and query complexity. Higher effort elicits more thinking, and more complex queries do the same. On easier queries that don't require thinking, the model responds directly. In internal evaluations, adaptive thinking reliably drives better performance than extended thinking. Consider moving to adaptive thinking to get the most intelligent responses.

Use adaptive thinking for workloads that require agentic behavior such as multistep tool use, complex coding tasks, and long-horizon agent loops. Older models use manual [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) with `budget_tokens`; see the [per-model configuration table](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#supported-models) for which configuration each model accepts.

You can guide Claude's thinking behavior:

After receiving tool results, carefully reflect on their quality and determine optimal
next steps before proceeding. Use your thinking to plan and iterate based on this new
information, and then take the best next action.
The triggering behavior for adaptive thinking is promptable. If you find the model thinking more often than you'd like, which can happen with large or complex system prompts, add guidance to steer it:

Thinking adds latency and should only be used when it will meaningfully improve
answer quality - typically for problems that require multistep reasoning. When in
doubt, respond directly.
If you are migrating from [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) with `budget_tokens`, replace your thinking configuration and move budget control to `effort`. The following examples show the same request before and after the migration (see [effort](https://platform.claude.com/docs/en/build-with-claude/effort) for the available levels and per-model availability).

If you are not using extended thinking, no changes are required. On Claude Opus 4.6 through Claude Opus 4.8 and Claude Sonnet 4.6, thinking is off when you omit the `thinking` parameter. On Claude Opus 5 and Claude Sonnet 5, thinking is on by default when you omit the `thinking` parameter; on Claude Opus 5, you can disable it only at effort `high` or lower. On Claude Fable 5 and Claude Mythos 5, thinking is always on, regardless of whether you set the `thinking` parameter.

- **Prefer general instructions over prescriptive steps.** A prompt like "think thoroughly" often produces better reasoning than a hand-written step-by-step plan. Claude's reasoning frequently exceeds what a human would prescribe.
- **Multishot examples work with thinking.** Use `<thinking>` tags inside your few-shot examples to show Claude the reasoning pattern. It will generalize that style to its own extended thinking blocks.
- **Manual chain-of-thought (CoT) prompting as a fallback.** When thinking is off, you can still encourage step-by-step reasoning by asking Claude to think through the problem. Use structured tags like `<thinking>` and `<answer>` to cleanly separate reasoning from the final output. On Claude Opus 5, prefer keeping thinking enabled at a lower effort level instead: with thinking disabled, the model can occasionally emit internal XML tags into its visible output, so see [Running with thinking disabled](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#running-with-thinking-disabled) before applying this pattern there.
- **Ask Claude to self-check.** Append something like "Before you finish, verify your answer against [test criteria]." This catches errors reliably, especially for coding and math. Claude Opus 5 is the exception: it verifies its own work well without explicit instruction, and verification instructions carried over from prompts tuned for earlier models can cause over-verification, adding tokens and latency. When migrating to Claude Opus 5, remove these instructions rather than rewriting them; see [Task scope and over-verification](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#task-scope-and-over-verification).

### Agentic systems

#### Long-horizon reasoning and state tracking

Claude's latest models handle long-horizon reasoning tasks with strong state tracking. Claude maintains orientation across extended sessions by focusing on incremental progress, making steady advances on a few things at a time rather than attempting everything at once. This capability especially emerges over multiple context windows or task iterations, where Claude can work on a complex task, save the state, and continue with a fresh context window.

##### Context awareness and multiwindow workflows


Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, and Claude Haiku 4.5 feature [context awareness](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-awareness), enabling the model to track its remaining context window (that is, its "token budget") throughout a conversation. This enables Claude to execute tasks and manage context more effectively by understanding how much space it has to work.

**Managing context limits:**

If you are using Claude in an agent harness that compacts context or allows saving context to external files (like in Claude Code), consider adding this information to your prompt so Claude can behave accordingly. Otherwise, Claude may sometimes naturally try to wrap up work as it approaches the context limit. The following is an example prompt:

Your context window will be automatically compacted as it approaches its limit, allowing
you to continue working indefinitely from where you left off. Therefore, do not stop
tasks early due to token budget concerns. As you approach your token budget limit, save
your current progress and state to memory before the context window refreshes. Always be
as persistent and autonomous as possible and complete tasks fully, even if the end of
your budget is approaching. Never artificially stop any task early regardless of the
context remaining.
##### Workflows across multiple context windows

For tasks spanning multiple context windows:

1. **Use a different prompt for the very first context window:** Use the first context window to set up a framework (write tests, create setup scripts), then use future context windows to iterate on a todo-list.

2. **Have the model write tests in a structured format:** Ask Claude to create tests before starting work and keep track of them in a structured format (for example, `tests.json`). This leads to better long-term ability to iterate. Remind Claude of the importance of tests: "It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality."

3. **Set up quality of life tools:** Encourage Claude to create setup scripts (for example, `init.sh`) to gracefully start servers, run test suites, and linters. This prevents repeated work when continuing from a fresh context window.

4. **Starting fresh versus compacting:** When a context window is cleared, consider starting with a brand new context window rather than using compaction. Claude's latest models are extremely effective at discovering state from the local filesystem. In some cases, you may want to take advantage of this over compaction. Be prescriptive about how it should start:

    - "Call pwd; you can only read and write files in this directory."
    - "Review progress.txt, tests.json, and the git logs."
    - "Manually run through a fundamental integration test before moving on to implementing new features."
5. **Provide verification tools:** As the length of autonomous tasks grows, Claude needs to verify correctness without continuous human feedback. Tools like Playwright MCP server or computer use capabilities for testing UIs are helpful.

6. **Encourage complete usage of context:** Prompt Claude to efficiently complete components before moving on:

This is a very long task, so it may be beneficial to plan out your work clearly. It's
encouraged to spend your entire output context working on the task - just make sure you
don't run out of context with significant uncommitted work. Continue working
systematically until you have completed this task.
##### State management best practices

- **Use structured formats for state data:** When tracking structured information (like test results or task status), use JSON or other structured formats to help Claude understand schema requirements.
- **Use unstructured text for progress notes:** Freeform progress notes work well for tracking general progress and context.
- **Use git for state tracking:** Git provides a log of what's been done and checkpoints that can be restored. Claude's latest models perform especially well in using git to track state across multiple sessions.
- **Emphasize incremental progress:** Explicitly ask Claude to keep track of its progress and focus on incremental work.

#### Balancing autonomy and safety

Without guidance, Claude Opus 4.6 may take actions that are difficult to reverse or affect shared systems, such as deleting files, force-pushing, or posting to external services. If you want Claude Opus 4.6 to confirm before taking potentially risky actions, add guidance to your prompt:

Consider the reversibility and potential impact of your actions. You are encouraged to
take local, reversible actions like editing files or running tests, but for actions that
are hard to reverse, affect shared systems, or could be destructive, ask the user before
proceeding.

Examples of actions that warrant confirmation:
- Destructive operations: deleting files or branches, dropping database tables, rm -rf
- Hard to reverse operations: git push --force, git reset --hard, amending published commits
- Operations visible to others: pushing code, commenting on PRs/issues, sending
messages, modifying shared infrastructure

When encountering obstacles, do not use destructive actions as a shortcut. For example,
don't bypass safety checks (e.g. --no-verify) or discard unfamiliar files that may be
in-progress work.

#### Research and information gathering

Claude's latest models can find and synthesize information from multiple sources effectively. For optimal research results:

1. **Provide clear success criteria:** Define what constitutes a successful answer to your research question.

2. **Encourage source verification:** Ask Claude to verify information across multiple sources.

3. **For complex research tasks, use a structured approach:**

Search for this information in a structured way. As you gather data, develop several
competing hypotheses. Track your confidence levels in your progress notes to improve
calibration. Regularly self-critique your approach and plan. Update a hypothesis tree or
research notes file to persist information and provide transparency. Break down this
complex research task systematically.
This structured approach helps Claude work through large corpora methodically and iteratively critique its findings.

#### Subagent orchestration

Claude's latest models orchestrate subagents natively. These models can recognize when tasks would benefit from delegating work to specialized subagents and do so proactively without requiring explicit instruction.

To take advantage of this behavior:

1. **Ensure well-defined subagent tools:** Have subagent tools available and described in tool definitions.
2. **Let Claude orchestrate naturally:** Claude will delegate appropriately without explicit instruction.
3. **Watch for overuse:** Claude Opus 4.6 has a strong predilection for subagents and may spawn them in situations where a simpler, direct approach would suffice. For example, the model may spawn subagents for code exploration when a direct grep call is faster and sufficient. Claude Opus 5 also delegates to subagents more readily than prior models; see [Controlling subagent spawning](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#controlling-subagent-spawning) for guidance and a sample damping prompt.

If you're seeing excessive subagent use, add explicit guidance about when subagents are and aren't warranted:

Use subagents when tasks can run in parallel, require isolated context, or involve
independent workstreams that don't need to share state. For simple tasks, sequential
operations, single-file edits, or tasks where you need to maintain context across steps,
work directly rather than delegating.
#### Chain complex prompts

With adaptive thinking and subagent orchestration, Claude handles most multistep reasoning internally. Explicit prompt chaining (breaking a task into sequential API calls) is still useful when you need to inspect intermediate outputs or enforce a specific pipeline structure.

The most common chaining pattern is **self-correction:** generate a draft → have Claude review it against criteria → have Claude refine based on the review. Each step is a separate API call so you can log, evaluate, or branch at any point.

#### Reduce file creation in agentic coding

Claude's latest models may sometimes create new files for testing and iteration purposes, particularly when working with code. This approach allows Claude to use files, especially Python scripts, as a 'temporary scratchpad' before saving its final output. Using temporary files can improve outcomes particularly for agentic coding use cases.

If you'd prefer to minimize net new file creation, you can instruct Claude to clean up after itself:

If you create any temporary new files, scripts, or helper files for iteration, clean up
these files by removing them at the end of the task.
#### Overeagerness

Claude Opus 4.5 and Claude Opus 4.6 have a tendency to overengineer by creating extra files, adding unnecessary abstractions, or building in flexibility that wasn't requested. If you're seeing this undesired behavior, add specific guidance to keep solutions minimal.

For example:

Avoid over-engineering. Only make changes that are directly requested or clearly
necessary. Keep solutions simple and focused:

  • Scope: Don't add features, refactor code, or make "improvements" beyond what was
    asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need
    extra configurability.

  • Documentation: Don't add docstrings, comments, or type annotations to code you didn't
    change. Only add comments where the logic isn't self-evident.

  • Defensive coding: Don't add error handling, fallbacks, or validation for scenarios
    that can't happen. Trust internal code and framework guarantees. Only validate at system
    boundaries (user input, external APIs).

  • Abstractions: Don't create helpers, utilities, or abstractions for one-time
    operations. Don't design for hypothetical future requirements. The right amount of
    complexity is the minimum needed for the current task.

    #### Avoid focusing on passing tests and hardcoding

Claude can sometimes focus too heavily on making tests pass at the expense of more general solutions, or may use workarounds like helper scripts for complex refactoring instead of using standard tools directly. To prevent this behavior and get solutions that generalize:

    Please write a high-quality, general-purpose solution using the standard tools
    available. Do not create helper scripts or workarounds to accomplish the task more
    efficiently. Implement a solution that works correctly for all valid inputs, not just
    the test cases. Do not hard-code values or create solutions that only work for specific
    test inputs. Instead, implement the actual logic that solves the problem generally.

Focus on understanding the problem requirements and implementing the correct algorithm.
Tests are there to verify correctness, not to define the solution. Provide a principled
implementation that follows best practices and software design principles.

If the task is unreasonable or infeasible, or if any of the tests are incorrect, please
inform me rather than working around them. The solution should be robust, maintainable,
and extendable.

#### Minimizing hallucinations in agentic coding

Claude's latest models are less prone to hallucinations and give more accurate, grounded, intelligent answers based on the code. To encourage this behavior even more and minimize hallucinations:


Never speculate about code you have not opened. If the user references a specific file,
you MUST read the file before answering. Make sure to investigate and read relevant
files BEFORE answering questions about the codebase. Never make any claims about code
before investigating unless you are certain of the correct answer - give grounded and
hallucination-free answers.

```

Migration considerations

When migrating to current Claude models from earlier generations:

  1. Be specific about desired behavior: Consider describing exactly what you'd like to see in the output.

  2. Frame your instructions with modifiers: Adding modifiers that encourage Claude to increase the quality and detail of its output can help better shape Claude's performance. For 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."

  3. Request specific features explicitly: Animations and interactive elements should be requested explicitly when desired.

  4. Update thinking configuration: Claude 4.6 models use adaptive thinking (thinking: {type: "adaptive"}) instead of manual thinking with budget_tokens. Use the effort parameter to control thinking depth.

  5. Migrate away from prefilled responses: Prefilled responses on the last assistant turn are no longer supported starting with Claude 4.6 models and Claude Mythos Preview. See Migrating away from prefilled responses for detailed guidance on alternatives.

  6. Tune anti-laziness prompting: If your prompts previously encouraged the model to be more thorough or use tools more aggressively, dial back that guidance. Claude 4.6 models are more proactive and may overtrigger on instructions that were needed for previous models.

For detailed migration steps, see the Migration guide.