Claude Code: The Complete Beginner's Guide to AI-Powered Development

If you've been hearing about AI coding assistants but haven't tried Claude Code yet — or you've tried it and feel like you're only scratching the surface — this guide is for you. I'll walk you through everything from installation to advanced workflows, step by step.

By the end, you'll know how to set up Claude Code, plan projects effectively, give it the right context, use memory to build persistent knowledge, leverage agents for complex tasks, and create custom skills to supercharge your workflow.

Part 1: Installation & Setup

System Requirements

Before installing, make sure your system meets these requirements:

OS: macOS 13.0+, Windows 10 1809+, Ubuntu 20.04+, or Debian 10+
RAM: 4 GB minimum
Network: Internet connection required
Account: Anthropic Pro, Max, Teams, or Enterprise account

Installing Claude Code

On macOS or Linux (recommended):

curl -fsSL https://claude.ai/install.sh | bash

On Windows (PowerShell):

irm https://claude.ai/install.ps1 | iex

Using Homebrew (macOS):

brew install --cask claude-code

First Launch & Authentication

Once installed, open your terminal, navigate to your project, and run:

cd /path/to/your-project
claude

Claude will open your browser for authentication. Log in with your Anthropic account and you're ready to go.

IDE Integration

Claude Code works great in the terminal, but it's even better inside your editor.

VS Code: Search "Claude Code" in the Extensions panel (Cmd+Shift+X) and install. You'll get inline diffs, side-by-side file comparisons, and @file references with line numbers.

JetBrains: Go to File → Settings → Plugins, search "Claude Code", and install. Works with IntelliJ, PyCharm, WebStorm, and other JetBrains IDEs.

Key VS Code shortcuts to remember:

| Shortcut | Action | |----------|--------| | Cmd+Esc | Toggle focus between editor and Claude | | Option+K | Insert @-mention with current file and line | | Shift+Enter | New line without sending |

Part 2: Your First Session

Essential Commands

Here are the commands you'll use most:

claude                    # Start interactive session
claude "fix the build"    # One-shot task
claude -c                 # Continue last conversation
claude -r                 # Resume a specific past session

Inside a session, type /help to see all available commands, or press / to browse skills and commands.

Keyboard Shortcuts

These will save you time from day one:

Tab — Command completion
↑ — Cycle through command history
Esc — Stop Claude mid-action (context is preserved)
Esc twice — Open the rewind menu to undo changes
Ctrl+O — Toggle verbose mode to see Claude's thinking
Shift+Tab — Cycle through permission modes

Understanding Permissions

Claude asks for permission before making changes. There are several modes:

| Mode | What Happens | |------|-------------| | Default | Asks before commands and edits | | Accept Edits | Auto-accepts file edits, asks for commands | | Plan Mode | Read-only — creates plans without changing anything | | Bypass | No prompts (only use in isolated environments) |

Toggle between modes with Shift+Tab during a session.

Part 3: Planning — Think Before You Code

This is the most underused and most powerful feature. Always plan before you implement, especially for complex tasks.

How to Use Plan Mode

Press Shift+Tab until you see "plan mode on", or start a session with:

claude --permission-mode plan

In Plan Mode, Claude can only read files and explore your codebase. It can't make any changes. This is perfect for:

Understanding unfamiliar code
Designing an implementation approach
Getting Claude's analysis before committing to a direction

The Four-Phase Workflow

This is the workflow I recommend for any non-trivial task:

Phase 1: Explore (Plan Mode)

"Look through the authentication module and explain how login works."

Claude reads the code, traces the flow, and gives you a clear summary.

Phase 2: Plan (Plan Mode)

"I need to add OAuth2 support. Create a detailed implementation plan."

Claude creates a step-by-step plan with specific files and changes needed.

Phase 3: Implement (Normal Mode)

Switch to Normal Mode with Shift+Tab, then: "Implement the plan."

Claude starts coding based on the approved plan.

Phase 4: Verify

"Run the tests and fix any failures."

Claude runs your test suite and fixes issues.

Pro Tip: Let Claude Interview You

For bigger features, try this prompt:

I want to build [feature description]. Interview me in detail.
Ask about implementation, edge cases, UI/UX, and tradeoffs.
Keep going until we've covered everything, then write a SPEC.md.

Claude will ask clarifying questions and produce a thorough specification before any code is written.

Part 4: Context — Give Claude What It Needs

Context is Claude Code's most important resource. The better the context, the better the output.

What Goes Into Context

Every session, Claude's context window holds:

Your conversation messages
Files Claude reads
Command outputs
CLAUDE.md instructions
Memory from past sessions
Skill definitions

Managing Context Effectively

Check usage: Run /context to see what's consuming your context window.

Clear between tasks: Use /clear when switching to an unrelated task. Don't let context from a debugging session pollute a feature implementation.

Compact manually: Run /compact focus on the API refactor to summarize older messages while keeping specific topics intact.

Quick questions: Use /btw for side questions that don't need to stay in conversation history.

Being Specific in Prompts

The quality of your prompts directly impacts results. Compare:

| Instead of... | Try... | |--------------|--------| | "Fix the login bug" | "Users report login fails after session timeout. Check src/auth/, especially token refresh. Write a failing test first." | | "Add tests for foo.py" | "Write tests for foo.py covering the logout edge case. Don't use mocks." | | "Add a calendar widget" | "Look at HotDogWidget.php to understand the pattern, then implement a calendar widget following the same approach." |

Rich Context Sources

You can feed Claude context in many ways:

@file references — Claude reads the file before responding
Paste images — Screenshots, mockups, error dialogs
URLs — Claude can fetch documentation pages
Stdin — Pipe data: cat logs.txt | claude "find the error"

Part 5: Memory — Build Persistent Knowledge

Memory lets Claude remember things across sessions. There are two memory systems: CLAUDE.md files (you write) and Auto Memory (Claude writes).

CLAUDE.md — Your Project Instructions

Create a CLAUDE.md file in your project root. Claude reads it at the start of every session. Think of it as your project's README for Claude.

# Project Instructions

## Build & Test
- Use `bun` instead of npm
- Run tests with `bun test`
- Build with `bun run build`

## Code Style
- Use 2-space indentation
- Prefer functional components with hooks
- All API routes must validate input with Zod

## Git
- Branch naming: feature/TICKET-description
- Commit messages: conventional commits format
- Always squash merge to main

CLAUDE.md scopes (from broadest to narrowest):

| Scope | Location | When to Use | |-------|----------|-------------| | User | ~/.claude/CLAUDE.md | Personal preferences across all projects | | Project | ./CLAUDE.md or .claude/CLAUDE.md | Shared team instructions (commit to git) | | Subdirectory | ./src/api/CLAUDE.md | Module-specific rules |

Golden rules for CLAUDE.md:

Keep it under 200 lines (longer = reduced adherence)
Be specific: "Use 2-space indentation" not "Format code properly"
Only include what would cause mistakes if removed
Don't include things Claude can figure out from reading the code

Importing Other Files

Reference existing docs with @ imports:

See @README.md for project overview.

# Additional Context
- Git workflow: @docs/git-instructions.md
- API docs: @docs/api-reference.md

Path-Specific Rules

Create rules that only apply to certain files using .claude/rules/:

.claude/
├── CLAUDE.md
└── rules/
    ├── api.md          # Rules for API code
    ├── testing.md      # Testing conventions
    └── frontend/
        └── components.md  # Frontend-specific rules

Add path filters in frontmatter:

---
paths:
  - "src/api/**/*.ts"
---

# API Rules
- All endpoints must include input validation
- Use standard error response format
- Log all requests with correlation IDs

These rules only load when Claude reads files matching those paths.

Auto Memory

Claude automatically saves learnings from your sessions — debugging insights, project patterns, your preferences. This happens in ~/.claude/projects/<project>/memory/.

Run /memory to:

View all loaded memory files
Toggle auto memory on/off
Open the memory folder to edit directly

You can also ask Claude to remember something explicitly:

"Remember that we use PostgreSQL 15 and all migrations must be backwards-compatible."

Part 6: Agents — Delegate Complex Work

Agents (subagents) are separate Claude instances that handle specific tasks with their own context window. This is powerful because they don't consume your main context.

Built-in Agents

Claude comes with several built-in agents:

| Agent | Purpose | Speed | |-------|---------|-------| | Explore | File discovery, codebase search | Fast (Haiku) | | Plan | Research during plan mode | Inherits model | | General-purpose | Complex multi-step tasks | Inherits model |

Claude automatically delegates to these when appropriate. For example, when you ask "find all files that use the auth middleware", Claude spawns an Explore agent rather than searching in the main context.

Creating Custom Agents

Run /agents and select "Create new agent", or create a markdown file manually.

Example: A test runner agent

Create .claude/agents/test-runner.md:

---
name: test-runner
description: Run tests and fix failures. Use after implementing features.
tools: Read, Glob, Grep, Bash, Edit
model: sonnet
maxTurns: 20
---

You are a testing specialist. When invoked:

1. Run the full test suite
2. Analyze any failures
3. Fix the failing tests or the code causing failures
4. Re-run tests to verify fixes
5. Report results

Example: A code reviewer agent

Create .claude/agents/reviewer.md:

---
name: reviewer
description: Review code for quality, security, and best practices.
tools: Read, Glob, Grep
model: opus
---

You are a senior code reviewer. Analyze code changes and provide:

1. Security vulnerabilities
2. Performance concerns
3. Code clarity issues
4. Missing edge cases
5. Suggestions with specific code examples

Key Agent Configuration Options

| Field | What It Does | Example | |-------|-------------|---------| | tools | Restrict available tools | Read, Grep, Glob (read-only) | | model | Choose the model | sonnet, opus, haiku | | maxTurns | Limit execution turns | 20 | | memory | Persistent memory scope | user, project, local | | isolation | Run in git worktree | worktree | | permissionMode | Permission behavior | default, bypassPermissions |

When to Use Agents vs Main Context

Use the main context when:

You need frequent back-and-forth
Context from one step informs the next
You're making small, targeted changes

Use agents when:

The task produces verbose output (test logs, search results)
You need specific tool restrictions
The work is self-contained
You want to explore without polluting your context

Invoking Agents

Claude delegates automatically based on the agent's description. You can also be explicit:

Use the test-runner agent to fix the failing tests.

Or use @-mention syntax:

@"reviewer (agent)" look at the changes in src/auth/

Part 7: Skills — Reusable Workflows

Skills are markdown files that teach Claude domain-specific knowledge or reusable workflows. Think of them as "prompt templates on steroids."

Built-in Skills

| Skill | What It Does | Example | |-------|-------------|---------| | /batch | Parallel changes across many files | /batch migrate all components to TypeScript | | /simplify | Review code for quality | /simplify | | /debug | Troubleshoot current session | /debug | | /loop | Run something on a recurring interval | /loop 5m check deploy status |

Creating Custom Skills

Create a skill file at .claude/skills/deploy-check/SKILL.md:

---
name: deploy-check
description: Check deployment status and verify all services are healthy
user-invocable: true
argument-hint: "[environment]"
---

# Deployment Health Check

Check the $ARGUMENTS environment (default: staging):

1. Run `curl -s https://$ARGUMENTS.example.com/health`
2. Check response status and response time
3. Verify all services report healthy
4. Report any issues found

Now you can run /deploy-check production anytime.

Dynamic Context in Skills

Skills can execute commands and inject the results:

---
name: pr-summary
description: Summarize current PR changes
---

## Current Changes
- Diff: !`git diff main...HEAD`
- Recent commits: !`git log main..HEAD --oneline`

Summarize these changes for a PR description.

The !`...` syntax runs the command before Claude processes the skill content.

Skill Locations

| Scope | Path | Shared? | |-------|------|---------| | Personal | ~/.claude/skills/<name>/SKILL.md | No | | Project | .claude/skills/<name>/SKILL.md | Yes (via git) |

Part 8: Hooks — Automated Guardrails

Hooks are shell commands that run at specific points in Claude's lifecycle. Unlike prompts (which Claude might ignore), hooks always execute.

When to Use Hooks

Use hooks when something must happen with zero exceptions:

Auto-format code after every edit
Block edits to protected files
Get notified when Claude needs input
Re-inject critical instructions after context compaction

Common Hook Recipes

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"
          }
        ]
      }
    ]
  }
}

Get a notification when Claude is waiting for you:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Preserve critical instructions after compaction:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'IMPORTANT: Use bun, not npm. Always run tests before committing.'"
          }
        ]
      }
    ]
  }
}

Hook Events

| Event | When It Fires | |-------|--------------| | SessionStart | Session begins, resumes, or after compaction | | PreToolUse | Before a tool runs (can block it) | | PostToolUse | After a tool succeeds | | UserPromptSubmit | When you send a message | | Notification | When Claude needs attention | | Stop | When Claude finishes responding |

View active hooks anytime with /hooks.

Part 9: MCP Servers — External Integrations

MCP (Model Context Protocol) connects Claude to external tools and services — GitHub, databases, Figma, Sentry, Slack, and more.

Adding an MCP Server

# Remote HTTP server
claude mcp add --transport http github https://api.anthropic.com/mcp/github/

# Local stdio server
claude mcp add --transport stdio postgres npx @mcp-servers/postgres --connection-string "postgresql://..."

Configuration File

You can also configure MCP servers in .mcp.json:

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["@anthropic-ai/claude-code-github-mcp"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

MCP Scopes

| Scope | Location | Applies To | |-------|----------|-----------| | Local | .mcp.json | Current project only | | Project | .claude/.mcp.json | Project + subdirectories | | User | ~/.claude/.mcp.json | All projects |

Once configured, MCP tools appear alongside Claude's built-in tools. You can manage them with /mcp.

Part 10: Advanced Tips & Workflows

Non-Interactive Mode (CI/CD, Scripts)

Run Claude in headless mode for automation:

# One-shot task
claude -p "Find security vulnerabilities in src/" --allowedTools "Read,Grep,Glob"

# Get structured output
claude -p "List all API endpoints" --output-format json

# Continue a previous conversation
claude -p "Now fix the issues you found" --continue

Git Worktrees for Parallel Work

Work on multiple features simultaneously:

claude --worktree feature-auth      # Creates isolated copy
claude --worktree feature-payments  # Another isolated copy

Each worktree gets its own git branch and Claude session.

Extended Thinking

For complex reasoning tasks, enable extended thinking:

Toggle with Option+T (Mac) / Alt+T (Windows/Linux)
Set effort level with /effort — options: low, medium, high, max
Include "ultrathink" in your prompt for one-off deep reasoning
View thinking with Ctrl+O (verbose mode)

The Rewind Safety Net

Made a wrong turn? Press Esc twice or type /rewind to:

Restore conversation to a checkpoint
Restore code to a previous state
Restore both
Claude creates checkpoints before every file edit

Session Management

claude -c              # Continue last session
claude -r              # Browse and resume past sessions
claude /rename "auth"  # Name your session for easy retrieval

Part 11: Common Mistakes to Avoid

| Mistake | Why It's Bad | What to Do Instead | |---------|-------------|-------------------| | Kitchen sink sessions | Multiple unrelated tasks clutter context | /clear between tasks | | Endless corrections | Same issue corrected repeatedly wastes tokens | After 2 failures, /clear and rewrite the prompt | | Overstuffed CLAUDE.md | 500+ lines means instructions get ignored | Keep under 200 lines, move details to skills | | Skipping verification | Plausible but broken code ships | Always provide tests, screenshots, or expected outputs | | Infinite exploration | Claude reads 100 files, context fills up | Scope narrowly or use subagents | | Vague prompts | "Fix the bug" gives vague results | Include symptoms, files, and expected behavior |

Part 12: Putting It All Together

Here's my recommended workflow for a real-world feature:

Step 1: Set Up Your Project

Create CLAUDE.md with build commands, code style, and testing instructions. Run /init for an auto-generated starting point.

Step 2: Plan

Switch to Plan Mode. Describe the feature. Let Claude explore the codebase and create an implementation plan.

Step 3: Implement

Switch to Normal Mode. Tell Claude to implement the plan. It will create files, edit code, and run commands.

Step 4: Test & Debug

Ask Claude to run tests. If anything fails, it debugs and fixes automatically. Use the test-runner agent for complex test suites.

Step 5: Review & Commit

Ask Claude to review the changes, then create a commit with a descriptive message.

Step 6: Learn

After the session, check /memory to see what Claude learned. Update your CLAUDE.md if you discovered new patterns or preferences.

Quick Reference Card

| What You Want | Command | |--------------|---------| | Start Claude | claude | | Plan mode | Shift+Tab | | Clear context | /clear | | Check context usage | /context | | Compact context | /compact | | View memory | /memory | | Manage agents | /agents | | Browse hooks | /hooks | | MCP servers | /mcp | | Settings | /config | | Undo changes | Esc twice or /rewind | | Quick question | /btw | | See all commands | /help | | Resume session | claude -c or claude -r | | Name session | /rename "feature-auth" |

Claude Code is a tool that rewards investment. The more you configure it — with CLAUDE.md files, custom agents, skills, and hooks — the more productive it becomes. Start simple, add complexity as you need it, and remember: plan first, then code.