The Complete Claude Code Guide (2026): Planning, Context Engineering, and High-Leverage Development

Part II: CLAUDE.md — Your Highest Leverage Asset

Most people overcomplicate this file or ignore it entirely. Both are wrong. This file defines how Claude thinks about your project. It's the single highest-ROI investment you can make.

How CLAUDE.md Files Cascade

CLAUDE.md files load from multiple locations with specific priority:

Always loaded at session start:

• ~/.claude/CLAUDE.md — Your global, personal preferences (keep under 50 lines)

• ./CLAUDE.md or .claude/CLAUDE.md — Project root (the main one)

• CLAUDE.local.md — Personal overrides, add to .gitignore

Conditionally loaded:

• .claude/rules/*.md — Loaded based on paths: frontmatter when working in matching directories

• Subdirectory CLAUDE.md files — Lazy-loaded when Claude enters that directory

This cascade matters. Put universal rules at the project root. Put module-specific rules in subdirectories. They'll only load when relevant, saving context tokens.

What to Include

Use the WHAT / WHY / HOW framework:

WHAT — Tech stack, project structure, key abstractions. Critical in monorepos where Claude needs to know which packages exist and how they relate.

WHY — What the project does and why certain patterns exist. "We use event sourcing because X" prevents Claude from refactoring toward a pattern that breaks your architecture.

HOW — Commands to build, test, lint, deploy. Verification steps. Workflow instructions.

Here's what a strong CLAUDE.md looks like:

# ShopFront — E-commerce Platform

Next.js 16 App Router, TypeScript strict, Prisma ORM, Stripe payments.

## Commands
- `npm run dev` — Dev server (port 3000)
- `npm test` — Jest suite
- `npm run lint` — ESLint
- `npm run db:migrate` — Prisma migrations

## Architecture
- `/app` — Next.js App Router pages
- `/components/ui` — Shared UI (Tailwind, no custom CSS files)
- `/lib` — Utilities and business logic
- `/prisma` — Database schema and migrations

## Code Style
- Named exports only, no default exports
- No `any` types — use `unknown` + type narrowing
- 2-space indentation, semicolons required

## Critical Rules
- NEVER commit .env files
- Stripe webhook handler MUST validate signatures
- All database queries go through Prisma — no raw SQL
- Run `npm test` after any change to `/lib`

That's about 30 lines. Tight. Specific. Every line earns its place.

Why Shorter Is Better

This is counterintuitive, but critical: Claude Code wraps your CLAUDE.md contents with a system note indicating the context "may or may not be relevant." This means Claude may deprioritize content it deems irrelevant to the current task.

Community compliance testing found:

• Specific rules ("Use 2-space indentation") — ~89% compliance

• Vague instructions ("Write clean code") — ~35% compliance

And length kills compliance uniformly. Files over 2,000 lines have been documented in the wild — and the result isn't that later rules get ignored. All rules degrade. The model's attention budget is finite.

Recommendations from the community:

• ~/.claude/CLAUDE.md — Under 50 lines

• Project root CLAUDE.md — Under 300 lines (shorter is better)

• Total across all loaded files — Under 2,000 tokens

The Progressive Disclosure Pattern

Instead of cramming everything into CLAUDE.md, keep task-specific instructions in separate files:

agent_docs/
  ├── building.md
  ├── testing.md
  ├── api_conventions.md
  └── deployment.md

Reference them in CLAUDE.md with brief descriptions. Claude will read them when the task is relevant. The @ import syntax supports this: See @docs/api-patterns.md for API conventions.

This is the difference between a 30-line CLAUDE.md that works and a 500-line one that doesn't.

Common Mistakes

Negation activates the concept. "Do NOT use semicolons" still puts semicolons in Claude's attention. Flipping negative rules to positive equivalents ("Use no-semicolons ESLint rule") cut violations roughly in half in community testing.

Marking everything as "IMPORTANT" dilutes everything. If you bold 10 rules, none of them are bold. Reserve emphasis for genuinely critical constraints — one or two at most.

@-mentioning large files. @docs/full-api-reference.md embeds the entire file into context at session start, burning thousands of tokens before you type anything. Reference files by path description instead and let Claude read them on demand.

Update It Continuously

When Claude makes a mistake:

1. Fix it manually

2. Add a rule to CLAUDE.md so it never happens again

This compounds over time. After a few weeks, your CLAUDE.md becomes a distillation of every hard-won lesson about your codebase.

Part III: Plan Mode — The Biggest Unlock

This is where most people leave the most value on the table.

The Three Operating Modes

Claude Code has three modes, toggled with Shift+Tab:

Plan mode is enforced at the tool level — not a prompt suggestion. Claude literally cannot edit files or run destructive commands in plan mode. It can only read, search, and think.

Other ways to enter plan mode: the /plan command, claude --permission-mode plan from the CLI, or Alt+M on Windows.

Why Planning Changes the Math

Here's the statistical argument. If you assume 80% accuracy per decision, and a feature involves 20 decision points:

0.8^20 = ~1% chance of getting everything right.

Plan mode adds a review phase at the beginning. Instead of making 20 sequential guesses, you make a plan, review it, fix it, then execute. This front-loads the hard thinking before context gets polluted with implementation details.

The 4-Phase Workflow

This is the workflow recommended by Anthropic's own documentation and Claude Code's creator:

Phase 1 — EXPLORE (Plan Mode)

Let Claude read files and understand the architecture. Don't let it write anything.

Read src/auth/ and understand how we handle sessions. 
What's the token refresh flow?

Phase 2 — PLAN (Plan Mode)

Claude creates a structured plan. You review and iterate.

ultrathink. Based on what you've read, propose a plan to add 
OAuth2 support. Break it into phases. Don't code yet.

Press Ctrl+G to open the plan in your editor for direct editing. Challenge assumptions. Ask about edge cases. Refine until it's right.

Phase 3 — IMPLEMENT (Normal or Auto-Accept)

Switch modes with Shift+Tab. Execute the approved plan.

Execute phase 1 of the plan.

Phase 4 — COMMIT

Commit these changes with a descriptive message and create a PR.

The opusplan Strategy

The /model opusplan alias automatically uses Opus for planning (superior reasoning, architecture decisions) and Sonnet for execution (fast, cost-efficient code generation). This gives you the best of both models without manually switching.

Boris Cherny's Workflow

Claude Code's creator reportedly uses plan mode for roughly 80% of tasks. The pattern: start in Plan Mode → iterate on the plan → switch to Auto-Accept for execution → flip between modes constantly. Plan mode for alignment, default for review, auto-accept for the mechanical bits.

Part IV: Context Management — The Real Skill

Context management is the single most important skill for Claude Code productivity. More important than prompt engineering. More important than knowing every feature. Users who manage context well consistently outperform those who don't.

How the Context Window Works

Claude Code's context window is currently 1 million tokens for Opus 4.6 and Sonnet 4.6. Auto-compaction triggers at approximately 83.5% capacity.

A 500-line TypeScript file consumes roughly 4,000 tokens. A detailed Claude response runs 1,500–3,000 tokens. You get roughly 50 complete exchanges before saturation in a 200K-equivalent working context.

The /context command shows a detailed token allocation breakdown. Check it regularly.

The Two Reset Commands

/compact — Summarizes conversation history into compressed form. Preserves key decisions, file paths, function names, and error messages while freeing 60-80% of tokens.

It accepts focus arguments:

/compact "Preserve only the auth module changes and test results"

/clear — Wipes context entirely. Full reset.

When to use which:

Use /compact when you're mid-feature but the conversation is getting long. Use /clear when switching to completely unrelated work.

Community consensus: proactively compact at 70-75% usage rather than waiting for auto-compaction at 83.5%. Several power users override the threshold:

{ "env": { "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "75" } }

The Session Scope Rule

A session should have one clear scope: "implement pagination" or "debug the auth token refresh." When that scope is done, the session is done.

Starting a second task in the same session because you still have context budget is the single most common path to unfocused, low-quality results. Fresh context is free. Use it.

MCP Context Bloat

One user documented 67,000 tokens consumed by connecting just 4 MCP servers — before typing a single prompt. Every tool from every server gets preloaded into context.

The newer Tool Search feature (enabled by default) loads tools on-demand instead, reducing MCP context consumption by roughly 47%. Control with ENABLE_TOOL_SEARCH=auto:5.

Context Degradation Signals

When context gets overloaded, you'll notice:

• Repetition — Claude suggests things you already tried

• Drift — It reverts to generic code style, ignoring your conventions

• Hallucination uptick — Wrong function names, invented APIs

When you see these, don't push through. Compact or clear.

Part V: Extended Thinking

You can control how much reasoning Claude does before responding. The thinking budget hierarchy:

Extended thinking is now enabled by default with a 31,999 token budget, and the older "ultrathink" keyword was officially deprecated. However, many community members report that explicit keywords still produce noticeably better results on complex tasks — likely because the keyword serves as an intent signal beyond just the token allocation.

Use /effort to set reasoning effort (low / medium / high). /effort auto resets to default.

When to use high-effort thinking:

• Architecture decisions

• Complex refactoring plans

• Debugging sessions where the root cause isn't obvious

• Any task where you'd want a senior engineer to think carefully before acting

When low effort is fine:

• Boilerplate generation

• Simple file edits

• Running familiar commands

Part VI: Advanced Features

Custom Slash Commands (Skills)

Custom commands are Markdown files where the filename becomes the command. commit.md in .claude/commands/ becomes /commit. Subdirectories use colons: tools/security-scan.md → /tools:security-scan.

---
description: Create a conventional commit from staged changes
allowed-tools: Bash(git add:*), Bash(git commit:*)
model: claude-3-5-haiku-20241022
---
<git_diff>
!`git diff --cached`
</git_diff>

Create a commit message following Conventional Commits format.
If $ARGUMENTS is provided, use it as the commit message.

The ! prefix executes shell commands and embeds their output. $ARGUMENTS captures everything typed after the command name.

Store project-level commands in .claude/commands/. Store personal commands in ~/.claude/commands/.

Built-in commands worth knowing:

• /simplify — Spawns 3 parallel review agents for code quality

• /batch <instruction> — Orchestrates large-scale parallel changes

• /commit-push-pr — One-step commit → push → PR creation

• /security-review — Vulnerability scanning

Sub-Agents

Sub-agents run in their own context window with custom system prompts. This is the key architectural concept: the parent agent's context stays clean while the sub-agent handles a focused task. The parent receives only the sub-agent's final result.

Built-in sub-agents include Explore (fast, read-only codebase analysis using Haiku) and Plan.

Define custom sub-agents as Markdown files with YAML frontmatter:

---
name: code-reviewer
description: Expert code review specialist
tools: Read, Grep, Glob, Bash
model: haiku
---
You are a senior code reviewer. Focus on correctness, 
performance, and adherence to project conventions.

Store in .claude/agents/ (project-level) or ~/.claude/agents/ (user-level). Launch with claude --agent code-reviewer.

When to use sub-agents vs. keeping it in the main context:

Sub-agents are for focused, parallelizable tasks — code review, research, file analysis. They return results, not full reasoning context.

If the task requires deep understanding of the ongoing conversation — core business logic, complex debugging with back-and-forth — keep it in the main context.

MCP Integration

MCP (Model Context Protocol) connects Claude Code to external tools and data sources.

Add via CLI:

claude mcp add github -- npx -y @modelcontextprotocol/server-github

Or via .mcp.json at project root:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

Transport types: stdio (local, most common), sse (remote servers), http.

The token cost warning is real. Each MCP server adds all its tools to context. Only connect servers you're actively using. Disconnect when you're done.

Hooks

Hooks are deterministic shell commands that fire at specific lifecycle points. Unlike LLM behavior, hooks always execute — they're not suggestions.

Key events: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop, PreCompact.

Example — auto-format TypeScript after every edit:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read f; if echo \"$f\" | grep -q '\\.ts$'; then npx prettier --write \"$f\"; fi; }"
          }
        ]
      }
    ]
  }
}

Exit code 0 = proceed. Exit code 2 = block the tool call. Default timeout: 10 minutes.

Practical hook uses:

• Auto-linting after file writes

• Running tests after implementation changes

• Enforcing TDD (block implementation when tests are missing)

• Logging all tool usage for audit

• Custom notifications on task completion

Headless Mode and CI/CD

The -p flag runs Claude Code non-interactively:

claude -p "Find potential bugs in this file" < file.js
claude -p "Analyze this code" --output-format json
claude -p "Generate docs" --output-format stream-json

Key flags for CI:

• --allowedTools "Read,Grep,Glob" — Restrict available tools

• --max-turns 5 — Limit iteration count

• --no-user-prompt — Prevent confirmation prompts

GitHub Actions integration uses the official anthropics/claude-code-action. You can mention @claude in issues and PRs to trigger automated implementation, review, and PR creation.

Git Integration

Claude Code has deep native git integration:

• Conversational commits — "Commit these changes with a descriptive message"

• PR creation — Uses gh CLI if available

• Merge conflict resolution — "Resolve the conflicts in auth.ts"

• History analysis — "What changed in this file over the last 5 commits?"

Git checkpoints — Claude creates temporary commits prefixed [checkpoint] before making changes. Press Esc+Esc to restore to the last checkpoint. This is your undo button.

Git worktrees enable true parallel development:

claude --worktree feature-auth    # Terminal 1
claude --worktree bugfix-123      # Terminal 2

Each worktree gets its own working directory and branch while sharing repository history.

Part VII: Power User Workflows

Multi-Phase Execution

Large tasks exceed a single context window. The solution: break work into phases, execute each in a focused session.

Step 1: Plan the phases

I want to add a full authentication system. Break this into 
5 discrete phases, each completable in one session. Write the 
plan to PLAN.md.

Step 2: Execute phase by phase

Read PLAN.md and execute Phase 1: Database schema and migrations.

Between phases, clear context and start fresh. The plan file persists on disk — it survives any number of context resets.

Why this works:

• Each session has a small, focused context

• The plan file is the source of truth

• You can review between phases

• Quality stays high because context never gets bloated

For even more persistence, use GitHub Issues as your plan store. Claude can create issues and fetch them in later sessions.

The Spec-First Interview Pattern

One of the most effective workflows for complex features:

I want to build [brief description]. Interview me using the 
AskUserQuestion tool. Ask about technical implementation, 
UI/UX, edge cases, and tradeoffs. Don't ask obvious questions — 
dig into the hard parts. Keep interviewing until we've covered 
everything, then write a complete spec to SPEC.md.

Then start a fresh session to implement from the spec. The interview session's only job was gathering requirements. The implementation session starts with clean context focused entirely on execution.

Test-Driven Development

Claude's natural instinct is to write implementation first, then tests. You need to explicitly invert this:

RED phase:

Write a FAILING test for the user registration endpoint. 
Test email validation, password strength, and duplicate detection.
Do NOT write any implementation yet.

GREEN phase:

The tests are failing. Implement the minimum code to make them pass.
Nothing more.

REFACTOR phase:

Tests pass. Refactor: extract validation logic, improve naming. 
Run tests after each change to confirm they still pass.

For advanced TDD, use separate sub-agents for test writing vs. implementation to prevent context pollution. The open-source TDD Guard tool uses hooks to block implementation when tests are missing.

Debugging Workflows

Start in Plan Mode. Paste the error message and stack trace. Let Claude investigate without making changes.

Here's the error: [paste error]. Read the relevant files, 
understand the data flow, and explain what's happening. 
Don't fix anything yet.

Once you understand the root cause, switch to normal mode for the fix.

For iterative debugging, pipe test output back in:

npm run test 2>&1 | tee outfile | claude

Key debugging tip: don't just ask for fixes. Ask Claude to explain why the bug occurred, how to prevent similar issues, and to update CLAUDE.md with a rule that prevents recurrence.

Parallel Development

Run multiple Claude Code instances simultaneously:

• Terminal 1 — Feature development

• Terminal 2 — Writing tests

• Terminal 3 — Documentation

Git worktrees make this seamless — each instance works on its own branch.

The bottleneck shifts from Claude's speed to your ability to manage context switching across instances.

Part VIII: Cost Optimization

Pricing

Over 90% of all tokens in typical sessions are cache reads, which cost roughly 10× less than fresh input. Output tokens cost 5× input, so reducing response length delivers outsized savings.

Average daily cost: $6/developer with good habits. 90% of users stay below $12/day. Poor habits push that to $20-40/day.

Model Selection Strategy

Sonnet 4.6 (default) handles most coding tasks. It's the sweet spot of speed, quality, and cost for day-to-day development.

Opus 4.6 is for complex architectural decisions, multi-agent orchestration, and critical reviews. It's 5× Sonnet's cost — use it deliberately. The /model opusplan alias gives you Opus for planning and Sonnet for execution automatically.

Haiku 4.5 achieves roughly 90% of Sonnet's capability for many tasks at 3× cost savings. Ideal for sub-agent tasks, linting, documentation, and simple code generation.

Switch models with /model, Alt+P / Option+P, or by setting ANTHROPIC_MODEL in your environment.

The Top Cost-Saving Practices

1. Default to Sonnet. Only escalate to Opus when you need it.

2. Clear between tasks. Fresh sessions are free. Bloated sessions are expensive.

3. Write specific prompts. "Add email validation to the registration form in src/auth/register.ts" costs far less than "improve the auth system."

4. Plan before implementing. Planning in plan mode is cheaper than iterating through bad implementations.

5. Press Escape early. If Claude heads in the wrong direction, interrupt. Don't wait for a bad response to finish generating.

6. Disconnect unused MCP servers. Each one burns context tokens.

7. Keep CLAUDE.md lean. Under 200 lines, under 2,000 tokens.

8. Use targeted file reads. Specify line ranges (--lines 1-50) instead of reading entire files. 70% fewer tokens.

9. Limit bash output. Pipe through | head -50 or | tail -20.

10. Disable non-essential calls. DISABLE_NON_ESSENTIAL_MODEL_CALLS=1 suppresses background model usage.

Subscription vs. API: The Math

One heavy user reported approximately $15,000 in equivalent API costs over 8 months but paid roughly $800 on the Max plan — a 93% savings. For most individual developers doing daily work, the Max subscription ($100–200/month) dramatically outperforms pay-per-token pricing.

Part IX: Common Pitfalls and Anti-Patterns

The Seven Named Anti-Patterns

1. Prompt Tunneling — Sending 10+ messages without checking intermediate results. Claude drifts further from your intent with each unreviewed step.

2. Ghost Context — Assuming Claude remembers a previous conversation. Without CLAUDE.md, every session starts from zero. This reportedly causes 60% of Claude Code support tickets.

3. Mega-Prompt — Requesting 5 features in a single 500-word message. Claude handles one focused task well. Five simultaneous tasks produce five mediocre results.

4. Security Bypass — Disabling all permissions to "go faster." Use granular permission rules instead: claude config set allowedTools "Edit,Read,Bash(git*)".

5. Zero Verification — Accepting generated code without review or tests. Claude is confident, not infallible.

6. Blind Copy-Paste — Pasting external code without explaining context. Claude needs to understand why you're showing it code, not just what the code is.

7. Ignoring Errors — Re-running the same command after failure without analyzing the error. Feed the error back to Claude with context about what you were trying to do.

The Session Length Trap

Community recommendation: prefer short, focused sessions of 30-45 minutes. A 2-hour session typically reaches 2-3 compactions, each of which progressively dilutes summary quality. Information loss compounds.

One power user avoids /compact entirely, preferring /clear plus a custom /catchup command for complex tasks. The logic: it's better to lose everything and re-read the relevant files than to work from a degraded summary.

The Productivity Paradox

A sobering counterpoint worth considering: "Self-reported productivity gains between 20% and 50%. Then someone checked the organizational dashboard. The delivery metrics hadn't moved."

Individual task speed improved, but end-to-end delivery in some organizations showed no change. Faster coding doesn't automatically mean faster shipping. The recommended metric: track cycle time end-to-end and defects per deploy, not just coding speed.

Part X: Essential Commands and Shortcuts

Commands You Should Actually Use

Keyboard Shortcuts That Matter

Interrupting is not bad. It's required. If Claude starts heading in the wrong direction, press Escape immediately. You save tokens, context space, and time. Don't wait for a bad response to finish.

Part XI: The Real Workflow

Here's what high-level Claude Code usage actually looks like, end to end:

1. Start in plan mode. Let Claude explore and understand the task.

2. Refine the plan. Challenge assumptions. Ask about edge cases. Edit with Ctrl+G.

3. Break large work into phases. Write phases to an external file (PLAN.md or a GitHub issue).

4. Execute phase by phase. Switch to normal or auto-accept mode. Clear between phases.

5. Validate each step. Run tests. Check output. Feed errors back.

6. Monitor context. Use /context regularly. Compact proactively at 70-75%.

7. Reset when needed. Fresh context beats bloated context. Always.

8. Persist important state externally. Plans, decisions, specs — anything that should survive a context reset goes to a file.

What Changes About Engineering

You are no longer writing every line or thinking at the syntax level.

You are:

• Designing systems — Architecture, data flow, API contracts

• Managing context — What Claude knows, when it knows it, how much it retains

• Orchestrating execution — Planning phases, assigning to sub-agents, reviewing output

• Expanding scope — Taking on tasks you'd have deprioritized: refactors, documentation, cross-stack features

The developers getting the most from Claude Code aren't typing the most prompts. They're structuring their work deliberately: small sessions, clear scopes, external plans that survive context resets, and aggressive use of sub-agents to keep the main context clean.

Final Principle

Everything comes back to this:

Give Claude exactly the context it needs. Nothing more. Nothing less.

If you get that right, output improves, iterations decrease, and speed compounds.

If you get it wrong, it drifts, bloats, and fails.

Claude Code is not a tool you "use." It's an environment you shape. The ones who get past surface-level usage stop thinking in terms of prompts and start thinking in terms of context, plans, and systems.

That's where the leverage is.