Claude Code Mastery Guide

Everything you need to become highly proficient with Claude Code. From essential commands to advanced automation patterns, this guide covers it all.

Quick Reference

The most important commands and shortcuts to memorize first.

Essential Commands

Essential Shortcuts

File References

Use @ to reference files in your prompts:

Explain @src/auth/login.ts

What's the structure of @src/components?

Compare @file1.js with @file2.js

Slash Commands

All commands you can run in Claude Code, organized by category.

Session Management

Configuration & Status

Monitoring & Debugging

Project & Planning

Special Commands

Keyboard Shortcuts

General Controls

Rewind & Recovery

The rewind menu offers three options:

• Restore code - Revert file changes, keep conversation
• Restore conversation - Revert messages, keep code
• Summarize from here - Compress from selected point forward

Permission Modes

Modes cycle: Normal → Auto-Accept → Plan → (Delegate if teams active)

Model & Thinking

Navigation & History

Images & Pasting

On iTerm2, use Cmd+V. On Windows, use Alt+V.

Multiline Input

Text Editing

CLAUDE.md Files

CLAUDE.md files provide persistent instructions Claude reads at the start of every session. They're the primary way to customize Claude's behavior for your project.

File Locations & Priority

Claude loads CLAUDE.md files in order of precedence (highest first):

What to Include

Example CLAUDE.md

# Code Style
- Use ES modules (import/export) not CommonJS (require)
- Destructure imports when possible
- 2-space indentation

# Workflow
- Typecheck: `npm run typecheck`
- Run single test: `npm test -- <filename>`
- Create PRs from feature branches only

# Architecture
- API routes in `/src/routes/`
- Database models in `/src/models/`
- Utilities in `/src/utils/`

# Environment
- Requires `.env` with API_KEY
- Run `npm install` before first session

Importing Other Files

Reference other files using @path/to/import:

See @README.md for overview and @package.json for commands.

# Git Workflow
@docs/git-instructions.md

Paths resolve relative to the CLAUDE.md file location.

Modular Rules with .claude/rules/

Break instructions into topic-specific files:

.claude/
├── CLAUDE.md
└── rules/
    ├── code-style.md
    ├── testing.md
    ├── security.md
    └── frontend/
        └── react.md

Path-Specific Rules

Apply rules only to matching files using YAML frontmatter:

---
paths:
  - "src/api/**/*.ts"
  - "src/**/*.{ts,tsx}"
---

# API Development Rules
- All endpoints require input validation
- Use standard error format

Memory System

Claude has multiple memory layers that persist across sessions.

Memory Types

Auto Memory

Claude automatically saves learnings without you writing anything:

• Project patterns and debugging insights
• Architecture notes and your preferences
• First 200 lines loaded automatically
• Topic files (debugging.md, patterns.md) loaded on-demand

Control auto memory with environment variable:

# Force on
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0

# Force off
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Using /memory Command

Run /memory to open any memory file in your editor for extensive additions or organization.

Load Memory from Additional Directories

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

Settings & Configuration

Settings Files (Precedence Order)

1. managed-settings.json (admin/organization)
2. Command-line arguments
3. .claude/settings.local.json (local project)
4. .claude/settings.json (shared project)
5. ~/.claude/settings.json (user)

Example settings.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Read"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ],
    "defaultMode": "acceptEdits"
  },
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["github.com", "npmjs.org"]
    }
  },
  "hooks": {
    "PostToolUse": []
  },
  "outputStyle": "Explanatory",
  "alwaysThinkingEnabled": true
}

Key Environment Variables

Permission System

Permission Modes

Toggle modes with Shift+Tab

Permission Rule Syntax

"permissions": {
  "allow": [
    "Bash(npm run *)",      // Glob patterns
    "Bash(git commit *)",   // Specific commands
    "Read(./.env)",         // Specific file
    "Edit(/src/**/*.ts)",   // Glob in paths
    "WebFetch(domain:github.com)",  // Domain filter
    "Task(Explore)"         // Specific subagent
  ],
  "deny": [
    "Bash(curl *)"
  ]
}

Rule Precedence

Rules evaluated in order: deny → ask → allow. First match wins.

Context Management

Your entire conversation lives in the context window. As it fills, performance degrades. Managing context is crucial for long sessions.

Monitor Context Usage

• /context - Visualize usage as colored grid
• /cost - See token counts
• Configure custom status line for continuous monitoring

Context Reduction Strategies

1. Clear Between Tasks

/rename auth-work   # Name for later
/clear              # Start fresh

2. Use Compact

/compact Focus on API changes and test results

Claude summarizes the conversation, preserving critical context.

3. Use Rewind

Press Esc Esc to:

• Restore code - Undo file changes, keep conversation
• Restore conversation - Undo messages, keep code
• Summarize from here - Compress from selected point

4. Isolate with Subagents

Delegate verbose operations (tests, logs) to subagents. Results return as summaries.

5. Use Skills Instead of CLAUDE.md

Keep CLAUDE.md <500 lines. Move specialized instructions to skills (loaded on-demand).

6. Reduce MCP Overhead

/mcp       # Check active servers
/context   # See what consumes space

Disable unused servers. Use CLI tools when available instead of MCP.

7. Choose Right Model

• Sonnet - Most tasks, lower cost
• Opus - Complex reasoning, architecture
• Haiku - Subagent tasks, budget-conscious

Plan Mode

Plan Mode enables Claude to analyze your codebase without making changes. It's read-only and prompts for clarifications before proposing a plan.

When to Use Plan Mode

• Multi-file implementations
• Complex refactoring
• Understanding unfamiliar code
• Interactive feature development

How to Use

# Start in plan mode
claude --permission-mode plan

# Switch during session
Shift+Tab (cycle modes)

# One-shot query
claude --permission-mode plan -p "Analyze auth system"

# Configure as default
{
  "permissions": {
    "defaultMode": "plan"
  }
}

Plan Mode Workflow

1. Claude analyzes codebase (read-only)
2. Claude asks clarifying questions
3. Claude proposes detailed plan
4. Press Ctrl+G to edit plan in editor
5. Switch to Normal Mode (Shift+Tab) to implement

Session Management

Naming Sessions

/rename auth-refactor

Named sessions are easier to find later.

Resume Sessions

claude --continue              # Most recent in cwd
claude --resume               # Show picker
claude --resume auth-refactor # By name
claude --from-pr 123          # From GitHub PR

Session Persistence

• Stored locally per project directory
• Include full message history
• Tool results preserved
• Persist across system restarts

Checkpointing with Rewind

Press Esc Esc or /rewind to access:

• Restore code - Revert file changes
• Restore conversation - Revert messages
• Summarize from here - Compress from selected point

Git Integration

Common Operations

# Create commits
"Create a commit for the auth changes"

# Create PRs
"Create a PR with a descriptive message"

# Resume from PR
claude --from-pr 123

Git Permissions

{
  "permissions": {
    "allow": [
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git push *)"
    ]
  }
}

Attribution

{
  "attribution": {
    "commit": "Generated with Claude Code\n\nCo-Authored-By: Claude <[email protected]>",
    "pr": "Generated with Claude Code"
  }
}

MCP Servers

MCP (Model Context Protocol) lets Claude connect to external tools, databases, and APIs.

Why Use MCP?

• Implement features from JIRA/GitHub issues
• Query databases directly
• Analyze Sentry errors
• Integrate Figma designs
• Automate workflows (Slack, Gmail)

Installation Methods

HTTP Server (Recommended for Remote)

claude mcp add --transport http notion https://mcp.notion.com/mcp

Local Stdio Server

claude mcp add --transport stdio airtable \
  --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server

Managing Servers

claude mcp list      # List all servers
claude mcp get github # Details for specific server
claude mcp remove github # Remove server
/mcp                 # Check status in Claude Code

Installation Scopes

MCP Resources

Reference MCP resources with @ mentions:

Can you analyze @github:issue://123 and suggest a fix?

Hooks

Hooks are shell commands that execute at specific lifecycle points. Unlike prompts, hooks are deterministic and guaranteed to run.

Lifecycle Events

Example: Auto-format After Edits

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Example: Desktop Notifications (macOS)

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Example: Block Protected Files

#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path')
if [[ "$FILE" == *".env"* ]]; then
  echo "Blocked: Protected file" >&2
  exit 2
fi
exit 0

Exit Codes

• 0 - Action proceeds (stdin output added to context)
• 2 - Action blocked (stderr becomes feedback to Claude)

Skills

Skills are custom commands that extend Claude's capabilities. They're loaded on-demand, keeping your context lean.

Create a Skill

mkdir -p ~/.claude/skills/my-skill

Create ~/.claude/skills/my-skill/SKILL.md:

---
name: my-skill
description: What this skill does
---

Instructions for Claude to follow when skill is invoked.

Skill Types

Reference Content (Knowledge)

---
name: api-conventions
description: API design patterns
---

When writing API endpoints:
- Use RESTful naming
- Return consistent errors

Task Content (Workflows)

---
name: deploy
description: Deploy to production
disable-model-invocation: true
---

1. Run tests
2. Build
3. Deploy

Skill Locations

• ~/.claude/skills/ - Personal (all projects)
• .claude/skills/ - Project (git-shared)

Skill Arguments

---
name: migrate-component
description: Migrate component framework
---

Migrate $0 from $1 to $2 while preserving behavior.

Run: /migrate-component SearchBar React Vue

Control Invocation

disable-model-invocation: true     # Manual invocation only
user-invocable: false              # Claude-only
allowed-tools: Read, Grep, Glob    # Restrict tools

Subagents

Subagents are specialized AI assistants that handle specific types of tasks.

Built-In Subagents

Create Custom Subagent

Using /agents command or create manually:

# ~/.claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer. Analyze code and provide specific feedback.

Configuration Options

When to Use Subagents

• Isolate verbose operations (tests, logs)
• Enforce tool restrictions
• Parallel research
• Control costs (use cheaper models)

Extended Thinking

Claude uses internal reasoning tokens to think through problems before responding.

Enable/Disable

• Toggle: Alt+T
• Default: /config to set default
• Environment: CLAUDE_CODE_EFFORT_LEVEL=high

Effort Levels (Opus 4.6)

Use /model and left/right arrows to adjust:

• Low - Minimal thinking, fast
• Medium - Balanced
• High - Deep reasoning, thorough

Thinking Token Budget

# Set budget
export MAX_THINKING_TOKENS=10000 claude

# Disable entirely
export MAX_THINKING_TOKENS=0 claude

View Thinking

Press Ctrl+O to toggle verbose mode and see thinking as gray italic text.

Effective Prompting

How you communicate with Claude dramatically affects results.

1. Give Verification Criteria

Include tests, screenshots, expected outputs:

2. Explore → Plan → Implement → Commit

# Step 1 (Plan Mode): Explore
"Analyze our auth system and explain the flow"

# Step 2 (Plan Mode): Plan
"Create a detailed plan to add OAuth2"

# Step 3 (Normal Mode): Implement
"Implement OAuth2 from your plan, write tests, verify"

# Step 4 (Normal Mode): Commit
"Create a PR with a descriptive message"

3. Provide Specific Context

4. Reference Files with @

Explain @src/utils/auth.js logic
What's the structure of @src/components?

5. Use Rich Content

• Paste screenshots/images (Ctrl+V)
• Reference files with @
• Pipe data: cat error.log | claude
• Provide documentation URLs

6. Point to Source Examples

"Look at how existing widgets implement X pattern in home.js and follow it"

7. Be Specific About Scope

Cost Optimization

Track Costs

/cost

Shows total cost, token count, code changes, and timing.

Reduction Strategies

Power User Tips

Efficient Workflows

1. Start with Plan Mode - Understand before implementing
2. Monitor context - Use /context continuously
3. Clear aggressively - /clear between unrelated tasks
4. Name sessions early - /rename for future reference
5. Specify deeply - More specific = fewer corrections needed
6. Verify everything - Include tests, screenshots, expected output
7. Rewind on mistakes - Esc Esc to undo and retry
8. Delegate exploration - Use subagents for research
9. Use hooks - Automate repetitive validations
10. Build skills library - Reuse workflows across projects

Advanced Patterns

Parallel Sessions with Worktrees

git worktree add ../project-feature -b feature
cd ../project-feature
claude

Each worktree has isolated state, allowing parallel Claude instances.

Piping & Scripting

cat logs.txt | claude -p "Find error patterns"
claude -p "analyze code" --output-format json > output.json

CI/CD Integration

claude -p "Review code changes for issues" --output-format json

Fan Out Across Files

for file in $(cat files-to-migrate.txt); do
  claude -p "Migrate $file from React to Vue" \
    --allowedTools "Edit,Bash(git commit *)"
done

Claude as Unix Utility

{
  "scripts": {
    "lint:claude": "claude -p 'check for typos in changes vs main'"
  }
}

Common Mistakes to Avoid

Headless Mode & Automation

One-Off Queries

claude -p "explain this function"              # Text output
claude -p "analyze code" --output-format json  # JSON output
claude -p "query data" --output-format stream-json  # Streaming

In Scripts

cat error.log | claude -p "find root cause"

Structured Output

claude -p "list endpoints" --json-schema '{"type":"object","properties":...}'

Key Flags

IDE Integration

VS Code

• Install "Claude Code" extension from Marketplace
• Use /config to configure settings
• Run CLI from VS Code terminal with claude
• Switch between extension and CLI with --ide flag

Key features: Prompt box in sidebar, resume conversations, work with git

JetBrains IDEs

• Install from Plugin Marketplace (IntelliJ, PyCharm, WebStorm)
• Run Claude Code from External Terminals
• Configure ESC key behavior in plugin settings

Debugging & Troubleshooting

Check Installation Health

/doctor

View Debug Log

/debug "description of issue"

Verbose Output

claude --verbose

Shows full turn-by-turn reasoning.

Enable Debug Mode

claude --debug "api,mcp"