claude-best-practice

🤖 Claude Code — Best Practices & Advanced Patterns

The most comprehensive, production-ready guide to mastering Claude Code From vibe coding → agentic engineering → autonomous AI development teams

Built for engineers who treat Claude Code as infrastructure, not a toy.

📖 Table of Contents

• Why This Guide Exists
• What is Claude Code?
• Architecture Overview
• Quick Start
• Core Concepts
  • Context Management
  • Plan Mode
  • Subagents
  • Commands
  • Skills
  • Hooks
  • MCP Servers
  • Memory System
  • Settings & Permissions
• Advanced Patterns
  • Multi-Agent Teams
  • Cross-Model Routing
  • Automated Pipelines
  • Security Patterns
  • Enterprise Patterns
• Development Workflows
  • Boris Cherny Creator Workflow
  • Verification Loops
  • Real-World Team Patterns
  • Babysit PRs
  • Batch Migrations
• Orchestration Patterns
• Tips & Tricks (190+)
• CLAUDE.md Mastery
• Model Selection Strategy
• Session Management
• Debugging Claude Code
• Performance Optimization
• Security Best Practices
• Team & Enterprise Usage
• Directory Structure
• Contributing

🎯 Why This Guide Exists

Most Claude Code guides cover the basics. This one doesn't stop there.

After thousands of hours of real-world usage across solo projects, startup teams, and enterprise codebases, this repository captures:

• What actually works — not what looks good in demos
• Anti-patterns to avoid — hard-won lessons from production failures
• Advanced architectural patterns — agent teams, automated pipelines, cross-model routing
• Copy-paste ready configs — .claude/settings.json, hooks, commands, skills
• Full development methodologies — end-to-end workflows from idea to deployment

Whether you're a solo developer building side projects or an engineering team shipping at scale, this guide gives you the mental models and practical tools to unlock Claude Code's full potential.

🧠 What is Claude Code?

Claude Code is Anthropic's official AI-powered CLI and IDE extension that brings Claude directly into your development workflow. Unlike chat-based AI tools, Claude Code:

• Reads and edits your actual files — not copy-pasted snippets
• Runs shell commands — tests, builds, linters, git operations
• Manages multi-file changes — across entire codebases
• Supports agentic workflows — autonomous multi-step task execution
• Integrates with external tools — via MCP (Model Context Protocol)
• Scales to teams — with shared configs, hooks, and agent definitions

Claude Code vs Other AI Tools

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                        CLAUDE CODE SYSTEM                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   USER INPUT                                                        │
│      │                                                              │
│      ▼                                                              │
│   ┌──────────────────────────────────────────────────────────────┐ │
│   │                    CLAUDE ORCHESTRATOR                        │ │
│   │  • Reads CLAUDE.md (project context)                         │ │
│   │  • Applies settings.json (permissions/model/style)           │ │
│   │  • Fires pre-tool hooks                                      │ │
│   │  • Routes to subagents / invokes tools                       │ │
│   └──────────┬───────────────────────────────────────────────────┘ │
│              │                                                       │
│     ┌────────┼────────────────────────────────────┐                │
│     ▼        ▼                    ▼                ▼                │
│  ┌──────┐ ┌──────┐           ┌────────┐       ┌────────┐           │
│  │ Read │ │ Edit │           │  Bash  │       │  MCP   │           │
│  │ File │ │ File │           │ Shell  │       │ Tools  │           │
│  └──────┘ └──────┘           └────────┘       └────────┘           │
│                                                                     │
│   SUBAGENTS (isolated context windows)                              │
│   ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐             │
│   │ Explore  │ │ Planner  │ │  Coder   │ │ Reviewer │             │
│   │  Agent   │ │  Agent   │ │  Agent   │ │  Agent   │             │
│   └──────────┘ └──────────┘ └──────────┘ └──────────┘             │
│                                                                     │
│   HOOKS (event-driven automation)                                   │
│   PreToolUse → PostToolUse → Stop → SubagentStop                   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

🚀 Quick Start

Installation

# Install Claude Code CLI
npm install -g @anthropic-ai/claude-code

# Or use the VS Code / JetBrains extension
# Or access via claude.ai/code

Your First Session

# Navigate to your project
cd my-project

# Start Claude Code
claude

# Or start with a specific task
claude "explain the architecture of this codebase"

# Enable plan mode for complex tasks
claude --plan "refactor the authentication system"

Essential First Setup

# Initialize CLAUDE.md for your project
claude /init

# Check settings
claude /config

# View available commands
claude /help

📚 Core Concepts

1. Context Management

Context is the most critical resource in Claude Code. Mismanaging it is the #1 cause of degraded output quality.

The Context Budget

Claude Code operates within a token context window. Think of it like RAM — finite, precious, and easy to exhaust.

Context Window
├── System prompt (CLAUDE.md + settings)    ~5-10%
├── Conversation history                    grows with each turn
├── File contents (read files)              can be large
├── Tool outputs (bash, search results)     often very large
└── Available for response                  shrinks as above grows

Context Health Rules

Rule 1: The 30% Rule Keep your context utilization below 30-40%. Above this threshold, Claude starts "forgetting" earlier context and output quality degrades.

0%  ────────────────────── 30% ──────────── 60% ──── 80% ── 100%
     IDEAL ZONE              WARNING        DANGER   CRITICAL

Rule 2: Rewind Don't Correct When Claude makes a mistake mid-task, don't keep piling on corrections. The corrections consume context AND confuse the model. Instead:

• Press ESC to interrupt
• Use /rewind to go back to the last clean state
• Re-issue the instruction with more specificity

Rule 3: Fresh Sessions for Fresh Tasks

# Wrong: Continuing from a long session for an unrelated task
# (you're now paying the cost of all that prior context)

# Right: New task = new session
claude /clear
claude "new task here"

# Or use /compact to summarize and continue
claude /compact "focus on the auth refactor"

Rule 4: Strategic /compact Use /compact with a specific hint so Claude summarizes what matters:

# Bad (no hint — Claude guesses what to keep)
/compact

# Good (Claude knows what to preserve)
/compact "we're mid-way through the database migration, keep all schema decisions"

Context-Aware File Reading

Don't read files you don't need. Be surgical:

# Instead of asking Claude to read the whole codebase, guide it:
"Read only src/auth/middleware.ts and tell me what token validation logic exists"

# Not:
"Read the codebase and tell me about auth"

2. Plan Mode

Plan Mode is Claude Code's most powerful feature for complex, multi-step tasks. It separates thinking from acting, preventing premature execution.

When to Use Plan Mode

How to Enter Plan Mode

# Via CLI flag
claude --plan "migrate the users table to add OAuth columns"

# Via slash command mid-session
/plan

# Via keyboard shortcut
Shift + Tab  # toggle plan/execute mode

Effective Plan Mode Usage

GOOD PLAN WORKFLOW:
1. Enter plan mode
2. State the goal + constraints
3. Review the plan Claude proposes
4. Ask questions / push back on decisions
5. Refine until you're confident
6. Exit plan mode → execute

BAD PLAN WORKFLOW:
1. Skip plan mode
2. Ask Claude to "just do it"
3. Get halfway through, realize the approach was wrong
4. Spend 3x as long cleaning up

Plan Mode Prompting

# Template for complex tasks
I need to [GOAL].

Constraints:
- [constraint 1]
- [constraint 2]

Do NOT touch:
- [file/system to leave alone]

Before executing, give me a step-by-step plan including:
1. Which files will be modified
2. What tests need to run
3. Any risks or irreversible steps

3. Subagents

Subagents are isolated Claude instances with their own context windows. They're the key to handling complex tasks without exhausting your main context.

Why Subagents?

WITHOUT SUBAGENTS:
Main Context: [task 1 history] [task 2 history] [task 3 history]
               ─────────────────────────────────────────────────
               Context fills up → quality degrades

WITH SUBAGENTS:
Main Context: [orchestration logic only]  ← stays clean
Subagent 1:   [task 1 isolated]
Subagent 2:   [task 2 isolated]
Subagent 3:   [task 3 isolated]
               Each starts fresh → quality stays high

Spawning Subagents