prompt-optimizer

# Prompt Optimizer Optimize prompts for Claude's latest models — the Claude 5 family (Opus 5, Sonnet 5, Fable 5) plus the still-active Opus 4.8, Sonnet 4.6, and Haiku 4.5 — using Anthropic's official guidance. Diagnose what is wrong, pick the right lever, apply a proven fix, then measure. ## Two levers, not one Many problems people try to fix by editing prompt wording are better fixed with an **API parameter**. Always weigh both: 1. **Prompt** — wording, structure, examples, role, explicit scope. 2. **Parameters** — `effort` (intelligence vs. speed/cost), `thinking` (adaptive on/off), `max_tokens` (room to think and act). On the latest models, **`effort` is frequently the highest-leverage change.** If reasoning is shallow on a hard task, raise effort to `high`/`xhigh` instead of prompting around it. If the model overthinks or over-explores, lower it. Detail in references/model-tuning.md. ## What changed for the latest models These shifts change how to optimize. Do not carry over old habits blindly: - **Effort governs depth, tool use, and thoroughness.** Start `xhigh` for coding/agentic work, minimum `high` for intelligence-sensitive work. Lower effort means more literal, more scoped, less tool use. - **Thinking defaults changed with Claude 5.** On the Claude 5 family thinking is on by default (Fable 5 rejects an explicit `disabled`); on Opus 4.8 it stays off unless you set `thinking: {type: "adaptive"}`. Opus 4.6 and Sonnet 4.6 use adaptive thinking. `budget_tokens` is removed on Claude 5 / Opus 4.8 — control depth through `effort`. - **Literal instruction following.** The model does what you said, not what you implied. State scope explicitly ("apply to every section, not just the first one"). - **Dial back anti-laziness prompting.** Aggressive "CRITICAL / You MUST" language needed for older models now causes overtriggering. Use normal phrasing ("Use this tool when..."). - **Prefilled assistant responses are no longer supported** on 4.6+ models (the request returns a 400). Migrations in references/formatting.md. - **Verbosity is calibrated to task complexity** and prose is more direct. Tune with positive examples of the concision you want, not "don't" rules. - **Subagent appetite differs by model.** Opus 4.8 under-delegates; Claude Opus 5 delegates readily. Steer explicitly — and cap fan-out on Opus 5. Effort levels and thinking defaults shift between releases — verify against the current docs at https://docs.claude.com before relying on the specifics here. ## Optimization workflow 1. **Diagnose** the symptom (use the routing table below). 2. **Choose the lever** — a parameter (effort / thinking / max_tokens) and/or a prompt change. 3. **Apply** the fix — pull a snippet from the references, or adjust the parameter. 4. **Be explicit and positive** — say what TO do, give the reason, state the scope, prefer positive examples over negative rules. 5. **Measure** — build a 10–20 case eval set and A/B the old vs. new prompt with the bundled harness: `python scripts/ab_eval.py cases.jsonl --prompt-a old.txt --prompt-b new.txt` (judge-based win rate, position-randomized; guide in references/evals.md). Never assume a prompt change helped without checking. ## Symptom → fix routing | Symptom | First lever | Reference | |---|---|---| | Too verbose / over-explains | Positive concision example; lower effort | model-tuning.md, formatting.md | | Shallow reasoning on hard task | Raise effort to high/xhigh | model-tuning.md | | Overthinks / over-explores / slow | Lower effort; "commit to an approach" snippet | model-tuning.md, agentic.md | | Ignores or partially applies an instruction | Make explicit; state scope; positive framing | core principles below | | Too much markdown / bullets | Prose-first snippet; match prompt style | formatting.md | | Outputs LaTeX, want plain text | Plain-text math snippet | formatting.md | | Will not take action (only suggests) | Explicit imperative; default_to_action | patterns.md | | Over- or under-uses tools | Adjust effort; explicit tool guidance; dial back "MUST" | patterns.md, model-tuning.md | | Not parallelizing tool calls | use_parallel_tool_calls snippet | agentic.md | | Spawns too many / too few subagents | Explicit subagent guidance | agentic.md | | Overengineers / extra files & abstractions | Anti-overengineering snippet | patterns.md | | Hardcodes to pass tests | General-solution snippet | patterns.md | | Hallucinates about code | investigate_before_answering snippet | patterns.md | | Risky autonomous actions | Reversibility / confirmation snippet | agentic.md | | Loses state over long or multi-window tasks | Context-awareness + state-file patterns | agentic.md | | Code-review harness misses bugs | Coverage-not-filter snippet | patterns.md | | Generic "AI slop" frontend | Concrete spec or propose-options-first; aesthetics snippet | frontend-design.md | | Was relying on prefill | Migrate to structured outputs / instructions | formatting.md | | Moving to a newer Claude model | Update thinking config; tune anti-laziness | model-tuning.md | ## Core principles (apply to every prompt) 1. **Be clear and direct.** Specify the desired output, format, and constraints. Want "above and beyond"? Ask for it explicitly. *Golden rule: if a colleague with no context would be confused by the prompt, so will Claude.* - Less: `Create an analytics dashboard` - More: `Create an analytics dashboard. Include as many relevant features and interactions as possible. Go beyond the basics to create a fully-featured implementation.` 2. **Give the reason.** Motivation lets Claude generalize correctly. - Less: `NEVER use ellipses` - More: `Your response will be read aloud by a text-to-speech engine, so never use ellipses since it will not know how to pronounce them.` 3. **Use examples (3–5).** Make them relevant, diverse, and wrapped in `<example>` tags. Examples steer format and tone better than description. 4. **Structure with XML tags.** Use `<instructions>`, `<context>`, `<input>` — consistent, descriptive names, nested when the content is hierarchical. 5. **Give a role** in the system prompt — even one sentence shifts tone and focus. 6. **State scope explicitly.** The latest models are literal: "every section, not just the first." 7. **Say what TO do, not what NOT to do.** Positive framing and positive examples outperform prohibitions. 8. **Long context:** put long documents at the top, above the query; wrap each in `<document>` tags; ask for relevant quotes first. ## Reference files Read the file that matches the optimization need: - **references/model-tuning.md** — effort levels, adaptive thinking, verbosity, literal instruction following, tone, model identity, computer use, and model-version migration. Read this for any parameter or model-version question. - **references/patterns.md** — copy-paste snippet library: action defaults, tool triggering, hallucination prevention, overengineering, hardcoding, research, code-review harnesses, progress updates. - **references/formatting.md** — output format and verbosity control, LaTeX, document creation, and prefill migration. - **references/agentic.md** — long-horizon reasoning and state, context awareness, multi-window workflows, autonomy & safety, subagents, parallel tools, prompt chaining. - **references/frontend-design.md** — overriding the Opus 4.8 design defaults, frontend-aesthetics snippets, and vision / crop-tool tips. - **references/evals.md** — building a 10–20 case eval set (case selection, expected_behavior phrasing, leakage, when a win rate is meaningful) and running scripts/ab_eval.py, the A/B harness with a judge-based win rate.