🧠 Claude Code Mastery Playbook

Understanding How Claude Code Works Better Than 99% of Users

Paint-by-Numbers Guide | Leverage-Optimized Learning Path

Watch Original Video by Mark (1hr deep-dive)

🎯 What You'll Master

This playbook extracts Mark's 1-hour video into actionable steps prioritized by leverage and temporal dependencies. Each section includes deeper insights ("why this matters") and teaching prompts to deepen understanding.

Sections

Time

2-3h

Checkpoints

45+

1 Core Architecture & System Design

Priority: Foundation | Goal: Understand how components interact

start-here 15-20 min

🧩 The 5 Core Components

What makes Claude Code work:

CLI: Terminal interface you interact with
Session Manager: Handles conversation state & context
Tool Executor: Runs file ops, bash commands, searches
Permission Layer: Security gatekeeper (ask/allow/block)
Claude API: Intelligence brain orchestrating everything

Why This Architecture Matters

Leverage insight: Claude Code isn't magic—it's smart orchestration of existing open-source tools. Understanding this means you can:

Predict what Claude can/can't do
Debug when things break (is it the tool or the AI?)
Build your own tools using the same pattern
Appreciate why some tasks are fast (native tools) vs slow (AI reasoning)

# View architecture in action
/context

# Shows:
# - System prompt overhead  
# - claude.md impact
# - Current token usage
# - What's consuming your bucket

Deep Learning Prompt (Copy & Use)

Paste this into any LLM to explore deeper:

I'm learning about Claude Code's architecture. It has 5 components: CLI, Session Manager, Tool Executor, Permission Layer, and Claude API.

Help me understand:
1. What would happen if the Permission Layer was removed entirely?
2. Why is Session Manager separate from Tool Executor?
3. How does this architecture compare to traditional IDEs like VS Code?
4. What are the bottlenecks in this design?
5. How would I build a simplified version of this for a specific task?

Use analogies and real examples.

📊 The Gather → Act → Verify Loop

Every Claude Code operation follows this pattern:

GATHER: Reads files, searches code, explores structure
ACT: Edits files, creates folders, runs bash commands
VERIFY: Runs tests, checks outputs, loops if needed

The Compound Effect of This Loop

Why this matters: This loop is the difference between 10x productivity and frustration. Understanding it means:

You can interrupt bad loops early: If Claude gathers for 5 min, your prompt was too vague
You can optimize each phase: Better prompts → faster gather → less wasted context
You can provide success criteria: "Verify by running npm test and checking for 0 errors"
You prevent infinite loops: Claude will loop forever without clear exit conditions

Deep Learning Prompt

The Gather → Act → Verify loop is Claude Code's core pattern.

Show me:
1. A real example where this loop would fail (and why)
2. How I could optimize each phase for a "fix login bug" task
3. What happens if verification is impossible (no tests exist)?
4. How this compares to how human developers work
5. What "good enough" verification looks like vs perfect verification

Be specific with code/file examples.

✅ I understand the 5 core components and their roles

✅ I've run /context to see architecture in action

✅ I can explain Gather → Act → Verify and when loops fail

2 Context Window Management (MOST CRITICAL)

Priority: HIGHEST | Goal: Master the 200k token "bucket" constraint

master-this-first 30-35 min

🪣 The Bucket Metaphor

Your context window is a bucket:

Opus 4.5 = 200,000 token capacity (~150k words)
Every message, file read, tool result fills it
When full → forced to compact (loses information)
Quality degrades sharply after 40-50% full

🚨 The Quality Cliff at 50%

After 50% context usage: Claude gets lazier, makes more errors, forgets earlier decisions, gives repetitive suggestions. This is THE constraint that separates experts from beginners.

Why Context Management Is Your Highest-Leverage Skill

The multiplier effect:

Bad context management: 10 min of productivity per session before compaction → restart loop → 1 hour wasted
Good context management: 2+ hours of sustained quality → 10x more work done
The asymmetry: One mistake (reading a PDF) nukes your entire session. One good habit (slim claude.md) pays dividends every session forever.
Compound advantage: Experts preserve context → build more → learn faster → compound skill growth

# Check bucket status anytime
/context

# Strategic monitoring:
# - Start session: Should be <10% used
# - Mid-session: If >40%, consider clearing or switching terminals
# - Before big task: If >60%, start fresh terminal

Deep Learning Prompt

Context window management is THE critical skill in Claude Code.

Explain like I'm trying to maximize productivity:
1. Why does quality degrade at 50% vs hard stop at 100%?
2. What's the token cost of common operations (file read, search, tool result)?
3. If I have a 10,000-line codebase, what's my strategy to avoid filling the bucket?
4. Show me the math: If bad context management costs me 30min/session and I code 3hrs/day, what's my annual time loss?
5. What's the single biggest mistake beginners make with context?

Use real numbers and examples.

📊 What Fills the Bucket Fastest (Ranked by Danger)

Token consumption ranked (worst offenders first):

🚨 PDFs: 1.8M tokens for 50-page doc (instant death—900% of your bucket!)
⚠️ Large file reads: 10k+ line files = 15-30k tokens
⚠️ MCP servers: 10-50k tokens at session start (before you type anything)
⚠️ Tool result spam: JSON-heavy database/API responses
⚠️ Bloated claude.md: 5-15k tokens loaded EVERY session
Normal: Conversation history grows ~500-1000 tokens per exchange

⚠️ Mark's Real Example (PDF Token Bomb)

Reading a 50-page economic report consumed 100% of context in ONE operation. The file was 1.8 MILLION tokens because PDFs are full of invisible formatting metadata.

Solution: External API (Gemini 2.5 Flash with 1M context) + return markdown summary only = 98% token savings

The Hidden Costs & Second-Order Effects

What beginners miss:

MCP bloat cascade: You install 10 MCPs for "just in case" → Each session starts at 30% capacity → Only get 70% productivity → Never realize MCPs are the problem
The compaction amnesia spiral: Fill bucket → compact → lose key decisions → make mistakes based on forgotten context → waste time debugging → fill bucket faster next time
Thrashing pattern: Hit 80% → compact → resume → hit 80% again in 10 min → restart session → lose momentum
Opportunity cost: Every wasted token is a lost opportunity for Claude to hold MORE useful information

# SOLUTION: Offload large docs to external API

"Create a skill called 'read_large_doc' that:
1. Uses Gemini 2.5 Flash API (1M context window)
2. Reads the PDF file
3. Converts to markdown (strips hidden metadata)  
4. Returns 2-3 page summary with key points
5. Saves my Claude Code context for actual work

Put Gemini API key in .env file."

# Result: 1.8M tokens → 5k token summary = 97% savings

Deep Learning Prompt

Token consumption in Claude Code has asymmetric impact.

Help me build a mental model:
1. Why are PDFs so token-heavy compared to text files?
2. Walk me through the exact token usage for this workflow: "Read 3 files (100 lines each), fix a bug, commit to git"
3. If MCPs cost 10-50k tokens at startup, when IS it worth using an MCP?
4. How would I audit my typical session to find hidden token waste?
5. What's the ROI calculation for spending 1 hour optimizing my context usage?

Give me formulas and decision frameworks.

💡 Context Preservation Strategies (4 High-Leverage Tactics)

Strategy 1: External API Offloading

When: Any file >20 pages or >5k lines

How: Create Python script that uses Gemini/GPT, returns summary only

Savings: 90-98% token reduction

Strategy 2: Sub-Agent Delegation

When: Exploration tasks (codebase mapping, research)

How: Spin up sub-agent with virgin 200k context → it explores → reports back summary

Savings: Main session stays clean, sub-agent context is disposable

Strategy 3: Multi-Terminal Workflow

When: Mutually exclusive tasks (frontend/backend/testing)

How: Terminal 1 = Frontend, Terminal 2 = Backend, Terminal 3 = Testing

Savings: 3x the effective context (600k total vs 200k compressed)

Strategy 4: Slim Claude.md (Routing Pattern)

When: Always

How: Keep claude.md <2k tokens, use it as index to other docs

Savings: 5-15k tokens per session start

The Compounding Leverage of These Strategies

Multiplier math:

Beginner: No optimization → 30min productive session → 6 restarts per 3hr coding block = 3hr actual work
Intermediate: Slim claude.md + avoiding PDFs → 60min sessions → 3 restarts = 4.5hr equivalent work (1.5x multiplier)
Expert: All 4 strategies + multi-terminal → 120min+ sessions → 0-1 restart = 7hr equivalent work in 3hr block (2.3x multiplier)
Annual impact: 2.3x multiplier × 500 coding hours/year = 650 "free" hours gained

# Audit your claude.md token usage
"Read my claude.md file and analyze:
1. How many tokens is it currently?
2. What content is repetitive or unnecessary?
3. What should be moved to separate playbooks?
4. Rewrite it to under 2k tokens using routing pattern
5. Show before/after token counts"

Deep Learning Prompt

I want to master context preservation in Claude Code using these 4 strategies.

Help me build an implementation plan:
1. Which strategy gives me the biggest ROI for least effort?
2. How do I decide between multi-terminal vs sub-agent for a given task?
3. Walk me through converting an MCP to a skill to save context
4. What's a realistic "before/after" for my session quality if I implement all 4?
5. Create a decision tree: Given [task type], which strategy should I use?

Make it actionable with specific examples.

✅ I understand the bucket metaphor and 50% quality cliff

✅ I know what fills context fastest and the PDF token bomb danger

✅ I can explain all 4 context preservation strategies

✅ I've audited my claude.md and optimized it to <2k tokens

✅ I've run /context and understand my current usage pattern

3 Tool Mastery: Read, Write, Edit, Search

Priority: Core Skill | Goal: Understand how Claude navigates code efficiently

intermediate 25-30 min

🔍 The Tool Arsenal & When to Use Each

Read: Load file contents (⚠️ token-heavy)
Write: Create new files from scratch
Edit: Surgical string replacement (token-efficient)
Glob: Pattern-based file finding (*.ts, **/*.jsx)
Grep (ripgrep): Fast text search across codebase

Why Tool Choice Multiplies Your Productivity

The leverage cascade: Glob finds 5 relevant files out of 100 → Grep searches within those 5 → Read loads only the 1 file that matters → Edit makes surgical change → Total tokens: ~5k instead of 150k if you read everything.

Expert pattern: Always search before reading. Reading is expensive, searching is cheap.

# Smart tool workflow example:

"Fix the login button bug. Before reading ANY files:
1. Use glob to find all *.tsx files
2. Use grep to search for 'login' in those files
3. Read ONLY the file that contains the login button
4. Make the fix with surgical edit
5. Verify the change worked"

# This approach uses ~5k tokens vs ~50k if you read the whole codebase

Deep Learning Prompt

Tool selection in Claude Code is about minimizing token waste.

Help me build intuition:
1. When would I use glob vs grep vs read for finding code?
2. Show me the token cost comparison for these 3 approaches to "find authentication code"
3. Why is Edit better than rewriting the whole file?
4. How does ripgrep enable parallel searching and why does that matter?
5. Give me a decision framework: [Task type] → [Optimal tool sequence]

Use real codebase examples.

✅ I know when to use each tool (read/write/edit/glob/grep)

✅ I understand the "search before read" principle

✅ I can estimate token costs for different tool operations

🎯 What You'll Master

1 Core Architecture & System Design

2 Context Window Management (MOST CRITICAL)

Strategy 1: External API Offloading

Strategy 2: Sub-Agent Delegation

Strategy 3: Multi-Terminal Workflow

Strategy 4: Slim Claude.md (Routing Pattern)

3 Tool Mastery: Read, Write, Edit, Search

📄 One-Page Quick Reference: 10 High-Leverage Principles & Hacks

1Context is King

2PDFs Are Poison

3Search Before Read

4Slim Claude.md

5Multi-Terminal Mastery

6MCP Minimalism

7Sub-Agent Delegation

8Plan → Clear → Execute

9Permission Graduation

10Session-End Capture

🎯 Your Action Plan (Do This Next)