Session 2

Advanced
Workflows

MCP · Hooks · Agents · Worktrees

Extending the foundation — MCP, hooks, agents, worktrees

● MCP Servers

MCP — Connect Claude to everything

Model Context Protocol servers give Claude Code access to external tools and data sources: vector databases, browsers, APIs, anything with an MCP server. These are capabilities Claude cannot get from Bash alone.

How It Works

Transport types: HTTP (recommended for remote), stdio (local processes). SSE is deprecated.
Three scopes: Local (~/.claude.json, per-project), Project (.mcp.json, committed), User (~/.claude.json, all projects).
Tool Search: Defers MCP tool loading until needed. Reduces context from ~72K tokens to ~8.7K with multiple servers. On by default.

.mcp.json Example

// .mcp.json (committed to git)
{
  "mcpServers": {
    "qdrant": {
      "command": "uvx",
      "args": ["mcp-server-qdrant"],
      "env": {
        "QDRANT_URL": "${QDRANT_URL}",
        "COLLECTION_NAME": "project-docs"
      }
    },
    "context7": {
      "command": "npx",
      "args": ["-y",
        "@upstash/context7-mcp@latest"]
    }
  }
}

● MCP Servers

MCP servers worth knowing

You don't need many. Pick the ones that match your daily work.

🧠

Qdrant (Vector DB)

Semantic search over your docs, ADRs, and domain knowledge. Claude searches by meaning, not keywords. Store with qdrant-store, retrieve with qdrant-find.

🎭

Playwright MCP

Browser automation, screenshots, testing. Essential for frontend — gives Claude visual feedback it can't get from code alone.

🗄️

PostgreSQL / Supabase

Database queries and schema exploration. Claude validates migrations against live schema — not just guessing from Prisma files.

📚

Context7

Up-to-date library docs. Claude gets current API signatures instead of hallucinating from stale training data.

🎨

Figma MCP

Design-to-code workflows. Read Figma designs and translate to components — Claude sees the mockup.

🔍

Browse the Registry

modelcontextprotocol.io — find servers for your specific tools. GitHub, Stripe, Slack, and hundreds more.

Why not GitHub MCP? Claude Code already has gh CLI via Bash — MCP doesn't add much there. Focus on servers that give Claude capabilities it can't get from the terminal: semantic search, visual feedback, live documentation, design files.

● MCP — Use Case

Real use case: vector DB as Claude's knowledge layer

Your team has architecture decision records, API specs, domain glossaries, past postmortems. Claude can't read your Confluence wiki — but it can query a vector database where you've indexed that knowledge.

The Setup

1

Index your knowledge
Embed ADRs, specs, domain docs into Qdrant

↓

2

Connect via MCP
Qdrant MCP server in .mcp.json

↓

3

Claude queries before coding
"Find relevant decisions about auth" → semantic search → informed code

What Goes In The Vector DB

Architecture Decision Records — "Why did we choose PostgreSQL over MongoDB?" Claude finds the reasoning before suggesting a new data store.
API specs and contracts — internal service documentation that's too large for CLAUDE.md but critical for cross-service work.
Domain knowledge — business rules, glossaries, regulatory requirements. "What are the GDPR rules for user data deletion?"
Postmortems and incidents — "Has this pattern caused problems before?" Claude learns from your team's history.

This is the MCP paradigm shift: Claude isn't limited to what's in the repo. It can search your team's entire knowledge base by meaning — finding relevant context that keyword search would miss. The vector DB becomes Claude's long-term memory for your organization.

● MCP — Config

Where do you declare your MCP servers?

Three scopes — same pattern as settings. Pick the right one based on who needs it.

1

Local scope — claude mcp add (default)

Current project only, private to you. Stored in ~/.claude.json under your project's path. Use for personal dev servers, experiments.

2

Project scope — .mcp.json (committed to git)

Shared with your team. claude mcp add --scope project. GitHub MCP, team databases, shared API servers. This is the most common.

3

User scope — claude mcp add --scope user

Available in all your projects. Stored in ~/.claude.json (cross-project). Personal GitHub, utility servers you use everywhere.

// .mcp.json — project scope (committed, shared with team)
{
  "mcpServers": {
    "qdrant": {
      "command": "uvx",
      "args": ["mcp-server-qdrant"],
      "env": { "QDRANT_URL": "${QDRANT_URL}", "COLLECTION_NAME": "project-docs" }
      // stdio — semantic search over your team's knowledge base
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
      // stdio — fetches current library docs on demand
    }
  }
}

Project scope (.mcp.json) is the team default — Qdrant, Context7, Playwright all go here. Local and User scope both live in ~/.claude.json — local is per-project, user is cross-project. Note: MCP local scope is not .claude/settings.local.json — that's for general settings only.

● MCP — Troubleshooting

When MCP servers don't connect

MCP issues are the most common source of frustration. Here's your debugging playbook.

Common Issues

Server not found → check command path, run which npx to verify
Connection refused → server process not running, check port
Tools not appearing → run /mcp to see status, check allowedTools in settings
Context explosion → Tool Search is on by default, verify with /context
Auth failures → check environment variables, echo $GITHUB_TOKEN

Debugging Commands

# Check MCP server status
/mcp

# See what's loaded in context
/context

# Test a server manually
npx @modelcontextprotocol/server-postgres $DB_URL

# Restart Claude Code after config changes
# (MCP config loads on startup)

The #1 mistake: editing .mcp.json and expecting instant changes. MCP servers load on startup. Restart your Claude Code session after config changes.

● Hooks

Hooks — automate your guardrails

Hooks are shell commands that fire at lifecycle events. They format your code, block dangerous commands, validate quality — automatically, every time. Claude doesn't control them — they run whether Claude wants them to or not.

Four Hook Types

command

Runs a shell command. Most common type. Fast, predictable, easy to debug.

prompt

LLM-evaluated (uses Haiku by default). Smart but slower. Good for nuanced checks.

agent

Full agent execution. For complex, multi-step validation that needs reasoning.

http

POST to a URL. For external integrations — Slack notifications, webhooks, logging.

Hooks are reflexes — they fire every time, without thinking. Claude doesn't choose to run them. They fire at lifecycle events automatically, enforcing your standards even when no one is watching.

● Hooks — Events & Examples

28 Events — the ones that matter

Hooks can fire on 28 different lifecycle events. You'll use about 5 of them regularly. Here are the key ones and what they look like in practice.

Key Events

PreToolUse — fires before an action. The only hook that can block.
PostToolUse — fires after an action. Auto-format, auto-lint.
Stop — fires when Claude finishes. Validate completion.
SessionStart — fires on startup. Load env vars, set up tooling.
UserPromptSubmit — fires before Claude processes your prompt. Pre-validation.
+ 23 more — SubagentStop, FileChanged, Notification, ConfigChange, etc.

Practical Examples

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit|MultiEdit",
      "type": "command",
      "command": "npx prettier --write $FILE"
    }],
    "PreToolUse": [{
      "matcher": "Bash",
      "type": "command",
      "command": "echo $COMMAND | grep -qE 'rm -rf|DROP' && exit 2 || exit 0"
    }]
  }
}

PreToolUse hooks with exit code 2 block the action — even in bypassPermissions mode. This is your ultimate safety net.

● Hooks — Patterns

PreToolUse hooks — your ultimate safety net

PreToolUse is the only hook that can block actions. Exit code 2 = blocked. These patterns prevent disaster before it happens.

Block dangerous commands

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "type": "command",
      "command": "echo $COMMAND | grep -qiE 'rm -rf|DROP TABLE|DELETE FROM[^;]*;|force push' && exit 2 || exit 0"
    }]
  }
}

Exit code 2 blocks the action AND shows a message to Claude. Exit code 0 allows it. This runs even in bypassPermissions mode.

Protect critical files

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit|MultiEdit",
      "type": "command",
      "command": "echo $FILE | grep -qE 'production|\\.env\\.prod|schema\\.prisma' && exit 2 || exit 0"
    }]
  }
}

What to block

Destructive SQL (DROP, DELETE without WHERE)
Production config files
Force push to main/master
Direct commits to protected branches

PreToolUse hooks are your last line of defense. Claude can bypass permissions — it cannot bypass a PreToolUse hook that returns exit code 2. This is by design.

● Hooks — Real Example

Real-world hook: block credentials from commits

A PreToolUse hook that scans staged files for secrets before git commit runs. If it finds anything, exit code 2 blocks the commit and tells Claude why.

The hook config

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "type": "command",
      "command": "bash .claude/hooks/credential-check.sh"
    }]
  }
}

What it catches

AWS keys (AKIA...)
Private keys (BEGIN RSA PRIVATE KEY)
API tokens & passwords in code
.env files with real values

The script

#!/bin/bash
# .claude/hooks/credential-check.sh

# Only run when the command is git commit
echo "$TOOL_INPUT" | grep -q "git commit" \
  || exit 0

# Scan staged files for secrets
SECRETS=$(git diff --cached --diff-filter=ACM \
  | grep -iEn \
    'AKIA[0-9A-Z]{16}'           # AWS access key \
    '|BEGIN (RSA|EC|DSA) PRIVATE'  # private key \
    '|password\s*[:=]\s*["\x27].+' # password assignment \
    '|secret\s*[:=]\s*["\x27].+'  # secret assignment \
    '|token\s*[:=]\s*["\x27].+'   # token assignment
)

if [ -n "$SECRETS" ]; then
  echo "BLOCKED: Credentials found in staged files:"
  echo "$SECRETS"
  echo "Remove secrets and use env vars instead."
  exit 2   # ← blocks the commit
fi

exit 0     # ← allows the commit

Claude runs
git commit

→

PreToolUse
hook fires

→

Script scans
staged diff

→

Secrets found?
exit 2 = BLOCKED

This is what hooks are for — automatic enforcement with zero user action. Claude can't skip this check. It fires every time, even with dangerouslySkipPermissions. Your credentials never make it into a commit.

● Hooks — Workflow

Hooks + Skills — two independent layers

They don't call each other. They cover different gaps. Hooks are automatic reflexes. Skills are on-demand expertise you invoke yourself.

Hooks — automatic, no user action

Run shell commands when Claude uses a tool. You never invoke them — they just fire.

Claude writes
a file

→

PostToolUse
hook fires

→

prettier
formats it

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "type": "command",
      "command": "npx prettier --write $FILE"
    }],
    "Stop": [{
      "type": "command",
      "command": "npm test"
    }]
  }
}

Skills — on-demand, user invokes

Markdown instructions loaded into Claude's context when you type a slash command.

You type
/review

→

SKILL.md loads
into context

→

Claude follows
the checklist

# .claude/skills/review/SKILL.md
---
name: review
description: Run code review checklist
---

## Steps
1. Read changed files via `git diff`
2. Check for security issues
   (SQL injection, XSS, hardcoded secrets)
3. Verify test coverage for new functions
4. Ensure error handling follows project
   conventions
5. Output summary with pass/fail per check

Hooks = shell commands that fire automatically. Claude doesn't even know they ran.
Skills = markdown instructions Claude reads and follows. You trigger them with /skillname.
They don't call each other. But in a mature setup, both are active — hooks enforce standards silently while skills guide complex workflows on demand.

● Extension Points

MCP, Skills, or Hooks — which extension point?

Now that you know all three, here's the decision framework. Each solves a different problem. Choosing wrong means fighting the tool.

🔌

MCP Servers

Give Claude new capabilities it doesn't have. Access to databases, browsers, APIs, external tools. Think: new senses.

When: You need Claude to interact with an external system.

📜

Skills

Give Claude specialized instructions for specific workflows. Code review checklists, test patterns, deployment steps. Think: new knowledge on demand.

When: You need Claude to follow a specific process consistently.

🪝

Hooks

Automate guardrails that fire at lifecycle events. Auto-format, block dangerous commands, validate quality. Think: new reflexes.

When: You need something to happen automatically, every time, without thinking.

Triggers

Loads

Best for

Example

MCP

On tool use

Always (with Tool Search)

External systems

Qdrant, Playwright, Context7

Skills

Slash command or auto

On demand

Workflows & processes

/review, /spec, /plan

Hooks

Lifecycle events

Always

Automatic guardrails

Auto-format, block rm -rf

Most projects use all three. MCP connects Claude to your world. Skills teach Claude your workflows. Hooks enforce your standards automatically. They compose, they don't compete.

Quick Check — type your answer in chat

Auto-format code after every edit?
→ Hook

Connect to your team's vector database?
→ MCP

Run your code review checklist?
→ Skill

● Permission Modes

How much autonomy does Claude get?

Permission modes control how much Claude can do without asking. Combined with hooks, this gives you a sliding scale from fully supervised to fully autonomous — with guardrails at every level.

🛡️

Default Mode

Claude asks permission before writing files, running commands, or taking actions. Best for: learning, unfamiliar codebases, critical projects.

Shift+Tab to cycle modes

📋

Plan Mode

Read-only. Claude can explore and analyze but cannot modify anything. No writes, no commands, no side effects.

Best for: architecture exploration, understanding a codebase before coding.

⚡

Auto / Bypass Mode

Claude acts freely — no permission prompts. PreToolUse hooks still fire. Your hooks are the safety net.

claude --dangerouslySkipPermissions

This is why hooks matter so much: in bypass mode, Claude skips permission dialogs — but it cannot skip your PreToolUse hooks. A well-hooked project is safe even at maximum autonomy. Start in default mode, graduate to auto mode only after your hooks are solid.

● Agents

What is an agent?

An agent is not just a prompt — it's an intelligent orchestrator that decides what to do next based on the situation. It invokes skills sequentially (one by one) and spawns subagents in parallel (many at once). This is the fundamental building block of agentic software engineering.

Agent = Intelligent Skill

Agent

reads context, makes decisions, orchestrates work

sequential

↓ → ↓ → ↓

parallel

↓ ↓ ↓

Skill 1

explore

Skill 2

plan

Skill 3

implement

Subagent A

test auth

Subagent B

test payments

Subagent C

test UI

What makes it "agentic"?

Autonomous decision-making — it reads context and decides what skill to invoke next, not just following a script
Sequential skill invocation — it chains skills one by one: explore the codebase, then plan the change, then implement it, then test it
Parallel subagent spawning — when tasks are independent, it launches multiple subagents simultaneously (e.g., test three modules at once)
Feedback loops — when a test fails, it doesn't stop. It reads the error, adjusts, and retries. It reacts to outcomes, not just instructions
Tool access — it can read files, run commands, search code, edit code — all the primitives needed to do real work

The simplest way to think about it: a skill is a recipe. An agent is a chef — it knows many recipes, picks the right one, and adapts when ingredients are missing.

Claude Code itself is an agent. When you ask it to "fix this bug," it autonomously explores the code, forms a hypothesis, writes a fix, runs tests, and iterates — invoking skills and spawning subagents as needed. Everything in this section is about understanding and extending that capability.

● Agents — Why

Why do you need subagents?

Your main Claude session has one context window. Every file it reads, every search it runs, every conversation turn — it all accumulates. Subagents solve three problems that single-session workflows hit.

🧠

Context Pollution

You ask Claude to explore 50 files to understand the auth system. Now your context is full of auth code — and you need to work on the payment module. Every subsequent answer is biased by what Claude just read.

Subagent fix: explorer runs in its own context, reports back a summary. Your main session stays clean.

💰

Cost Explosion

A long session with heavy exploration hits 100K+ tokens. Every new message re-processes that entire context. You're paying for auth exploration tokens on every payment question.

Subagent fix: heavy exploration stays in a cheap Haiku agent. Your main Opus/Sonnet session stays lean.

🔒

Safety Boundaries

You want Claude to review code but not modify it. You want it to explore but not run commands. In a single session, you can't restrict tools per task.

Subagent fix: each agent gets only the tools it needs. A reviewer gets Read/Grep. A builder gets Edit/Bash. Least privilege by design.

Subagents are not about doing more — they're about doing the same work without polluting your main session's context, budget, or safety boundaries. Think of it as separation of concerns for your AI workflow.

● Agents

Subagents — delegate with precision

Now that you know why — here's how. Subagents get their own context window, their own tool restrictions, and can use different models.

Agent Definition

# .claude/agents/explorer.md
---
name: explorer
description: Investigate codebase
  structure and patterns
tools: Read, Grep, Glob
model: haiku
---

Explore the codebase and report:
- Directory structure
- Key patterns used
- Dependency relationships
- Potential issues

Model Routing Strategy

model: haiku — Exploration

Read-only agents that scan, search, investigate. Cheap and fast. No code changes.

model: sonnet — Implementation

Writing code, tests, documentation. The workhorse. Most agents should use this.

model: opus — Architecture

Critical design decisions, complex refactors. Use sparingly — expensive but thorough.

Built-in agents: Explore and Plan are available without configuration. Try them with /agents.

● Agents — Architecture

Under the hood — how subagents actually work

Each subagent gets its own context window, its own tool restrictions, and its own model. Understanding the architecture helps you design better agents.

The Architecture

Main Session

your conversation, full context

↓ spawns ↓

🔍

Explorer Agent

model: haiku · tools: Read, Grep, Glob

→ returns results

📝

Reviewer Agent

model: sonnet · tools: Read, Grep, Glob

→ returns results

🏗️

Architect Agent

model: opus · tools: Read, Grep, Glob

→ returns results

Key Architectural Facts

Isolated context — each agent starts fresh. Your main conversation doesn't carry over. This is why agents are perfect for heavy exploration.
Tool restrictions — agents only get the tools you list. An explorer with Read/Grep/Glob can't modify files. Safety by design.
Result return — agents send their findings back to your main session as a summary. The full exploration stays in the agent's context, not yours.
Cost isolation — each agent's token usage is tracked separately. Run /cost to see the breakdown.
Session continuity — agents get a session_id. You can continue a conversation with the same agent, preserving its context.

The key insight: subagents keep your main context clean. Heavy exploration in a subagent = zero context pollution in your main session. This is why context: fork in skills does the same thing — it runs the skill as a subagent.

● Agents — Routing

Matching models to tasks — the routing strategy

Not every task needs Opus. Not every task can use Haiku. Here's the decision framework for agent model selection.

Decision Framework

Does the task modify code?

YES → Sonnet (default for implementation)

Does the task read only?

YES → Haiku (cheap, fast, sufficient for exploration)

Is it a critical design decision?

YES → Opus (expensive but thorough)

Is it a routine check?

YES → Haiku (code style, lint rules, pattern matching)

Model Comparison

model: haiku

Read-only tasks: exploration, search, pattern matching, documentation lookup. Significantly cheaper than Sonnet/Opus.

Use for: Explore agents, documentation agents, pattern detection.

model: sonnet

Implementation tasks: writing code, tests, documentation, refactoring. The workhorse model.

Use for: Build agents, test agents, docs agents. Default choice unless you have a reason not to.

model: opus

Architecture tasks: design decisions, complex refactors, security reviews, multi-system tradeoffs.

Use sparingly — substantially more expensive. Reserve for decisions that cost more to fix than to make correctly.

Start with Sonnet. Downgrade to Haiku if the task is read-only. Upgrade to Opus only when the cost of a wrong decision exceeds the cost of the tokens. Most agents should use Sonnet or Haiku.

● Orchestration

Agents in action — orchestrating skills on the fly

This is where agents stop being a concept and start doing work. A well-designed agent reads the codebase, detects the stack, and dynamically invokes the right skills — you don't hardcode the workflow.

The Agent Definition

# .claude/agents/code-reviewer.md
---
name: code-reviewer
model: sonnet
description: Reviews code changes
---

You are a code reviewer. When invoked:

1. Detect the stack
   Read package.json, scan src/
   Identify: Express? Prisma? React?

2. Route to skills
   Express routes → /security-review
   Prisma queries → /performance-review
   React components → /accessibility-review

3. Synthesize
   Combine findings into one report

Runtime Behavior

1. Agent reads codebase
Scans package.json, file structure, imports

↓

2. Detects: Express + Prisma + React
Each stack element triggers a different skill

↓

/security
API routes

/performance
DB queries

/accessibility
Components

The agent decides which skills to invoke based on what it finds — you don't hardcode the workflow.

● Part 2

Extension layer complete.
Now: orchestration.

MCP, Hooks, and Agents extend what Claude can do. Now: how to scale it, script it, and recover when things go wrong.

Worktrees

The Full Stack

Headless Mode

Recovery

● Worktrees

Git worktrees — parallel development

Run multiple Claude Code sessions on the same repo without file conflicts. Each worktree gets its own branch and working directory.

🌳

How It Works

claude -w feature-auth creates:

• Directory: .claude/worktrees/feature-auth/
• Branch: worktree-feature-auth from origin/HEAD
• Full isolated working copy

No changes → auto-removed on exit.
Changes exist → prompt to keep/remove.

⚡

Practical Patterns

Hotfix interrupt: Working on a feature, urgent bug comes in. Open new terminal, claude -w hotfix-auth, fix and merge, return to feature work.

Parallel features: Terminal 1: claude -w feature-a. Terminal 2: claude -w feature-b. Both running independently.

Sweet spot: 2–4 active worktrees. Beyond that, coordination overhead exceeds gains.

● Worktrees — Lifecycle & Mechanics

Worktree lifecycle — create, work, merge, clean up

The full workflow from creating a worktree to merging the result and cleaning up.

# 1. Create — starts a new worktree + branch
claude -w feature-auth

# 2. Work — you're now in an isolated copy
#    commits go to branch: worktree-feature-auth

# 3. Merge back — from your main working directory
git merge worktree-feature-auth
# or push the branch and open a PR:
git push origin worktree-feature-auth
gh pr create --head worktree-feature-auth

# 4. Clean up — remove the worktree when done
git worktree remove .claude/worktrees/feature-auth
# or force-remove if you want to discard:
git worktree remove --force .claude/worktrees/feature-auth

# .worktreeinclude — gitignored files to
# copy into new worktrees (missing otherwise!)
.env
.env.local

# Optimize: symlink large dirs
# worktree.symlinkDirectories: ["node_modules"]

Merge: treat the worktree branch like any feature branch — merge or PR.
Clean up: git worktree remove deletes the directory and unlinks the branch.
List active: git worktree list shows all worktrees and their branches.

● Worktrees

Worktree arena — compete, then choose

The real power of worktrees: run competing AI implementations in parallel, then pick the winner yourself. You stay the decision-maker.

Use Case 1: Compare Implementations

# Terminal 1 — approach A: recursive
claude -w approach-recursive
"implement parseConfig using recursion"

# Terminal 2 — approach B: iterative
claude -w approach-iterative
"implement parseConfig using iteration"

# You compare both, pick the better one
diff -u \
  .claude/worktrees/approach-recursive/src/config.ts \
  .claude/worktrees/approach-iterative/src/config.ts

Same problem, different strategies, you judge. This is human-in-the-loop at its best — AI does the grunt work, you make the design call.

Use Case 2: Compare Different LLMs

# Each worktree has its own settings.local.json
# Override the LLM provider per worktree

# Worktree A — uses Claude Opus
.claude/worktrees/opus-impl/
  └── .claude/settings.local.json
      { "model": "claude-opus-4-6" }

# Worktree B — uses a local model via Ollama
.claude/worktrees/local-llm/
  └── .claude/settings.local.json
      { "model": "ollama/deepseek-r1" }

# Worktree C — uses LM Studio / GLM / MiniMax
# Same pattern — override in settings.local.json

Each worktree gets its own .claude/settings.local.json — the LLM config is per-worktree. You can't run two different models in the same shell, but with worktrees each gets its own config and its own Claude instance.

Why not just branches?

Branches share the working directory. You can't run two Claude instances on the same directory — they'd conflict on file writes. Worktrees give true isolation.

The arena pattern

Spin up 2–3 competing implementations → let each run independently → diff the results → merge the winner → delete the rest. Treat AI like candidates, not oracles.

Human stays in the loop

AI generates options, you evaluate tradeoffs — readability, performance, maintainability. This is how you stay sharp while still leveraging AI speed.

● Full Stack

The complete picture — both sessions

Everything you've learned across two sessions, assembled into one system.

The full instruction stack

~/.claude/settings.json     → global defaults
.claude/settings.json       → team shared config
CLAUDE.md                   → always-loaded knowledge
.claude/rules/*.md          → conditional rules
.claude/skills/*/SKILL.md   → on-demand instructions
.mcp.json                   → external tool connections
hooks                       → automatic guardrails
subagents                   → isolated specialists
worktrees                   → parallel development
permission modes            → autonomy dial
headless mode               → scripts & CI/CD
session management          → /clear /compact /cost

One sentence per layer

Settings → what Claude is allowed to do
CLAUDE.md → what Claude always knows
Rules → what Claude knows in specific directories
Skills → what Claude does when triggered
MCP → what external tools Claude can access
Hooks → what happens automatically at lifecycle events
Agents → who Claude can delegate to
Worktrees → how many things Claude can do at once
Modes → how much autonomy Claude gets
Headless → Claude in scripts and CI

Each layer does one thing well. Together they create a development environment where Claude arrives knowing your project, follows your standards, connects to your tools, and can work in parallel — all while you stay in control.

● Real World

A reference setup — what to aim for

This is a realistic target for a team using Claude Code daily. You don't need all of this on day one — build up incrementally.

The .claude/ directory

.claude/
├── settings.json          # hooks + permissions
├── settings.local.json    # personal overrides (gitignored)
├── agents/
│   ├── explorer.md        # haiku, read-only
│   ├── reviewer.md        # sonnet, read + write
│   └── architect.md       # opus, read-only
├── skills/
│   ├── review/SKILL.md    # code review checklist
│   ├── deploy/SKILL.md    # deployment workflow
│   └── test/SKILL.md      # TDD workflow
└── rules/
    ├── api.md             # paths: ["src/api/**"]
    ├── frontend.md        # paths: ["src/components/**"]
    └── db.md              # paths: ["prisma/**", "migrations/**"]

# Root files
.mcp.json                  # qdrant, context7, playwright
.worktreeinclude           # .env, .env.local
CLAUDE.md                  # <80 lines, project identity

What each layer does in practice

CLAUDE.md — "We use Next.js 15 + TypeScript 5.8. All API routes need auth middleware. Never commit .env files." (always present, team-shared)
Rules — "API routes validate with Zod. React components use server components by default. Migrations never drop columns." (path-scoped)
Skills — "Run /review before every PR. Run /deploy for production releases. Run /test when implementing new features." (on-demand)
MCP — "Qdrant for semantic search over ADRs. Context7 for current library docs. Playwright for visual testing." (always connected)
Hooks — "Auto-format on every file write. Block changes to production configs. Lint-check staged files before commit." (automatic)
Agents — "Explorer for understanding new areas. Reviewer for PR checks. Architect for design decisions." (delegated)

Start with CLAUDE.md and one hook — you can have a basic setup in an hour. The full stack builds up over your first week as you discover what your team actually needs. The layers compose incrementally.

● Headless Mode

Headless mode — Claude in scripts and CI

Claude Code isn't just interactive. With claude -p (pipe mode), it becomes a programmable tool you can embed in scripts, CI pipelines, and automation.

Pipe Mode Basics

# One-shot prompt — returns result to stdout
claude -p "explain what this project does"

# Pipe input from another command
git diff | claude -p "review this diff for bugs"

# Structured output for scripts
claude -p --output-format json \
  "list all API routes as JSON"

# Use in CI — auto-review PRs
git diff main...HEAD | claude -p \
  "review for security issues, output pass/fail"

Where It Fits

CI/CD pipelines — auto-review PRs, generate changelogs, check for security issues on every push.
Shell scripts — chain Claude into your existing automation. git log | claude -p "summarize this week's changes"
Batch operations — process multiple files, generate tests for untested modules, migrate patterns across a codebase.
GitHub Actions — anthropics/claude-code-action@v1 brings Claude Code into your PR workflow. @claude mentions in issue comments.

Key: your CLAUDE.md, hooks, and MCP servers all apply in headless mode. Same guardrails, no interactive shell.

Interactive Claude Code is your pair programmer. Headless Claude Code is your automation layer. Same engine, same configuration, different interface. Master both.

● Recovery

When things go wrong — and they will

Claude will occasionally go off the rails — wrong architecture, massive diffs, broken tests. The question isn't if, it's how fast you recover.

🔍

Before Committing

Always review the diff.

git diff — see what changed
git diff --stat — see scope

If the diff is larger than expected, something went wrong. Don't commit blindly.

⏪

Rolling Back

Small commits = easy recovery.

git stash — save and reset
git checkout -- . — discard all
git reset HEAD~1 — undo last commit

Commit after every successful step. Never let Claude build for 20 minutes without a checkpoint.

🧹

Context Recovery

When Claude gets confused:

/clear — fresh session
/compact — compress context
Escape (2x) — interrupt a runaway

A new session with a clear prompt beats fighting a confused one.

The #1 recovery pattern: commit early, commit often. Every passing test, every working feature — commit it. Git is your undo button. A 30-second commit saves a 30-minute re-implementation.

● What's Next

Going further

What this guide covers is the foundation and the advanced layer. Here's what lies further ahead for those who want to go deeper.

🔌

Claude Agent SDK

Use Claude Code programmatically from your own scripts and applications.

TypeScript: @anthropic-ai/claude-agent-sdk
Python: claude-agent-sdk

query() async generator for streaming. Headless mode with claude -p "prompt" for scripts. --json-schema for typed output in pipelines.

🚀

CI/CD Integration

Claude Code in your deployment pipeline.

GitHub Actions: anthropics/claude-code-action@v1
GitLab CI/CD: Also supported

Automated PR review on every push. @claude mentions in issues. Cron-scheduled maintenance tasks. Your CLAUDE.md applies automatically.

📦

Build & Publish Plugins

Bundle your skills, hooks, agents, and MCP servers into distributable packages.

Distribute via: GitHub, npm, marketplace
Manage: /plugin command

Create organizational standards as plugins. Share across teams. Enforce consistency automatically.

The expert-level unlock: Claude Code is not just a dev tool — it's a platform. The SDK and headless mode let you build systems that use Claude Code as infrastructure.

Your Next Steps

Build your
complete setup

1

Add an MCP server

Add an MCP server to your project (.mcp.json). Pick one that fits your daily work — Qdrant, Context7, Playwright, or browse the registry.

2

Set up one hook

Add a PostToolUse Prettier hook or a PreToolUse safety blocker. Make it fire. Feel it work.

3

Create a custom agent

Write an explorer or reviewer agent in .claude/agents/. Invoke it. Check /cost.

4

Try a worktree

Run claude -w feature-x. Build something in isolation. See the workflow in action.

Goal: push a .claude/ directory to your project with at least settings.json (with hooks), one agent, and one skill. Share it in the group. Compare setups.

The best way to learn this is to set it up for your own project — not a tutorial project.

Closing

What you now have

A Framework

The 5-phase methodology for disciplined agentic development.

Configuration

Settings, CLAUDE.md, rules, skills — 80% of Claude's effectiveness.

Extension

MCP, hooks, agents — new senses, reflexes, and specialists.

Orchestration

Worktrees, modes, headless — parallel, autonomous, scriptable.

Discipline

Recovery patterns, session hygiene, commit checkpoints.

Code is generated. Architecture is engineered. The discipline is yours.

Session 2

AdvancedWorkflows

MCP — Connect Claude to everything

How It Works

.mcp.json Example

MCP servers worth knowing

Real use case: vector DB as Claude's knowledge layer

The Setup

What Goes In The Vector DB

Where do you declare your MCP servers?

When MCP servers don't connect

Common Issues

Debugging Commands

Hooks — automate your guardrails

Four Hook Types

28 Events — the ones that matter

Key Events

Practical Examples

PreToolUse hooks — your ultimate safety net

Block dangerous commands

Protect critical files

What to block

Real-world hook: block credentials from commits

The hook config

What it catches

The script

Hooks + Skills — two independent layers

Hooks — automatic, no user action

Skills — on-demand, user invokes

MCP, Skills, or Hooks — which extension point?

Quick Check — type your answer in chat

How much autonomy does Claude get?

What is an agent?

Agent = Intelligent Skill

What makes it "agentic"?

Why do you need subagents?

Subagents — delegate with precision

Agent Definition

Model Routing Strategy

Under the hood — how subagents actually work

The Architecture

Key Architectural Facts

Matching models to tasks — the routing strategy

Decision Framework

Model Comparison

Agents in action — orchestrating skills on the fly

The Agent Definition

Runtime Behavior

Extension layer complete.Now: orchestration.

Git worktrees — parallel development

Worktree lifecycle — create, work, merge, clean up

Worktree arena — compete, then choose

Use Case 1: Compare Implementations

Use Case 2: Compare Different LLMs

The complete picture — both sessions

The full instruction stack

One sentence per layer

A reference setup — what to aim for

The .claude/ directory

What each layer does in practice

Headless mode — Claude in scripts and CI

Pipe Mode Basics

Where It Fits

When things go wrong — and they will

Going further

Your Next Steps

Build yourcomplete setup

Closing

What you now have

Advanced
Workflows

Extension layer complete.
Now: orchestration.

Build your
complete setup