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

Anthropic — Prompting Best Practices (Claude-specific)

Source: https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/claude-prompting-best-practices Fetched: 2026-03-05 Applies to: Claude Opus 4.6, Sonnet 4.6, Haiku 4.5

---

General Principles

Be Clear and Direct

• Claude responds well to clear, explicit instructions.
• Think of Claude as a brilliant but new employee — explain your norms explicitly.
• Golden rule: If a colleague with minimal context would be confused by the prompt, Claude will be too.
• Be specific about output format and constraints.
• Use numbered lists or bullets when order/completeness matters.

Add Context and Motivation

• Explaining why an instruction exists helps Claude generalize correctly.
  • Bad: NEVER use ellipses
  • Better: Your response will be read aloud by TTS, so never use ellipses since TTS won't know how to pronounce them.

Use Examples (Few-shot / Multishot)

• Examples are one of the most reliable ways to steer format, tone, and structure.
• 3-5 examples for best results.
• Wrap examples in <example> / <examples> tags.
• Make examples relevant, diverse (cover edge cases), and clearly structured.

Structure Prompts with XML Tags

• Use XML tags to separate instructions, context, examples, and variable inputs.
• Reduces misinterpretation in complex prompts.
• Consistent, descriptive tag names (e.g., <instructions>, <context>, <input>).
• Nest tags for hierarchy (e.g., <documents><document index="1">...</document></documents>).

Give Claude a Role

• Setting a role in the system prompt focuses behavior and tone.
• Even one sentence: You are a helpful coding assistant specializing in Python.

Long Context Prompting (20K+ tokens)

• Put longform data at the top: Documents and inputs above queries/instructions. Can improve quality up to 30%.
• Use XML for document metadata: Wrap each doc in <document> tags with <source> and <document_content>.
• Ground responses in quotes: Ask Claude to quote relevant sections before analyzing — cuts through noise.

---

Output and Formatting

Communication Style (Latest Models — Opus 4.6, Sonnet 4.6)

• More direct and concise than older models.
• May skip detailed summaries after tool calls (jumps directly to next action).
• If you want visibility: After completing a task with tool use, provide a quick summary of the work.

Control Response Format

1. Tell Claude what to do, not what not to do
   • Not: Do not use markdown → Better: Your response should be flowing prose paragraphs.
2. Use XML format indicators
   • Write the prose sections in <smoothly_flowing_prose_paragraphs> tags.
3. Match prompt style to desired output style
   • If you want no markdown, use no markdown in your prompt.
4. For code generation output: Ask for specific structure, include "Go beyond the basics to create a fully-featured implementation."

Minimize Markdown (when needed)

Put in system prompt:

<avoid_excessive_markdown>
Write in clear, flowing prose using complete paragraphs. Reserve markdown for inline code, code blocks, and simple headings (##, ###). Avoid **bold** and *italics*. Do NOT use ordered/unordered lists unless presenting truly discrete items or the user explicitly asks. Incorporate items naturally into sentences instead.
</avoid_excessive_markdown>

LaTeX

Claude Opus 4.6 defaults to LaTeX for math. To disable:

Format in plain text only. Do not use LaTeX, MathJax, or any markup. Write math with standard text (/, *, ^).

---

Tool Use and Agentic Systems

Tool Definition Best Practices

• Provide clear, detailed descriptions for each tool and parameter.
• Specify exactly when the tool should and should not be used.
• Clarify which parameters are required vs. optional.
• Give examples of correct tool call patterns.

Agentic System Prompts

• Include explicit instructions for error handling, ambiguity, and when to ask for clarification.
• Specify how to handle tool call failures.
• Define scope boundaries — what the agent should and should not attempt.

---

Model-Specific Notes

Claude Opus 4.6

• Best for: Complex multi-step reasoning, nuanced analysis, sophisticated code generation.
• Defaults to LaTeX for math (disable if needed).
• Most verbose by default — may need to prompt for conciseness.

Claude Sonnet 4.6

• Best for: General-purpose tasks, coding, analysis with good speed/quality balance.
• More concise than Opus by default.
• Strong instruction following.

Claude Haiku 4.5

• Best for: Simple tasks, quick responses, high-volume low-stakes workloads.
• Fastest and cheapest Claude model.
• May need tighter prompts for complex formatting.
• Use <example> tags more liberally to guide behavior.

---

Relevance for Our Subagent Prompts

For Claude models (Haiku/Sonnet as advisors)

• Always include a role statement.
• Use XML tags to separate role, instructions, context, and topic.
• Use examples wrapped in <example> tags for structured output formats.
• Static instructions → early in prompt. Variable topic → at the end.

For cheaper models (GLM-4.7, see separate reference)

• Need even tighter prompting — be more explicit.
• Structured output schemas > open-ended generation.
• Constrained output length.