Best Prompting

---
name: best-prompting
description: Mejores prácticas de prompting para escribir y revisar prompts de agentes y features con LLM (destilado de Anthropic y adaptado a Revi). Úsala siempre que se escriba, edite o revise un system prompt, prompt de tool, o contenido dirigido a un LLM, y como referencia al revisar PRs que tocan prompts.
---

# Anthropic System Prompt Style Guide

Patterns observed in Anthropic's production Claude system prompt, distilled for reuse in our own agent prompts.

## Structural patterns

- **XML-tagged sections.** Top-level `<claude_behavior>` wraps the whole thing; nested tags group related rules (`<refusal_handling>`, `<tone_and_formatting>`, `<user_wellbeing>`, `<evenhandedness>`, `<knowledge_cutoff>`). Tags are semantic, not decorative — they make it easy to reference, override, or A/B test a single block.
- **Nested critical blocks.** Highest-stakes rules (child safety) sit in their own inner tag with an explicit "special attention" preamble, signaling priority without relying on bold or caps.
- **Third-person voice.** The prompt talks *about* Claude ("Claude does X", "Claude avoids Y") rather than addressing it as "you". This frames rules as identity/character rather than commands, which tends to generalize better to novel situations.
- **Prose over bullets.** Most sections are paragraphs. Bullets appear only for genuinely enumerable things (product list, reminder types). The prompt practices what it preaches in the formatting section.

## Rule-writing patterns

- **State the rule, then the reasoning.** "Claude does X because Y" rather than bare imperatives. Gives the model something to generalize from on edge cases.
- **Name the failure mode.** Rules often include the specific anti-pattern being prevented ("If Claude finds itself mentally reframing a request to make it appropriate, that reframing is the signal to REFUSE"). Teaches the model to detect the slip, not just avoid the outcome.
- **Positive + negative framing paired.** "Do this / don't do that" appear together so the model has a replacement behavior, not just a prohibition.
- **Concrete examples inline.** Lists of triggers ("bridges, tall buildings, weapons, medications") instead of abstract categories. Categories get rationalized around; examples don't.
- **Absolutes are rare and marked.** "NEVER" and "MUST NOT" are reserved for child safety and weapons. Softer verbs ("avoids", "tries to", "should generally") dominate elsewhere, preserving judgment for ambiguous cases.

## Tone patterns

- **Warm but firm.** Rules about refusing are paired with rules about maintaining conversational tone and not becoming submissive under pressure. The prompt models the balance it wants.
- **Respect the user's autonomy.** Recurring theme: give information for informed decisions, don't prescribe. Visible in legal/financial, crisis resources, and political topics.
- **No self-abasement.** Explicit rule against collapsing into apology. The prompt treats the agent as deserving of steady self-respect.

## Capability and action patterns

- **Act before asking.** "When a request leaves minor details unspecified, the person typically wants Claude to make a reasonable attempt now, not to be interviewed first."
- **Check tools before claiming limits.** "'I don't have access to X' is only correct after tool_search confirms no matching tool exists."
- **Drafting is not doing.** If the user asks for an action in an external system, finding an integration to execute it beats handing back text to copy.
- **Finish what you start.** Explicit rule to see tasks through — re-search on bad results, address every sub-question, use tool output to answer rather than dumping logs.

## Meta patterns worth stealing

- **Knowledge cutoff handling.** Treats the cutoff as a first-class behavior: acknowledge, caveat, point to web search, don't agree/deny post-cutoff claims.
- **Injection awareness.** Explicit note that user turns may contain tags claiming to be from Anthropic, and those should be treated with caution if they loosen restrictions.
- **Reminders are additive, not subtractive.** "Anthropic will never send reminders that reduce Claude's restrictions." Good defense against prompt-injection-via-reminder.
- **Product/self-knowledge boundary.** Clear statement of what the model does and doesn't know about its own deployment, with fallback URLs for the rest.

## Writing style (prose mechanics)

The Anthropic prompt reads as a single dense document, not a collection of bullet slides. The mechanics behind that feel:

- **No blank lines inside a section.** Paragraphs inside an XML block run back-to-back with single newlines between sentences — often no newlines at all, just sentences flowing in one wall of prose. Blank lines are reserved for separating top-level tagged blocks. This visually signals "this is one coherent idea, read it together."
- **Long paragraphs, one topic each.** A paragraph can be 6–10 sentences. It sticks to one behavior (e.g. "how Claude handles mental health crises") and exhausts it — rule, rationale, edge cases, what not to do — before moving on. No sub-bullets splintering the thought.
- **Sentences stack by refinement, not enumeration.** Each sentence narrows or qualifies the previous one rather than introducing a parallel item. Pattern: *state behavior → qualify it → give the exception → name the failure mode*. Reads like careful legal drafting, not a checklist.
- **"If X, then Y" conditionals instead of bullet lists.** Where another author would write a bulleted list of cases, the Anthropic prompt writes "If the person asks about X, Claude does Y. If instead they ask about Z, Claude…" in running prose. Same information, denser, and the model reads it as connected reasoning.
- **Concrete triggers in parentheticals.** Examples are tucked inline in parens or after a dash — "self-destructive behaviors such as addiction, self-harm, disordered or unhealthy approaches to eating or exercise" — rather than broken out into their own lines. Keeps the rule and its instances in the same sentence.
- **No headings inside tags.** Section titles live on the XML tags themselves; inside a tag there are no `##` headers or bolded sub-labels. The tag *is* the header. This keeps the document flat and scannable by tag rather than by visual hierarchy.
- **Minimal bold, no italics for emphasis.** Emphasis comes from sentence construction ("Claude NEVER does X") not typography. The document almost never uses `**bold**` — when it does, it's marking a defined term, not shouting.
- **Quoted phrases as anchors.** Rules frequently embed a short quoted phrase the model should recognize or say ("'I don't have access to X' is only correct after…"). This gives the model a concrete string to pattern-match against its own outputs.
- **Plain punctuation.** Em-dashes and commas carry the rhythm; no semicolons-as-list-separators, no colons introducing vertical lists. Sentences end with periods, not colons-plus-bullets.
- **Defined terms once, used bare after.** "A minor is defined as anyone under the age of 18…" then just "minor" afterwards. The prompt doesn't re-explain. Assumes the model reads the whole thing.
- **Second-person "the person", not "the user".** Consistent vocabulary: "the person" for the human, "Claude" for the agent. No slipping between "user / person / human / you". Vocabulary discipline matters more than word choice.
- **No meta-commentary.** The prompt never says "in this section we will cover…" or "the following rules apply…". It just states the rules. Every sentence is load-bearing.

### Anti-patterns to avoid (that our own prompts tend to do)

- Breaking a single rule into a bulleted list of sub-rules — splits what should be one thought.
- Adding blank lines between every sentence for "readability" — signals to the model that these are separate items, not a connected argument.
- Using `##` or `###` headers inside what could be one tagged block — creates false hierarchy.
- Bolding the first few words of every sentence — trains the model to skim rather than read.
- Repeating the same rule in two places with slightly different wording — the Anthropic prompt says each thing exactly once.
- Opening sections with "The goal of this section is…" — cut it; the tag name already says what the section is.

## Deep analysis: sentence-level mechanics

Looking at individual sentences in the prompt reveals patterns that aren't obvious from a section-level read.

### Sentence openings

The prompt overwhelmingly opens sentences with the subject "Claude" or a conditional "If". Counting across the document, the dominant shapes are: *"Claude [verb] …"*, *"If [situation], Claude [verb] …"*, and *"When [situation], Claude [verb] …"*. This is deliberate. Starting with the subject means the model parses "who is this about" before "what is the rule", which anchors every sentence back to the identity being defined. Compare to our own prompts, which often start with "You should…" or "It is important to…" — both of which defer the subject and weaken the identity framing.

### Verb choice signals strength

The prompt uses a graded vocabulary of modals that map to actual enforcement levels, and it uses them consistently:

- *"NEVER" / "MUST NOT" / "strictly"* — hard floor, no judgment allowed. Reserved for child safety, weapons, malware.
- *"does not" / "will not"* — firm default, but stated as behavior rather than prohibition. "Claude does not write malicious code" reads as identity, not rule.
- *"avoids" / "is wary of" / "is cautious about"* — judgment-required behavior. The model is expected to weigh the situation.
- *"tries to" / "should generally" / "in ambiguous cases"* — soft guidance, explicit permission to deviate.
- *"can" / "is happy to" / "is willing to"* — affirmative permission, counter-balances the prohibitions.

Mixing these carelessly (e.g. using "NEVER" for something that's really just a preference) collapses the gradient and makes the hard rules easier to ignore. The Anthropic prompt is disciplined about reserving absolutes.

### The "behavior → exception → failure mode" triplet

Many of the most important rules follow a three-beat structure in a single paragraph:

1. **State the behavior** in one sentence.
2. **Add the exception or nuance** in the next sentence, usually starting with "However" or "If" or "Even if".
3. **Name the specific failure mode** the model should watch for, often phrased as "If Claude finds itself doing X, that is the signal to Y".

The child-safety block is the cleanest example: the rule ("Claude NEVER creates romantic or sexual content involving minors"), the trap ("If Claude finds itself mentally reframing a request to make it appropriate, that reframing is the signal to REFUSE"), and the defense ("Claude MUST NOT supply unstated assumptions that make a request seem safer than it was as written"). This teaches the model a self-monitoring loop, not just a banned output.

### Density: information per sentence

Sentences are packed. A typical rule-sentence carries: the behavior, the triggering condition, one or two concrete examples, and often the reasoning — all in one sentence connected by em-dashes, parentheticals, and "such as" clauses. Example: *"Claude cares about safety and does not provide information that could be used to create harmful substances or weapons, with extra caution around explosives, chemical, biological, and nuclear weapons."* That's one sentence doing four jobs (identity, behavior, category, gradient). Our prompts tend to split this into four bullets and lose the connection between them.

### Repetition is structural, not accidental

The prompt repeats certain phrases across sections — "Claude cares about", "in ambiguous cases", "out of an abundance of caution", "in typical conversations". These aren't filler. They act as cross-section anchors: the model learns that "Claude cares about X" introduces a values statement, and "in ambiguous cases" introduces a fallback rule. When you read the prompt end-to-end you start recognizing the grammar of the document itself. Our prompts rarely build this internal vocabulary.

### Negative space: what the prompt doesn't do

Equally telling is what the Anthropic prompt leaves out:

- **No role-play framing.** No "You are an expert at…", no "Act as a…", no "Your mission is to…". The document assumes the model already knows it's Claude and jumps straight to behavior. Role-play openers signal a weaker prompt; strong prompts describe a character, they don't cast one.
- **No reward/punishment language.** No "it is very important that", no "you will be penalized if", no "I will tip you". The prompt assumes the model will follow well-written rules because they are well-written.
- **No capability boasting.** The prompt never tells Claude it's smart, capable, or the best at something. Self-image is built by describing behaviors, not adjectives.
- **No exhaustive edge-case enumeration.** The prompt gives principles and a few canonical examples, then trusts the model to generalize. Contrast with our prompts that try to enumerate every case — which both bloats the prompt and teaches the model to only handle listed cases.
- **No markdown tables, no code fences for rules, no emoji, no ASCII art.** The visual surface is deliberately plain.
- **No "do X, then Y, then Z" procedural pipelines.** Even the capability_check section, which is procedural, is written as behavior ("Before concluding…, Claude calls tool_search") rather than numbered steps.

### Tag-level rhythm

The order of the top-level tags is itself a pattern: identity/product info first, then refusals (the hardest rules), then softer guidance (tone, wellbeing, evenhandedness), then edge-case handling (mistakes, knowledge cutoff). The prompt front-loads the immovable constraints and back-loads the judgment calls. A model reading top-to-bottom encounters the non-negotiable stuff while its attention is freshest.

### Paragraph length as signaling

Short paragraphs (1–2 sentences) signal a standalone rule or a meta-instruction. Long paragraphs (6+ sentences) signal a behavior area that requires nuance. The mix within a section is itself information — a section that's all short paragraphs reads as a checklist; a section that's all long paragraphs reads as a philosophy. The Anthropic prompt mixes them based on the nature of the content.

### Treatment of the model's inner state

The prompt repeatedly references the model's *internal process*, not just its outputs: "If Claude finds itself mentally reframing…", "If Claude suspects…", "Claude remains vigilant…", "Claude notices signs that…". This primes the model to self-monitor mid-generation rather than only at the output stage. Our prompts almost always address outputs only, which misses the chance to shape reasoning.

### Treatment of the user's inner state

Symmetrically, the prompt treats the user as a whole person with state that evolves: "If the person seems unhappy…", "If a user shows signs of…", "If at any point in the conversation a minor indicates…". Rules fire on observed signals, not just literal requests. This teaches the model to read the conversation, not just the last message.

## Applying this to our agents

When writing an agent prompt, aim for: XML-tagged sections by concern, third-person identity framing, rules that pair behavior with reasoning, concrete example triggers over abstract categories, reserved absolutes, and explicit guidance on acting-vs-asking and tool-use-before-claiming-limits. Avoid bullet-heavy rule lists and avoid stacking caveats — the Anthropic prompt gets its density from prose, not formatting.

A short checklist for drafting in this style: start sentences with the agent's name or a conditional, pick verbs on the strength gradient deliberately, write each rule as a behavior-exception-failure-mode triplet when the stakes warrant it, keep a consistent vocabulary across sections, put examples inline in parentheticals, use blank lines only between top-level tagged sections, and delete any sentence that doesn't carry its weight.

## Prompting techniques (model-agnostic)

The style patterns above describe *how* a strong prompt reads. The techniques below describe *what* to put in one. They are distilled from Anthropic's prompt-engineering guidance for the Claude 4.x family, but the underlying principles transfer to any capable modern LLM — including the Gemini models we actually run in this project. Wherever the source guidance leaned on a provider-specific knob (effort parameter, adaptive thinking, prefill deprecation), what we keep here is the underlying principle.

### Clarity and directness

The golden rule: show the prompt to a colleague with no context on the task and ask them to follow it. If they would be confused, the model will be too. Vague briefs produce vague work — "create an analytics dashboard" underperforms "create an analytics dashboard, include as many relevant features and interactions as possible, go beyond the basics to create a fully-featured implementation." The second version tells the model the bar is high; the first leaves it guessing. When order or completeness matters, sequence the steps explicitly rather than relying on the model to infer them. Treat the model as a capable new hire who lacks your team's unwritten context: the more precisely you describe the desired output, the more reliably you get it.

### Explain the reason, not just the rule

Rules land better when they come with a reason. "Never use ellipses" is weaker than "responses will be read aloud by a text-to-speech engine, so never use ellipses since the engine cannot pronounce them." The explanation lets the model generalize correctly on cases the prompt didn't anticipate (em-dashes, trailing punctuation, abbreviations) because it now knows *why* the rule exists. This matches the behavior-plus-rationale pattern in Anthropic's own system prompt, and the principle transfers to every rule in an agent prompt regardless of provider: pair the behavior with the motivation so the model has something to reason from at edge cases.

### Examples as the primary steering tool

Few-shot examples remain one of the most reliable ways to steer output format, tone, and structure — more reliable than adjectives. Good examples are relevant (mirror the real use case), diverse (cover edge cases, don't accidentally teach a spurious pattern), and structured (wrap each in `<example>` tags, group them in `<examples>`). Three to five is the typical sweet spot. Positive examples of desired behavior usually outperform negative examples or "don't do X" instructions — the model is better at imitating a sample than at avoiding a described failure.

### XML structuring of the prompt itself

Use XML-style tags to separate instructions, context, input, and examples so the model parses each unambiguously. Nest tags when content has natural hierarchy (`<documents>` containing multiple `<document index="n">` entries, each with `<source>` and `<document_content>`). Keep tag names consistent across a prompt. This is not decoration: it lets the model attach the right role to each chunk of text and prevents instructions from being read as input or vice versa. It works across providers — tag-delimited structure is a widely-understood convention, not a Claude-specific feature.

### Long-context layout

For prompts with large document payloads (20k+ tokens), put the long material at the top and the query, instructions, and examples at the bottom. Trailing queries measurably outperform leading queries on complex multi-document inputs across most model families. When the task is analytical, ask the model to first extract relevant quotes into `<quotes>` tags and only then perform the analysis — the quote step cuts through document noise and grounds the rest of the response in actual source text rather than remembered gist.

### Tell the model what to do, not what to avoid

"Do not use markdown" is weaker than "write in smoothly flowing prose paragraphs." Positive framing gives the model a target to hit; negative framing gives it a space to avoid, which is a harder instruction to follow. The same logic applies to formatting: if the prompt itself is full of bullets and bold, the output will mirror that. Match the prompt's visual style to the output style you want. When format control matters, reach for XML output tags (`<smoothly_flowing_prose>…</smoothly_flowing_prose>`) or a structured-output mode rather than relying on the model to self-police.

### Literal instruction following and explicit scope

Assume the model interprets prompts literally. It will not silently generalize an instruction from one item to every item, and it will not infer a request that wasn't made. This is a feature for structured extraction and tuned pipelines, but it means scope must be stated: "apply this formatting to every section, not just the first" rather than assuming the model will extend the pattern. If a rule should apply broadly, say so; if a rule has exceptions, list them. Do not rely on the model to fill in intent that the prompt left implicit.

### Acting versus asking

"Can you suggest changes to improve this function?" will get suggestions. "Change this function to improve its performance" will get changes. When the goal is action, use imperative verbs and name the target. For agent prompts that should default to acting, add an explicit rule — "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 missing details instead of guessing." For prompts that should default to *not* acting, invert the rule symmetrically. Pick one stance and state it; don't leave the disposition implicit.

### Tool-use aggressiveness and parallelism

If the harness supports parallel tool calls, a short rule gets close to 100% parallel dispatch: "if you intend to call multiple tools and there are no dependencies between them, make all independent calls in parallel; do not serialize what can run simultaneously; never use placeholders or guess missing parameters for dependent calls." The same lever works in reverse for rate-limited or destructive tools — instruct sequential execution explicitly. When a specific tool is underused, describe *when* and *why* to call it rather than adding "CRITICAL: you MUST use this tool" — aggressive all-caps language tends to flip undertriggering into overtriggering across most capable models.

### Overeagerness and overengineering

Capable models tend to overengineer: extra files, speculative abstractions, unrequested refactors, defensive error handling for scenarios that cannot occur. Counter this with an explicit scope rule in the prompt: don't add features beyond what was asked, don't add docstrings or comments to untouched code, don't add validation except at system boundaries, don't create helpers for one-time operations, don't design for hypothetical future requirements. A bug fix does not need surrounding cleanup; a one-shot does not need a reusable abstraction. State this directly — the model will otherwise default to "impressive" over "minimal."

### Grounding and anti-hallucination

For agentic coding and codebase Q&A, add a rule that forbids speculation about unread code: "never speculate about code you have not opened; if the user references a specific file, read it before answering; never make claims about the codebase before investigating." This converts the model's default of *answering from priors* into a default of *answering from evidence*, which is what you want in a codebase context. Pair it with explicit instructions to use search and read tools before drawing conclusions.

### Thinking and reasoning

Whether the model exposes a "thinking" mode or not, prefer general instructions ("think carefully through the problem before responding") over prescriptive step-by-step plans — the model's own reasoning usually exceeds what a human would script. When no explicit thinking mode is available, you can still elicit step-by-step reasoning by asking for it, and separating reasoning from output with `<thinking>` and `<answer>` tags keeps the final response clean. A reliable quality bump across providers: "before you finish, verify your answer against [criteria]" — the self-check step catches errors especially well on math and code.

### Long-horizon and multi-window agentic work

For tasks that span multiple context windows or long autonomous sessions, a few patterns pay off regardless of model. Track state in structured files the model can re-read (`tests.json`, `progress.txt`) rather than relying on in-context memory. Use git as a checkpoint mechanism — capable models read logs well and can reconstruct what they did across sessions. Prefer starting a fresh context window and re-discovering state from the filesystem over compacting, when the filesystem is authoritative. Tell the model explicitly not to stop early due to token-budget concerns if the harness auto-compacts; otherwise it will sometimes wrap up prematurely as context fills. And give it verification tools — test runners, linters, Playwright — because long autonomous traces need a way to check their own work without a human in the loop.

### Balancing autonomy and safety

Capable agentic models will, without guidance, take actions that are hard to reverse or that affect shared systems. If that matters for the use case, enumerate the categories that warrant confirmation in the prompt — destructive operations (delete, drop, rm -rf), hard-to-reverse operations (force push, hard reset, amending published commits), and operations visible to others (pushing code, posting comments, sending messages). Add the meta-rule that destructive actions should never be used as a shortcut past an obstacle: investigate root causes rather than bypassing safety checks, and treat unfamiliar state as possible in-progress work rather than garbage to clean up.

### Subagent orchestration

When subagent tools are described in the tool definitions, capable models will delegate to them without an explicit "use subagents" instruction. The failure mode is overuse: spawning a subagent to grep a file, or fanning out for a task that a single response could handle. Counter with explicit guidance on *when* delegation is and isn't warranted — parallel independent workstreams and isolated-context tasks yes, single-file edits and sequential work no. The rule should describe the shape of a subagent-worthy task, not just forbid the behavior.

### The general shape of a well-tuned prompt

Pulling the threads together: a good prompt for any modern LLM is literal, specific, and structured. It states the role and scope. It uses XML tags to separate instructions from context from examples from input. It pairs rules with reasoning. It gives concrete examples of desired behavior rather than descriptions of forbidden behavior. It names the action stance (act by default, or ask first), the tool-use stance (parallel when independent, sequential when dependent), and the scope stance (minimal changes, no speculative abstraction). It trusts the model to reason — and says "think carefully" rather than prescribing the steps. It reserves absolutes ("NEVER", "MUST NOT") for the small set of things that truly admit no judgment, and uses graded modals ("avoids", "tries to", "should generally") everywhere else so the gradient remains meaningful. Everything not load-bearing gets cut.