Claude Code Playbook

A concise guide covering everything you need to know to get started and work effectively with Claude Code.

---

Table of Contents

• How It Works
• Initial Setup and Knowledge
• Best Practices
• Sessions and Memory
• Rules and Permissions
• Skills
• MCPs
• Hooks
• Sub-agents
• Plugins
• Other Useful Info
  • Videos

---

How It Works

Reference: How Claude Code Works

Claude Code is an agentic assistant that runs in your terminal. It can read files, run commands, edit code, search the web, and more.

1.1 The Agentic Loop

When you give Claude a task, it works through a loop of gathering context, taking action, and verifying results -- repeating until the task is complete. You can interrupt at any point to steer it.

1.2 Models

Claude Code uses Claude models to reason about your code. Multiple models are available:

Model	Strength	Switch with
Sonnet	Most coding tasks, good balance	/model or --model sonnet
Opus	Complex architectural decisions	/model or --model opus
Haiku	Fast, low-latency tasks	/model or --model haiku

1.3 Tools

Tools make Claude Code agentic. Without them, Claude can only respond with text. With them, it can act.

Category	What Claude Can Do
File operations	Read, edit, create, rename files
Search	Find files by pattern, search content with regex
Execution	Run shell commands, tests, use git
Web	Search the web, fetch documentation
Code intelligence	Type errors, jump to definitions, find references (requires plugins)

1.4 What Claude Can Access

When you run claude in a directory, it gains access to:

• Your project -- files in the directory and subdirectories
• Your terminal -- any command you could run (build tools, git, package managers, etc.)
• Your git state -- current branch, uncommitted changes, recent history
• Your CLAUDE.md -- persistent project instructions
• Extensions -- MCP servers, skills, sub-agents, plugins

---

Initial Setup and Knowledge

2.1 CLAUDE.md

CLAUDE.md is a markdown file that Claude reads at the start of every session. Use it to store instructions, conventions, and context that Claude cannot infer from code alone.

What to include:

• Build/test/lint commands Claude can't guess
• Code style rules that differ from defaults
• Repository etiquette (branch naming, PR conventions)
• Architectural decisions specific to your project

What to exclude:

• Anything Claude can figure out by reading code
• Standard language conventions
• Long explanations or tutorials

Locations:

Location	Scope	Shared
~/.claude/CLAUDE.md	All projects	No (personal)
./CLAUDE.md or ./.claude/CLAUDE.md	Current project	Yes (commit to git)
./CLAUDE.local.md	Current project	No (auto-gitignored)
.claude/rules/*.md	Modular project rules	Yes (commit to git)

Run /init to generate a starter CLAUDE.md based on your project.

2.2 Common Commands

Command	Purpose
/init	Generate a starter CLAUDE.md
/model	Switch between models
/clear	Reset context window
/rewind	Reset context window
/compact	Summarize conversation to free context
/ide	Connect to an IDE
/add-dir	Add an additional working directory (e.g.: reference the code from another project in a different dir to use as context)
/context	See what's using context space
/doctor	Diagnose installation issues
/export	Export conversation
/theme	Change the UI theme

2.3 Key Bindings

Key	Action
@	Add a file/folder to context
Shift+Tab	Cycle permission modes (Default → Auto-accept edits → Plan mode)
Esc	Interrupt Claude

2.4 How to Work Effectively

Reference: Work Effectively

• Be specific upfront -- reference files, mention constraints, point to patterns
• Give verification criteria -- tests, screenshots, expected outputs
• Explore before implementing -- use Plan mode for complex problems
• Delegate, don't dictate -- give context and direction, trust Claude with the details
• Interrupt and steer -- type a correction and press Enter at any time

2.5 Common Workflow Patterns

Explore → Plan → Confirm → Commit:

Write Tests → Commit → Code → Iterate → Commit:

Write Code → Screenshot Result → Iterate → Commit:

---

Best Practices

Reference: Best Practices

3.1 The #1 Rule: Give Claude a Way to Verify Its Work

Include tests, screenshots, or expected outputs so Claude can check itself. This is the single highest-leverage thing you can do.

3.2 Context Management

Context is your most important resource. Performance degrades as it fills.

• /clear between unrelated tasks
• /compact with a focus (e.g., /compact focus on the API changes)
• Use sub-agents for research -- they run in separate context
• Keep CLAUDE.md concise

3.3 Prompting Tips

Strategy	Before	After
Scope the task	"add tests for foo.py"	"write a test for foo.py covering the edge case where the user is logged out, avoid mocks"
Point to sources	"why is this API weird?"	"look through ExecutionFactory's git history and summarize how its API came to be"
Reference patterns	"add a calendar widget"	"look at how HotDogWidget.php is implemented, follow the same pattern for a calendar widget"
Describe symptoms	"fix the login bug"	"users report login fails after session timeout, check src/auth/, especially token refresh"

3.4 Avoid Common Failure Patterns

• Kitchen sink session -- mixing unrelated tasks in one session. Fix: /clear between tasks.
• Correcting over and over -- context polluted with failed approaches. Fix: after 2 failed corrections, /clear and write a better prompt.
• Over-specified CLAUDE.md -- Claude ignores half of it. Fix: ruthlessly prune.
• Trust-then-verify gap -- no tests provided. Fix: always provide verification.
• Infinite exploration -- unscoped investigation fills context. Fix: scope narrowly or use sub-agents.

---

Sessions and Memory

Reference: Memory

4.1 Sessions

Each session is an independent conversation tied to your current directory. Sessions save locally and can be resumed.

Action	Command
Resume most recent	claude --continue
Pick from recent sessions	claude --resume
Fork a session	claude --continue --fork-session
Rename a session	/rename

4.2 Checkpoints

Before every file edit, Claude snapshots the current state. Press Esc + Esc or run /rewind to restore a previous state (conversation, code, or both).

Checkpoints only track changes made by Claude, not external processes. This is not a replacement for git.

4.3 Memory Types

Auto Memory -- Claude automatically saves learnings (patterns, commands, preferences) to ~/.claude/projects/<project>/memory/MEMORY.md. The first 200 lines are loaded each session.

CLAUDE.md Files -- You write and maintain these. Loaded in full at session start.

4.4 Memory Best Practices

• Be specific: "Use 2-space indentation" not "Format code properly"
• Use structure: bullet points grouped under descriptive headings
• Review periodically as your project evolves
• Use /memory to open any memory file in your editor

---

Rules and Permissions

Reference: Permissions | Modular Rules

5.1 Permission System

Tool Type	Example	Approval Required
Read-only	File reads, Grep	No
Bash commands	Shell execution	Yes
File modification	Edit/write files	Yes

Rules are evaluated in order: deny → ask → allow. Deny always wins.

5.2 Permission Modes

Cycle with Shift+Tab:

Mode	Behavior
Default	Asks before edits and commands
Auto-accept edits	Edits without asking, still asks for commands
Plan mode	Read-only tools only, creates a plan for approval

5.3 Permission Rules

Configure in .claude/settings.json:

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

A more comprehensive example of common permission rules can be found here

5.4 Modular Rules with .claude/rules/

Organize instructions into focused rule files:

.claude/rules/
├── code-style.md      # Code style guidelines
├── testing.md         # Testing conventions
└── security.md        # Security requirements

All .md files in .claude/rules/ are automatically loaded. Rules can be scoped to specific file paths using YAML frontmatter:

---
paths:
  - "src/api/**/*.ts"
---
# API Rules
- All endpoints must include input validation

---

Skills

Reference: Skills

6.1 What Is a Skill?

A skill is a SKILL.md file with instructions that extend what Claude can do. Claude applies skills automatically when relevant, or you invoke them directly with /skill-name.

6.2 When Is It Used?

• By Claude automatically -- when the task matches the skill's description
• By you manually -- via /skill-name with optional arguments

Example use cases:

• /fix-issue 1234 -- fetch a GitHub issue and implement the fix end-to-end
• /deploy staging -- run a repeatable deployment checklist
• /review-pr -- enforce team code-review standards on the current diff
• Background knowledge skills (e.g., API conventions, legacy system context) that Claude applies automatically without you invoking them

6.3 How to Create a Skill

Create a directory with a SKILL.md in .claude/skills/:

.claude/skills/fix-issue/
└── SKILL.md

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Fix GitHub issue $ARGUMENTS:
1. Use `gh issue view` to get details
2. Search the codebase for relevant files
3. Implement the fix
4. Write and run tests
5. Commit and create a PR

Run with /fix-issue 1234.

See more here: Antrophic: The Complete Guide to Building Skills for Claude

6.4 Supporting Files

Reference: Add Supporting Files

A skill directory can contain more than just SKILL.md. You can add templates, examples, reference docs, and scripts that Claude loads on demand:

my-skill/
├── SKILL.md           # Main instructions (required)
├── reference.md       # Detailed API docs (loaded when needed)
├── examples.md        # Usage examples (loaded when needed)
└── scripts/
    └── helper.py      # Utility script (executed, not loaded)

Reference these files from SKILL.md so Claude knows when to load them:

## Additional resources
- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

Keep SKILL.md under 500 lines and move detailed content to supporting files.

Security warning: Supporting files can include executable scripts that Claude will run. If you copy a third-party skill into your project without reviewing its contents, you may be giving Claude permission to execute arbitrary code on your machine.

6.5 Where Skills Live

Location	Scope
~/.claude/skills/	All your projects (personal)
.claude/skills/	Current project (team-shared)

6.6 Invocation Control

Setting	Effect
disable-model-invocation: true	Only you can invoke (e.g., /deploy)
user-invocable: false	Only Claude can invoke (background knowledge)

6.7 Security Concerns

• Skills with disable-model-invocation: true prevent Claude from auto-triggering side effects
• Use allowed-tools in frontmatter to restrict what tools a skill can use
• Review third-party skills before adding them to your project -- inspect all files in the skill directory, not just SKILL.md. Supporting files can contain scripts that Claude will execute
• Be especially cautious with skills that bundle scripts/ directories or use allowed-tools: Bash(*) -- these grant broad execution privileges

---

MCPs

Reference: MCP

7.1 What Is an MCP?

MCP (Model Context Protocol) is an open standard for connecting Claude Code to external tools, databases, and APIs. MCP servers give Claude access to services beyond the terminal.

7.2 Use Cases

• Implement features from issue trackers (Jira, Linear, GitHub)
• Query databases (PostgreSQL, etc.)
• Integrate designs from Figma
• Monitor errors with Sentry
• Automate workflows (Slack, Gmail, etc.)

7.3 When Is It Used?

Whenever Claude needs to interact with an external service that isn't accessible via a CLI tool.

7.4 How to Configure

# Add a remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Add a local stdio server
claude mcp add --transport stdio airtable -- npx -y airtable-mcp-server

# List / manage servers
claude mcp list
claude mcp remove <name>

# Check server status inside Claude Code
/mcp

Scopes:

Scope	Storage	Shared
local (default)	~/.claude.json	No
project	.mcp.json (project root)	Yes (commit to git)
user	~/.claude.json	No (all projects)

7.5 Security Concerns

• Use third-party MCP servers at your own risk
• Be cautious with servers that fetch untrusted content (prompt injection risk)
• MCP tool output can consume significant context -- use /mcp to check per-server costs
• For organizations: use managed-mcp.json to control which servers are allowed

7.6 MCPs vs. Skills

Both extend Claude's capabilities, but they solve different problems:

	Skills	MCPs
What they are	Markdown instructions + optional scripts/files	External server processes exposing tools via a protocol
Best for	Workflows, conventions, repeatable tasks	Connecting to live external services (APIs, databases, SaaS)
Runs where	Inside Claude's existing tools (Bash, Read, Edit, etc.)	In a separate process that Claude calls over stdio/HTTP
Setup	Drop a SKILL.md in a directory -- no runtime dependency	Requires running a server (often via npx, Docker, or a remote URL)
State	Stateless -- instructions re-loaded each invocation	Can maintain state (DB connections, auth sessions, caches)

Rule of thumb: If the task is about how Claude should work (process, conventions, multi-step workflows), use a skill. If the task requires talking to something external (Jira, PostgreSQL, Figma), use an MCP.

---

Hooks

Reference: Hooks Guide

8.1 What Is a Hook?

A hook is a user-defined shell command that executes at specific points in Claude Code's lifecycle. Unlike CLAUDE.md instructions (advisory), hooks are deterministic -- they guarantee the action happens.

8.2 Use Cases

• Auto-format code after every edit
• Block edits to protected files
• Send desktop notifications when Claude needs input
• Re-inject context after compaction
• Log every Bash command Claude runs

8.3 How It Works

Hook Events:

Event	When It Fires
SessionStart	Session begins/resumes/compacts
PreToolUse	Before a tool call (can block it)
PostToolUse	After a tool call succeeds
Notification	Claude needs your attention
Stop	Claude finishes responding
SessionEnd	Session terminates

8.4 Example: Auto-Format After Edits

Add to .claude/settings.json:

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

8.5 Hook Types

Type	Description
command	Runs a shell command
prompt	Sends to a Claude model for yes/no decision
agent	Spawns a sub-agent that can read files and run commands to verify

Configure hooks via /hooks interactive menu or by editing settings files directly.

---

Sub-agents

Reference: Sub-agents

9.1 What Is a Sub-agent?

A sub-agent is a specialized AI assistant that runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a matching task, it delegates to the sub-agent, which works independently and returns results.

9.2 Use Cases

• Preserve context -- keep exploration out of your main conversation
• Enforce constraints -- limit tools a sub-agent can use
• Specialize behavior -- focused prompts for specific domains
• Control costs -- route to faster/cheaper models like Haiku

9.3 Built-in Sub-agents

Agent	Model	Purpose	Tools
Explore	Haiku	Search and analyze codebases	Read-only
Plan	Inherited	Research for planning mode	Read-only
General-purpose	Inherited	Complex, multi-step tasks	All

9.4 How to Create Your Own

Create a markdown file in .claude/agents/ (project) or ~/.claude/agents/ (personal):

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep, Bash
model: sonnet
---

You are a code reviewer. Analyze code and provide specific,
actionable feedback on quality, security, and best practices.

Or use the interactive /agents command to create one.

9.5 Key Configuration

Field	Purpose
name	Unique identifier
description	When Claude should delegate to this agent
tools	Restrict available tools
model	sonnet, opus, haiku, or inherit
permissionMode	Override permission handling
skills	Preload skills into the agent's context
memory	Enable persistent cross-session learning (user, project, or local)

---

Plugins

Reference: Discover Plugins | Create Plugins

10.1 What Is a Plugin?

A plugin bundles skills, hooks, sub-agents, and MCP servers into a single installable unit. Plugins are distributed through marketplaces.

10.2 How to Install

# Browse and install via interactive UI
/plugin

# Install directly
/plugin install plugin-name@marketplace-name

10.3 Notable Official Plugins

Category	Plugins
Code intelligence	typescript-lsp, pyright-lsp, rust-analyzer-lsp, gopls-lsp, etc.
Integrations	github, gitlab, slack, sentry, figma, notion, etc.
Workflows	commit-commands, pr-review-toolkit

10.4 How to Create a Plugin

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # Manifest (name, description, version)
├── skills/               # Skills
├── agents/               # Sub-agents
├── hooks/                # Hook definitions
└── .mcp.json             # MCP server configs

Test locally with:

claude --plugin-dir ./my-plugin

10.5 Security Concerns

• Anthropic does not verify all third-party plugins
• Review plugin source and permissions before installing
• Be cautious with plugins that include MCP servers or hooks with broad access

---

Other Useful Info

Videos

• Anthropic: Mastering Claude Code in 30min
• Anthropic: Claude Code Best Practices

11.2 Programmatic Usage

Reference: Headless Mode

Run Claude Code non-interactively with -p:

# Simple query
claude -p "Explain what this project does"

# Structured JSON output
claude -p "List all API endpoints" --output-format json

# Auto-approve specific tools
claude -p "Run tests and fix failures" --allowedTools "Bash,Read,Edit"

# Continue a previous session
claude -p "Now fix the edge cases" --continue

11.3 GitHub Actions

Reference: GitHub Actions

Use @claude in PR/issue comments to trigger Claude. Setup:

1. Install the Claude GitHub app: github.com/apps/claude
2. Add ANTHROPIC_API_KEY to repository secrets
3. Copy the workflow file to .github/workflows/

Or run /install-github-app inside Claude Code for guided setup.

11.4 IDE Integrations

• VS Code Extension
• JetBrains Plugin

11.5 Troubleshooting

Reference: Troubleshooting

Issue	Solution
Permission prompts too frequent	Use /permissions to allowlist safe commands
Authentication problems	Run /logout, restart, re-authenticate
High CPU/memory	Use /compact, restart between major tasks
Command hangs	Ctrl+C to cancel, close terminal if unresponsive
Search not working	Install system ripgrep, set USE_BUILTIN_RIPGREP=0
General diagnosis	Run /doctor