Claude Code Tutorial: Complete Beginner's Guide 2026

What is Claude Code?

Claude Code is Anthropic’s official command-line interface for Claude. Unlike chat interfaces, Claude Code runs directly in your terminal with full access to your filesystem, can execute commands, edit files, and work autonomously on complex tasks.

Think of it as having a senior developer pair programming with you—one who can read your entire codebase, run tests, fix bugs, and ship features while you focus on higher-level decisions.

Why Claude Code Over Chat?

Feature	Claude Chat	Claude Code
File access	Copy/paste snippets	Full filesystem access
Command execution	None	Run any terminal command
Context	Limited to conversation	Entire codebase
Autonomy	Requires manual steps	Can work independently
Integration	Browser-based	Native terminal + IDE

After using both daily for 6+ months, Claude Code is 5-10x more productive for real development work.

Installation

Prerequisites

• Node.js 18+ (check with node --version)
• npm or yarn
• Anthropic API key (get one here)

Install Claude Code

npm install -g @anthropic-ai/claude-code

Set Your API Key

export ANTHROPIC_API_KEY="sk-ant-..."

Add this to your shell profile (~/.zshrc or ~/.bashrc) to persist it.

Verify Installation

claude --version

You should see output like Claude Code v1.x.x.

Your First Session

Navigate to any project and start Claude Code:

cd ~/my-project
claude

You’ll see an interactive prompt. Try these commands:

> What files are in this project?
> Explain what this codebase does
> Find all TODO comments

Claude Code reads your files, understands context, and responds with actionable insights.

The CLAUDE.md File

This is the most important concept in Claude Code. A CLAUDE.md file in your project root gives Claude persistent instructions about your codebase.

Basic CLAUDE.md Structure

# Project Name

## Overview
Brief description of what this project does.

## Tech Stack
- Framework: Next.js 14
- Database: PostgreSQL
- Deployment: Vercel

## Important Patterns
- We use server components by default
- API routes follow REST conventions
- Tests live next to source files

## Commands
- `npm run dev` - Start development server
- `npm test` - Run test suite
- `npm run build` - Production build

## Do NOT
- Modify files in /legacy (deprecated code)
- Use any packages not in package.json
- Skip TypeScript types

Why CLAUDE.md Matters

Without it, Claude starts fresh every session. With it, Claude:

• Knows your conventions immediately
• Avoids mistakes you’ve documented
• Follows your team’s patterns
• Remembers project-specific context

Real Example from Our Codebase

Here’s a snippet from our production CLAUDE.md:

## Git Workflow
- Commit format: Conventional Commits (feat:, fix:, docs:)
- All commits include Co-Authored-By for AI attribution
- Never push directly to main without PR for non-trivial changes

## Agent Architecture
- Agents are markdown files in .agents/squads/
- Each agent has: purpose, inputs, outputs, instructions
- No microservices—just prompts

This ensures Claude follows our patterns across every session.

Essential Commands

Reading and Understanding Code

> Read src/components/Button.tsx and explain it
> What functions call the authenticate() method?
> Find all files that import from @/lib/db

Writing and Editing Code

> Add a logout button to the header component
> Fix the TypeScript error in api/users.ts
> Refactor this function to use async/await

Running Commands

> Run the test suite and fix any failures
> Build the project and report any errors
> Install lodash and update the imports

Git Operations

> Show me what changed since last commit
> Commit these changes with a descriptive message
> Create a PR for this feature branch

Slash Commands

Claude Code has built-in slash commands for common operations:

Command	Purpose
/help	Show all available commands
/clear	Clear conversation history
/compact	Summarize and compress context
/cost	Show token usage and costs
/doctor	Diagnose configuration issues

Custom Slash Commands

You can create project-specific commands in .claude/commands/:

<!-- .claude/commands/test-and-fix.md -->
# Test and Fix

Run the test suite. If any tests fail:
1. Read the failing test
2. Read the implementation
3. Fix the bug
4. Re-run tests to verify
5. Commit with message "fix: [description]"

Now /test-and-fix runs this workflow automatically.

Hooks: Automate Everything

Hooks run shell commands at specific points in Claude’s lifecycle.

Configure in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'File modification detected'",
            "timeout": 5
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Command completed'",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Practical Hook Examples

Auto-format on file save:

{
  "matcher": "Write|Edit",
  "hooks": [{
    "type": "command",
    "command": "npx prettier --write $CLAUDE_FILE_PATH"
  }]
}

Run tests after code changes:

{
  "matcher": "Edit",
  "hooks": [{
    "type": "command",
    "command": "npm test -- --related $CLAUDE_FILE_PATH"
  }]
}

Sync memory on session start:

{
  "hooks": {
    "SessionStart": [{
      "type": "command",
      "command": "git pull --rebase origin main"
    }]
  }
}

MCP Servers: Extend Claude’s Capabilities

Model Context Protocol (MCP) servers give Claude access to external tools and data.

What MCP Enables

• Database queries (PostgreSQL, MySQL)
• API integrations (GitHub, Slack, Linear)
• File system operations beyond the project
• Custom tools specific to your workflow

Example: GitHub MCP Server

// .claude/mcp.json
{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Now Claude can:

• Create issues and PRs
• Read repository contents
• Manage labels and milestones
• Search across your organization

Building Custom MCP Servers

For custom integrations, create an MCP server:

// my-mcp-server/index.ts
import { Server } from "@anthropic-ai/mcp-sdk";

const server = new Server({
  name: "my-tools",
  version: "1.0.0",
});

server.addTool({
  name: "query_database",
  description: "Run a read-only SQL query",
  parameters: {
    query: { type: "string", description: "SQL query to execute" }
  },
  handler: async ({ query }) => {
    // Your database logic here
    return { results: [] };
  }
});

server.start();

Real-World Workflows

Workflow 1: Bug Fix

> There's a bug where users can't logout. Find and fix it.

Claude will:

1. Search for logout-related code
2. Identify the bug
3. Propose a fix
4. Apply the change
5. Run relevant tests

Workflow 2: Feature Implementation

> Add dark mode support to the settings page.
> Use the existing theme context.
> Include a toggle switch.

Claude will:

1. Read the theme context implementation
2. Understand current patterns
3. Create the toggle component
4. Wire it up to settings
5. Add any necessary styles

Workflow 3: Code Review

> Review the changes in this PR and suggest improvements

Claude will:

1. Run git diff to see changes
2. Analyze code quality
3. Check for bugs or edge cases
4. Suggest improvements
5. Optionally apply fixes

Workflow 4: Documentation

> Generate API documentation for all endpoints in /api

Claude will:

1. Find all API route files
2. Analyze request/response types
3. Generate markdown documentation
4. Include examples

Cost Management

Claude Code uses the Anthropic API, which charges per token.

Monitor Usage

/cost

Shows tokens used and estimated cost for the session.

Reduce Costs

1. Use CLAUDE.md - Reduces repeated explanations
2. Be specific - Vague prompts cause exploration
3. Use /compact - Compresses context when it grows
4. Batch requests - Multiple small asks cost more than one detailed ask

Typical Costs

Task	Tokens	Cost (approx)
Bug fix	10-50K	$0.10-0.50
Feature	50-200K	$0.50-2.00
Refactor	100-500K	$1.00-5.00
Full session	200K-1M	$2.00-10.00

Best Practices

1. Start with Context

Before asking Claude to do anything, ensure it understands:

• What the project does
• What conventions you follow
• What the current state is

2. Be Specific

❌ “Fix the bug” ✅ “Fix the authentication bug where JWT tokens aren’t being refreshed after expiry”

3. Verify Before Committing

Always review changes before committing:

> Show me the git diff before committing

4. Use Checkpoints

For large changes, work incrementally:

> First, create the data model
> [review]
> Now add the API endpoint
> [review]
> Finally, create the UI component

5. Trust but Verify

Claude is powerful but not infallible. Always:

• Run tests after changes
• Review generated code
• Check edge cases

Troubleshooting

”API key not found”

echo $ANTHROPIC_API_KEY  # Should show your key

If empty, set it in your shell profile.

”Permission denied”

Claude Code needs read/write access to your project:

chmod -R u+rw .

“Context too long”

Use /compact to summarize and reduce context, or start a fresh session.

”Tool not available”

Check MCP server configuration:

claude /doctor

What’s Next?

Now that you understand the basics:

1. Create your CLAUDE.md - Start documenting your project conventions
2. Set up hooks - Automate your most common workflows
3. Explore MCP servers - Connect Claude to your tools
4. Build custom commands - Create project-specific workflows

Claude Code transforms how you write software. The investment in setup pays dividends every day.

---

Have questions? Reach out on Twitter or check our engineering articles for more advanced patterns.