Most Claude Code users treat it like a smarter terminal chatbot: type a request, read the output, repeat. That works well enough for one-off tasks. It fails badly for anything that spans more than a single session, involves a non-trivial codebase, or has to fit inside a budget.

The structured setup — CLAUDE.md per project, custom slash commands in .claude/commands/, specialized subagents, and a handful of hooks — is what separates a $200/month Max user who burns through their quota by Wednesday from a $20/month Pro user who ships more code by Friday.

This is that setup, with real numbers and specific file contents.

---

The chatbot trap

Three habits mark the developer who will regret their Claude Code subscription within a month:

Pasting full files into Chat. You open src/api/handlers/payments.ts, copy 600 lines, paste it with “what’s wrong here?” Claude reads it, answers, and now your context window holds 600 lines of boilerplate for every message that follows. Every subsequent turn pays the token cost of those 600 lines. By message 15 you hit “Prompt is too long” and lose the session.

Re-explaining the project every session. “This is a Next.js 14 app with a Prisma ORM backed by PostgreSQL. We use tRPC for the API layer. We deploy to Vercel. Please don’t suggest Mongoose…” — typed again, for the fourth week in a row.

Using Opus for everything. Checking if a console.log was removed? That doesn’t need Claude Opus 4.7. It needs Claude Haiku 4.5, which costs $1/M input tokens versus Opus’s $5/M. Running Opus by default on the kind of work Sonnet handles just as well is the fastest way to burn through a Max 5x subscription.

The fix for all three is structural, not behavioral.

---

CLAUDE.md per project: the minimal viable setup

CLAUDE.md is the file Claude reads at the start of every session in your project. It acts as the permanent context you used to re-type every time. Claude’s docs put it plainly: “Add to it when Claude makes the same mistake a second time.” That’s the right bar.

Two scoped locations matter:

Location	Scope
./CLAUDE.md or ./.claude/CLAUDE.md	Project-wide, committed to git, visible to the whole team
~/.claude/CLAUDE.md	Personal, applies across all your projects
./CLAUDE.local.md	Personal + project-specific, add to .gitignore

Keep each file under 200 lines. Longer files consume context tokens on every message and degrade adherence — Claude starts treating them as background noise rather than instructions.

A sample for a TypeScript backend

# Project: payments-api

## Stack
- Node.js 22, TypeScript strict mode
- Prisma 5.x + PostgreSQL 16
- tRPC v11 for API layer
- Vitest for unit tests; supertest for integration tests
- Deployed via Vercel (serverless functions)

## Commands
- `npm run dev` — start local dev server (port 3000)
- `npm run test` — run Vitest
- `npm run typecheck` — tsc --noEmit
- `npx prisma migrate dev` — apply local migration

## Conventions
- Use `zod` for all input validation, not manual if-checks
- Error handling: throw `TRPCError` with appropriate code, never raw `new Error()`
- Database queries live in `src/db/queries/`, never inline in route handlers
- No `any` types. If you can't avoid it, add a `TODO(type):` comment
- All money amounts in integer cents; never floats

## Things Claude should never do
- Suggest switching ORMs
- Use `console.log` for production logging; use `src/lib/logger.ts`
- Add new npm dependencies without asking first
- Run `prisma migrate deploy` (production command — requires explicit confirmation)

That’s 25 lines. It removes the top 5 questions Claude would otherwise ask you, and the top 3 mistakes it would otherwise make.

For larger projects, move subsystem rules into .claude/rules/ as separate markdown files. Path-scoped rules load only when Claude opens matching files — your testing.md rules can specify paths: ["**/*.test.ts"] so they appear in context only during test work, not when editing migrations.

---

Custom slash commands: 3 examples you’ll use every day

Slash commands live in .claude/commands/<name>.md (project scope) or ~/.claude/commands/<name>.md (personal scope). The filename is the command name. Type /name in any session to run it.

The modern equivalent is .claude/skills/<name>/SKILL.md, which also supports autonomous invocation — but .claude/commands/ still works and is simpler for custom prompts.

/pr-review — code review before every merge

---
allowed-tools: Read, Grep, Glob, Bash(git diff *), Bash(git log *)
description: Review staged changes before opening a PR
---

## Context
- Changed files: !`git diff --name-only HEAD~1`
- Full diff: !`git diff HEAD~1`
- Recent commits: !`git log --oneline -5`

## Review checklist
1. Check for security issues: SQL injection, XSS, exposed secrets, missing input validation
2. Verify error handling is consistent with the project pattern (TRPCError, not raw throws)
3. Check for missing or incorrect TypeScript types
4. Flag any inline `TODO` comments that should be issues instead
5. Call out any new npm dependencies added without a corresponding package.json note

Provide feedback as a prioritized list: MUST FIX → SHOULD FIX → OPTIONAL.

Use it: /pr-review. Claude runs git diff automatically via the !``command`` syntax and reviews what’s actually staged — no copy-pasting.

/test-failure-fix — diagnose a failing test

---
allowed-tools: Bash, Read, Edit
argument-hint: [test-file-path]
description: Run a failing test and fix it
---

Run the failing test at $ARGUMENTS, then diagnose and fix the failure.

Steps:
1. Run: `npx vitest run $ARGUMENTS --reporter=verbose`
2. Read the relevant source file
3. Identify the root cause — distinguish a real bug from a stale test
4. Fix the source (preferred) or update the test if the assertion is genuinely wrong
5. Re-run to confirm the test passes
6. Stop after one fix attempt — don't spiral into refactoring

Use it: /test-failure-fix src/api/payments.test.ts. One focused command instead of a multi-turn conversation.

/deploy — pre-deployment checklist

---
allowed-tools: Bash, Read
description: Run pre-deployment checks before pushing
---

Run the full pre-deployment checklist:

1. `npm run typecheck` — must pass with zero errors
2. `npm run test` — all tests must pass
3. `git diff --stat origin/main` — show what's shipping
4. Check for any `console.log` calls added recently: !`git diff origin/main | grep "console.log"`
5. Check for any hardcoded secrets or API keys: !`git diff origin/main | grep -i "secret\|api_key\|password" | grep "^+" | grep -v "// "`

If all checks pass, print "✓ Ready to deploy." If any fail, print the specific error and stop.

Use it: /deploy. Three minutes saved per deployment, every deployment.

---

Subagents for specialized work

A subagent is a separate Claude instance that runs a focused task and returns only its final answer to the parent conversation. The key benefit isn’t intelligence — it’s context isolation. The subagent can read 40 files, run tests, and generate a long analysis without any of that intermediate noise accumulating in your main session.

Define subagents as files in .claude/agents/<name>.md:

Code-reviewer subagent

---
name: code-reviewer
description: Expert security and quality reviewer. Invoke when reviewing a PR, new module, or any code with auth/payment logic.
model: sonnet
tools: [Read, Grep, Glob]
---

You are a code review specialist focused on security, correctness, and maintainability.

When reviewing code:
- Identify injection risks, privilege escalation paths, and missing input validation
- Flag type safety gaps and incorrect error propagation
- Check for missing tests on critical paths
- Suggest specific fixes with line references, not general advice

Return a structured report: Critical → High → Medium → Low severity.
Never modify files — Read, Grep, and Glob only.

Test-writer subagent

---
name: test-writer
description: Writes unit and integration tests for new functions or modules. Invoke when a file has no test coverage.
model: haiku
tools: [Read, Glob, Write]
---

You write tests for the project's Vitest framework.

For each function passed to you:
1. Read the source and identify the public API surface
2. Write tests for: happy path, empty/null inputs, error conditions, edge cases
3. Match the existing test file conventions — import style, describe blocks, assertion patterns
4. Create the test file at the path I give you; do not overwrite existing tests

Return the path of the file you created.

Note that the test-writer uses model: haiku — it doesn’t need Opus-level reasoning to write test scaffolding. At $1/M input tokens vs $5/M for Opus, that’s an 80% reduction on every test-writing task.

Invoke by name: “Use the code-reviewer agent to review src/payments/stripe.ts.” Or just describe the task and Claude routes to the right agent based on the description field.

One hard constraint: subagents cannot spawn their own subagents. Don’t include Agent in a subagent’s tools array.

---

Hooks for safety and automation

Hooks are shell commands or SDK callbacks that run at fixed lifecycle events — before a tool call fires (PreToolUse), after it completes (PostToolUse), when a session ends (Stop). Unlike CLAUDE.md instructions, hooks execute 100% of the time regardless of what Claude decides. That distinction matters for safety rules.

Configure them in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/block-destructive.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/auto-format.sh"
          }
        ]
      }
    ]
  }
}

Hook: block destructive Bash commands

Create ~/.claude/hooks/block-destructive.sh:

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')

# Block rm -rf and related patterns
if echo "$cmd" | grep -qE 'rm\s+-rf|DROP\s+TABLE|DELETE\s+FROM\s+[a-z]+ WHERE 1'; then
  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Destructive command blocked by hook. Confirm manually.\"}}"
else
  echo "{}"
fi

Claude sees the block reason, won’t retry, and will ask you to confirm before it runs the command manually. Hard enforcement — not a polite suggestion in CLAUDE.md.

Hook: auto-format on write

Create ~/.claude/hooks/auto-format.sh:

#!/bin/bash
input=$(cat)
file=$(echo "$input" | jq -r '.tool_input.file_path // ""')

# Format TypeScript/JavaScript files after every write
if [[ "$file" =~ \.(ts|tsx|js|jsx)$ ]]; then
  npx prettier --write "$file" 2>/dev/null
fi

echo "{}"

Every time Claude writes or edits a TypeScript file, prettier runs automatically. No more “Claude, run prettier” follow-up messages.

---

The token bill: how to go from $200 to $30

The math on Claude Code billing is simpler than it looks. There are three levers.

Lever 1: Subscription tier vs. API — pick correctly

Who you are	Best option
Daily driver, moderate session length	Pro at $20/mo
Heavy user, long agentic sessions, need Opus	Max 5x at $100/mo
Needs Opus daily + runs parallel instances	Max 20x at $200/mo
Running CI pipelines or batch automation	API directly

The April 2026 pricing confusion is resolved: Opus 4.7 is not available on Pro. If you hit the “Claude Opus is not available with the Claude Pro plan” error and you need Opus, you must be on Max. If Sonnet handles your work (it handles 80%+ of typical coding tasks), Pro is fine.

One team tracked 10 billion tokens over eight months. At direct API rates, that would have cost over $15,000. Under Max at $100/month, the same period ran under $800 — a 93% discount from subscription pricing. Subscriptions win for heavy interactive use. The API wins for automation where you control the prompt sizes.

Lever 2: Model routing

Current API prices (verified May 20, 2026):

Model	Input / M tokens	Output / M tokens
Claude Haiku 4.5	$1.00	$5.00
Claude Sonnet 4.6	$3.00	$15.00
Claude Opus 4.7	$5.00	$25.00

Use /model mid-session to switch. The practical routing rule:

• Haiku: subagent tasks, test scaffolding, boilerplate generation, simple diffs
• Sonnet: most coding work, refactoring, debugging, PR reviews
• Opus: multi-file architecture decisions, complex security reviews, anything that needs genuine reasoning across 10+ interdependent files

Setting model: haiku in a subagent definition is a one-line change that drops subagent costs by 80%.

Lever 3: Context management

Claude Code’s docs are direct: “The more context Claude processes, the more tokens you use.” Three practices keep context small:

• /clear between tasks. Stale context from the payments refactor you finished an hour ago costs tokens on every message in your current session. Clear it.
• /compact proactively. Don’t wait for the “Prompt is too long” error. Run /compact Focus on code changes and test results once your session runs 20+ messages.
• Keep CLAUDE.md under 200 lines; move large workflow docs to skills. Skills load on-demand only when invoked. A 500-line deployment guide in CLAUDE.md costs tokens every session; as a skill file at .claude/skills/deploy/SKILL.md, it costs tokens only when you type /deploy.

Prompt caching handles the rest automatically — Claude Code caches system prompts and repeated content across turns. Cache reads cost 10% of base input price ($0.30/M for Sonnet vs $3.00/M uncached). Sessions with stable CLAUDE.md + tools preamble regularly hit 60-70% cache hit rates, cutting effective input costs by more than half.

Combine model routing + context management + caching and a $200/mo Max bill is often a sign that the workload should stay on Max — but an API user who was spending $200/month without any of these optimizations can realistically land at $60-80/month.

For subscription users: the fastest path from Max 20x ($200) to Pro ($20) is honest self-assessment. If you hit the session limit once a month but never hit the weekly cap, you don’t need Max 20x.

---

Troubleshooting: 3 errors with exact fixes

”You’ve hit your session limit · resets 3:45pm”

What it means: you’ve consumed your plan’s rolling usage allowance. The reset time in the message is exact.

Fixes:

1. Wait for the reset (fastest, free)
2. Run /usage-credits to buy additional usage on Pro or Max
3. If you hit this daily, run /usage to see your actual consumption pattern — you may need to upgrade or optimize (see token bill section above)
4. Switch to API auth temporarily: set ANTHROPIC_API_KEY in your shell, run /logout, and Claude Code routes to pay-per-token billing until you re-authenticate with your subscription

”Prompt is too long” / “Error during compaction: Conversation too long”

What it means: the conversation + CLAUDE.md + MCP tool definitions + attached files have exhausted the model’s context window. Auto-compact tried and failed.

Fixes for “Prompt is too long”:

1. Run /compact immediately
2. If that fails too (“Conversation too long”), press Esc twice to step back several turns, then run /compact
3. Run /context to see what’s filling the window — MCP tool definitions are a common culprit. Disable unused servers: /mcp disable <name>
4. If CLAUDE.md is over 200 lines, trim it now

Prevention: run /usage or configure the status line to show context window usage continuously. Don’t let sessions run past 60% context fill without compacting.

”Claude Opus is not available with the Claude Pro plan”

What it means: you’re authenticated with a Pro subscription but the active session or a slash command frontmatter specifies model: claude-opus-4-7 (or model: opus).

Fixes:

1. Run /model and select Sonnet or Haiku
2. If a subagent or command file has model: opus in its frontmatter, change it to model: sonnet
3. If you genuinely need Opus, upgrade to Max 5x ($100/mo) at claude.com/pricing
4. After upgrading, run /logout then /login — the stored token reflects your plan at sign-in time, so an in-session upgrade doesn’t take effect until re-authentication

---

Cursor vs Claude Code: which tool for which task

If you use Cursor daily and are evaluating whether Claude Code replaces it: the answer is no, it complements it.

Cursor’s Tab autocomplete and .cursor/rules/ inline editing are faster for the moment-to-moment coding loop — keeping your hands on the keyboard while a suggestion lands in a split second. Claude Code’s strength is autonomous multi-step work: “refactor these 12 files to use the new auth module, run the tests, fix what breaks, and commit.” That’s a 30-minute task for a developer and a 4-minute background job for Claude Code.

The practical split: Cursor for reactive editing, Claude Code for agentic tasks. They’re complementary, not competing.

---

The structured setup in one checklist

If you implement nothing else from this article, implement these five things:

• ./CLAUDE.md with stack, commands, and conventions (under 200 lines)
• .claude/commands/pr-review.md so code review is one command
• A subagent for the task you do most repetitively (test-writer or code-reviewer)
• block-destructive.sh hook (20 lines; prevents one catastrophic mistake)
• model: haiku on any subagent that doesn’t need reasoning

That’s the floor. The ceiling is a full .claude/skills/ library, path-scoped .claude/rules/, a custom status line showing context fill, and hooks that auto-format every file Claude touches.

If you want the full kit — 5 CLAUDE.md templates for different project types, 4 ready-to-use slash commands, 4 subagent definitions, 3 hooks, and 5 deep documentation files — the Claude Code Power User Kit on Gumroad is $29. First 50 buyers get it for $19 with code EARLYBIRD50.

---

Sources

• Manage costs effectively — Claude Code Docs
• Memory and CLAUDE.md files — Claude Code Docs
• Slash commands in the SDK — Claude Code Docs
• Subagents in the SDK — Claude Code Docs
• Hooks in the SDK — Claude Code Docs
• Error reference — Claude Code Docs
• Claude API Pricing 2026: Haiku 4.5, Sonnet 4.6, Opus 4.7 — BenchLM.ai
• Claude Code Pricing 2026: Pro vs Max, Limits & Hidden Costs — Duet
• Claude Code Token Optimization: Stop the $1,600 Bill — Build to Launch
• Claude Code Customization: CLAUDE.md, Slash Commands, Skills, and Subagents — alexop.dev

Last updated May 20, 2026. Pricing and plan features change frequently; verify current state at claude.com/pricing before purchasing.