Improving Prompts

Overview

When to Use

• Optimizing CLAUDE.md or AGENTS.md files
• Improving custom command prompts
• Refining skill instructions
• Migrating prompts from older Claude models to 4.5

When NOT to Use

• Writing new prompts from scratch (just follow best practices directly)
• The prompt is working well and user hasn't identified issues

The Core Problem

• Invent "best practices" from general knowledge
• Make structural changes without asking what's broken
• Add complexity assuming more structure = better
• Change things to demonstrate value rather than solve problems

Common Rationalizations (Do Not Fall For These)

Required Process

Step 1: Understand Before Changing

1. Ask what specific behaviors are underperforming
2. Ask what the prompt should achieve that it currently doesn't
3. If user says "just improve it generally" - ask for at least one concrete issue

• "Claude ignores my instruction to be concise" ✓
• "The examples I provide don't match the output format" ✓
• "Claude suggests changes but doesn't implement them" ✓

• "It's too vague" ✗ (vague about what?)
• "It doesn't follow best practices" ✗ (which practice? what fails?)
• "It's inconsistent" ✗ (inconsistent how? show examples)

Step 2: Reference Actual Best Practices

references/claude-4.5-best-practices.md

• Claude 4.5 follows instructions precisely - vague requests get literal interpretations
• If you want "above and beyond" behavior, explicitly request it
• Example: "Create a dashboard" → "Create a dashboard. Include relevant features and interactions. Go beyond basics."

• Explain WHY a rule exists, not just WHAT the rule is
• Claude generalizes from explanations
• Example: "NEVER use ellipses" → "Never use ellipses because the text-to-speech engine cannot pronounce them"

• Examples are followed precisely - ensure they demonstrate desired behavior
• One excellent example beats many mediocre ones

• When extended thinking is disabled, "think" triggers unwanted behavior
• Use alternatives: "consider," "evaluate," "assess," "determine"

• Claude 4.5 defaults to efficiency/conciseness
• If you want summaries or explanations, request them explicitly

• "Can you suggest changes" → Claude suggests but doesn't implement
• "Make these changes" → Claude implements
• Be explicit about whether to act or advise

Step 3: Preserve What Works

• Do NOT restructure sections that aren't problematic
• Do NOT add complexity unless solving a stated problem
• Do NOT change tone/voice unless specifically requested
• Keep the user's examples if they demonstrate the right behavior

Step 4: Propose Changes with Rationale

1. What specific best practice it applies
2. What problem it solves
3. Show before/after

Red Flags - You're About to Fail

• "Based on general best practices..." → STOP. Use documented practices.
• "Structure is always better..." → STOP. Ask if structure is the problem.
• "I'll assume the user wants..." → STOP. Ask.
• Making 10+ changes to a short prompt → STOP. What specific problem are you solving?
• "This is how I would write it..." → STOP. You're not the user.

Quick Reference: Claude 4.5 Improvements

Common Mistakes