ISA-Frontend/claude-code-guide.md

The Complete Claude Code Guide

From Configuration to Mastery

A comprehensive reference for instructions, agents, commands, skills, hooks, and best practices

Compiled from Anthropic Engineering Blog, Official Documentation, and Community Best Practices — November 2025

---

Table of Contents

1. Introduction
2. Part 1: Effective Instructions Through CLAUDE.md
3. Part 2: Commands
4. Part 3: The Agentic Architecture
5. Part 4: Agent Skills
6. Part 5: Hooks
7. Part 6: Best Practices
8. Part 7: Context Engineering
9. Part 8: Advanced Features
10. Conclusion

---

Introduction

Claude Code represents a paradigm shift in AI-assisted development—an agentic command-line tool that provides near-raw model access without forcing specific workflows. Unlike traditional code assistants that offer suggestions, Claude Code follows an autonomous feedback loop: gather context, take action, verify work, and repeat.

This guide synthesizes official Anthropic documentation, engineering blog posts, and community best practices into a comprehensive reference for maximizing productivity with Claude Code. Three key configuration layers determine Claude's behavior:

• CLAUDE.md files for project context
• Hooks for deterministic control
• Skills for modular capabilities

---

Part 1: Effective Instructions Through CLAUDE.md

CLAUDE.md serves as Claude's persistent memory—a special file automatically loaded into context at session start. This file fundamentally shapes how Claude understands and works with your codebase.

The Configuration Hierarchy

Claude loads CLAUDE.md files in a specific precedence order, allowing layered configuration from organization-wide policies down to personal preferences:

Location	Scope	Version Control
/Library/Application Support/ClaudeCode/CLAUDE.md (macOS)	Enterprise-wide	IT-managed
~/.claude/CLAUDE.md	All projects	Personal
./CLAUDE.md or ./.claude/CLAUDE.md	Project-wide	Committed to git
./CLAUDE.local.md	Project-specific personal	Git-ignored
Child directories	On-demand loading	Per-directory

Claude recursively loads CLAUDE.md files from the current working directory up to the root, then pulls in child directory files on-demand when accessing those locations.

Structure and Syntax

A well-crafted CLAUDE.md contains concise, actionable information organized into clear sections:

# Bash commands
- npm run build: Build the project
- npm run typecheck: Run the typechecker
- npm test -- --watch: Run tests in watch mode

# Code style
- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible: import { foo } from 'bar'
- Prefer named exports over default exports

# Workflow
- Always typecheck after making code changes
- Prefer running single tests over the full suite for performance
- Commit logical units of work with descriptive messages

# Architecture
- Frontend: Next.js with TypeScript in /app
- Backend: Node.js with Express in /api
- Database: PostgreSQL with Prisma ORM

Import Syntax

The @path/to/file syntax extends CLAUDE.md's capabilities by referencing external files. Maximum recursion depth is 5 hops.

Example: "For complex usage or if you encounter FooBarError, see @docs/troubleshooting.md for advanced steps."

Critical Anti-Patterns to Avoid

• Don't @-file documentation directly: Embedding entire files bloats context unnecessarily. Instead, provide paths with context: "For complex usage or if you encounter FooBarError, see path/to/docs.md"

• Don't just say "never" without alternatives: Negative-only constraints trap the agent. Always pair prohibitions with preferred approaches: "Never use the --foo flag; prefer --bar instead"

• Keep it concise: Large teams at Anthropic cap their CLAUDE.md files at approximately 13KB. If CLI commands require paragraphs to explain, write a simpler bash wrapper instead—keeping CLAUDE.md concise forces better tooling design.

• Use CLAUDE.md as a forcing function: Keeping it short forces better tooling design.

Quick Memory Feature

• Press # during any session to add memories that Claude automatically incorporates into the appropriate CLAUDE.md file
• Use /memory to view and edit all loaded memories
• Use /init to bootstrap a new CLAUDE.md by having Claude analyze your codebase

---

Part 2: Commands

Claude Code provides extensive command functionality through built-in slash commands and user-definable custom commands.

Essential Built-in Commands

Command	Purpose
/clear	Reset context window—use frequently between tasks
/compact	Compress context while preserving critical information
/context	Visualize current token usage in the 200k window
/init	Generate CLAUDE.md from codebase analysis
/memory	View and edit CLAUDE.md files
/permissions	Manage tool allowlists interactively
/hooks	Configure automation hooks via menu interface
/model	Switch between Claude models (Opus, Sonnet, Haiku)
/rewind	Roll back conversation and code state
/add-dir	Add directories to current session
/terminal-setup	Configure terminal for optimal Claude Code usage
/ide	Connect to IDE for linter integration

Keyboard Shortcuts

Shortcut	Action
Escape	Stop Claude mid-execution
Escape twice	Jump back to previous messages or fork conversation
Shift+Tab	Toggle auto-accept mode (⏵⏵ indicator)
Shift+Tab twice	Activate Plan Mode
Ctrl+V	Paste images
Up arrow	Navigate chat history
#	Add quick memory to CLAUDE.md
@	Tag files with tab-completion

Creating Custom Slash Commands

Store prompt templates as Markdown files in .claude/commands/ (project-scoped) or ~/.claude/commands/ (user-scoped). Commands support frontmatter metadata:

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [message]
description: Create a git commit with the specified message
model: claude-3-5-haiku-20241022
---
Create a git commit with message: $ARGUMENTS

Follow these steps:
1. Run `git status` to check staged changes
2. Review what will be committed
3. Create the commit with the provided message
4. Confirm success

Dynamic variables in custom commands:

• $ARGUMENTS: All arguments passed to the command
• $1, $2, $3: Positional arguments
• @filename: Include file contents
• !command: Execute bash command before processing

Use subdirectories for namespaced organization: .claude/commands/testing/unit.md becomes /project:testing:unit.

💡 Best Practice: Keep slash commands as simple shortcuts, not complex workflows. If you have a long list of complex custom commands, you've created an anti-pattern.

---

Part 3: The Agentic Architecture

Claude Code functions as a fully autonomous agent with access to powerful tools. Understanding this architecture helps you leverage its capabilities effectively.

Core Design Principle

The key design principle behind Claude Code is that Claude needs the same tools that programmers use every day. By giving Claude access to the user's computer via the terminal, it can read files, write and edit files, run tests, debug, and iterate until tasks succeed.

The Agent Feedback Loop

1. Gather Context: Navigate filesystem, read files, use tools to understand the task
2. Take Action: Execute bash commands, edit files, run scripts
3. Verify Work: Run tests, check linting, validate output
4. Repeat: Continue until task is complete

Permission Modes

Mode	Behavior	Activation
Normal	Asks permission for risky actions	Default
Auto-Accept	Executes without confirmation	Shift+Tab toggle
Plan Mode	Research only, no modifications	--permission-mode plan or Shift+Tab×2
Dangerous	Skips all permissions	--dangerously-skip-permissions (containers only)

Extended Thinking Keywords

Claude Code maps trigger words to increasing thinking budgets. Use these progressively for more complex analysis:

"think" < "think hard" < "think harder" < "ultrathink"

Each level allocates progressively more computational budget:

• "think" triggers ~4,000 tokens
• Medium phrases ~10,000 tokens
• "ultrathink" provides maximum analysis depth at ~32,000 tokens

Multi-Agent Patterns

Claude Code excels at multi-agent workflows. Anthropic's internal research shows that multi-agent Claude Opus 4 with Sonnet 4 subagents outperformed single-agent Opus 4 by 90.2% on research evaluations.

The Orchestrator-Worker Pattern

1. A lead agent analyzes the query and develops strategy
2. Subagents spawn in parallel with isolated context windows
3. Each subagent acts as an "intelligent filter," returning condensed findings
4. The lead agent synthesizes results into coherent output

Practical Multi-Claude Workflows

• Writer + Reviewer: One Claude writes code, another reviews—use /clear between or run in separate terminals
• Git worktrees: git worktree add ../project-feature-a feature-a enables parallel sessions on different branches
• Task() feature: Use Claude's built-in Task() to spawn clones of the general agent with isolated context
• Multiple checkouts: Create 3-4 git checkouts in separate folders, run different Claude instances with different tasks

Headless Mode for Automation

Claude Code supports non-interactive execution for CI/CD and scripting:

# Basic execution
claude -p "your prompt here"

# With JSON output for parsing
claude -p "analyze code" --output-format json

# Streaming JSON for real-time processing
claude -p "analyze code" --output-format stream-json

# Continue previous conversation
claude --continue -p "follow up question"

# Resume specific session
claude --resume <session-id> -p "continue task"

---

Part 4: Agent Skills

Skills extend Claude's functionality through organized folders containing instructions, scripts, and resources. Unlike slash commands (user-invoked), skills are model-invoked—Claude autonomously decides when to use them based on task context.

What is a Skill?

A skill is a directory containing a SKILL.md file with organized folders of instructions, scripts, and resources that give agents additional capabilities. Building a skill for an agent is like putting together an onboarding guide for a new hire.

Skill Structure

Skills live in ~/.claude/skills/ (personal) or .claude/skills/ (project). Each skill requires a SKILL.md file with YAML frontmatter:

---
name: generating-commit-messages
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
---

# Generating Commit Messages

## Instructions
1. Run `git diff --staged` to see changes
2. Analyze the nature and scope of modifications
3. Suggest a commit message with:
   - Summary under 50 characters (imperative mood)
   - Detailed description if needed
   - List of affected components

## Best Practices
- Use present tense ("Add feature" not "Added feature")
- Explain what and why, not how
- Reference issue numbers when applicable

The description field is critical—it's the primary signal Claude uses to decide when to invoke a skill.

Progressive Disclosure

Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable. Like a well-organized manual:

1. At startup: Only skill names and descriptions load into context
2. When triggered: Full SKILL.md content loads when the skill is relevant
3. On-demand: Additional referenced files load during execution

This means you can have many skills available without bloating every session's context window.

Skills vs. Slash Commands

Aspect	Slash Commands	Agent Skills
Invocation	User-invoked (/command)	Model-invoked (automatic)
Complexity	Simple prompts, single file	Multiple files + scripts
Use case	Quick shortcuts	Comprehensive workflows
Discovery	Listed in /help	Based on task context

Best Practices for Building Skills

• Start with evaluation: Identify specific gaps in your agents' capabilities by running them on representative tasks and observing where they struggle
• Structure for scale: When the SKILL.md file becomes unwieldy, split its content into separate files and reference them
• Think from Claude's perspective: Pay special attention to the name and description—Claude uses these when deciding whether to trigger the skill
• Iterate with Claude: Ask Claude to capture its successful approaches into reusable context within a skill

---

Part 5: Hooks

Hooks provide deterministic control over Claude Code's behavior through shell commands that execute at specific lifecycle points. While CLAUDE.md offers "should-do" suggestions, hooks enforce "must-do" rules.

Hook Events

Event	Trigger	Can Block?
SessionStart	Session begins	No
SessionEnd	Session ends	No
UserPromptSubmit	User submits prompt	Yes
PreToolUse	Before tool execution	Yes
PostToolUse	After tool completion	No
Stop	Claude completes response	No
Notification	Claude needs user input	No
PreCompact	Before context compaction	No
PermissionRequest	When permission dialog shown	No
SubagentStop	When subagent tasks complete	No

Configuration Structure

Configure hooks in settings files (~/.claude/settings.json, .claude/settings.json, or .claude/settings.local.json):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_FILE_PATHS\" | grep -q '\\.py$'; then black \"$CLAUDE_FILE_PATHS\"; fi"
          }
        ]
      }
    ]
  }
}

Matcher Syntax

• Exact match: "Write" matches only Write tool
• Regex: "Edit|Write" matches either tool
• Wildcard: "*" or "" matches everything
• File patterns: "Write(*.py)" matches Python file writes

Exit Codes

• Exit 0: Success (stdout shown in transcript mode)
• Exit 2: Blocking error (stderr fed back to Claude for correction)
• Other codes: Non-blocking error (stderr shown to user)

Practical Hook Examples

Auto-format TypeScript after edits:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
      }]
    }]
  }
}

Desktop notification when Claude finishes (macOS):

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "osascript -e 'display notification \"Claude has finished!\" with title \"✅ Claude Done\" sound name \"Glass\"'"
      }]
    }]
  }
}

Block dangerous commands:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "if [[ \"$CLAUDE_TOOL_INPUT\" == *\"rm -rf\"* ]]; then echo 'Blocked!' && exit 2; fi"
      }]
    }]
  }
}

Hook Strategies

• Block-at-Submit Hooks: Primary strategy—check state at commit time, forcing Claude into a "test-and-fix" loop until the build is green
• Hint Hooks: Non-blocking hooks that provide "fire-and-forget" feedback for suboptimal behavior

💡 Best Practice: Do NOT use "block-at-write" hooks. Blocking an agent mid-plan confuses it. Let the agent finish its work, then check the final result at commit time.

Security Best Practices for Hooks

• Always quote shell variables: "$VAR" not $VAR
• Validate and sanitize all inputs
• Block path traversal by checking for ..
• Use absolute paths with $CLAUDE_PROJECT_DIR
• Default timeout: 60 seconds per command

---

Part 6: Best Practices

The Explore-Plan-Code-Commit Workflow

This four-phase workflow consistently produces better results than immediate coding:

1. Explore: Ask Claude to read relevant files, images, or URLs—explicitly say "don't write code yet"
2. Plan: Request a plan using thinking keywords ("think hard about the approach")
3. Document: Have Claude create a plan document or GitHub issue as a checkpoint
4. Execute: Implement the solution, then commit and create a PR

Test-Driven Development with Claude

TDD aligns perfectly with Claude Code's verification-oriented nature:

1. Ask Claude to write tests based on expected input/output pairs
2. Have Claude run tests and confirm they fail (no implementation yet)
3. Commit the tests
4. Ask Claude to write code that passes tests without modifying them
5. Use subagents to verify implementation isn't overfitting
6. Commit the working code

Prompting Strategies

Specificity dramatically improves success rates:

Ineffective	Effective
"add tests for foo.py"	"Write a new test case for foo.py, covering the edge case where the user is logged out. Avoid mocks."
"why is this API weird?"	"Look through ExecutionFactory's git history and summarize how its API evolved"
"add a calendar widget"	"Look at HotDogWidget.php for our widget pattern. Follow it to implement a calendar widget with month selection and pagination."

Key Prompting Principles

• Give all context—Claude can't read your mind
• Mention edge cases explicitly
• Reference similar patterns in the codebase
• Provide concrete examples instead of abstract descriptions
• Break large tasks into smaller, verifiable chunks
• Encourage Claude to ask clarifying questions during planning

Context Management

The 200k token context window fills quickly. Monitor with /context and manage proactively:

• Use /clear aggressively between unrelated tasks
• Avoid /compact when possible—auto-compaction is opaque and error-prone
• Document and clear for complex tasks: dump progress to a .md file, /clear, then resume by reading the file
• Fresh monorepo sessions start at ~20k tokens baseline

Common Pitfalls to Avoid

1. Not using /clear enough: Context pollution causes unpredictable behavior
2. Treating Claude like autocomplete: Real power comes from planning first
3. Vague prompts: Specificity dramatically improves success rate
4. Massive one-shot tasks: Break into smaller, verifiable chunks
5. Not giving visual context: Screenshots improve UI work significantly
6. Ignoring the escape key: Course-correct actively rather than letting Claude go down rabbit holes
7. Not staging git changes: Stage early and often as checkpoints
8. Complex custom slash commands: Keep them as simple shortcuts, not replacements for good CLAUDE.md

Configuration for Claude 4.x Models

Claude 4.x models follow instructions more precisely but require explicit requests for "above and beyond" behavior. Add these prompts to CLAUDE.md:

For proactive action:

By default, implement changes rather than only suggesting them. If intent is unclear, infer the most useful likely action and proceed, using tools to discover missing details instead of guessing.

To prevent over-engineering (especially for Opus 4.5):

Avoid over-engineering. Only make changes directly requested or clearly necessary. Don't add features, refactor code, or make "improvements" beyond what was asked. A bug fix doesn't need surrounding code cleaned up.

To minimize hallucinations:

Never speculate about code you have not opened. If the user references a specific file, you MUST read the file before answering. Investigate and read relevant files BEFORE answering questions about the codebase.

---

Part 7: Context Engineering

Context engineering is the natural progression of prompt engineering. While prompt engineering focuses on writing effective prompts, context engineering manages the entire context state including system instructions, tools, external data, and message history.

Why Context Engineering Matters

LLMs, like humans, lose focus at a certain point. This phenomenon is called context rot: as the number of tokens increases, the model's ability to accurately recall information decreases. Context must be treated as a finite resource with diminishing marginal returns.

The Guiding Principle

Find the smallest possible set of high-signal tokens that maximize the likelihood of your desired outcome.

System Prompts: The Goldilocks Zone

System prompts should be extremely clear and use simple, direct language at the right "altitude":

• Too prescriptive: Hardcoding complex if-else logic creates brittle agents
• Too vague: High-level guidance fails to give concrete signals
• Just right: Specific enough to guide behavior, flexible enough to provide strong heuristics

Just-In-Time Context Retrieval

Rather than pre-processing all relevant data up front, agents can maintain lightweight identifiers (file paths, queries, links) and use these references to dynamically load data at runtime.

This approach mirrors human cognition: we don't memorize entire corpuses, but use external organization systems like file systems, inboxes, and bookmarks to retrieve relevant information on demand.

Claude Code uses this hybrid model: CLAUDE.md files are naively dropped into context up front, while primitives like glob and grep allow it to navigate its environment and retrieve files just-in-time.

Techniques for Long-Horizon Tasks

Compaction

Take a conversation nearing the context window limit, summarize its contents, and reinitiate with the summary. The art of compaction lies in selecting what to keep vs. discard:

• Start by maximizing recall to capture all relevant information
• Then iterate to improve precision by eliminating superfluous content
• One safe form: clearing tool calls and results deep in message history

Structured Note-Taking (Agentic Memory)

Regularly write notes persisted outside the context window that get pulled back in when needed:

• Like Claude Code creating a to-do list
• Or your custom agent maintaining a NOTES.md file
• Enables tracking progress across complex tasks

Sub-Agent Architectures

Specialized sub-agents handle focused tasks with clean context windows:

• Each subagent might use tens of thousands of tokens exploring
• But returns only a condensed summary (1,000-2,000 tokens)
• The lead agent focuses on synthesizing results
• Clear separation of concerns keeps the main context clean

---

Part 8: Advanced Features

Code Execution with MCP

Anthropic's code execution with MCP pattern restructures how agents interact with tools. Instead of loading all tool definitions upfront, agents write code to interact with MCP servers, achieving up to 98.7% reduction in token consumption (from 150,000 to 2,000 tokens).

How It Works

Present MCP servers as code APIs in a filesystem structure:

servers
├── google-drive
│   ├── getDocument.ts
│   └── index.ts
├── salesforce
│   ├── updateRecord.ts
│   └── index.ts
└── ... (other servers)

The agent discovers tools by exploring the filesystem, loading only the definitions it needs for the current task.

Benefits

• Progressive disclosure: Load tools on-demand rather than all up-front
• Context-efficient data handling: Filter and transform data in the execution environment before returning to the model
• Privacy-preserving operations: Intermediate results stay in the execution environment by default
• State persistence and skills: Save working code as reusable functions in a ./skills/ directory

Claude Code GitHub Action

The GitHub Action runs Claude Code in a GHA container. You control the entire container and environment, giving you more access to data and stronger sandboxing and audit controls than any other product provides.

Use cases:

• Build custom "PR-from-anywhere" tooling triggered from Slack, Jira, or CloudWatch alerts
• Review GHA logs for common mistakes to create a data-driven improvement flywheel
• Supports all advanced features including Hooks and MCP

Example meta-improvement loop:

$ query-claude-gha-logs --since 5d | claude -p "see what the other claudes were getting stuck on and fix it, then put up a PR"

Sandboxing Features

Claude Code includes native sandboxing with filesystem and network isolation:

• Filesystem isolation: Claude can only access or modify specific directories, preventing prompt-injected Claude from modifying sensitive system files
• Network isolation: Claude can only connect to approved servers, preventing exfiltration of sensitive information
• Activation: claude --sandbox

Both isolation types are needed—without network isolation, a compromised agent could exfiltrate files; without filesystem isolation, it could escape the sandbox and gain network access.

Claude Agent SDK

The SDK that powers Claude Code can power many other types of agents too. Use it for:

• Massive parallel scripting: Write bash scripts that call claude -p "..." in parallel for large-scale refactors
• Building internal chat tools: Wrap complex processes in a simple chat interface for non-technical users
• Rapid agent prototyping: Build and test agentic prototypes before committing to full deployment scaffolding

Settings.json Configuration

Key configurations for advanced users:

• HTTPS_PROXY/HTTP_PROXY: For debugging and fine-grained network sandboxing
• MCP_TOOL_TIMEOUT/BASH_MAX_TIMEOUT_MS: Increase for long, complex commands
• ANTHROPIC_API_KEY: Use enterprise API keys for usage-based pricing
• permissions: Self-audit the list of commands allowed to auto-run

---

Conclusion

Claude Code's power emerges from the thoughtful combination of its configuration systems:

• CLAUDE.md establishes context and preferences, shaping how Claude understands your project
• Hooks enforce deterministic rules, ensuring consistent behavior regardless of how Claude interprets instructions
• Skills provide modular capabilities that Claude invokes autonomously when appropriate
• Commands offer user-triggered shortcuts for common workflows

The key insight from Anthropic's engineering team: start simple, add complexity only when needed. A well-crafted CLAUDE.md file often eliminates the need for elaborate hooks or custom skills. Use the explore-plan-code-commit workflow to prevent Claude from jumping straight to implementation. Clear context frequently. Be specific in your prompts.

Multi-agent workflows represent the frontier of Claude Code productivity, with orchestrator-worker patterns achieving 90% better results than single-agent approaches on complex tasks. As you gain experience, experiment with git worktrees for parallel sessions, headless mode for automation, and the built-in Task() feature for spawning focused subagents.

The tool rewards investment in configuration. The secret isn't in the prompts—it's in the process. Plan first, think appropriately hard, collaborate actively, and teach Claude about your specific context through CLAUDE.md files.

---

Sources

• Anthropic Engineering: Claude Code Best Practices
• Anthropic Engineering: Building Agents with the Claude Agent SDK
• Anthropic Engineering: Equipping Agents with Agent Skills
• Anthropic Engineering: Effective Context Engineering for AI Agents
• Anthropic Engineering: Writing Effective Tools for Agents
• Anthropic Engineering: Code Execution with MCP
• Anthropic Engineering: How We Built Our Multi-Agent Research System
• Claude Code Documentation
• Claude 4.x Prompting Best Practices
• How I Use Every Claude Code Feature - Shrivu Shankar
• Mastering the Vibe: Claude Code Best Practices - Dinanjana Gunaratne

---

— End of Guide —