Best Practices

Best Practices -- Prompt Transformer

Transform prompts by adding what Claude Code needs to succeed.

Overview

This guide transforms vague or incomplete Claude Code prompts into precise, verifiable instructions. A well-formed prompt gives Claude specific file locations, clear success criteria, explicit constraints, and supporting materials -- reducing correction cycles from 5+ iterations to a single execution.

What you will learn:

• The 5 transformation principles ranked by impact
• How to choose between direct transformation and context-first workflows
• Prompt patterns for common task types (bug fix, feature, refactor, test, debug, UI, exploration, migration)
• An evaluation rubric to score prompt quality before execution

When to use this skill:

• Before submitting a multi-step prompt to Claude Code
• When a previous prompt led to a correction spiral (2+ failed attempts)
• When reviewing team prompts in shared CLAUDE.md configurations

Mode Selection

When the user provides a prompt to transform, ask using AskUserQuestion:

• Question: "How should I improve this prompt?"
• Header: "Mode"
• Options:
  1. Transform directly -- Apply the 5 principles and output an improved version
  2. Build context first -- Gather codebase context and intent analysis first

When the user asks to learn, show the Transformation Principles below. When the user asks for examples, see references/transformation-examples.md. When the user asks to evaluate a prompt, use the Quality Rubric at the end.

Learning Path

Level 1: The Core Rule

Context is your most valuable resource. Everything follows from managing the context window effectively.

Claude Code performs dramatically better when it can verify its own work (tests, screenshots, build commands), knows exactly where to look (src/auth/login.ts:42), understands what NOT to do (constraints), and receives actual error messages.

Level 2: The 5 Transformation Principles

Apply in priority order. Each addresses a specific failure mode.

Principle 1: Add Verification (Highest Impact)

The single highest-leverage improvement for prompt quality.

# BEFORE
implement email validation

# AFTER
write a validateEmail function. test cases:
  user@domain.com -> true
  invalid -> false
  user@.com -> false
run the tests after implementing.

Principle 2: Provide Specific Context

Replace vague references with precise file paths, function names, line numbers.

# BEFORE
fix the login bug

# AFTER
users report login fails after session timeout.
check auth flow in src/auth/, especially token refresh
in refresh_token.ts. write a failing test that
reproduces the issue, then fix it.

Principle 3: Add Constraints

Tell Claude what NOT to do. Prevents over-engineering and scope expansion.

# BEFORE
add a calendar widget

# AFTER
implement calendar widget with month selection and year
pagination. follow pattern in HotDogWidget.php. no
libraries beyond what the codebase already uses.

Principle 4: Structure Complex Tasks in Phases

Separate exploration from implementation for larger tasks:

# Phase 1 - EXPLORE
read src/auth/ and understand sessions and login.
# Phase 2 - PLAN
design the OAuth flow. what files change? create plan.
# Phase 3 - IMPLEMENT
follow plan. write tests for callback. run after each change.
# Phase 4 - COMMIT
commit with descriptive message.

Use phases when: uncertain about approach, multi-file change, unfamiliar code. Skip phases when: one-liner change (typo, rename, log line).

Principle 5: Include Rich Content

# BEFORE
the build is failing

# AFTER
build fails with:
  TypeError: Cannot read properties of undefined (reading 'map')
    at OrderList (src/components/OrderList.tsx:42)
fix and verify build succeeds. address root cause.

Level 3: Context-First Workflow

For complex prompts, gather context before transforming. Launch 3 parallel agents via Task tool:

After agents return:

1. Synthesize findings -- combine intent + best practices + codebase context
2. Apply matching patterns -- use examples from referencer as templates
3. Ground in codebase -- add specific file paths from context builder
4. Transform the prompt -- apply all 5 principles with gathered context
5. Output improved prompt with before/after comparison

Best Practices

Do

• Start with verification -- highest impact on output quality
• Reference specific files with @path syntax
• Provide actual error messages verbatim, not descriptions
• Use /clear between unrelated tasks to prevent context pollution
• Scope investigations narrowly: "check src/auth/" not "figure out why it is slow"
• Delegate outcomes, not steps -- let Claude choose implementation
• Respect project CLAUDE.md conventions when transforming

Do Not

• Combine multiple unrelated tasks in one prompt (split with /clear)
• Say "getting an error" without pasting the actual error
• Use "make it better" without specific criteria for "better"
• Micromanage file edits -- state the outcome, not the keystrokes
• Continue correcting after 2 failures -- /clear and rewrite
• Add try/catch to suppress errors instead of fixing root causes

Common Questions

Q: When should I use "Transform directly" vs "Build context first"?

A: Use "Transform directly" when you can see what is missing (no verification, vague location). Use "Build context first" when the prompt references unfamiliar code, spans multiple systems, or the approach is uncertain.

Q: How do I handle prompts that combine multiple tasks?

A: Split them. Each prompt should have a single clear objective. After each task, use /clear to free context, then submit the next. Compound prompts cause scope creep and make verification ambiguous.

Q: What if the prompt is already well-formed?

A: Score it against the Quality Rubric below. If it scores 6+ out of 8, it is ready. Focus on verification criteria and specific file locations -- these two principles account for most of prompt effectiveness.

Examples

Example 1: Bug Fix

BEFORE: fix the login bug

AFTER: users report login fails after session timeout.
check auth flow in src/auth/, especially token refresh
in refresh_token.ts. write a failing test that reproduces
the issue, then fix it. run the auth test suite after.

ADDED: symptom, location, verification (failing test), suite run

Example 2: Feature Implementation

BEFORE: add a search feature

AFTER: implement search for products page. look at filtering
in ProductList.tsx for the pattern. search by name and category.
tests: empty query returns all, partial match works, no results
shows message. no external search libraries.

ADDED: location, reference pattern, test cases, constraint

Example 3: Refactoring

BEFORE: make the code better

AFTER: refactor utils.js to ES2024: convert callbacks to
async/await, use optional chaining, add TypeScript types.
run the existing test suite after each change to ensure
nothing breaks. do not change public API signatures.

ADDED: specific changes, incremental verification, constraint

Example 4: Debugging

BEFORE: the API is slow

AFTER: /api/orders takes 3+ seconds for large orders.
profile database queries in OrderService.ts. look for
N+1 queries or missing indexes. fix and verify response
time is under 500ms with 1000+ order items.

ADDED: endpoint, location, what to look for, measurable target

Transformation Output Format

When transforming a prompt, output in this structure:

**Original:** [user prompt]

**Improved:**
[transformed prompt in code block]

**Added:**
- [what was missing and added]
- [another improvement]

Quality Rubric

Rate the prompt against these 4 dimensions (0-2 each, max 8):

Quick assessment: 0-3 needs significant work, 4-5 needs some improvements, 6-8 good to go.

Transformation Checklist

Before outputting, verify the improved prompt has:

• Verification -- How to know it worked (tests, screenshot, output)
• Location -- Specific files, functions, or areas
• Constraints -- What NOT to do
• Single task -- Not compound (split if needed)
• Phases -- If complex, structured as explore then plan then implement
• Root cause -- For bugs: "address root cause, do not suppress"
• CLAUDE.md -- Respects project conventions if they exist

Anti-Patterns Quick Reference

Session Management

• /clear between unrelated tasks to free context
• After 2 failed corrections, /clear + write a better prompt
• Use subagents (Task tool) for investigation in separate context
• Esc to stop current operation, Esc+Esc to rewind
• claude --continue / --resume for persistent sessions

References

• references/prompt-patterns.md -- Templates, anti-patterns, task-type prompt recipes
• references/transformation-examples.md -- Extended before/after examples for all task types