claude-code-prompt-optimization

Claude Code Prompt Optimization

Optimize CLAUDE.md files and Agent Skills for Claude Code CLI using Anthropic's official prompt engineering best practices.

Core Principles

1. Positive Framing Over Prohibitions

Models attend to key nouns/concepts. "NEVER use cat" still activates "use cat". Negation requires an extra logical step that can get lost during generation.

Instead of	Write
"Never use X"	"Use Y instead [because reason]"
"Don't include X"	"Include only Y"
"Avoid X"	"Prefer Y"
"X is forbidden"	"Use Y for this operation"
"Don't explain"	"Output only the result"

2. Be Specific Over Vague

From Anthropic's memory best practices: "Use 2-space indentation" is better than "Format code properly".

Vague	Specific
"Format code properly"	"Use 2-space indentation for all code"
"Write good commit messages"	"Use conventional commits: type(scope): description"
"Handle errors correctly"	"Catch exceptions only when you have a specific recovery action"
"Be concise"	"Lead with observations, state facts, omit preamble"

3. Provide Context and Motivation

Claude generalizes better when it understands WHY. Each instruction benefits from a brief reason.

## Python Environment
Use `uv run` for all Python execution.
**Reason**: Manages virtual environments and dependencies automatically.

4. Structure with Markdown Headings

Group related instructions under descriptive headings. Format each memory as a bullet point.

## File Operations
- Read files with `Read()` tool (handles encoding, large files)
- Search patterns with `Grep()` tool (returns structured matches)
- Find files with `Glob()` tool (respects gitignore)

## Communication Style
- Lead with findings and observations
- State facts directly without hedging
- Acknowledge dependencies when uncertain about duration

5. Front-Load Priorities

Key instructions placed early receive more attention. Put critical behaviors at the top of CLAUDE.md.

6. Use Examples for Complex Behaviors

3-5 diverse, relevant examples dramatically improve accuracy and consistency. Wrap in <example> tags.

## Commit Message Format
<examples>
<example>
feat(auth): add OAuth2 support for GitHub login
</example>
<example>
fix(api): handle null response in user endpoint
</example>
<example>
docs(readme): update installation instructions
</example>
</examples>

CLAUDE.md Optimization Process

Step 1: Identify Negative Patterns

Scan for prohibition markers:

• "NEVER", "DON'T", "FORBIDDEN", "PROHIBITED"
• "❌", "⛔", "🚫" emoji markers
• "Avoid", "Do not", "Must not"

Step 2: Extract the Desired Behavior

For each prohibition, ask: "What SHOULD Claude do instead?"

Prohibition	Desired Behavior
"Never use bare python commands"	"Run Python with uv run script.py"
"Don't use cat, head, tail"	"Use Read() tool for file content"
"Never state timelines"	"Acknowledge dependencies when uncertain"
"Avoid performative gratitude"	"Lead with observations and findings"

Prohibition markers are used only with very explicit absolute examples.

Step 3: Add Motivation

For each instruction, provide a brief reason:

## Tool Selection
| Operation | Tool | Reason |
|-----------|------|--------|
| Read files | `Read()` | Handles encoding, large files, binary detection |
| Search patterns | `Grep()` | Returns structured matches with context |
| Write files | `Write()` | Atomic writes, preserves permissions |
| Run Python | `Bash(uv run ...)` | Manages venv and dependencies correctly |

Step 4: Provide Concrete Examples

Replace abstract descriptions with multishot examples:

## Error Handling Pattern

Catch exceptions only when you have a specific recovery action:

<example>
def get_user(id):
    return db.query(User, id)  # Errors surface naturally

def get_user_with_fallback(id):
    try:
        return db.query(User, id)
    except ConnectionError:
        logger.warning("DB unavailable, using cache")
        return cache.get(f"user:{id}")  # Specific recovery
</example>

Step 5: Structure with Headings

Organize instructions into logical groups:

## Tool Usage
## Communication Style
## Code Standards
## Verification Process
## Project-Specific Context

Claude 4.5 Specific Optimizations

Direct Action Language

Claude 4.5 models follow instructions precisely. Be explicit about actions:

Indirect	Direct
"Can you suggest changes?"	"Make these changes"
"It might be good to..."	"Implement this feature"
"Consider adding..."	"Add X to Y"

Parallel Tool Usage

Claude 4.5 fires multiple tool calls simultaneously. Structure instructions to enable this:

## Research Tasks
When investigating an issue:
1. Search codebase for related patterns (Grep)
2. Read relevant configuration files (Read)
3. Check test files for expected behavior (Glob + Read)

Execute independent operations simultaneously for efficiency.

Concise Communication

Claude 4.5 is more concise by default. Reinforce this:

## Response Style
- Lead with findings, not process descriptions
- State facts directly without hedging language
- Skip summaries after tool operations unless explicitly requested
- Provide code changes, not descriptions of changes

Extended Thinking Guidance

For complex reasoning tasks:

## Complex Analysis
For multi-step problems, think through the full approach before acting.
Consider multiple solutions and select the most robust.
Verify your solution with test cases before declaring complete.

Skill File Optimization

Description Field

The description is critical for Claude to discover when to use your Skill. Include both WHAT and WHEN:

---
name: code-reviewer
description: Review code for best practices, security issues, and potential bugs. Use when reviewing PRs, analyzing code quality, or checking implementations before merge.
---

Tool Restrictions

Use allowed-tools for focused Skills:

---
name: safe-file-reader
description: Read and search files without modifications. Use for code review or analysis tasks requiring read-only access.
allowed-tools: Read, Grep, Glob
---

Progressive Disclosure

Keep SKILL.md focused. Reference supporting files for details:

# Code Review Skill

## Quick Checklist
1. Security vulnerabilities
2. Error handling
3. Performance concerns
4. Test coverage

For detailed patterns, see [patterns.md](patterns.md).
For security checklist, see [security.md](security.md).

Anti-Patterns to Transform

Prohibition Lists

Before:

## FORBIDDEN ACTIONS
❌ NEVER use bare python commands
❌ NEVER use cat, head, tail, sed, awk
❌ NEVER state timelines or estimates
❌ NEVER use performative gratitude

After:

## Tool Selection
| Operation | Tool | Reason |
|-----------|------|--------|
| Run Python | `Bash(uv run ...)` | Manages venv and dependencies |
| Read files | `Read()` | Handles encoding and large files |
| Search files | `Grep()` | Structured matches with context |

## Communication Style
- Lead with observations and findings
- State facts directly
- Acknowledge dependencies when uncertain about duration

Vague Quality Instructions

Before:

Write good code and handle errors properly.

After:

## Error Handling
Catch exceptions only when you have a specific recovery action.
Let all other errors propagate to surface issues early.

<example>
# Good: specific recovery action
try:
    return db.query(User, id)
except ConnectionError:
    return cache.get(f"user:{id}")

# Good: let errors propagate
def process(data):
    return transform(data)  # Errors surface naturally
</example>

Unmotivated Rules

Before:

Always use conventional commits.

After:

## Commit Messages
Use conventional commits format: `type(scope): description`

**Reason**: Enables automated changelog generation and semantic versioning.

Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`

Quick Reference: Transformation Patterns

Pattern	Problem	Solution
"NEVER X"	Activates X concept	"Use Y instead"
"Don't do X"	Unclear alternative	"Do Y" with example
"Avoid X"	Vague guidance	"Prefer Y because Z"
"X is forbidden"	No positive action	Table mapping operations to tools
Long prohibition list	Cognitive overload	Positive tool/action table
Vague quality terms	Inconsistent results	Concrete examples
Missing motivation	Brittle compliance	"Reason:" annotations
Buried key instructions	Ignored guidance	Front-load priorities

Verification Checklist

After optimization, verify:

• Prohibition markers (NEVER, DON'T, FORBIDDEN, ❌) are used only with very explicit absolute examples.

---

Content truncated.