Best Practices

If "Transform directly"

Apply the 5 principles below and output the improved prompt immediately.

If "Build context first"

Launch 3 parallel agents to gather context:

Run these agents IN PARALLEL using the Task tool:

- Task task-intent-analyzer("[user's prompt]")
- Task best-practices-referencer("[user's prompt]")
- Task codebase-context-builder("[user's prompt]")

What Each Agent Returns

After Agents Return

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

Agent Definitions

The agents are defined in agents/:

• agents/task-intent-analyzer.md — Analyzes intent, gaps, and edge cases
• agents/best-practices-referencer.md — Finds relevant examples and patterns from references/
• agents/codebase-context-builder.md — Explores codebase for files and conventions

Transformation Workflow

When transforming (after mode selection):

1. Identify what's missing — Check against the 5 principles below
2. Add missing elements — Verification, context, constraints, phases, rich content
3. Output the improved prompt — In a code block, ready to copy-paste
4. Show what changed — Brief comparison of before/after

The 5 Transformation Principles

Apply these in order of priority:

1. Add Verification (Highest Priority)

The single highest-leverage improvement. Claude performs dramatically better when it can verify its own work.

BEFORE: "implement email validation"
AFTER:  "write a validateEmail function. test cases: [email protected] → true,
         invalid → false, [email protected] → false. run the tests after implementing"

BEFORE: "fix the API error"
AFTER:  "the /api/orders endpoint returns 500 for large orders. check
         OrderService.ts for the error. address the root cause, don't suppress
         the error. after fixing, run the test suite and summarize what passed
         and what you verified."

2. Provide Specific Context

Replace vague references with precise locations and details.

Four ways to add context:

Respect Project CLAUDE.md:

If the project has a CLAUDE.md, the transformed prompt should:

• Not contradict project conventions
• Reference project-specific patterns when relevant
• Note any project constraints that apply

BEFORE: "add a new API endpoint"
AFTER:  "add a GET /api/products endpoint. check CLAUDE.md for API conventions
         in this project. follow the pattern in routes/users.ts. run the API
         tests after implementing."

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

3. Add Constraints

Tell Claude what NOT to do. Prevents over-engineering and unwanted changes.

BEFORE: "add a calendar widget"
AFTER:  "implement a calendar widget with month selection and year pagination.
         follow the pattern in HotDogWidget.php. build from scratch without
         libraries other than the ones already used in the codebase"

4. Structure Complex Tasks in Phases

For larger tasks, separate exploration from implementation.

The 4-Phase Pattern:

Phase 1: EXPLORE
"read src/auth/ and understand how we handle sessions and login.
 also look at how we manage environment variables for secrets."

Phase 2: PLAN
"I want to add Google OAuth. What files need to change?
 What's the session flow? Create a plan."

Phase 3: IMPLEMENT
"implement the OAuth flow from your plan. write tests for the
 callback handler, run the test suite and fix any failures."

Phase 4: COMMIT
"commit with a descriptive message and open a PR"

When to use phases:

• Uncertain about the approach
• Change modifies multiple files
• Unfamiliar with the code being modified

Skip phases when:

• Could describe the diff in one sentence
• Fixing a typo, adding a log line, renaming a variable

BEFORE: "add OAuth"
AFTER:  "read src/auth/ and understand current session handling. create a plan
         for adding OAuth. then implement following the plan. write tests and
         verify they pass"

5. Include Rich Content

Provide supporting materials that Claude can use directly.

BEFORE: "make the dashboard look better"
AFTER:  "[paste screenshot] implement this design for the dashboard.
         take a screenshot of the result and compare it to the original.
         list any differences and fix them. ensure responsive behavior
         at 768px and 1024px breakpoints"

BEFORE: "the build is failing"
AFTER:  "the build fails with this error: [paste actual error]. fix it
         and verify the build succeeds. address the root cause, don't
         suppress the error"

Output Format

When transforming a prompt, output:

**Original:** [their prompt]

**Improved:**

[transformed prompt in code block]

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

Quick Transformation Examples

Bug Fix

BEFORE: "fix the login bug"

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

ADDED: symptom, location, verification (failing test), success criteria

Feature Implementation

BEFORE: "add a search feature"

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

ADDED: location, reference pattern, specific behavior, test cases, constraint

Refactoring

BEFORE: "make the code better"

AFTER: "refactor utils.js to use ES2024 features while maintaining the same
behavior. specifically: convert callbacks to async/await, use optional
chaining, add proper TypeScript types. run the existing test suite after
each change to ensure nothing breaks."

ADDED: specific changes, constraint (same behavior), verification after each step

Testing

BEFORE: "add tests for foo.py"

AFTER: "write tests for foo.py covering the edge case where the user is
logged out. avoid mocks. use the existing test patterns in tests/. test