Claude Code Best Practices: Tips for Faster, Cheaper, Better Results

Battle-tested patterns from teams running hundreds of Claude Code sessions per week. Learn how to decompose tasks, write effective prompts, manage context, optimize costs, and scale with parallel agents.

1. Task decomposition: the single most important skill

The biggest mistake people make with Claude Code is giving it tasks that are too large. "Build the entire checkout flow" will produce worse results than five focused tasks, even if Claude Code could theoretically handle it in one shot. Here's why:

• Context pressure — Large tasks fill the context window with intermediate state, leaving less room for reasoning about the current step
• Error compounding — A wrong decision in step 2 of 10 cascades through the remaining 8 steps
• Review difficulty — A 2,000-line diff is much harder to review than five 400-line diffs
• Parallelization — Small tasks can run simultaneously across multiple agents

A good decomposition for "build the checkout flow" looks like:

# Task 1: Cart data model and API
"Create the CartItem and Cart models in src/models/. Add REST endpoints
for add-to-cart, remove-from-cart, and get-cart. Write unit tests."

# Task 2: Stripe integration
"Create src/services/stripe.ts with functions for creating payment intents,
confirming payments, and handling webhook events. Write tests using Stripe
test mode."

# Task 3: Checkout UI
"Build the checkout page at src/pages/Checkout.tsx. Three steps: cart review,
shipping address, payment. Use the existing DesignSystem components."

# Task 4: Order confirmation
"After successful payment, create an Order record, send confirmation email
via the existing EmailService, and redirect to /orders/:id."

# Task 5: Integration tests
"Write end-to-end tests for the full checkout flow using Playwright.
Cover: happy path, card declined, empty cart, and expired session."

Each task has a clear scope, a clear deliverable, and can be verified independently.

2. Prompt engineering for coding agents

Prompting a coding agent is different from prompting a chatbot. You're not having a conversation — you're writing a specification. The best prompts share these characteristics:

Be specific about location

# Bad
"Add logging to the app"

# Good
"Add structured JSON logging to all route handlers in src/api/routes/.
Use the existing logger from src/lib/logger.ts. Log request method, path,
status code, and duration. Don't add logging to middleware — that's already handled."

Specify the testing strategy

# Bad
"Write tests"

# Good
"Write unit tests for src/services/billing.ts. Mock the Stripe client.
Test: successful charge, card declined, idempotency key collision,
and network timeout. Use the existing test helpers in tests/helpers/."

Reference existing patterns

# Bad
"Create a new API endpoint"

# Good
"Create a GET /api/invoices endpoint following the same pattern as
the existing /api/orders endpoint in src/api/orders.ts. Use the same
auth middleware, pagination, and error handling approach."

State constraints explicitly

If there are things the agent should not do, say so. Claude Code is helpful by default, which means it might "improve" things you didn't ask it to touch.

"Fix the date parsing bug in utils/date.ts line 42. The timezone offset
is being applied twice. Do NOT refactor the rest of the file — only fix
the specific bug."

3. Context window management

Claude Code's context window is large but finite. Every file it reads, every command output, and every conversation turn consumes context. When it fills up, the agent starts forgetting earlier instructions. Active management is essential:

A strong CLAUDE.md reduces the need for /compact because the agent doesn't waste turns exploring your codebase — it already knows the layout, conventions, and current priorities.

4. Git worktree isolation

Never run multiple Claude Code sessions in the same working directory. They will step on each other's changes, create merge conflicts mid-task, and produce broken commits. Git worktrees solve this elegantly:

# Create isolated worktrees for each task
git worktree add ../myproject-auth feature/auth
git worktree add ../myproject-api feature/api-rate-limiting
git worktree add ../myproject-tests feature/payment-tests

# Each Claude Code session works in its own worktree
cd ../myproject-auth && claude
cd ../myproject-api && claude
cd ../myproject-tests && claude

amux handles worktree creation automatically when you register a project. Each session gets its own branch and working directory:

amux register myproject --dir ~/Dev/myproject --yolo
# amux creates worktrees at ~/Dev/myproject-worktrees/session-name/

5. When to use YOLO mode vs. interactive

YOLO mode (auto-approve all actions) is not an all-or-nothing decision. Use it strategically:

The pattern: use YOLO mode when changes are isolated and verifiable, interactive mode when changes are destructive or shared.

6. Cost optimization

Claude Code bills by token usage. Parallel agents multiply your token consumption. Here are proven strategies to keep costs under control:

• Write detailed CLAUDE.md files — Every token the agent spends exploring your codebase is a token you pay for. A good CLAUDE.md eliminates exploratory reads.
• Use /compact before context is full — Compacting at 60% is cheaper than letting the context fill up and having the agent re-read files.
• Scope tasks tightly — "Fix the bug in utils/date.ts line 42" costs 5-10x less than "find and fix date handling bugs across the codebase."
• Kill stuck sessions — An agent retrying a failing approach burns tokens. If you see a session looping, kill it and start fresh with better instructions.
• Batch related changes — "Add input validation to all 5 form components" is cheaper as one task than five separate tasks, because the agent only reads the shared code once.

Typical cost per task (as of March 2026):

7. Error handling patterns

Claude Code sometimes gets stuck. Recognizing failure modes early saves time and tokens:

• Retry loops — The agent keeps trying the same approach and getting the same error. Fix: kill the session, analyze the error yourself, and restart with explicit instructions about the correct approach.
• Scope creep — The agent starts "improving" code you didn't ask it to touch. Fix: add explicit boundaries in your prompt ("only modify files in src/auth/").
• Hallucinated APIs — The agent calls a function or endpoint that doesn't exist. Fix: include the actual API surface in your CLAUDE.md or reference the correct file ("use the client exported from src/lib/api.ts").
• Test-fitting — The agent modifies tests to pass instead of fixing the code. Fix: state explicitly "do not modify existing tests — fix the implementation to make them pass."

8. Scaling with amux

The practices above become critical when you scale from one session to many. amux codifies them:

# Register with best-practice defaults
amux register myproject --dir ~/Dev/myproject --yolo

# amux automatically:
# - Creates git worktrees for each session
# - Adds CLAUDE.md to each worktree
# - Runs sessions in isolated tmux panes
# - Provides a dashboard for monitoring all sessions
# - Tracks tasks on a shared kanban board

# Start the dashboard
amux serve

# Assign tasks via the board
amux board add "Implement user search API" --session api-worker
amux board add "Write search UI component" --session frontend-worker
amux board add "Add search integration tests" --session test-worker

The dashboard at https://localhost:8822 gives you real-time visibility into all sessions. You can see output, send messages, and manage tasks from your browser or phone.

Quick reference: the rules

• One task per session. One branch per session. One worktree per session.
• Write a CLAUDE.md before you start. Update it as the project evolves.
• Use /compact at 60% context, not at 100%.
• YOLO mode for isolated, verifiable work. Interactive mode for destructive operations.
• Kill and restart stuck sessions. Don't let them loop.
• Review every diff before merging, regardless of mode.
• Scope prompts tightly. Specify files, functions, and constraints.

git clone https://github.com/mixpeek/amux && cd amux && ./install.sh
amux register myproject --dir ~/Dev/myproject --yolo
amux start myproject
amux serve  # → https://localhost:8822