Claude Code: Overview

1. Intro — Why & What

The Problem Claude Code Solves

Modern software development suffers from context-switching hell. Developers jump between their IDE, documentation, Stack Overflow, terminal windows, and project management tools — losing up to 23 minutes per interruption to regain focus. Meanwhile, codebases grow beyond any single developer’s comprehension, with critical logic buried across thousands of files.

Agentic coding means giving an AI assistant the autonomy to:

• Navigate your entire codebase
• Make multi-file edits atomically
• Run tests and iterate on failures
• Execute terminal commands with your permission
• Maintain context across hours-long sessions

According to Anthropic’s announcement, September 29, 2025, Claude Sonnet 4.5 is “the best coding model in the world” and “handles 30+ hours of autonomous coding.” This isn’t hyperbole — it’s backed by benchmark data:

• SWE-bench Verified: 77.2% (measuring real-world software engineering tasks)
• OSWorld: 61.4% (real-world computer interaction, leading the benchmark

What’s New with Claude Sonnet 4.5

1. Enhanced reasoning: Substantial improvements in domain-specific reasoning (finance, law, medicine, STEM)
2. Better alignment: Reduced concerning behaviors like sycophancy and deception
3. Improved security: Enhanced prompt injection defense
4. Efficient tool execution: More reliable command execution and error recovery
5. Context awareness: Tracks its own token budget throughout conversations

Fun fact: Claude Sonnet 4.5’s 30+ hour autonomous coding capability means it can potentially work through an entire sprint without human intervention, though you’ll want checkpoints along the way.

2. Claude Code Overview

What Is Claude Code?

Claude Code is “an agentic coding tool that lives in your terminal and helps you turn ideas into code faster than ever before”. Unlike code completion tools, Claude Code is a full agent that:

• Edits files directly across your entire project
• Runs commands (tests, builds, git operations)
• Plans before acting in optional “plan mode”
• Creates commits with AI-generated messages
• Navigates codebases using grep, file search, and semantic understanding
• Integrates with external tools via MCP (Model Context Protocol)

CLI Capabilities

The command-line interface is the primary way to use Claude Code:

Basic Commands:

# Start interactive REPL
claude

# Start with initial prompt
claude "Add user authentication to this Express app"

# Quick query without interactive mode
claude -p "Explain the algorithm in src/utils.js"

# Continue most recent conversation
claude -c

# Resume specific session
claude -r "session-abc123" "Now add rate limiting"

# Update Claude Code
claude update

Key Flags:

• --add-dir: Add additional directories for Claude to access
• --agents: Define custom subagents dynamically
• --allowedTools / --disallowedTools: Control tool permissions
• --output-format json: Output JSON for scripting (e.g., CI/CD pipelines)
• --permission-mode plan: Start in Plan Mode (read-only analysis)
• --max-turns: Limit autonomous iterations
• --verbose: Enable detailed logging

Composable & Scriptable: Claude Code follows Unix philosophy. You can pipe data in:

tail -f app.log | claude -p "Slack me if you see anomalies in this log stream"

3. All Features (with Examples)

Feature 1: Multi-File Editing

What it is: Claude can edit multiple files atomically as part of a single operation, with live diff previews before applying changes.

Why it’s useful: Refactoring often requires coordinated changes across files (e.g., renaming a function, updating its callers, and fixing tests).

Example workflow:

> Refactor the `getUserData` function to use async/await instead of promises. Update all 12 call sites and fix the tests.

Expected output:

• Claude identifies all files containing getUserData
• Proposes changes with diffs for each file
• Shows test updates
• Requests permission: “Accept 4 file edits?”
• Applies changes atomically after approval

Time saved: 15–30 minutes for manual find-and-replace plus test updates.

Feature 2: Planning Mode

What it is: A read-only mode (--permission-mode plan) where Claude analyzes and proposes solutions without making changes (CLI reference).

When to use:

• Complex implementations requiring architecture decisions
• Unfamiliar codebases where you want analysis first
• High-stakes changes where you want a detailed plan before execution

Example workflow:

claude --permission-mode plan
> How would you implement OAuth 2.0 login for this Next.js app? Consider our existing auth middleware and database schema.

Expected output:

• Architectural analysis (files to modify, new files to create)
• Step-by-step implementation plan
• Potential pitfalls identified
• Estimated complexity and testing strategy

Pro tip: Exit plan mode with /edit to switch to editing mode with context preserved.

Feature 3: Checkpoints

What it is: Automatic code state snapshots before each change, allowing instant rollback (announcement, September 2025).

How to use:

• Auto-created: Claude saves state before every file modification
• Rewind: Press Esc twice or use /rewind command
• Browse: /checkpoints shows all saved states

Example scenario:

> Optimize this database query for performance
# Claude applies changes, tests fail
# Press Esc twice to rewind
# Try again: "Optimize but maintain the same result ordering"

Why it matters: Enables ambitious refactors without fear of breaking things irreversibly. As noted in Anthropic’s announcement, “Checkpoints let you pursue more ambitious and wide-scale tasks knowing you can always return to a prior code state.”

Feature 4: Subagents

What it is: Specialized AI assistants with separate context windows, custom prompts, and restricted tool access.

Key benefits:

• Preserve main context: Subagents explore deeply without polluting your primary conversation
• Specialized expertise: Create domain-specific agents (code-reviewer, test-generator, security-auditor)
• Parallel workflows: Main agent builds frontend while backend subagent sets up API

Creating a custom subagent:

# Create .claude/agents/security-reviewer.md
---
name: security-reviewer
description: "Expert security analyst. Reviews code for vulnerabilities, injection flaws, and insecure patterns."
tools: Read, Grep, Glob
model: sonnet-4-5
---

You are a security expert specializing in web application security. When reviewing code:
1. Check for SQL injection, XSS, CSRF vulnerabilities
2. Verify input sanitization
3. Review authentication/authorization logic
4. Flag hardcoded secrets or API keys
5. Assess cryptographic implementations
Provide severity ratings (Critical/High/Medium/Low) and remediation steps.

Invocation:

> Review the authentication module for security issues
# Claude automatically delegates to security-reviewer subagent

Best practices (best practices guide, accessed October 2025):

• Keep subagents focused (single responsibility)
• Limit tool access to minimum necessary
• Version control project-specific agents in .claude/agents/
• Use descriptive names that Claude can match to tasks

Fun fact: Subagents can explore “tens of thousands of tokens” but return only condensed summaries (1,000–2,000 tokens), making them efficient for deep analysis without context window bloat.

Feature 5: Test Generation & Execution

What it is: Claude generates test scaffolding and runs test suites, iterating on failures automatically.

Example workflow:

> Find functions in NotificationsService.swift that aren't covered by tests. Generate unit tests with >90% coverage.

Claude’s process:

1. Uses Grep and Glob to find untested functions
2. Generates test cases with edge cases
3. Runs test suite with Bash tool
4. If tests fail, analyzes errors and refines
5. Iterates until all tests pass

Supported frameworks (inferred from community usage):

• Jest/Vitest (JavaScript/TypeScript)
• pytest (Python)
• JUnit (Java)
• XCTest (Swift)
• RSpec (Ruby)
• Go’s testing package

Time saved: 1–2 hours for comprehensive test suite generation.

Feature 6: Repository-Wide Reasoning

What it is: Claude understands your entire codebase structure, not just individual files.

Example tasks:

# Find architectural patterns
> What design patterns are used in this codebase? Where's the dependency injection configured?

# Trace execution flow
> Trace the login process from frontend form submission to database write

# Find legacy code
> Find all usages of the deprecated `UserService` class. Suggest migration to the new `UserRepository`.

How it works:

• Uses Glob to discover file structure
• Leverages Grep for code search
• Builds mental model of architecture
• Cross-references imports, function calls, type definitions

Context window management: With Sonnet 4.5’s 200K token context window (API docs), Claude can hold ~150,000 words or ~500 average files simultaneously. For larger repos, Claude uses “just-in-time” retrieval (fetching files as needed).

Feature 7: Slash Commands

What it is: Interactive commands that control Claude’s behavior, both built-in and custom (slash commands docs, accessed October 2025).

Built-in commands:

• /clear: Reset context (use frequently between tasks)
• /help: Show available commands
• /config: View current configuration
• /model: Switch models (e.g., /model haiku for faster, cheaper responses)
• /rewind: Revert to previous checkpoint
• /agents: List available subagents

Creating custom slash commands:

# Project-specific: .claude/commands/optimize.md
---
description: "Analyze code for performance bottlenecks"
allowedTools: Read, Grep, Bash
---

Analyze the code in $1 for performance issues:
1. Identify O(n²) or worse algorithms
2. Find unnecessary database queries
3. Detect memory leaks (closures, event listeners)
4. Suggest optimizations with benchmarks

# Usage:
> /optimize src/api/users.ts

Personal commands (shared across all projects):

# ~/.claude/commands/pr-description.md
Generate a pull request description for my recent commits:
- Summarize changes
- List breaking changes
- Suggest test plan
- Format for GitHub markdown

Advanced: Commands support argument placeholders ($ARGUMENTS, $1, $2), bash execution blocks, and file references with @.

Feature 8: Long-Context Behavior

What it is: Claude Sonnet 4.5 maintains coherence across 200K token context windows with “context awareness” (announcement, September 2025).

Context management techniques:

1. Context Editing (context management announcement): “Automatically clears stale tool calls and results from within the context window when approaching token limits. Context editing alone delivered a 29% improvement in performance.”
2. Memory Tool: Stores information outside the context window in a file-based system, persisting across conversations.
3. Progressive Disclosure: Claude starts with file paths/identifiers and loads full content only when needed.

Best practices:

# Clear context between unrelated tasks
> /clear

# For long sessions, periodically summarize
> Summarize our progress so far. What's left to do?

# Use memory for long-horizon tasks
> Remember: We're migrating from Redux to Zustand. All state files should follow the new pattern in stores/example.ts

Token budget awareness: Sonnet 4.5 can “track its remaining context window throughout a conversation,” enabling better context management decisions.

Feature 9: File Creation (Docs, Sheets, Presentations)

What it is: Claude can generate formatted documents, spreadsheets, and presentation files.

Supported formats:

• Markdown (README, documentation, runbooks)
• CSV (data exports, reports)
• JSON/YAML (config files, API responses)
• LaTeX (technical documentation, academic papers)
• HTML/CSS (static sites, email templates)

Example workflow:

> Create a technical runbook for deploying our Next.js app to Vercel. Include environment variables, build steps, rollback procedures, and monitoring checklist. Format as markdown.

Expected output: docs/deployment-runbook.md with structured sections, code blocks, and checklists.

Pro tip: Use with MCP servers to pull data directly:

# With PostgreSQL MCP server configured
> Query our production database for user growth stats (last 90 days). Generate a CSV report with weekly cohorts.

Feature 10: Limits & Boundaries

Token limits (pricing page):

• Context window: 200K tokens (≈150,000 words)
• Output limit: Varies by tier (higher on Max plan: “Higher output limits”)
• Rate limits: Vary by API tier and plan

File system restrictions (security docs, accessed October 2025):

• Write access: Only the folder where Claude Code was started and subfolders
• Read access: Can read files outside working directory (but requires permission)
• Cannot modify: Parent directories without explicit permission

Command blocklist (default):

• curl, wget (arbitrary web content fetching)
• Other risky commands configurable via settings

Performance characteristics (observed, not officially documented):

• Typical speed: 2–3 seconds per response for simple queries
• Multi-file edits: 10–30 seconds depending on file count
• Test generation: 30–60 seconds for comprehensive suites

Best practices for large repos:

• Use .gitignore to exclude node_modules, build/, etc.
• Create project-specific .claude/ directory with focused context
• Break large tasks into smaller subtasks
• Use subagents for isolated modules

4. Context Engineering

Context is your finite resource (Anthropic engineering blog on context, accessed October 2025). The goal: “Find the smallest possible set of high-signal tokens that maximize the likelihood of desired outcome.”

Core Principle: Treat Context as Currency

Don’t bloat context with:

• Entire files when a function signature suffices
• Verbose explanations when examples demonstrate
• Redundant information (DRY applies to prompts too)

Do include:

• Task brief: What you want, why, and success criteria
• Constraints: Performance requirements, compatibility, style guides
• Interfaces: Type definitions, API contracts, database schemas
• Relevant examples: Edge cases, desired patterns

Pattern 1: Rules + Steps + Examples

Structure:

RULES:
- All functions must have TypeScript type annotations
- Use async/await, never callbacks
- Follow existing naming conventions (camelCase for functions, PascalCase for classes)

STEPS:
1. Read the existing UserService.ts to understand patterns
2. Create a new ProductService.ts following the same structure
3. Generate unit tests with >80% coverage
4. Update the dependency injection container in src/di.ts

EXAMPLES:
@filename: src/services/UserService.ts
[Include 20-30 lines showing the pattern to follow]

Why it works: Rules constrain behavior, steps decompose complexity, examples ground abstractions.

Pattern 2: Progressive Revelation

Scenario: Adding a feature to a 500-file monorepo.

Bad approach:

> Add user preferences feature
# Claude flounders, doesn't know where to start

Good approach (progressive):

# Step 1: High-level planning
> We need to add user preferences (theme, language, notifications). Where should this logic live in our architecture?

# Step 2: Schema design
> Design a database schema for user preferences. Here's our existing User model: [paste schema]

# Step 3: Backend implementation
> Implement the preferences API endpoint. Follow the pattern in @src/api/users.ts

# Step 4: Frontend integration
> Create a PreferencesPanel component. Use our existing SettingsLayout and FormInput components.

Benefit: Each step builds on previous context. Claude explores deeply at each stage, then you distill learnings into the next prompt.

Pattern 3: “Thin→Thick” Context

Concept: Start with lightweight identifiers (file paths, function names), load full content only when needed.

Example:

# Thin: Start with file structure
> List all API route handlers in src/api/

# Claude returns: users.ts, products.ts, orders.ts, auth.ts
# Thick: Drill into specific file
> Explain the authentication logic in @src/api/auth.ts. How does it integrate with our JWT middleware?

Why it works: Avoids loading irrelevant files. Claude fetches details on-demand via Read tool.

Pattern 4: Retrieval Hooks with MCP

Scenario: Claude needs information not in your codebase (design specs, product docs, business logic).

Solution: Configure MCP servers to provide “retrieval hooks.”

Example (with Notion MCP server):

# In .claude/mcp-config.json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-notion"],
      "env": {
        "NOTION_API_KEY": "secret_xxx"
      }
    }
  }
}

# Now in conversation:
> Before implementing the new checkout flow, review the product requirements in our Notion wiki (page: "Checkout v2 Spec"). Then implement according to those requirements.

Claude’s process:

1. Calls Notion MCP server to fetch page content
2. Reads requirements (included in context)
3. Implements based on authoritative spec

Benefit: Single source of truth. No copy-pasting docs into prompts.

Pattern 5: Interface Contracts

When to use: Building against existing APIs, database schemas, or type definitions.

Example:

> Implement a new `POST /api/orders` endpoint. Follow this contract:

Request:
{
  "userId": string (UUID),
  "items": Array<{ productId: string, quantity: number }>,
  "shippingAddress": Address
}

Response (201):
{
  "orderId": string,
  "total": number,
  "estimatedDelivery": ISO8601 date
}

Errors:
- 400: Invalid input (missing fields, invalid UUIDs)
- 404: User or product not found
- 409: Product out of stock

Follow the error handling pattern in @src/api/users.ts. Use our existing OrderService for business logic.

Why it works: Explicit contracts prevent ambiguity. Claude knows exactly what to validate, what errors to throw, and what structure to return.

Pattern 6: Architectural Constraints

Scenario: You have non-negotiable technical constraints.

Example:

CONSTRAINTS:
- Must support Node.js 18+ (no bleeding-edge features)
- Zero external API calls in critical path (cache everything)
- Max response time: 200ms (p99)
- Database queries must use our query builder (no raw SQL)
- All user input must be sanitized via our sanitize() utility

Given these constraints, implement a search feature for our product catalog.

Enforcement: Claude will validate proposals against these constraints. If a solution violates a constraint (e.g., requires Node 20 feature), Claude will propose alternatives.

CLAUDE.md: Persistent Context

What it is: A special file Claude loads automatically at startup (best practices guide).

Location options:

1. Project-specific: your-project/.claude/CLAUDE.md
2. Global (personal): ~/.claude/CLAUDE.md

What to include:

# Project: Acme E-Commerce Platform

## Code Style
- TypeScript strict mode enabled
- Prefer functional components (React)
- Use Tailwind for styling (no inline styles)
- All API routes must have OpenAPI/Swagger annotations

## Architecture
- Monorepo structure: /apps (Next.js, mobile), /packages (shared libs)
- State management: Zustand (no Redux)
- Database: PostgreSQL via Prisma ORM
- API: tRPC (type-safe, no REST)

## Testing Standards
- Unit tests: Vitest
- E2E tests: Playwright
- Minimum coverage: 80%
- Tests must be colocated (MyComponent.tsx → MyComponent.test.tsx)

## Review Criteria
Before marking tasks complete:
1. Run `pnpm test` (all tests must pass)
2. Run `pnpm lint` (zero warnings)
3. Update relevant .md docs if public API changed
4. Check bundle size impact with `pnpm analyze`

## Key Files
- Authentication logic: packages/auth/src/jwt.ts
- Database schema: packages/db/prisma/schema.prisma
- API contracts: packages/api/src/contracts/

Pro tip: Use the # key in Claude Code to quickly update CLAUDE.md during sessions (experimental feature).

5. MCP Servers (Model Context Protocol)

What Is MCP?

MCP is “an open-source standard for connecting AI applications to external systems” (modelcontextprotocol.io). Think of it as USB-C for AI — a universal connector between Claude and your tools, data sources, and workflows.

Announced: Anthropic’s announcement describes MCP as solving the problem of “AI assistants trapped behind information silos and legacy systems.”

Core architecture:

• MCP Server: Exposes data or tools (e.g., PostgreSQL database, Slack API, file system)
• MCP Client: Claude Code (or any AI application that speaks MCP)
• Transport: Stdio (local) or HTTP (remote servers)

Three primitives:

1. Resources: Data Claude can read (files, database schemas, API docs)
2. Tools: Actions Claude can invoke (query database, send Slack message, create Jira ticket)
3. Prompts: Pre-defined prompt templates with variables

When to Use MCP

Use MCP when:

• Claude needs real-time data not in your codebase (database records, API responses, Notion docs)
• You want Claude to take actions in external systems (update Jira, send Slack alerts, deploy to Vercel)
• You have proprietary internal tools Claude should integrate with

Don’t use MCP for:

• Static data that can live in CLAUDE.md or project files
• Simple one-time data fetches (just paste it into the prompt)
• Public information Claude can web-search

6. Hacks from Docs & Community

Note: All hacks sourced from official documentation or verified Anthropic resources to ensure accuracy.

Hack 1: Parallel Workflows with Git Worktrees

Source: Best practices guide, accessed October 2025

Problem: You want to work on two unrelated features simultaneously with separate Claude instances.

Solution:

# Create worktree for feature-a
git worktree add ../project-feature-a feature-a

# Create worktree for feature-b
git worktree add ../project-feature-b feature-b

# Run Claude in each directory
cd ../project-feature-a && claude &
cd ../project-feature-b && claude &

# Both instances have isolated contexts, no cross-contamination

Why it works: Each worktree is a separate working directory. Claude instances don’t share context, so you can explore different approaches in parallel.

Hack 2: Headless Mode for CI/CD

Source: CLI reference, accessed October 2025

Use case: Automate code reviews, test generation, or documentation updates in GitHub Actions.

Example GitHub Action:

name: Claude Code Automation
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Generate PR review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "Review this PR for security issues and code quality. Output JSON." \
            --output-format json > review.json
      - name: Post review comment
        uses: actions/github-script@v6
        with:
          script: |
            const review = require('./review.json');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: review.summary
            });

Pro tip: Use --max-turns 3 to limit autonomous iterations in CI (avoid runaway token usage).

Hack 3: Pipe Log Streams for Real-Time Monitoring

Source: CLI overview, accessed October 2025

Scenario: You want Claude to monitor application logs and alert on anomalies.

# Monitor logs in real-time
tail -f /var/log/app.log | claude -p "Watch this log stream. If you see ERROR or 5xx status codes, summarize the issue and suggest investigation steps. Alert me via Slack (use MCP server)."

# Works with any streaming source
kubectl logs -f pod/my-app | claude -p "Monitor for OOMKilled or CrashLoopBackOff events"

Limitation: Claude Code doesn’t persist across restarts, so this is best for ad-hoc monitoring sessions.

Hack 4: Visual Iteration with Screenshots

Source: Common workflows, accessed October 2025

Workflow:

1. Paste design mockup or screenshot into Claude Code
2. Ask Claude to implement UI to match
3. Take screenshot of your implementation
4. Paste back to Claude: “Compare my implementation to the design. What’s different?”
5. Iterate until pixel-perfect

Example:

> [Paste design mockup]
> Implement this UI using Tailwind CSS and React

# After implementation:
> [Paste screenshot of your implementation]
> Compare this to the original design. Fix spacing, colors, and typography to match exactly.

Pro tip: Use browser DevTools to take full-page screenshots for long pages.

Hack 5: The # Key for Quick Context Updates

Source: Best practices guide

Feature: Experimental shortcut to update CLAUDE.md mid-session.

Usage:

# During conversation, press #
# Claude opens CLAUDE.md for editing
# Add new rule: "Never use 'any' type in TypeScript"
# Save and continue

# Future responses will respect the new rule

Why it matters: Allows you to refine instructions based on Claude’s behavior without restarting the session.

Hack 6: Extended Thinking Mode (Tab Key)

Source: Common workflows

When to use: Complex architectural decisions, algorithm design, system tradeoffs.

How:

> [Press Tab to toggle extended thinking mode]
> Design a caching strategy for our API. Consider: Redis vs in-memory, cache invalidation, cold start performance, cost tradeoffs.

# Claude shows extended reasoning process before answering
# You see the "thinking" step-by-step

Benefit: Transparency into reasoning helps you catch flawed assumptions early.

Hack 7: Reference Multiple Files with @

Source: Common workflows

Syntax:

> Compare the authentication logic in @src/api/auth.ts with the pattern in @src/api/users.ts. The auth file should follow the same error handling approach.

# Claude reads both files, compares patterns, refactors auth.ts

Advanced: Reference directories:

> Review all files in @src/api/ for consistent error handling

Pro tip: Use with glob patterns for bulk operations:

> Add JSDoc comments to all functions in @src/utils/**/*.ts

7. Resources & Citations

1. https://www.anthropic.com/news/claude-sonnet-4-5
2. https://docs.claude.com/en/docs/claude-code/overview
3. https://docs.claude.com/en/docs/claude-code/setup
4. https://docs.claude.com/en/docs/claude-code/cli-reference
5. https://docs.claude.com/en/docs/claude-code/common-workflows
6. www.anthropic.com/engineering/claude-code-best-practices
7. https://docs.claude.com/en/docs/claude-code/security
8. https://docs.claude.com/en/docs/claude-code/slash-commands
9. https://docs.claude.com/en/docs/claude-code/sub-agents
10. https://www.anthropic.com/news/enabling-claude-code-to-work-more-autonomously
11. https://modelcontextprotocol.io
12. https://www.anthropic.com/news/model-context-protocol
13. https://registry.modelcontextprotocol.io
14. https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices
15. https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
16. https://www.anthropic.com/news/context-management
17. https://www.anthropic.com/news/automate-security-reviews-with-claude-code