Mastering Claude Code — CLAUDE.md, Hooks, MCPs & Workflows

The definitive guide to Claude Code — Anthropic's agentic coding CLI that lives in your terminal and understands your entire codebase. This cookbook covers CLAUDE.md configuration, hooks, MCP integrations, debugging with extended thinking, headless CI/CD workflows, and the prompting patterns that get the best results.

Claude Code is Anthropic's terminal-based AI pair programmer. It reads your entire codebase, autonomously executes multi-step coding tasks, runs shell commands, manages git workflows, and iterates until the job is done. It reached $1 billion in run-rate revenue within six months of launch — the fastest-growing agentic coding tool of 2025.

---

What is Claude Code

Claude Code is an agentic coding CLI tool that connects directly to Anthropic's Claude models via your terminal. Unlike IDE plugins, it operates with no intermediate server, supports full codebase awareness, and can autonomously plan, implement, test, and commit code. Installation

npm install -g @anthropic-ai/claude-code
cd my-project
claude

Models Available

Model	Best For
Claude Opus 4.6	Maximum capability, agent teams, architecture
Claude Sonnet 4.6 (default)	Fast + capable, cost-efficient daily use
Claude Sonnet 4	Good baseline coding
Claude Haiku 4.5	Simple tasks, low latency
Switching models:

# At startup
claude --model claude-opus-4-20250514

# During session
/model opus
/model sonnet

Authentication:

Method	How
Claude.ai subscription	/login → select claudeai
API key	export ANTHROPIC_API_KEY=sk-ant-...
AWS Bedrock	export CLAUDE_CODE_USE_BEDROCK=1
Google Vertex	export CLAUDE_CODE_USE_VERTEX=1

---

Core Skills and Capabilities

Code Generation

Reads your entire codebase context, writes multi-file features, creates project structures, and verifies implementations.

> write tests for the auth module, run them, and fix any failures
> create the folder structure and files for a REST API following our existing patterns

Debugging

Paste error messages or describe symptoms — Claude traces issues through your entire codebase to the root cause.

> the build fails with this error: [paste]. fix it and verify the build succeeds
> users report login fails after session timeout — trace the auth flow

Multi-File Editing

Coordinated changes across multiple files — renaming, bulk linting, architecture refactors, schema changes with migrations.

git diff main --name-only | claude -p "review these changed files for security issues"

Git Operations

Full workflow automation — staging, commits, branches, PRs.

> commit my changes with a descriptive message
> create a pr for my changes
> look through the git history and summarize how this API evolved

Test Writing

> write a test for foo.py covering the edge case where the user is logged out. avoid mocks.
> run all tests and fix any failures

Codebase Exploration

> explain how our authentication system handles token refresh
> give me a high-level architecture overview

PR Reviews

git diff origin/main...HEAD | claude -p "review this diff for bugs, security flaws, and convention violations"

---

CLAUDE.md — Project Instructions

CLAUDE.md is the highest-leverage part of your Claude Code setup. It's read at the start of every session and acts as persistent memory for your project. File Locations:

Location	Scope
~/.claude/CLAUDE.md	Global — all projects
./CLAUDE.md	Project root (commit to git)
./subdir/CLAUDE.md	Subdirectory-specific
./CLAUDE.local.md	Personal overrides (.gitignore)
Quick Start:

/init

This analyzes your codebase and generates a starter CLAUDE.md. Example CLAUDE.md:

# Project: My SaaS App
A Next.js e-commerce app with Stripe and PostgreSQL.

## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- DB: `npx prisma migrate dev --name <name>`

## Architecture
- /app — Next.js App Router pages
- /components/ui — Reusable UI components
- /lib — Utilities and shared logic
- /prisma — Database schema and migrations

## Code Style
- ES modules (import/export), not CommonJS
- Named exports over default exports
- TypeScript strict mode, no `any`
- Conventional Commits (feat:, fix:, docs:)

## Important
- NEVER commit .env files
- Stripe webhook handler MUST validate signatures

File Imports:

## Code Style
See @docs/code-style.md for detailed guidelines

## Testing
See @docs/testing-conventions.md

Modular Rules:

your-project/
├── CLAUDE.md
└── .claude/
    └── rules/
        ├── code-style.md
        ├── testing.md
        └── security.md

Best Practices:

1. Keep under 300 lines — every line must earn its place
2. Be specific — "Use named exports" not "follow good practices"
3. Use emphasis for critical rules: IMPORTANT: Never commit .env
4. Add instructions as you work — tell Claude to update CLAUDE.md when it makes wrong assumptions
5. Review periodically — ask Claude to optimize for outdated rules

---

Slash Commands Reference

Command	Description
/init	Analyze codebase, generate CLAUDE.md
/clear	Reset conversation context
/compact	Compress context (preserves key info)
/cost	Show token usage and session cost
/model	Switch models mid-session
/memory	Open/edit CLAUDE.md
/mcp	Manage MCP connections
/hooks	Interactive hook configuration
/permissions	Manage tool allowlist
/rewind	Undo last action + restore state
/plan	Enter plan mode
/context	Visualize context usage
/doctor	Diagnose installation health
/export	Export conversation to file
Keyboard Shortcuts:
Shortcut	Action
---	---
Esc	Stop current operation
Esc Esc	Rewind to checkpoint
Shift+Tab	Cycle: Normal → Auto-Accept → Plan
Ctrl+G	Open prompt in external editor
Ctrl+R	Search command history
# at prompt	Add instruction to CLAUDE.md
! at prompt	Execute bash command
@ in prompt	Reference a file (autocomplete)

---

Popular MCP Integrations

Adding MCP Servers

# Remote HTTP
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Local stdio
claude mcp add github -- npx -y @modelcontextprotocol/server-github
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Projects

# List / check
claude mcp list
/mcp

Essential MCP Servers

MCP Server	Install	Use Case
GitHub	claude mcp add github -- npx -y @modelcontextprotocol/server-github	Issues, PRs, repo management
Filesystem	claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Projects	File access beyond project
Puppeteer	claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer	Browser automation
PostgreSQL	claude mcp add db -- npx -y @bytebase/dbhub --dsn "postgresql://..."	Database queries
Brave Search	claude mcp add brave-search -- npx -y @anthropic-ai/mcp-server-brave-search	Web search
Context7	claude mcp add context7 -- npx -y @upstash/context7-mcp@latest	Live library docs
Sentry	claude mcp add --transport http sentry https://mcp.sentry.dev/mcp	Error analysis
Notion	claude mcp add --transport http notion https://mcp.notion.com/mcp	Docs and specs
Supabase	Via Supabase dashboard	Database and auth

MCP Configuration Files

Scope	File	Shareable
User-global	~/.claude.json	No
Project (team)	.mcp.json in project root	Yes (git)
Project-specific	.claude/settings.local.json	No

Tool Search (Context Optimization)

When many MCP tools are loaded, enable tool search to save up to 47% context:

ENABLE_TOOL_SEARCH=auto claude

---

Hooks and Custom Commands

Hooks

Scripts that run before or after Claude Code actions — for auto-formatting, linting, blocking dangerous commands, or audit logging. Common hook examples:

# Auto-format after file writes
PostToolUse hook: Run Prettier on modified files

# Block dangerous commands
PreToolUse hook: Reject commands containing "rm -rf", "DROP TABLE"

# Block .env access
PreToolUse hook: Block any file read/write to .env files

# Audit logging
PostToolUse hook: Log all tool calls to audit file

Configure with /hooks command.

Custom Slash Commands

Create .claude/commands/<name>.md:

# .claude/commands/review.md
Review the following files for:
1. Security vulnerabilities
2. Performance issues
3. Convention violations

Files: $ARGUMENTS

Then use: /review src/auth.ts src/api.ts

---

Debugging with Extended Thinking

Claude Code supports extended thinking modes that allocate more reasoning tokens for complex problems:

Trigger	Token Budget	Best For
"think"	Standard	Routine debugging
"think hard"	2x standard	Multi-file bugs
"ultrathink"	Maximum	Architecture decisions, complex traces
Debugging Patterns:

Explore → Plan → Fix

> read /src/auth and understand how sessions work (Plan Mode)
> I want to fix the session timeout bug. What files need to change? Create a plan.
> implement the fix from your plan. run tests and verify.

Subagent Debugging

For large codebases, Claude can spawn focused sub-agents:

> use a code-reviewer subagent to check the auth module for security issues

Git Bisect with AI

> use git bisect to find the commit that introduced this regression in the checkout flow

---

Headless Mode and CI/CD

The -p flag enables non-interactive mode:

# Basic headless
claude -p "Generate a .gitignore for Node.js"

# Pipe input
cat error.log | claude -p "analyze these errors and suggest fixes"

# JSON output
claude -p "review this code" --output-format json > review.json

GitHub Actions Example

name: Claude Code Review
on: pull_request

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @anthropic-ai/claude-code
      - run: |
          git diff origin/main...HEAD | claude -p \
            "Review this PR diff for bugs, security issues, and convention violations. 
             Output a structured review with severity levels." \
            --output-format json > review.json
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

---

Workflows

Core Workflow: Explore → Plan → Implement

1. Explore (Plan Mode):

> read /src/auth and understand sessions and login

2. Plan:

> I want to add Google OAuth. What files change? Create a plan.

3. Implement (Normal Mode):

> implement the OAuth flow. write tests, run them, fix failures.

Multi-Claude Fan-Out

Run multiple Claude Code sessions in parallel on different subtasks:

# Terminal 1
claude -p "implement user CRUD endpoints"

# Terminal 2
claude -p "implement auth middleware"

# Terminal 3
claude -p "write integration tests for API"

---

Limitations and Workarounds

Limitation	Workaround
Reward hacking (passes tests but wrong approach)	Write precise test assertions; review implementation
Stub implementations	Add to CLAUDE.md: "Never use stub or placeholder code"
Context rot in long sessions	Use /compact; start new sessions per task
Rate limits on subscription plans	Use /cost to monitor; switch to lighter models
No GUI	Pair with Cursor for visual tasks; use Playwright MCP

---

Cost and Plan Optimization

Plan	Price	Best For
Pro	$20/month	Individual developers, moderate usage
Max 5x	$100/month	Heavy daily use, parallel sessions
Max 20x	$200/month	Teams, CI/CD pipelines
API (pay-per-use)	Variable	Enterprise, predictable billing
Cost-saving tips:

• Use /cost regularly to track spending
• Use Sonnet for routine tasks, Opus only for complex reasoning
• Use /compact to reduce token usage in long sessions
• Use headless mode (-p) for batch operations

---

Last updated: February 27, 2026 Built for authorityaitools.com — AI Coding Tools Directory