Claude Code CLI: The Definitive Technical Reference

Updated December 12, 2025

December 2025 Update: Claude Code now powers enterprise engineering workflows with agentic multi-file editing, MCP protocol integration with 300+ external services, specialized subagents for complex tasks, and hooks system for CI/CD automation. Permission system enables fine-grained security controls. Model switching between Haiku (fast/cheap) and Opus (powerful) optimizes cost-performance tradeoffs.

I've spent months pushing Claude Code to its limits across production codebases, CI/CD pipelines, and enterprise deployments. This guide distills that experience into the comprehensive reference I wish existed when I started. It covers everything from first installation to advanced patterns that most users never discover.

Claude Code isn't a chat interface that happens to know about programming. It's an agentic system that reads your codebase, executes commands, modifies files, manages git workflows, connects to external services, and delegates complex tasks to specialized subagents—all through a command-line interface that integrates into how developers actually work.

The difference between using Claude Code casually and using it effectively is understanding its architecture: the configuration hierarchy that controls behavior, the permission system that gates operations, the hook system that enables deterministic automation, the MCP protocol that extends capabilities, and the subagent system that handles complex multi-step tasks. Master these systems and Claude Code becomes a force multiplier. Miss them and you're leaving most of the value on the table.

This guide assumes you're comfortable with command-line tools and want the complete picture. Every feature is documented with actual syntax, real configuration examples, and the edge cases that trip up experienced users. Whether you're setting up your first project or deploying across an enterprise engineering organization, the information is here.

How Claude Code Works: The Mental Model

Before diving into features, understand how Claude Code's architecture shapes everything you do with it. The system operates in three layers:

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Subagents (up to 10 parallel)       │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Isolated contexts for focused work, returns summaries  │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Main Conversation Context                │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Your primary interaction; limited context; costs money │
└─────────────────────────────────────────────────────────┘

Core Layer: Your main conversation. Every message, file read, and tool output consumes context from a shared 200K token window (1M with premium). When context fills, Claude loses track of earlier decisions and quality degrades. This layer costs money per token.

Delegation Layer: Subagents spawn with clean contexts, do focused work, and return summaries. The exploration results don't bloat your main conversation—only the conclusions return. Use Haiku subagents for exploration (cheap, fast) and Sonnet for implementation.

Extension Layer: MCP connects external services (databases, GitHub, Sentry). Hooks guarantee execution of shell commands regardless of model behavior. Skills encode domain expertise that Claude applies automatically. Plugins package all of these for distribution.

The key insight: Most users work entirely in the Core Layer, watching context bloat and costs climb. Power users push exploration and specialized work to the Delegation Layer, keep the Extension Layer configured for their workflow, and use the Core Layer only for orchestration and final decisions.

Table of Contents

1. Installation and Authentication
2. Core Interaction Modes
3. Configuration System Deep Dive
4. Model Selection and Switching
5. Permission System and Security
6. Hooks System
7. MCP (Model Context Protocol)
8. Subagents and Task Delegation
9. Extended Thinking Mode
10. Output Styles
11. Slash Commands
12. Skills
13. Plugin System
14. Memory and Context Management
15. Image and Multimodal Input
16. Git Integration and Workflows
17. IDE Integration
18. Advanced Usage Patterns
19. Claude Code Remote
20. Background Agents
21. Cost Management and Billing
22. Performance Optimization
23. Troubleshooting and Debugging
24. Enterprise Deployment
25. Keyboard Shortcuts Reference
26. Best Practices

Installation and Authentication

System Requirements

Claude Code runs on macOS 10.15+, Ubuntu 20.04+/Debian 10+, and Windows 10+ through WSL or Git Bash. The system requires 4 GB RAM minimum and an active internet connection. Shell compatibility works best with Bash, Zsh, or Fish.

For Windows, both WSL 1 and WSL 2 work. Git Bash also works if you prefer native Windows. Alpine Linux and other musl-based systems require additional packages:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

Installation Methods

Native installation (recommended)

The native binary provides the cleanest experience with no Node.js dependency:

# macOS and Linux
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew alternative
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

For version-specific installation:

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

NPM installation

For environments where npm is preferred:

npm install -g @anthropic-ai/claude-code

Never use sudo with npm installation—it creates permission issues that complicate everything downstream.

Migration from existing installation

If you have an older npm-based installation, migrate to the native binary:

claude install

Authentication Options

Claude Code supports three authentication paths, each with different tradeoffs:

Claude Console (API billing)

Connect to Anthropic's API directly through console.anthropic.com. Create an account, set up billing, and authenticate through the CLI. This provides usage-based billing with full API access. A dedicated "Claude Code" workspace is created automatically—you cannot create API keys for this workspace, but you can monitor usage.

Claude Pro or Max subscription

Use your claude.ai account credentials. The subscription covers both the web interface and CLI usage under a single monthly plan. This simplifies billing for individual users who want predictable costs.

Enterprise platforms

AWS Bedrock, Google Vertex AI, and Microsoft Foundry each provide enterprise-grade access with existing cloud billing relationships:

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

For enterprise deployments behind proxies or through LLM gateways:

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

Verification

claude doctor

This reports installation type, version, system configuration, and any detected issues.

Updates

Claude Code auto-updates by default, checking at startup and periodically during sessions. Updates download in the background and apply on next launch.

Disable auto-updates:

export DISABLE_AUTOUPDATER=1

Or in settings.json:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

Manual update:

claude update

Uninstallation

Native installation (macOS/Linux/WSL):

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

Native installation (Windows PowerShell):

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

Clean configuration (removes all settings):

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

Core Interaction Modes

Interactive REPL

Launch Claude Code without arguments to enter the interactive read-eval-print loop:

cd your-project
claude

The REPL maintains conversation context across turns. Type queries directly, receive responses, and continue until you exit with /exit or Ctrl+D.

Start with an initial prompt to focus the session:

claude "explain the authentication flow in this project"

Expert tip: The REPL persists state across compaction events. When context grows too large, Claude automatically summarizes older conversation while preserving key decisions and code snippets. You can trigger this manually with /compact or add custom instructions for what to preserve.

Non-Interactive Mode

Print mode (-p) executes a single query and exits:

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

For structured output suitable for parsing in scripts:

claude -p "count lines by file type" --output-format json

The JSON output includes everything you need for automation:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

For real-time processing of streaming output:

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r '.result // empty'
done

Session Management

Sessions persist conversation history for continuation. This is essential for complex multi-session work:

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

Create reproducible sessions with explicit IDs:

claude --session-id "feature-auth-$(date +%s)"

Expert tip: Use session IDs that encode context: feature-${branch}-${timestamp} or bug-JIRA-123. When you come back days later, the ID tells you what the session was about. View available sessions within the REPL using /resume.

Sessions are stored as JSONL transcripts. Agent execution gets assigned unique agentId values with transcripts stored as agent-{agentId}.jsonl. Resume preserves full context from previous conversations.

Configuration System Deep Dive

Claude Code uses a layered configuration system. Understanding the hierarchy is essential because higher levels override lower ones, and enterprise settings cannot be bypassed at all.

Configuration Hierarchy

Expert tip: Use .claude/settings.local.json for personal preferences in shared projects—it should be in .gitignore. Use .claude/settings.json for team-wide configuration that gets checked into version control.

Complete settings.json Reference

A comprehensive configuration demonstrating all major options:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "Write(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory"
}

Environment Variables Reference

Authentication and API:

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers

Model configuration:

ANTHROPIC_MODEL=claude-opus-4-5                 # Override default model
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-5-20251101
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5-20250929-v1:0
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Model for subagents
MAX_THINKING_TOKENS=10000                       # Enable extended thinking
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length

Cloud provider configuration:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region

Behavior control:

DISABLE_AUTOUPDATER=1                           # Prevent automatic updates
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls

Tool configuration:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Bash output limit
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

Network and proxy:

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

UI and terminal:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory

Debugging:

ANTHROPIC_LOG=debug                             # Enable API request logging

Model Selection and Switching

Choosing the right model for each task significantly impacts both cost and quality. Claude Code provides flexible model switching at multiple levels.

Available Models

Why these price differences matter: A typical coding session consumes 50K-200K input tokens and 10K-50K output tokens. With Haiku, that's $0.10-$0.45 per session. With Opus, the same session costs $0.50-$2.25—5x more. Reserve Opus for genuinely hard problems.¹

When to Use Each Model

Haiku: Use for subagents doing exploration, simple file searches, quick questions. It's 10-20x cheaper than Opus and responds faster. Perfect for background tasks where you don't need deep reasoning.

Sonnet: The workhorse for daily development. Handles most coding tasks well: implementing features, fixing bugs, writing tests, code review. Use this as your default.

Opus: Reserve for genuinely complex reasoning: architectural decisions, tricky debugging, understanding complex systems, security analysis. The quality difference is real for hard problems, but so is the cost.

Opusplan: A hybrid mode that uses Opus for planning (where reasoning quality matters most) and Sonnet for execution (where speed matters). Excellent for complex refactoring where you want the best plan but don't need Opus-level reasoning for each individual edit.

Switching Models

During session:

> /model opus
> /model sonnet
> /model haiku

At startup:

claude --model opus

Via environment:

export ANTHROPIC_MODEL=opus

In settings.json:

{
  "model": "claude-sonnet-4-5-20250929"
}

For subagents specifically:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Extended Context

For large codebases or long sessions, enable 1M token context:

claude --model sonnet[1m]

Or within a session:

> /model anthropic.claude-sonnet-4-5-20250929-v1:0[1m]

Extended context costs more per token. Use it when you actually need it, not as a default.

Checking Current Model

> /status

This shows current model, account info, applied settings, and other session state.

Decision Frameworks

Knowing features exists isn't enough—you need to know when to use each. These decision trees transform knowledge into action.

Which Model Should I Use?

START → Is the task simple? (file search, quick question, formatting)
         │
         ├── YES → Use Haiku
         │         Cost: ~$0.03/task
         │         Speed: Fastest
         │
         └── NO → Does it require deep reasoning?
                  (architecture, complex debugging, security analysis)
                  │
                  ├── YES → Use Opus
                  │         Cost: ~$2.00/task
                  │         Quality: Highest
                  │
                  └── NO → Use Sonnet (default)
                           Cost: ~$0.75/task
                           Balance: Best overall

Rule of thumb: Start with Sonnet. Drop to Haiku for subagents. Escalate to Opus only when Sonnet's answer feels shallow.

Command vs Skill vs Subagent?

Do you want explicit control over when it runs?
│
├── YES → Use Slash Command
│         Example: /deploy, /test, /security-review
│         You invoke it. You control timing.
│
└── NO → Should the expertise apply automatically based on context?
         │
         ├── YES → Use Skill
         │         Example: Security patterns, domain rules, code standards
         │         Claude recognizes context and applies expertise.
         │
         └── NO → Does the work need isolated context?
                  │
                  ├── YES → Use Subagent
                  │         Example: Deep exploration, parallel analysis
                  │         Prevents context bloat in main conversation.
                  │
                  └── NO → Just prompt directly
                           Not everything needs abstraction.

Hook vs Prompt?

Must the action ALWAYS happen, regardless of Claude's judgment?
│
├── YES → Use Hook (deterministic)
│         Examples:
│         - Format code after every edit
│         - Log all bash commands
│         - Block access to .env files
│         Claude cannot skip, forget, or decide otherwise.
│
└── NO → Use Prompt (probabilistic)
         Examples:
         - "Consider adding tests"
         - "Think about edge cases"
         - "Review for security if relevant"
         Claude decides based on context.

When to Use Extended Thinking?

Is this a genuinely hard problem?
│
├── Architectural decision with many tradeoffs → YES, use thinking
├── Complex debugging with unclear root cause → YES, use thinking
├── Security analysis requiring careful reasoning → YES, use thinking
├── Understanding unfamiliar codebase → YES, use thinking
│
├── Routine bug fix → NO, skip thinking
├── Simple refactoring → NO, skip thinking
├── Code formatting → NO, skip thinking
└── Quick questions → NO, skip thinking

Toggle with Tab during session. Higher thinking budgets cost more—start with minimum and increase only if responses feel rushed.

Permission System and Security

Claude Code's permission system provides fine-grained control over what operations can execute. Understanding it is essential for both security and workflow efficiency.

Permission Tiers

Read-only tools (auto-approved): - Read - Read file contents - Glob - Find files by pattern - Grep - Search file contents - WebSearch - Search the web

Modification tools (require approval): - Edit - Modify existing files - Write - Create new files - Bash - Execute shell commands - WebFetch - Fetch URL contents - NotebookEdit - Modify Jupyter notebooks

The first time a modification tool runs, Claude Code prompts for approval. Approvals persist for the session unless explicitly configured otherwise.

Permission Modes

Set mode via CLI:

claude --permission-mode acceptEdits

Toggle during session:

Shift+Tab  # Cycles through modes

In settings.json:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Permission Rules Syntax

Fine-grained rules control specific operations. Rules are evaluated in order: first match wins.

Bash command patterns:

{
  "allow": [
    "Bash(npm run build)",
    "Bash(npm run test:*)",
    "Bash(git commit:*)",
    "Bash(make:*)"
  ],
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(sudo:*)",
    "Bash(curl|wget:*)"
  ]
}

The asterisk provides prefix matching: Bash(npm run test:*) allows npm run test, npm run test:unit, and npm run test:integration.

Important limitation: Bash patterns match prefixes only, not regex. A pattern like Bash(curl http:*) won't match curl -X GET http://... because the options come before the URL. For robust blocking, deny the command entirely: Bash(curl:*).

File operation patterns:

{
  "allow": [
    "Edit(src/**)",
    "Write(src/**)",
    "Read(docs/**)"
  ],
  "deny": [
    "Read(.env*)",
    "Read(secrets/**)",
    "Edit(.git/**)",
    "Edit(node_modules/**)"
  ]
}

Path syntax: - Relative paths: Edit(src/**) - relative to working directory - Absolute from settings file: Edit(/build/**) - relative to settings file location - True absolute: Edit(//tmp/**) - starts with // - Home directory: Read(~/.zshrc)

MCP tool patterns:

{
  "allow": [
    "mcp__github",
    "mcp__database__query"
  ],
  "deny": [
    "mcp__dangerous_server"
  ]
}

WebFetch patterns:

{
  "allow": [
    "WebFetch(domain:github.com)",
    "WebFetch(domain:api.example.com)"
  ]
}

Additional Directories

Extend Claude's access beyond the current project:

{
  "permissions": {
    "additionalDirectories": [
      "../shared-lib",
      "../docs",
      "~/reference-projects/design-system"
    ]
  }
}

This is essential for monorepos or when Claude needs to reference code in sibling directories.

Sandbox Mode

Enable filesystem and network isolation:

> /sandbox

Or configure in settings:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true
    }
  }
}

When sandboxed: - Filesystem access restricted to project directory - Network access controlled - Certain commands excluded from sandbox restrictions - Bash commands auto-allowed if autoAllowBashIfSandboxed is true

Expert tip: Sandbox mode is excellent for running Claude on untrusted codebases. Enable it when exploring unfamiliar projects or when you want an extra layer of protection.

Hooks System

Hooks execute deterministic shell commands at specific points in Claude Code's workflow. Unlike prompting Claude to perform actions, hooks guarantee execution regardless of model behavior. They're essential for enforcing team standards and automating repetitive tasks.

Why hooks instead of prompts: Telling Claude "always run Prettier after editing files" works sometimes. But Claude might forget, prioritize speed, or decide the change is "too small." Hooks guarantee execution—every Edit or Write triggers your formatter, every time, no exceptions. For compliance, security, and team standards, deterministic beats probabilistic.⁷

Available Events

Hook Configuration

Define hooks in settings.json or a dedicated hooks.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/inject-context.sh"
          }
        ]
      }
    ]
  }
}

Matchers

The matcher field determines which tools trigger a hook:

{"matcher": "*"}              // Match all tools
{"matcher": "Bash"}           // Match Bash only
{"matcher": "Edit|Write"}     // Match Edit or Write
{"matcher": "mcp__github"}    // Match MCP server tools
{"matcher": ""}               // Match for events without tools (like UserPromptSubmit)

Hook Input/Output Protocol

Hooks receive JSON on stdin:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123"
}

Exit codes control behavior: - 0: Success—operation proceeds. Stdout shown in verbose mode (Ctrl+O). For UserPromptSubmit and SessionStart, stdout is added to context. - 2: Blocking error—operation stops. Stderr becomes the error message fed back to Claude. - 1, 3, etc.: Non-blocking error—operation continues. Stderr shown as warning in verbose mode.

For advanced control, hooks can output JSON:

{
  "decision": "allow",
  "message": "Command validated and modified",
  "modifications": {
    "tool_input": {
      "command": "npm test -- --coverage"
    }
  }
}

Practical Hook Examples

Auto-format TypeScript files after editing:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.ts ]] && npx prettier --write \"$FILE_PATH\" || true'"
          }
        ]
      }
    ]
  }
}

Log all bash commands:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-history.log"
          }
        ]
      }
    ]
  }
}

Block access to sensitive files:

#!/bin/bash
# .claude/hooks/protect-files.sh
data=$(cat)
path=$(echo "$data" | jq -r '.tool_input.file_path // empty')

if [[ "$path" == *".env"* ]] || [[ "$path" == *"secrets/"* ]] || [[ "$path" == *".pem"* ]]; then
  echo "Blocked: Cannot access sensitive file $path" >&2
  exit 1
fi
exit 0

Run tests after code changes:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.test.ts ]] || npm run test:affected'"
          }
        ]
      }
    ]
  }
}

Custom notification system:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Waiting for your input'"
          }
        ]
      }
    ]
  }
}

Inject dynamic context into prompts:

#!/bin/bash
# .claude/hooks/inject-context.sh
# Add current git branch and recent commits to every prompt

branch=$(git branch --show-current 2>/dev/null)
commits=$(git log --oneline -3 2>/dev/null | tr '\n' ' ')

if [ -n "$branch" ]; then
  echo "[Context: Branch '$branch', Recent: $commits]"
fi
exit 0

Hook Debugging

Enable debug mode to troubleshoot hooks:

claude --debug

This logs: - Hook execution times - Input/output data - Error messages and stack traces - Decision results (allow/reject/ask)

MCP (Model Context Protocol)

MCP extends Claude Code with access to external tools, databases, APIs, and services through a standardized protocol. The ecosystem has grown from 100,000 total downloads in November 2024 to over 8 million by April 2025—80x growth in five months.³ Over 300 integrations exist, from GitHub and Slack to PostgreSQL and custom internal systems. Understanding MCP is essential for integrating Claude into your existing toolchain.

Why MCP matters for developers: Without MCP, Claude Code can only read files and run bash commands. With MCP, Claude can query your production database, create Jira tickets, review GitHub PRs, check Sentry errors, and interact with any API your team uses—all from natural language requests. The protocol standardizes how AI tools connect to external services, preventing vendor lock-in.

Interactive MCP Setup Wizard

Run claude mcp add without arguments to launch a step-by-step interface for adding MCP servers. The wizard walks through transport type selection, authentication, and configuration.¹⁵

Transport Types

HTTP (recommended for remote servers):

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# With authentication
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer $API_TOKEN"

SSE (deprecated but functional):

claude mcp add --transport sse asana https://mcp.asana.com/sse \
  --header "X-API-Key: your-key"

Stdio (local servers):

# PostgreSQL
claude mcp add --transport stdio postgres \
  --env "DATABASE_URL=postgresql://user:pass@localhost/db" \
  -- npx -y @anthropic-ai/mcp-server-postgres

# Custom server
claude mcp add --transport stdio custom -- python /path/to/server.py --port 8000

Windows requires a cmd wrapper for stdio:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Scope Management

MCP servers exist at three scopes with clear precedence (local overrides project overrides user):

Specify scope during installation:

claude mcp add --scope project --transport http github https://...
claude mcp add --scope user --transport stdio personal-tool -- ./my-tool

Configuration File Format

The .mcp.json file defines project-level servers:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_API_KEY}"
      }
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "X-API-Key": "${INTERNAL_API_KEY}"
      }
    }
  }
}

Environment variables expand using ${VAR} syntax with optional defaults: ${VAR:-default}.

MCP Management Commands

claude mcp list                      # View all configured servers
claude mcp get github                # Get specific server details
claude mcp remove github             # Remove a server
claude mcp reset-project-choices     # Reset project-scoped approvals
claude mcp add-from-claude-desktop   # Import from Claude Desktop
claude mcp add-json weather '{"type":"http","url":"..."}'  # Add from JSON

# Within Claude Code REPL
> /mcp                               # Interactive MCP management

OAuth Authentication

For servers requiring OAuth:

> /mcp
# Follow browser-based OAuth flow
# Tokens stored securely and auto-refreshed
# Use "Clear authentication" to revoke access

Using MCP Resources and Prompts

Reference resources:

@github:issue://123
@postgres:schema://users
@docs:file://api/authentication

MCP prompts as slash commands:

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high

Output Limits

MCP output is limited to prevent context overflow: - Warning threshold: 10,000 tokens - Default maximum: 25,000 tokens

Increase if needed:

export MAX_MCP_OUTPUT_TOKENS=50000

Popular MCP Servers

Practical MCP Patterns

GitHub workflow:

> Review PR #456
> List all open issues assigned to me
> Create a bug issue for the authentication failure we found

Database queries:

> What's our total revenue this quarter?
> Show the schema for the users table
> Find customers with no purchases in 90 days

Error monitoring:

> What errors occurred in production today?
> Show the stack trace for error ABC123
> Which deployment introduced these errors?

Enterprise MCP Configuration

System administrators can enforce MCP policies via managed-mcp.json:

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "sentry" },
    { "serverCommand": ["npx", "-y", "@approved/server"] }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" }
  ]
}

Location: - macOS: /Library/Application Support/ClaudeCode/managed-mcp.json - Linux: /etc/claude-code/managed-mcp.json - Windows: C:\ProgramData\ClaudeCode\managed-mcp.json

Denylist takes absolute precedence. Commands must match exactly including argument order.

Subagents and Task Delegation

Subagents are specialized Claude instances that handle complex tasks independently. They're one of the most powerful features in Claude Code and one of the least understood. Mastering subagents dramatically expands what you can accomplish.

Why subagents exist: Claude Code's main conversation has a single context window. Everything you discuss, every file Claude reads, every tool output—all consume that context. In long sessions, context fills up, Claude loses track of earlier decisions, and performance degrades. Subagents solve this by isolating work: exploration results don't bloat your main conversation, only the summary returns. Claude can also run up to 10 subagents in parallel, enabling concurrent work that would be impossible sequentially.²

How Subagents Work

When Claude encounters a task that benefits from focused attention—deep exploration, multi-step analysis, specialized work—it can spawn a subagent. The subagent:

1. Starts with a clean context (no pollution from main conversation)
2. Has access to specified tools
3. Operates with a specific model (often cheaper/faster)
4. Returns results to the main conversation

This architecture prevents context overflow while enabling complex workflows.

Built-In Subagent Types

Explore (fast, read-only): - Model: Haiku (ultra-fast) - Mode: Strictly read-only - Tools: Glob, Grep, Read, and safe bash commands (ls, git status, git log, git diff, find, cat, head, tail) - Thoroughness levels: Quick, Medium, Very thorough - Use for: Codebase exploration, finding files, understanding structure

General-purpose: - Model: Sonnet - Mode: Full read/write - Tools: All available tools - Use for: Complex research + modification tasks

Plan: - Model: Sonnet (or Opus with opusplan) - Mode: Read-only - Tools: Read, Glob, Grep, Bash - Use for: Planning complex implementations before execution

Triggering Subagents

Claude automatically delegates to subagents based on task type. You can also explicitly request them:

> Use the explore agent to find all authentication-related files

> Have a subagent analyze the database schema thoroughly

> Spawn an agent to research how error handling works in this codebase

Expert tip: For complex tasks, explicitly request subagent delegation. "Use an explore agent to find..." prevents context bloat in your main conversation.

Creating Custom Subagents

Define subagents in .claude/agents/ (project) or ~/.claude/agents/ (personal):

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

Configuration fields:

Managing Subagents

> /agents                    # Interactive management
> /agents create             # Create new subagent
> /agents edit               # Modify existing
> /agents delete             # Remove subagent
> /agents list               # View all

Running Agents in Background

For long-running tasks:

> Run a thorough security review in the background

> /agents  # Check status of running agents

Retrieve results later with the agent ID.

Advanced Patterns

Chained subagents:

> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

Parallel exploration:

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

Resumable agents: Agents can be resumed with their ID to continue previous work:

> Resume agent abc123 and continue the analysis

Extended Thinking Mode

Extended thinking gives Claude more time to reason through complex problems before responding. It's particularly valuable for architectural decisions, debugging tricky issues, and tasks requiring careful analysis.

Supported Models

• Claude Opus 4.5
• Claude Sonnet 4.5
• Claude Haiku 4.5

Enabling Extended Thinking

Quick toggle during session:

Press Tab to toggle thinking on/off

Via prompts:

> think deeply about the architecture for this feature
> think hard about what's causing this bug

Environment variable (permanent):

export MAX_THINKING_TOKENS=10000
claude

Thinking Token Budgets

Expert tip: Start with the minimum budget and increase only if Claude's responses seem rushed. Higher budgets cost more and aren't always better—they can lead to overthinking simple problems.

How It Works

When thinking is enabled, Claude's response includes internal reasoning that's not shown in the output but influences the answer. The thinking is encrypted and returned in a signature field for verification.

In multi-turn conversations with tool use, thinking blocks must be passed back to the API to preserve reasoning continuity. Claude Code handles this automatically.

When to Use Extended Thinking

Enable for: - Architectural decisions - Complex debugging - Security analysis - Performance optimization - Understanding unfamiliar codebases

Skip for: - Simple file edits - Routine refactoring - Quick questions - Code formatting

Cache Behavior

System prompt caching is preserved when thinking parameters change. Message caching is invalidated when thinking budget or enabled status changes between turns.

Output Styles

Output styles customize how Claude presents information—useful for learning, documentation, or specific team preferences.¹⁹

Built-In Styles

Setting Output Style

> /output-style Explanatory
> /output-style Learning

Or via settings:

{
  "outputStyle": "Explanatory"
}

Custom Output Styles

Create in .claude/styles/:

# my-style

## Instructions
- Always explain the WHY behind each decision
- Include relevant documentation links
- Format code examples with comments
- End with a "What to do next" section

## Format
Use markdown headers for organization.
Keep explanations under 200 words per section.

Invoke with /output-style my-style.

Slash Commands

Slash commands provide quick access to Claude Code features and enable custom workflows. They're faster than typing out full prompts for common operations.

Built-In Command Reference

Custom Command Creation

Create reusable commands in .claude/commands/ (project) or ~/.claude/commands/ (personal):

---
description: Security-focused code review
allowed-tools: Read, Grep, Glob
model: claude-sonnet-4-5
---

Review this code for security vulnerabilities:

1. Injection attacks (SQL, command, XSS)
2. Authentication and authorization flaws
3. Sensitive data exposure
4. Insecure dependencies

Focus on actionable findings with specific line references.

Save as .claude/commands/security-review.md, invoke with /security-review.

Command Frontmatter Options

---
description: Brief description for /help
allowed-tools: Read, Edit, Bash(npm:*)
model: opus
argument-hint: [arg1] [arg2]
disable-model-invocation: false
---

Argument Interpolation

All arguments as single string:

---
description: Fix GitHub issue
argument-hint: [issue-number]
---

Fix GitHub issue #$ARGUMENTS following our coding standards.

Usage: /fix-issue 123

Numbered arguments:

---
description: Create component
argument-hint: [name] [type]
---

Create a new $2 component named $1 in src/components/.

Usage: /create-component Button functional

Inline Bash Execution

Execute bash commands within command prompts:

---
description: Git status summary
allowed-tools: Bash(git:*)
---

Current branch: !`git branch --show-current`
Recent commits: !`git log --oneline -5`
Changed files: !`git status --short`

Summarize the current state of this repository.

File References

Include file contents in commands:

---
description: Compare implementations
---

Compare these files:
@src/v1/handler.ts
@src/v2/handler.ts

Which implementation is more maintainable?

Command Namespacing

Organize commands in subdirectories:

.claude/commands/
├── backend/
│   ├── test.md
│   └── deploy.md
├── frontend/
│   ├── test.md
│   └── build.md
└── review.md

Commands with the same name show their namespace in help: /test (project:backend) vs /test (project:frontend).

Skills

Skills represent a fundamentally different approach to extending Claude Code. Unlike slash commands that you invoke explicitly, skills are model-invoked—Claude automatically discovers and uses them based on context. You embed domain expertise into a skill, and Claude draws on that expertise whenever the situation calls for it, without you needing to remember to ask.

Why skills change everything: Consider domain expertise—the payment processing rules, the compliance requirements, the architectural patterns your team has refined over years. Without skills, you either re-explain this context every session or hope Claude infers it from code comments. With skills, you encode it once. Claude reads the skill definition and applies that expertise automatically whenever relevant. Your junior developers get senior-level guidance without asking. Your security patterns get enforced without remembering to invoke them.

This distinction matters. A slash command is a shortcut you remember to use. A skill is knowledge Claude always has available. When you create a security review skill with your team's specific vulnerability patterns and compliance requirements, Claude applies that expertise whenever it encounters relevant code—during PR reviews, refactoring, or any task where security matters. You don't invoke /security-review; Claude recognizes the context and applies the skill automatically.

Skills vs Commands vs Subagents

Understanding when to use each extension mechanism prevents duplication and maximizes effectiveness:

Use slash commands when you want explicit control: /deploy, /test, /review PR 456. You decide when to run them.

Use skills when expertise should be automatically available: security patterns, code style enforcement, domain-specific knowledge. Claude decides when to apply them.

Use subagents when tasks need isolation: background exploration, parallel analysis, specialized reasoning that shouldn't pollute your main conversation.

Skill Structure and Location

Skills live in dedicated directories containing a required SKILL.md file plus optional supporting resources:

Personal skills (available across all your projects):

~/.claude/skills/
├── code-reviewer/
│   ├── SKILL.md
│   ├── SECURITY_PATTERNS.md
│   └── PERFORMANCE_CHECKLIST.md
├── sql-analyst/
│   ├── SKILL.md
│   └── QUERY_PATTERNS.md
└── api-designer/
    └── SKILL.md

Project skills (shared with team via git):

.claude/skills/
├── domain-expert/
│   ├── SKILL.md
│   ├── BUSINESS_RULES.md
│   └── DATA_MODELS.md
└── deployment/
    ├── SKILL.md
    └── RUNBOOKS.md

Project skills commit to version control. When teammates pull, they get your skills automatically—no installation, no configuration. This is how you standardize expertise across a team.

SKILL.md Format

Every skill requires a SKILL.md file with YAML frontmatter:

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues, and best practice violations. Use when examining code changes, reviewing PRs, analyzing code quality, or when asked to review or audit code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Analysis

When reviewing code, check for:

### Input Validation
- All user input sanitized before use
- Parameterized queries for database operations
- Output encoding for rendered content

### Authentication & Authorization
- Session tokens properly validated
- Permission checks before sensitive operations
- No hardcoded credentials or API keys

### Data Exposure
- Sensitive data not logged
- PII properly masked in error messages
- API responses don't leak internal details

## Performance Patterns

### Database
- N+1 query detection
- Missing indexes on filtered columns
- Unbounded result sets

### Memory
- Large object lifecycle management
- Stream processing for big files
- Connection pool exhaustion risks

## Review Output Format

For each finding:
- **File**: path/to/file.ts:123
- **Severity**: Critical | High | Medium | Low
- **Category**: Security | Performance | Maintainability
- **Issue**: Clear description of the problem
- **Recommendation**: Specific fix with code example
- **Rationale**: Why this matters

See [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md) for detailed vulnerability patterns.
See [PERFORMANCE_CHECKLIST.md](PERFORMANCE_CHECKLIST.md) for optimization guidelines.

Frontmatter Reference

The description field is critical. Claude discovers skills by matching your requests against skill descriptions. A vague description means Claude won't recognize when to use the skill. A specific description with clear trigger conditions means reliable activation.

Poor description:

description: Helps with code

Effective description:

description: Review code for security vulnerabilities, performance issues, and best practice violations. Use when examining code changes, reviewing PRs, analyzing code quality, or when asked to review, audit, or check code.

The effective description includes: - What the skill does (review code for specific issues) - When to use it (examining changes, PRs, quality analysis) - Trigger phrases (review, audit, check)

Tool Restrictions

The allowed-tools field limits what Claude can do when a skill is active. This is essential for skills that should be read-only or limited in scope:

---
name: security-auditor
description: Audit code for security vulnerabilities without making changes
allowed-tools: Read, Grep, Glob
---

With this configuration, Claude can analyze code but cannot edit files, run bash commands, or make modifications. The skill enforces read-only behavior.

Common restriction patterns:

Supporting Files

Skills can include multiple files. Claude reads the main SKILL.md on activation, then accesses supporting files as needed—progressive disclosure that manages context efficiently.

Structure pattern:

my-skill/
├── SKILL.md           # Required: overview + quick reference
├── DETAILED_GUIDE.md  # Deep documentation
├── EXAMPLES.md        # Concrete examples
├── PATTERNS.md        # Reference patterns
├── templates/         # Reusable templates
│   └── component.tsx
└── scripts/           # Helper utilities
    └── validate.py

Reference supporting files from SKILL.md:

For detailed security patterns, see [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md).

Use this template for new components:
@templates/component.tsx

Validate configurations with:
```bash
python scripts/validate.py config.json

**Expert tip:** Put essential information in SKILL.md directly. Reserve supporting files for deep reference material. Claude reads SKILL.md immediately but only accesses supporting files when needed. If critical information is buried in a supporting file, Claude might not find it.

### Complete Example: Domain Expert Skill

Here's a production-quality skill for a fintech application:

**Directory structure:**

.claude/skills/payments-domain/ ├── SKILL.md ├── BUSINESS_RULES.md ├── COMPLIANCE.md └── DATA_MODELS.md

**SKILL.md:**
```markdown
---
name: payments-domain
description: Expert knowledge of payment processing domain including transaction flows, compliance requirements, and business rules. Use when working with payment code, transaction handling, refunds, disputes, or financial calculations.
---

# Payments Domain Expertise

## Core Concepts

### Transaction States

PENDING → AUTHORIZED → CAPTURED → SETTLED ↘ VOIDED AUTHORIZED → DECLINED CAPTURED → REFUNDED (partial or full) SETTLED → CHARGEBACK → REPRESENTED

### Money Handling Rules
- ALL monetary values stored as integers (cents, not dollars)
- Currency always explicitly tracked (never assume USD)
- Rounding: HALF_EVEN for calculations, HALF_UP for display
- Never use floating point for money

### Idempotency Requirements
Every payment operation MUST be idempotent:
```typescript
// Required pattern
async function processPayment(idempotencyKey: string, amount: number) {
  const existing = await findByIdempotencyKey(idempotencyKey);
  if (existing) return existing; // Return cached result

  const result = await executePayment(amount);
  await storeWithIdempotencyKey(idempotencyKey, result);
  return result;
}

Quick Reference

Fee Calculations

• Interchange: 1.5% + $0.10 (debit), 2.1% + $0.10 (credit)
• Platform fee: 2.9% + $0.30 (standard), 2.2% + $0.30 (enterprise)
• International: +1% cross-border fee
• Currency conversion: mid-market rate + 1%

Compliance Thresholds

• $3,000: Enhanced due diligence trigger
• $10,000: CTR filing required
• $25,000: Additional verification required

Refund Windows

• Full refund: 120 days from capture
• Partial refund: 180 days from capture
• Chargeback window: 120 days (Visa), 180 days (Mastercard)

Key Files

• src/payments/processor.ts - Core payment logic
• src/payments/refunds.ts - Refund handling
• src/compliance/aml.ts - AML checks
• src/models/transaction.ts - Transaction model

See BUSINESS_RULES.md for detailed business logic. See COMPLIANCE.md for regulatory requirements. See DATA_MODELS.md for schema documentation.

With this skill in place, Claude automatically applies payments domain expertise when you work on transaction code, ask about refund logic, or debug payment flows. You don't invoke anything—the expertise is just there.

### Creating Effective Skills

**Start with the description.** Write the description first, then build the skill content to match. The description determines when Claude uses the skill, so get it right:

1. State what the skill provides
2. List specific trigger conditions
3. Include relevant keywords and phrases

**Keep skills focused.** One skill should cover one domain or capability:

| Good (focused) | Bad (too broad) |
|----------------|-----------------|
| `security-auditor` | `code-helper` |
| `react-patterns` | `frontend-stuff` |
| `postgres-optimization` | `database-expert` |
| `api-documentation` | `docs-generator` |

If a skill tries to cover too much, its description becomes vague, and Claude won't reliably recognize when to use it.

**Use progressive disclosure.** Put the most important information in SKILL.md directly. Reference supporting files for depth:

```markdown
## Quick Reference
[Essential patterns here - Claude sees this immediately]

## Deep Dive
For comprehensive coverage, see [DETAILED_GUIDE.md](DETAILED_GUIDE.md).

Include concrete examples. Abstract descriptions are less useful than concrete patterns:

## Input Validation

### Pattern
```typescript
// Good: Explicit validation with typed errors
const validated = PaymentSchema.safeParse(input);
if (!validated.success) {
  throw new ValidationError(validated.error.issues);
}

// Bad: Implicit coercion
const amount = Number(input.amount); // Silent NaN on invalid input

**Test with realistic requests.** After creating a skill, test whether Claude activates it:

Review this payment processing code for issues

Should activate payments-domain skill

How should I handle refunds?

Should activate payments-domain skill

What's the weather like?

Should NOT activate payments-domain skill

If Claude doesn't activate the skill when expected, revise the description to include the trigger phrases you're using.

### Team Sharing Strategies

**Git-based sharing (recommended for project skills):**
```bash
# Add skill to project
mkdir -p .claude/skills/team-standard
# Create SKILL.md and supporting files

# Commit
git add .claude/skills/
git commit -m "Add team coding standards skill"
git push

# Teammates get it automatically
git pull
claude  # Skill now available

Cross-project sharing via symlinks:

# Create canonical skill location
mkdir -p ~/shared-skills/security-reviewer
# Create SKILL.md

# Symlink into projects
ln -s ~/shared-skills/security-reviewer ~/.claude/skills/security-reviewer
# Now available in all your projects

Plugin distribution: For broader distribution, package skills into plugins:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── my-skill/
        └── SKILL.md

Skills bundled in plugins become available when users install the plugin.

Debugging Skills

Skill not activating:

1. Check the description matches your request: yaml # If you're saying "check this code" but description says "review" description: Review OR check code for issues...

2. Verify file location: ```bash # Personal ls ~/.claude/skills/my-skill/SKILL.md

# Project ls .claude/skills/my-skill/SKILL.md ```

1. Validate YAML frontmatter:
2. First line must be exactly ---
3. Closing --- before markdown content
4. No tabs in YAML (use spaces)

5. Name field is lowercase with hyphens only

6. Run in debug mode: bash claude --debug # Watch for skill loading messages

Skill activating unexpectedly:

Narrow the description. If your skill activates when it shouldn't, the description is too broad:

# Too broad - activates on any "code" mention
description: Help with code

# Specific - activates only for security contexts
description: Audit code for security vulnerabilities including injection attacks, authentication flaws, and data exposure. Use when specifically asked about security, vulnerabilities, or when reviewing code for security issues.

Supporting files not found:

• Use relative paths from SKILL.md location
• Forward slashes only (even on Windows)
• Check file actually exists: ls .claude/skills/my-skill/REFERENCED.md

When to Create a Skill

Create a skill when: - Domain expertise should be automatically available - Multiple team members need the same knowledge - You're repeatedly explaining the same patterns or rules - Context should be injected without explicit invocation - Knowledge spans multiple files and needs organization

Don't create a skill when: - You want explicit control over invocation (use slash command) - The task needs separate context (use subagent) - It's a one-off prompt (just type it) - The "skill" is really just a single template (use slash command)

Expert tip: If you find yourself repeatedly typing /security-review before working on auth code, convert it to a skill. The expertise should be ambient, not explicitly invoked. If you want explicit invocation, keep it as a command.

Plugin System

Plugins package Claude Code extensions for distribution. A plugin can include custom commands, subagents, skills, hooks, and MCP servers.

Plugin Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json              # Required: metadata
├── commands/                     # Slash commands
│   └── hello.md
├── agents/                       # Subagents
│   └── helper.md
├── skills/                       # Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                        # Event handlers
│   └── hooks.json
└── .mcp.json                     # MCP servers

Plugin Manifest

Minimal plugin.json:

{
  "name": "my-plugin",
  "description": "What this plugin does",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Plugin Management

> /plugin                              # Interactive interface
> /plugin install name@marketplace     # Install
> /plugin enable name@marketplace      # Enable
> /plugin disable name@marketplace     # Disable
> /plugin uninstall name@marketplace   # Remove
> /plugin marketplace add ./local      # Add local marketplace
> /plugin marketplace list             # View marketplaces

Local Development

Create a local marketplace for testing:

mkdir dev-marketplace && cd dev-marketplace
mkdir my-plugin
# Create plugin structure

cd ..
claude
> /plugin marketplace add ./dev-marketplace
> /plugin install my-plugin@dev-marketplace

Plugin Components

• Commands: Available as slash commands (/plugin-command)
• Agents: Appear in /agents list
• Skills: Auto-load based on skill config
• Hooks: Merged with user/project hooks, run in parallel
• MCP Servers: Auto-start when plugin enabled

Memory and Context Management

Claude Code's memory system enables persistent context across sessions. Effective memory management is the difference between Claude understanding your project deeply and treating every session as a fresh start.

CLAUDE.md Hierarchy

Effective CLAUDE.md Structure

# Project Context

## Architecture
- Monorepo with packages in /packages
- React frontend in /packages/ui
- Node.js API in /packages/api
- Shared types in /packages/types
- PostgreSQL database via Prisma

## Code Standards
- TypeScript strict mode everywhere
- ESLint + Prettier enforced (pre-commit hooks)
- No default exports
- JSDoc on all public APIs
- Tests required for all new code

## Commands
- `npm test` - Run all tests
- `npm run test:watch` - Watch mode
- `npm run lint` - Check linting
- `npm run lint:fix` - Auto-fix lint issues
- `npm run build` - Production build
- `npm run dev` - Start dev servers
- `npm run db:migrate` - Run migrations
- `npm run db:seed` - Seed database

## Patterns

### API Endpoints
Create in packages/api/src/routes/
Use Zod for request/response validation
All endpoints need OpenAPI documentation

### React Components
Create in packages/ui/src/components/
Use React Query for server state
Prefer composition over inheritance

### Database
Prisma schema in packages/api/prisma/
Always create migration for schema changes
Use transactions for multi-table operations

## Important Notes
- NEVER commit .env files
- API runs on :3000, UI on :3001
- Local DB: postgres://localhost:5432/myapp
- Feature flags in packages/api/src/flags.ts

## Recent Decisions
- 2025-12-01: Migrated to React Query v5
- 2025-11-15: Adopted Zod for all validation
- 2025-11-01: Moved to ESM modules

# Summary Instructions
When using compact, focus on:
- Recent code changes
- Test results
- Architecture decisions made this session

File Imports

Reference other files within CLAUDE.md:

See @README.md for project overview
Coding standards: @docs/STYLE_GUIDE.md
API documentation: @docs/API.md
Personal preferences: @~/.claude/preferences.md

Import syntax: - Relative: @docs/file.md - Absolute from project: @/absolute/path.md - Home directory: @~/.claude/file.md - Maximum depth: 5 levels of imports

Memory Rules Directory

For more organized memory, use .claude/rules/ to store categorized rule files:¹⁸

.claude/rules/
├── testing.md          # Testing conventions
├── security.md         # Security requirements
├── api-patterns.md     # API design patterns
└── deployments.md      # Deployment procedures

Rules load automatically and provide structured context without cluttering CLAUDE.md.

Quick Memory Addition

Use the # prefix to add notes during a session:

# Always run tests before committing
# The payment module is especially fragile
# Use the new logger from packages/api/src/logger.ts

You'll be prompted to select which memory file to store the note in.

Context Management Commands

View context usage:

> /context

Shows a visual grid of context allocation across system prompt, conversation, tools, and file contents.

Compact conversation:

> /compact
> /compact focus on the authentication changes
> /compact preserve test output and error messages

Intelligently summarizes older conversation while preserving key information.

Custom compaction instructions (in CLAUDE.md):

# Summary Instructions
When using compact, focus on:
- Test output and failures
- Code changes made this session
- Architecture decisions

Extended thinking for context:

export MAX_THINKING_TOKENS=10000

More thinking tokens means more reasoning capacity but higher costs.

Context Optimization Strategies

1. Use specific file references instead of asking Claude to search
2. Clear unrelated conversations with /clear between tasks
3. Compact proactively during long sessions
4. Use subagents to isolate exploratory work
5. Break complex tasks into focused interactions
6. Resume sessions for ongoing work rather than re-explaining

Image and Multimodal Input

Claude Code can analyze images—screenshots, diagrams, mockups, error messages, database schemas.

Input Methods

1. Drag and drop: Drag image files into the Claude Code window
2. Paste: Ctrl+V (not Cmd+V on Mac) to paste from clipboard
3. Path reference: "Analyze this image: /path/to/screenshot.png"

Use Cases

• Debug UI issues: "Here's a screenshot of the bug, what's causing it?"
• Implement designs: "Build this component based on the mockup"
• Analyze diagrams: "Explain this architecture diagram"
• Database schemas: "Create Prisma models matching this ERD"
• Error analysis: "What does this error screenshot mean?"

Expert tip: When implementing from mockups, include multiple screenshots showing different states (default, hover, loading, error). The more visual context, the better the implementation.

Git Integration and Workflows

Claude Code has deep git integration with built-in safety protocols.

Safety Protocols

• Respects .gitignore automatically
• Won't modify branches without permission
• Shows diffs before commits
• Follows project's commit conventions
• Never force pushes without explicit request
• Checks authorship before amending commits

Common Workflows

Create commits:

> commit these changes
> create a commit with a meaningful message

Claude will: 1. Run git status and git diff 2. Analyze changes 3. Generate a conventional commit message 4. Wait for approval before committing

Create pull requests:

> create a PR for this feature
> summarize the changes and create a PR

Review code:

> review the changes in this PR
> what could go wrong with these changes?

GitHub Actions Integration

Automate Claude in CI/CD with the official action:

Quick setup:

> /install-github-app

Manual workflow file:

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
  issue_comment:
    types: [created]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Review this PR for bugs, security issues, and performance problems"
          claude_args: "--max-turns 5"

For Bedrock (with OIDC):

- name: Configure AWS
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
    aws-region: us-west-2

- uses: anthropics/claude-code-action@v1
  with:
    use_bedrock: "true"
    claude_args: '--model us.anthropic.claude-sonnet-4-5-20250929-v1:0'

IDE Integration

VS Code Extension

Requirements: VS Code 1.98.0+

Installation: Search "Claude Code" in Extensions marketplace

Features: - Sidebar panel (Spark icon) - Plan mode with diff preview - Auto-accept edits toggle - Extended thinking toggle - File attachment and image pasting - Conversation history - Multiple simultaneous sessions

Third-party provider configuration (in .claude/settings.json):

{
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "AWS_REGION": "us-east-1",
    "AWS_PROFILE": "your-profile"
  }
}

JetBrains Plugin

Supported: IntelliJ IDEA, PyCharm, WebStorm, GoLand, PhpStorm, DataGrip

Installation: Settings → Plugins → Search "Claude Code" → Install → Restart

Key shortcuts: - Cmd+Esc (Mac) / Ctrl+Esc (Windows): Quick launch - Cmd+Option+K (Mac) / Alt+Ctrl+K (Windows): Add file reference

Features: - Diff viewing in IDE diff viewer - Selection context auto-sharing - Diagnostic integration - Multiple sessions

WSL2 configuration: Set Claude command to:

wsl -d Ubuntu -- bash -lic "claude"

Terminal Integration

Connect an external terminal to your IDE:

> /ide

Claude Code auto-detects VS Code, Cursor, Windsurf, and JetBrains IDEs.

Slack Integration (December 2025)

Claude Code now integrates directly with Slack, enabling developers to delegate coding tasks from chat threads.¹⁴

How it works: 1. Mention @Claude in a Slack channel or thread 2. Claude reviews the message to determine if it's a coding task 3. A Claude Code session automatically starts on Anthropic infrastructure 4. Claude gathers context from recent channel/thread messages 5. Progress updates post back to your Slack thread 6. Links to review changes and open PRs provided on completion

Use cases: - Bug investigation from bug reports posted in Slack - Quick code reviews based on team feedback - Small feature implementations from feature requests

Requirements: - Claude app installed via Slack App Marketplace - Paid Slack plan - Access to Claude Code on the web

Privacy: Claude respects Slack's existing permission structure. It cannot access conversations or repositories you aren't authorized to see. Conversations are not used for model training.

Advanced Usage Patterns

Headless and CI Mode

Run Claude Code in scripts and CI pipelines:

#!/bin/bash
# Automated code review

result=$(claude -p "Review this code for quality issues" \
  --output-format json \
  --allowedTools "Read,Grep,Glob" \
  --permission-mode plan \
  --disable-slash-commands \
  --max-turns 5)

if echo "$result" | jq -e '.result | test("critical|high severity")' > /dev/null; then
  echo "Issues found:"
  echo "$result" | jq -r '.result'
  exit 1
fi

echo "Review passed"
exit 0

Piping and Chaining

# Analyze logs
cat production.log | claude -p "summarize errors" > error-summary.md

# Process multiple files
find . -name "*.ts" -exec cat {} \; | claude -p "find security issues"

# Chain with jq
claude -p "generate config" --output-format json | jq -r '.result' > config.json

Background Tasks

Run long operations without blocking:

> start the build in the background

Or press Ctrl+B during command execution.

Manage background tasks:

> /bashes                    # List running tasks
> get output from task xyz   # Retrieve output

Parallel Sessions with Git Worktrees

# Create worktrees for parallel work
git worktree add ../project-feature-a -b feature-a
git worktree add ../project-bugfix bugfix-123

# Run Claude in each
cd ../project-feature-a && claude --session-id "feature-a"
cd ../project-bugfix && claude --session-id "bugfix-123"

Each worktree is an independent project directory with its own session.

JSON Output Parsing

result=$(claude -p "analyze this code" --output-format json)

# Extract fields
echo "Result: $(echo $result | jq -r '.result')"
echo "Cost: $(echo $result | jq -r '.total_cost_usd')"
echo "Session: $(echo $result | jq -r '.session_id')"
echo "Duration: $(echo $result | jq -r '.duration_ms')ms"

Programmatic Session Management

# Named sessions for tracking
claude --session-id "feature-$(git branch --show-current)-$(date +%s)"

# Continue previous work
claude -c "continue implementing the tests"

# Fork for parallel exploration
claude -r "main-session" --fork-session "try alternative approach"

Claude Code Remote

Claude Code Remote bridges the gap between web and terminal, letting you start tasks in the cloud and continue them locally—or vice versa. This feature transforms how you work across devices.

The Core Concept

The web interface at claude.ai/code runs Claude Code in the cloud. Tasks execute in the background while you're away from your terminal. When you're ready to continue, teleport the session to your local machine and pick up exactly where Claude left off.

This enables workflows that weren't possible before: - Start a complex refactoring task from your phone, let it run while you commute, then finish on your workstation - Queue up multiple tasks on the web interface, review results when you return to your desk - Hand off long-running operations to the cloud when you need to close your laptop

The & Prefix

Send a task to run on Claude Code web in the background:

& Build a comprehensive REST API for user management with authentication, CRUD operations, and proper error handling

The & prefix dispatches your prompt to the cloud. Claude works on it asynchronously—you can close your terminal, switch devices, or continue with other work. The web interface at claude.ai/code shows your running and completed sessions.

The --teleport Flag

Pull a cloud session into your local terminal:

claude --teleport session_abc123

This retrieves the session state from the web and resumes it locally. You get the full conversation history, any files Claude modified, and can continue the interaction as if you'd been there the whole time.

The session ID appears in the web interface. Click on any session to see its ID and current status.

Requirements

Claude Code Remote requires a Claude Max subscription. The web interface runs on Anthropic's infrastructure, executing the same Claude Code capabilities you have locally—file operations, bash commands, MCP integrations—but in a managed cloud environment.

Practical Workflow

Morning commute:

& Review all PRs assigned to me and prepare summaries with recommendations

At your desk:

# Check what completed
# Visit claude.ai/code to see session list

# Pull the session locally to review and act on recommendations
claude --teleport pr-review-session-xyz

Before leaving work:

& Run the full test suite, fix any failures, and prepare a summary of what was changed

Next morning:

claude --teleport test-fixes-session-abc
# Review what Claude did overnight, make final adjustments

Current Status

Claude Code Remote is currently in research preview. Expect the feature to evolve as Anthropic gathers feedback. The core workflow—cloud execution with local teleportation—represents where agentic coding is headed: AI that works for you around the clock, not just when you're at your keyboard.

Background Agents (December 2025)

Background agents run while you continue working—no waiting for long-running tasks to complete.¹⁷

How Background Agents Work

Instead of blocking your terminal while Claude runs a complex task, background agents: 1. Execute independently in a separate process 2. Continue working even if you close your terminal 3. Report results when complete via notification 4. Can be monitored and managed while running

Starting a Background Agent

Using Ctrl+B: While Claude is working, press Ctrl+B to send the current task to the background. Your terminal becomes available immediately.

Using the & prefix:

& Run all tests and fix any failures
& Refactor the authentication module to use JWT
& Generate comprehensive API documentation

The & prefix dispatches to Claude Code Remote (cloud execution). For local background execution, use Ctrl+B on an already-running task.

Monitoring Background Tasks

> /tasks                    # List all running tasks
> /task status abc123       # Check specific task
> /task cancel abc123       # Stop a task
> /task output abc123       # View task output so far

Parallel Background Workflows

Run multiple agents simultaneously:

& Fix all failing tests in src/
& Update documentation for the API module
& Run security scan on the codebase

Each runs independently. Monitor progress with /tasks and pull results as they complete.

Cost Management and Billing

Understanding and controlling costs is essential for sustainable Claude Code usage.

Viewing Costs

> /cost

Output:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

Cost Factors

Real-World Cost Examples

Cost-saving insight: Using Haiku for exploration subagents and Sonnet for implementation typically reduces costs 40-50% compared to using Sonnet for everything.

Team Cost Management

Recommended TPM/RPM by team size:

Hidden Tool Fees

Beyond per-token pricing, some tools incur separate charges:¹⁶

These add up in agent loops. A 100-iteration debug cycle with Bash costs ~24,500 extra input tokens in overhead alone.

Cost-Saving Strategies

1. Use Haiku for subagents: Most exploration doesn't need Sonnet
2. Enable prompt caching: Default, but verify it's not disabled
3. Set max turns: claude --max-turns 5 prevents runaway conversations
4. Use plan mode for exploration: No execution = no accidental expensive operations
5. Compact proactively: Smaller context = fewer tokens
6. Limit output: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
7. Batch API for non-urgent work: 50% off both input and output tokens

Monitoring Usage

• Claude Console: console.anthropic.com (requires Admin or Billing role)
• Workspace limits: Set spending limits per workspace
• Bedrock/Vertex: Use native cloud cost monitoring
• LiteLLM: For detailed per-user tracking with third-party providers

Background Token Usage

Some operations consume tokens in the background: - Conversation summarization for /resume - /cost and /status commands - Auto-compaction

Typically under $0.04 per session.

Performance Optimization

Reducing Latency

Model selection: - Haiku: Fastest responses, lowest cost - Sonnet: Good balance - Opus: Best quality, highest latency

Streaming: All responses stream by default—you see output as it's generated.

Prompt caching: Enabled by default. Reduces latency for repeated context (system prompts, tool definitions).

Caching Strategies

System prompts and tool definitions are cached automatically: - Cache duration: 5 minutes (ephemeral) - Cache hit: Reduced input tokens and faster response

Thinking blocks from previous turns are cached in multi-turn conversations.

Disable caching per model if needed:

export DISABLE_PROMPT_CACHING_SONNET=1
export DISABLE_PROMPT_CACHING_OPUS=1
export DISABLE_PROMPT_CACHING_HAIKU=1

Parallel Operations

Subagent parallelization: Multiple subagents can run simultaneously. Each operates independently without polluting main context.

Background bash: Long-running commands don't block the conversation:

> run the full test suite in the background

Git worktrees: Enable true parallel sessions on separate branches.

Memory Optimization

• Specific file references: @src/auth.ts instead of "find the auth file"
• Targeted searches: "search in src/api" not "search everywhere"
• Fresh sessions: /clear between unrelated tasks
• Custom compaction: Add instructions to CLAUDE.md for what to preserve

Troubleshooting and Debugging

Installation Issues

WSL path problems:

npm config set os linux
npm install -g @anthropic-ai/claude-code --force --no-os-check
which npm  # Should start with /usr not /mnt/c

Node version conflicts (nvm): Add to ~/.bashrc or ~/.zshrc:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Permission errors: Use native installation instead of npm:

curl -fsSL https://claude.ai/install.sh | bash

Authentication Issues

# Complete reset
/logout
rm -rf ~/.config/claude-code/auth.json
claude  # Fresh login

Performance Issues

High CPU/memory: - Use /compact to reduce context - Restart between major tasks - Add large directories to .gitignore - Run claude doctor

Slow search: Install system ripgrep:

# macOS
brew install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

# Linux
sudo apt install ripgrep

Then:

export USE_BUILTIN_RIPGREP=0

Slow on WSL: - Move project to Linux filesystem (not /mnt/c/) - Use specific directory filters in searches

IDE Integration Issues

JetBrains not detected (WSL2):

Option 1 - Windows Firewall:

wsl hostname -I  # Get WSL IP
New-NetFirewallRule -DisplayName "Allow WSL2" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16

Option 2 - Mirrored networking (add to ~/.wslconfig):

[wsl2]
networkingMode=mirrored

Then: wsl --shutdown

Escape key not working in JetBrains: Settings → Tools → Terminal → Uncheck "Move focus to the editor with Escape"

Debug Mode

claude --debug                    # Full debug output
ANTHROPIC_LOG=debug claude       # API request logging
claude doctor                    # Health check

Configuration Reset

# Reset user settings
rm ~/.claude.json
rm -rf ~/.claude/

# Reset project settings
rm -rf .claude/
rm .mcp.json

Common Error Messages

Enterprise Deployment

Cloud Provider Comparison

Managed Settings Deployment

Deploy organization-wide policies via managed-settings.json:

Location: - macOS: /Library/Application Support/ClaudeCode/managed-settings.json - Linux: /etc/claude-code/managed-settings.json - Windows: C:\Program Files\ClaudeCode\managed-settings.json

Example policy:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(curl:*)",
      "Read(.env*)",
      "WebFetch"
    ],
    "defaultMode": "default"
  },
  "model": "claude-sonnet-4-5-20250929",
  "disableBypassPermissionsMode": "disable"
}

Users cannot override managed settings.

Enterprise CLAUDE.md

Deploy organization-wide context:

Location: - macOS: /Library/Application Support/ClaudeCode/CLAUDE.md - Linux: /etc/claude-code/CLAUDE.md

Content:

# Company Standards

## Security Requirements
- Never commit secrets or credentials
- All external API calls require security review
- Use parameterized queries for all database access

## Code Standards
- Follow company style guide at @docs/STYLE.md
- All PRs require two approvals
- Test coverage minimum: 80%

## Approved Tools
- npm, yarn, pnpm for package management
- Jest for testing
- ESLint + Prettier for formatting

Rollout Strategy

1. Start with documentation: Get CLAUDE.md right before deploying
2. Pilot group: Begin with 5-10 developers
3. Q&A phase: Let pilots use Claude for code exploration
4. Guided development: Progress to small bug fixes
5. Full deployment: Roll out with managed settings
6. Monitor costs: Track per-team usage

Audit and Compliance

• Session transcripts stored locally by default
• Use cloud provider logging for enterprise audit
• Consider LiteLLM for detailed usage tracking
• Managed settings enforce compliance policies

Keyboard Shortcuts Reference

General Controls

Prompt suggestions (Dec 2025): Claude now suggests prompts to speed up your workflow. Press Tab to accept a suggestion or Enter to submit your own prompt.¹³

Multiline Input

Quick Prefixes

Vim Mode

Enable with /vim:

Normal mode: - h/j/k/l - Navigation - w/e/b - Word movement - 0/$ - Line start/end - gg/G - Buffer start/end - dd - Delete line - cc/C - Change line/to end - dw/de/db - Delete word variations - x - Delete character - . - Repeat last edit

Insert mode: - i/I - Insert before/at line start - a/A - Insert after/at line end - o/O - Open line below/above - Esc - Return to normal mode

Best Practices

Session Strategy

Use descriptive session IDs:

claude --session-id "feature-$(git branch --show-current)-$(date +%s)"
claude --session-id "bug-JIRA-456"
claude --session-id "spike-new-architecture"

Resume sessions for ongoing work rather than re-explaining context.

CLAUDE.md Design

Keep it scannable. Claude reads this every session—dense prose wastes context.

Focus on the non-obvious. Document project-specific patterns, unusual conventions, decisions. Skip what Claude can infer from code.

Update continuously. Add notes during development with #. Review and consolidate weekly.

Include command reference. The commands you run constantly should be documented.

Custom Commands

Create commands for repetitive workflows:

---
description: Start new feature
allowed-tools: Bash(git:*), Read, Edit
---

1. Create branch: !`git checkout -b feature/$ARGUMENTS`
2. Pull latest main
3. Set up boilerplate
4. Begin implementation

Effective Prompting

Be specific:

# Good
"Add email validation to LoginForm in src/components/LoginForm.tsx"

# Too vague
"Improve the login"

Reference files directly:

"Review @src/auth/middleware.ts for security issues"

Provide constraints:

"Refactor using the same pattern as @src/repositories/UserRepository.ts"

Use subagents for exploration:

"Have an explore agent find all places where we handle errors"

Cost Control

• Use /cost regularly
• Use Haiku for simple tasks and subagents
• Set MAX_THINKING_TOKENS only when needed
• Use --max-turns for automated scripts
• Compact proactively in long sessions

Security

• Configure .claude/settings.json deny rules for sensitive files
• Use sandbox mode for untrusted projects
• Never allow Bash(rm -rf:*) or Bash(sudo:*)
• Use hooks to block access to secrets
• Deploy managed settings for enterprise

Enterprise teams deploying Claude Code at scale benefit from standardized configuration, managed policies, and integrated tooling. Teams at Introl help organizations implement AI development infrastructure across distributed engineering teams, from initial architecture through production deployment.

Common Anti-patterns

Learning what NOT to do often provides more value than best practices. These patterns consistently cause problems:

Cost Anti-patterns

Context Anti-patterns

Workflow Anti-patterns

Configuration Anti-patterns

Prompt Anti-patterns

Workflow Recipes

End-to-end patterns for common scenarios.

Recipe 1: Starting a New Project

# 1. Initialize
cd my-project
claude

# 2. Let Claude understand the codebase
> "Explore this codebase and summarize the architecture"

# 3. Set up project configuration
> /init

# 4. Create CLAUDE.md with learned patterns
> "Create CLAUDE.md documenting the patterns you observed"

# 5. Add team commands
> "Create a /test command that runs our test suite"
> "Create a /deploy command for staging deployment"

Recipe 2: Daily Development Flow

# 1. Continue yesterday's session
claude -c

# 2. Quick context recap
> "What did we work on yesterday?"

# 3. Check current state
> /status

# 4. Work on feature (Sonnet handles most tasks)
> "Implement the user profile endpoint"

# 5. Proactive context management
> /compact  # Before context exceeds 50%

# 6. Check spending
> /cost

# 7. End session cleanly
> "Summarize what we accomplished today"

Recipe 3: Complex Refactoring

# 1. Use Opus for planning, Sonnet for execution
> /model opusplan

# 2. Plan the refactoring
> "Plan refactoring our authentication from sessions to JWT"

# 3. Review the plan
# (Claude presents approach, you approve or modify)

# 4. Execute with Sonnet
> "Execute the plan"

# 5. Verify nothing broke
> "Have an explore agent verify all auth-related tests pass"

# 6. Review the diff
> !git diff

Recipe 4: PR Review Automation

# In CI/CD (GitHub Actions, etc.)
claude -p "Review this PR for:" \
  --input-file pr_diff.txt \
  --output-format json \
  --permission-mode plan \
  --max-turns 5 << EOF
- Security vulnerabilities
- Performance issues
- Code style violations
- Missing test coverage
Provide findings in JSON format.
EOF

Recipe 5: Debugging Production Issues

# 1. Configure Sentry MCP for error access
claude --add-mcp sentry

# 2. Get error context
> "Fetch the last 10 errors from Sentry for the auth service"

# 3. Deep dive with thinking
> Tab  # Enable extended thinking
> "Analyze these errors and identify the root cause"

# 4. Fix and verify
> "Implement a fix and add a regression test"
> !npm test

Migration Guide

Coming from other AI coding tools? Here's how concepts map.

From GitHub Copilot

What you gain: True agentic capability—Claude Code reads your codebase, runs tests, creates PRs, and delegates to subagents. Not just suggestions.

From Cursor

What you gain: MCP integrations (databases, GitHub, Sentry), subagent delegation, hooks for automation, and terminal-native workflow.

From ChatGPT / Claude Web

What you gain: Everything. Web interfaces require copy-paste workflows; Claude Code operates directly on your codebase.

Key Mindset Shifts

1. Stop copying code. Claude Code writes to files directly.
2. Stop context-switching. MCP brings external tools into the session.
3. Delegate aggressively. Subagents handle exploration without bloating your context.
4. Automate with hooks. Formatting, linting, logging happen automatically.
5. Think in sessions. Continue work with -c, not fresh conversations.

Key Takeaways

For developers: - Haiku costs 10-20x less than Opus—use for subagents and simple tasks - Use /compact proactively during long sessions to manage context - Session IDs encoding context (feature-${branch}-${timestamp}) help navigate back to previous work - Prefix common prompts with # to add to persistent memory without extra typing

For DevOps and platform teams: - Headless mode (-p flag) enables CI/CD integration with JSON output for parsing - Hooks guarantee execution regardless of model behavior—use for linting, formatting, security checks - MCP extends capabilities to databases, GitHub, Sentry, and 300+ integrations - Background tasks (& prefix) run on Claude Code Remote for asynchronous execution

For security teams: - Permission rules evaluated first-match-wins—structure allow/deny lists carefully - Sandbox mode isolates filesystem and network for untrusted codebases - Bash patterns match prefixes only—Bash(curl:*) blocks all curl, not just specific URLs - Enterprise managed settings cannot be overridden by users

For team leads: - Skills auto-activate based on context—embed domain expertise without explicit invocation - Project skills commit to git—teammates get standardized expertise automatically - Cost tracking via /cost shows session breakdown; budget 10k-300k TPM per user based on team size - Custom commands in .claude/commands/ create reusable workflows

For enterprise architects: - Managed settings deploy organization-wide policies via /etc/claude-code/managed-settings.json - AWS Bedrock, Google Vertex AI, and Microsoft Foundry integrate with existing cloud billing - Extended thinking (Tab to toggle) improves complex reasoning at higher cost - Start pilot with 5-10 developers before full rollout

Quick Reference Card

Print this. Tape it to your monitor.

╔═══════════════════════════════════════════════════════════════╗
║                    CLAUDE CODE QUICK REFERENCE                 ║
╠═══════════════════════════════════════════════════════════════╣
║  MODELS                                                        ║
║    haiku     $1/$5/M     Exploration, simple tasks            ║
║    sonnet    $3/$15/M    Daily coding (default)               ║
║    opus      $5/$25/M    Architecture, hard problems          ║
║    sonnet[1m] $6/$22.50/M Large codebases (1M context)        ║
╠═══════════════════════════════════════════════════════════════╣
║  ESSENTIAL COMMANDS                                            ║
║    /compact        Reduce context (do at 50% capacity)        ║
║    /cost           Check session spending                     ║
║    /model opus     Switch to Opus                             ║
║    /status         Show current state                         ║
║    /init           Set up project config                      ║
║    /mcp            Configure integrations                     ║
╠═══════════════════════════════════════════════════════════════╣
║  KEYBOARD SHORTCUTS                                            ║
║    Tab             Toggle extended thinking                   ║
║    Shift+Tab       Cycle permission modes                     ║
║    Ctrl+C          Interrupt current operation                ║
║    Esc → Esc       Rewind last change                         ║
║    Ctrl+L          Clear screen                               ║
╠═══════════════════════════════════════════════════════════════╣
║  PREFIXES                                                      ║
║    #message        Add to persistent memory                   ║
║    @path/file      Reference file in prompt                   ║
║    !command        Execute bash directly                      ║
║    &task           Send to cloud (async)                      ║
╠═══════════════════════════════════════════════════════════════╣
║  CONFIG FILE HIERARCHY (first found wins)                      ║
║    .claude/settings.local.json    Personal (gitignored)       ║
║    .claude/settings.json          Project (shared)            ║
║    ~/.claude/settings.json        User global                 ║
║    /etc/.../managed-settings.json Enterprise (locked)         ║
║    CLAUDE.md                      Project context             ║
╠═══════════════════════════════════════════════════════════════╣
║  DAILY WORKFLOW                                                ║
║    1. claude -c              Continue session                 ║
║    2. Work on features       Use Sonnet                       ║
║    3. /compact               Before context bloats            ║
║    4. /cost                  Check spending                   ║
║    5. Summarize              Clean exit                       ║
╠═══════════════════════════════════════════════════════════════╣
║  DECISION RULES                                                ║
║    Simple task?        → Haiku                                ║
║    Hard reasoning?     → Opus                                 ║
║    Everything else?    → Sonnet                               ║
║    Must always run?    → Hook (not prompt)                    ║
║    Auto-apply wisdom?  → Skill (not command)                  ║
║    Needs isolation?    → Subagent                             ║
╚═══════════════════════════════════════════════════════════════╝