The Complete Guide to Claude Code: Build Smarter, Ship Faster

Claude Code is not just another AI coding assistant — it's an agentic development environment that lives in your terminal, understands your entire codebase, and autonomously executes tasks ranging from bug fixes to full feature builds. Whether you're a solo developer or part of an enterprise team, Claude Code fundamentally changes how software gets written.

This guide covers everything: installation, IDE integration, CLAUDE.md, advanced features like MCPs, Agents, and Skills, plus two real-world use cases showing Claude Code in action.

---

What is Claude Code?

Claude Code is a CLI (Command Line Interface) tool built by Anthropic that turns your terminal into an intelligent coding partner. Unlike tools that just generate code snippets for you to paste in, Claude Code:

• Reads your actual codebase and understands context deeply
• Executes terminal commands, installs packages, and manages git
• Edits multiple files simultaneously across an entire project
• Delegates complex sub-tasks to specialized sub-agents
• Connects to external tools and services via MCP integrations
• Remembers your project's rules and conventions via CLAUDE.md

Think of it as having a senior engineer sitting next to you who can read every file in your project, autonomously work through a task list, and ask for permission before doing anything risky.

---

Part 1: Getting Started with Claude Code

System Requirements

Before installing, make sure you have:

• macOS 10.15+, Ubuntu 20.04+, or Windows 10+ (via WSL or Git Bash)
• At least 4 GB RAM
• An active internet connection
• A Claude account (Pro, Max, or API access via console.anthropic.com)

Installation

Open your terminal and run the following:

bash
1# macOS and Linux
2curl -fsSL https://claude.ai/install.sh | bash
3
4# macOS via Homebrew
5brew install --cask claude-code
6
7# Windows (PowerShell)
8irm https://claude.ai/install.ps1 | iex
9
10# npm (alternative)
11npm install -g @anthropic-ai/claude-code

Important: If installing via npm, never use sudo. It creates permission conflicts down the line.

Verifying Your Installation

Once installed, verify everything is working correctly:

bash
1claude doctor

This command checks your installation type, version, system configuration, and reports any issues.

Authentication

When you run claude for the first time, it will ask you to authenticate. You have three options:

1. Claude Pro/Max Account – Connect your claude.ai subscription. Best for individual developers who want predictable monthly pricing.
2. API (Console) – Connect via console.anthropic.com for usage-based billing. Ideal for teams or heavy users.
3. Enterprise – AWS Bedrock, Google Vertex AI, or Microsoft Foundry for enterprise deployments.

Starting Claude Code in Your Project

Navigate to your project folder and launch Claude Code:

bash
1cd my-project
2claude

This opens an interactive REPL (Read-Eval-Print Loop) scoped to your project directory. Claude can now see and interact with every file in that folder.

---

Part 2: Using Claude Code via Command Line

The Three Chat Modes

Once inside Claude Code, you can cycle between three distinct modes using Shift+Tab:

1. Default Mode

Claude suggests changes, waits for your approval, and then executes. This is the safest mode for beginners. Every edit is confirmed before it happens.

bash
1> Add input validation to the login form
2# Claude shows you the proposed changes → you approve → it executes

2. Auto Mode (Agentic Mode)

Claude works autonomously — editing files, installing packages, and completing tasks without asking for permission at each step. Perfect for larger feature builds where you want to "set it and go."

bash
1> Build a complete REST API for user authentication with JWT
2# Claude plans, executes, tests — all autonomously

To allow specific bash commands without prompting, use:

bash
1/permissions

For full auto-pilot (use with caution in trusted environments):

bash
1claude --dangerously-skip-permissions

You can always press Esc to stop Claude mid-task.

3. Plan Mode

Before touching any code, Claude activates extended thinking to create a comprehensive strategy. This is the mode to use for new features, complex refactors, or new projects. Claude will ask clarifying questions and produce a Plan.md file with the full strategy.

bash
1> [Switch to Plan Mode via Shift+Tab]
2> I want to build a multi-tenant SaaS billing system
3# Claude asks questions → creates plan → saves to Plan.md

Essential CLI Commands

Useful Slash Commands Inside REPL

Piping Input to Claude Code

Claude Code works natively with Unix pipes, making it powerful in shell scripts and CI/CD pipelines:

bash
1# Analyze logs
2cat error.log | claude -p "identify the root cause of these failures"
3
4# Generate documentation
5claude -p "generate a README for this project" > README.md
6
7# Code review via diff
8git diff | claude -p "review this diff for bugs and security issues"

---

Part 3: Using Claude Code with IDEs

Claude Code integrates seamlessly with popular IDEs, so you don't have to choose between your editor and your AI agent.

VS Code Integration

Install the official Claude Code extension from the VS Code marketplace. Once installed:

• A Claude Code panel appears in your sidebar
• You can open Claude Code terminal instances directly in VS Code
• Run multiple Claude Code instances in parallel in split panes (useful for working on different parts of your codebase simultaneously)

Cursor Integration

Cursor users can install the Claude Code extension the same way. Many developers use a hybrid workflow:

• Claude Code for full agentic tasks (building features, refactoring, debugging)
• Cursor's Command+K for quick inline completions and tab suggestions

This combination is extremely powerful — Claude Code handles the heavy lifting while Cursor handles fast, in-context edits.

Windsurf Integration

Windsurf also supports the Claude Code extension with similar functionality to VS Code.

Workflow Tip

When using Claude Code inside an IDE, you can have Claude work on one area of your codebase in one terminal pane, while you review its changes in the editor. This keeps you in control without slowing down Claude's autonomous work.

---

Part 4: CLAUDE.md — Your Project's Brain

What is CLAUDE.md?

CLAUDE.md is a Markdown file that acts as persistent memory for Claude Code. Every time a new Claude Code session starts in your project, this file is automatically loaded into Claude's context. It stores:

• Project architecture and structure
• Coding conventions and style rules
• Important commands (how to run tests, start the dev server, etc.)
• Team decisions and constraints Claude should always follow
• Database schemas, API structures, and key patterns

Without CLAUDE.md, Claude starts every session without knowing anything about your project. With a well-written CLAUDE.md, it feels like Claude was there from day one.

Creating CLAUDE.md

The easiest way is to let Claude generate it automatically from your existing project:

bash
1cd your-project
2claude
3/init

The /init command makes Claude scan your entire codebase and produce a detailed CLAUDE.md file.

CLAUDE.md Structure and Example

Here is an example of a well-structured CLAUDE.md:

markdown
1# CLAUDE.md
2
3## Project Overview
4This is a SaaS analytics dashboard built with Next.js 14, Supabase, and Tailwind CSS.
5
6## Architecture
7- Frontend: Next.js 14 App Router, TypeScript
8- Backend: Supabase (Postgres + Auth + Storage)
9- Styling: Tailwind CSS with shadcn/ui components
10- State Management: Zustand for global state, React Query for server state
11
12## Commands
13- `npm run dev` — Start development server (port 3000)
14- `npm run test` — Run Jest test suite
15- `npm run lint` — Run ESLint
16- `npm run build` — Build for production
17
18## Coding Conventions
19- Use TypeScript strict mode at all times
20- All components go in /components, all pages go in /app
21- Never use `any` type — always define proper interfaces
22- Use async/await, never raw .then() chains
23- All API routes must validate input with Zod
24
25## Database Schema
26```sql
27users: id, email, name, created_at
28projects: id, user_id, name, description, created_at
29events: id, project_id, name, properties (jsonb), timestamp

Important Notes

• Never commit .env files
• Always run tests before committing
• Use Supabase RLS policies for all database access

### CLAUDE.md Tips

- **Keep it updated** — After major architectural decisions, update CLAUDE.md to reflect them.
- **Be explicit about what NOT to do** — Negative constraints ("never use jQuery") are just as valuable as positive ones.
- **Add team-specific context** — If you have a monorepo, document what each package does.
- **Version it** — CLAUDE.md should live in your git repo so the whole team benefits.

---

## Part 5: Advanced Features

### MCPs — Model Context Protocol

#### What are MCPs?

MCP (Model Context Protocol) is how Claude Code connects to external tools, databases, APIs, and services. Without MCP, Claude can only read/write files and run bash commands. With MCP, Claude can:

- Query your production database in real-time
- Create GitHub issues and review pull requests
- Interact with Slack, Jira, Notion, Linear, or any other tool
- Read from Sentry, Datadog, or any monitoring system
- Talk to any custom internal API

The MCP ecosystem has grown from 100,000 downloads in November 2024 to over 8 million by April 2025 — that's 80x growth in 5 months. There are now over 300 integrations available.

#### Installing MCP Servers

```bash
# Add an MCP server (interactive wizard)
claude mcp add

# Add a specific MCP server directly
claude mcp add sqlite npx '@modelcontextprotocol/server-sqlite@latest'

# Add GitHub MCP
claude mcp add github npx '@modelcontextprotocol/server-github@latest'

# List all connected MCP servers
claude mcp list

# Search the official MCP registry
claude mcp search <keyword>

Popular MCP Integrations

Adding MCP with Authentication

bash
1claude mcp add my-api \
2  --client-id "your-client-id" \
3  --client-secret "your-secret" \
4  npx '@api-mcp-server@latest'

Real-World MCP Example

With GitHub and Sentry MCPs connected, you can say:

bash
1> There's a production error in Sentry. Find the root cause, fix it, and open a pull request.

Claude will read the Sentry error, trace it to the relevant code, write the fix, run tests, and create a GitHub PR — all without you touching anything manually.

---

Agents and Sub-Agents

What are Sub-Agents?

Sub-agents are isolated Claude instances that Claude Code spawns to handle specific sub-tasks. They work in parallel (up to 10 at once), each with a clean context window, and report their results back to the main conversation.

This is powerful because:

• Each agent focuses on one thing without getting confused by unrelated context
• Haiku sub-agents (fast and cheap) handle exploration; Sonnet sub-agents handle implementation
• Parallel agents dramatically speed up large tasks

How Sub-Agents Work in Practice

When you give Claude a complex task, it automatically decomposes it:

Main Task: "Refactor the entire authentication system to use OAuth 2.0"
      │
      ├─→ Explore Agent: Maps the current auth system
      ├─→ Plan Agent: Creates the migration strategy
      ├─→ Implementation Agent: Writes the new OAuth flow
      ├─→ Test Agent: Writes unit and integration tests
      └─→ Review Agent: Checks for security vulnerabilities

Each agent operates independently and returns its work to the main context.

Background Agents

Background agents let Claude keep working even after you close your terminal:

bash
1# Press Ctrl+B to background a running task
2# Your terminal is immediately freed up
3
4# Manage background tasks
5/tasks          # List all running tasks
6/task status abc123   # Check specific task
7/task cancel abc123   # Stop a task
8/task output abc123   # View current output

Or use the & prefix to launch directly as a background task:

bash
1& Run all tests and fix any failures
2& Refactor the payment module to use the new Stripe API

---

Skills (Custom Slash Commands)

What are Skills?

Skills are Markdown files you place in .claude/commands/ that define reusable workflows Claude can run on demand. They let you encode your team's best practices as commands that anyone can invoke with a slash.

Skills are sometimes called "custom slash commands" — they're the same thing.

Creating a Skill

Create the .claude/commands/ directory in your project:

bash
1mkdir -p .claude/commands

Create a skill file, for example .claude/commands/review.md:

markdown
1# Code Review Skill
2
3You are a senior code reviewer. When invoked, perform a thorough review of the specified files or the most recent changes.
4
5## Your review must cover:
61. **Bugs** — Logical errors, edge cases, null pointer risks
72. **Security** — SQL injection, XSS, unvalidated inputs, exposed secrets
83. **Performance** — Unnecessary re-renders, N+1 queries, blocking operations
94. **Readability** — Naming clarity, function length, code duplication
105. **Test coverage** — Missing test cases for critical paths
11
12## Output Format
13For each issue found:
14- **Severity**: Critical / High / Medium / Low
15- **Location**: File and line number
16- **Issue**: Description of the problem
17- **Fix**: Concrete suggestion to resolve it

Now invoke it anytime:

bash
1/review src/auth/login.ts

Example Skill Library

Team Skills

Commit your .claude/commands/ folder to your git repository so every team member gets access to the same skills automatically.

---

Hooks — Deterministic Automation

Hooks are shell commands that execute automatically at specific points in Claude Code's lifecycle, regardless of what Claude decides to do. They guarantee consistency — even if Claude forgets a step, the hook enforces it.

Hook Lifecycle Points

Configuring Hooks

Use the interactive interface:

bash
1/hooks

Or edit ~/.claude/settings.json directly:

json
1{
2  "hooks": {
3    "PostToolUse": [
4      {
5        "matcher": "Edit|Write",
6        "hooks": [
7          {
8            "type": "command",
9            "command": "npm run lint --fix"
10          }
11        ]
12      }
13    ],
14    "Stop": [
15      {
16        "hooks": [
17          {
18            "type": "command",
19            "command": "npm run test"
20          }
21        ]
22      }
23    ]
24  }
25}

The matcher supports exact strings ("Edit") or regex patterns ("Edit|Write").

Real-World Hook Examples

bash
1# Auto-format after every file edit
2PostToolUse → matcher: "Edit|Write" → command: "prettier --write ."
3
4# Run tests after Claude finishes a task
5Stop → command: "npm test"
6
7# Validate no secrets were committed
8PreToolUse → matcher: "Bash" → command: "git-secrets --scan"
9
10# Notify Slack when a big task finishes
11Stop → command: "curl -X POST $SLACK_WEBHOOK -d '{"text": "Claude Code task complete"}'"

---

Plugin System and Marketplace

Plugins are packaged extensions that bundle MCP servers, skills, and hooks into a single installable unit — like npm packages but for Claude Code capabilities.

bash
1# Install a plugin
2/plugins install typescript-lsp
3
4# List installed plugins
5/plugins list
6
7# Update all plugins
8/plugins update

The official Anthropic plugin marketplace launched in December 2025. Community marketplaces are also emerging. Plugins can be auto-updated so your tooling stays current.

---

Memory Management and Context

Context is Claude Code's most precious and limited resource. Managing it well is the difference between Claude that stays focused and one that starts making mistakes.

Context Warning Signs

Context Management Commands

bash
1/compact   # AI-summarizes old context, keeps key decisions
2/clear     # Wipe context entirely, fresh start

Pro tip: Use /clear aggressively. Every time you switch to a new task, clear the chat. Don't carry irrelevant history forward — it eats tokens and degrades quality.

---

Git Integration

Claude Code has first-class git support:

bash
1> Commit all my changes with a descriptive message
2> Create a branch called feature/oauth and push it
3> Review the last 5 commits and write a changelog
4> Find and fix the regression introduced in commit a3f9c2

GitHub PR Reviews

Install the GitHub app via:

bash
1/install-github-app

Claude will automatically review pull requests, flagging real bugs and security issues rather than style nitpicks. Customize the review behavior via claude-code-review.yml in your repo:

yaml
1direct_prompt: |
2  Review this PR for bugs and security vulnerabilities only.
3  Be concise. Only report actual issues, not style preferences.

---

Part 6: Use Case 1 — Building a Beautiful Landing Page

Here is the exact workflow Claude Code follows when tasked with creating a production-ready landing page from scratch.

The Prompt

bash
1cd my-landing-page
2claude

> I want to build a stunning SaaS landing page for an AI writing tool called "Quillify".
> It should have a hero section, features section, pricing section, and a CTA.
> Use Next.js, Tailwind CSS, and make it feel premium — dark theme, glassmorphism effects.

Step 1: Claude Enters Plan Mode

Claude switches to extended thinking and asks clarifying questions:

• What's the target audience? (Marketers, content creators, developers?)
• What's the pricing model? (Free tier + Pro?)
• Any brand colors or inspiration sites?
• Do you want animations? (Framer Motion?)

You answer, and Claude generates a Plan.md:

markdown
1# Quillify Landing Page — Build Plan
2
3## Stack
4- Next.js 14 (App Router)
5- Tailwind CSS + shadcn/ui
6- Framer Motion for animations
7- Deployed on Vercel
8
9## Sections
101. Navigation (sticky, blur backdrop)
112. Hero (headline, subheadline, CTA, animated dashboard mockup)
123. Features (3-column grid with icons)
134. Pricing (3 tiers with toggle monthly/annual)
145. Testimonials (carousel)
156. CTA Banner
167. Footer
17
18## Design Principles
19- Dark theme (#0a0a0a background)
20- Glassmorphism cards (backdrop-blur with border-white/10)
21- Gradient accents (purple to blue)
22- Smooth scroll animations

Step 2: Claude Builds the Project

Claude executes autonomously in Auto Mode:

✅ Initializing Next.js project with TypeScript
✅ Installing Tailwind CSS, shadcn/ui, Framer Motion
✅ Creating /app/layout.tsx with dark theme globals
✅ Building <Navigation /> with blur backdrop
✅ Building <Hero /> with animated gradient headline
✅ Building <Features /> with icon grid
✅ Building <Pricing /> with tier cards and toggle
✅ Building <Testimonials /> carousel
✅ Building <CTABanner /> with gradient background
✅ Building <Footer /> with links
✅ Adding scroll animations with Framer Motion
✅ Making all sections fully responsive
✅ Running npm run build — ✅ No errors

Step 3: Claude Reviews Its Own Work

bash
1/review

Claude runs a multi-perspective review:

• UX Review: Checks CTA visibility, above-the-fold clarity, mobile experience
• Performance Review: Checks image optimization, bundle size, Core Web Vitals
• Accessibility Review: Checks color contrast, ARIA labels, keyboard navigation
• Security Review: No exposed API keys, safe external links

Step 4: Final Delivery

bash
1> Run the dev server and tell me if everything looks correct

Claude runs npm run dev, reads the terminal output, catches any issues, and fixes them automatically. The result is a production-ready, beautifully designed landing page — built without you writing a single line of code.

Total time: ~8 minutes for a full, responsive, animated landing page.

---

Part 7: Use Case 2 — Building an AI Agent

Here is how Claude Code approaches building a production AI agent — in this case, a customer support agent that reads your support tickets, researches answers, and drafts responses.

The Prompt

bash
1cd ai-support-agent
2claude

> Build me an AI customer support agent. It should:
> 1. Read incoming support tickets from a Supabase database
> 2. Understand the issue and search a knowledge base for answers
> 3. Draft a response and send it via email
> 4. Log all actions for human review
> Use the Anthropic SDK, Node.js, and connect to Supabase.

Step 1: Plan Mode

Claude thinks through the architecture:

markdown
1# AI Support Agent — Architecture Plan
2
3## Agent Loop
41. Poll Supabase `tickets` table for new unhandled tickets (every 60s)
52. For each ticket: extract issue category and key entities
63. Search `knowledge_base` table for relevant articles
74. Call Claude API with ticket + context to generate a draft response
85. Send response via SendGrid API
96. Mark ticket as `handled` and log to `agent_logs` table
10
11## Tools the Agent Uses
12- Supabase MCP → read tickets, search knowledge base, write logs
13- SendGrid API → send emails
14- Claude Sonnet 4.6 → generate human-quality responses
15
16## File Structure
17/agent
18  index.js        ← Main agent loop
19  tools/
20    fetchTickets.js
21    searchKB.js
22    sendEmail.js
23    logAction.js
24  prompts/
25    system.md     ← System prompt for the response AI
26  config.js       ← Environment config

Step 2: Claude Builds the Agent

✅ Setting up Node.js project with Anthropic SDK
✅ Installing @supabase/supabase-js, @sendgrid/mail, dotenv
✅ Creating Supabase schema (tickets, knowledge_base, agent_logs tables)
✅ Building fetchTickets.js — polls for unhandled tickets
✅ Building searchKB.js — semantic search on knowledge base
✅ Building sendEmail.js — formats and sends responses
✅ Building logAction.js — logs every agent action
✅ Writing system prompt (prompts/system.md)
✅ Building main agent loop (index.js) with error handling
✅ Adding retry logic for API failures
✅ Writing integration tests
✅ Creating .env.example with all required variables

Step 3: The Agent's Core Loop (Generated by Claude)

javascript
1// agent/index.js — Generated by Claude Code
2import Anthropic from "@anthropic-ai/sdk";
3import { fetchNewTickets } from "./tools/fetchTickets.js";
4import { searchKnowledgeBase } from "./tools/searchKB.js";
5import { sendEmail } from "./tools/sendEmail.js";
6import { logAction } from "./tools/logAction.js";
7
8const client = new Anthropic();
9
10async function processTicket(ticket) {
11  // Search knowledge base for relevant context
12  const context = await searchKnowledgeBase(ticket.issue);
13
14  // Generate response using Claude
15  const message = await client.messages.create({
16    model: "claude-sonnet-4-6",
17    max_tokens: 1024,
18    system: "You are a helpful customer support agent. Use the provided knowledge base context to answer accurately and empathetically.",
19    messages: [
20      {
21        role: "user",
22        content: `Ticket: ${ticket.message}\n\nKnowledge Base Context:\n${context}`,
23      },
24    ],
25  });
26
27  const response = message.content[0].text;
28
29  // Send response and log action
30  await sendEmail(ticket.customer_email, response);
31  await logAction(ticket.id, response, "sent");
32
33  console.log(`✅ Ticket ${ticket.id} handled successfully.`);
34}
35
36async function runAgentLoop() {
37  console.log("🤖 Support Agent is running...");
38  while (true) {
39    const tickets = await fetchNewTickets();
40    for (const ticket of tickets) {
41      await processTicket(ticket);
42    }
43    await new Promise((resolve) => setTimeout(resolve, 60000)); // Poll every 60s
44  }
45}
46
47runAgentLoop();

Step 4: Claude Connects MCP for Live Testing

bash
1claude mcp add supabase-mcp npx '@modelcontextprotocol/server-supabase@latest'

bash
1> Insert a test ticket into Supabase and run the agent to verify it handles it correctly

Claude inserts a test record, runs the agent, monitors the output, verifies the email was sent, and checks the log entry — all autonomously.

Step 5: Production Hardening

bash
1> Add exponential backoff retry logic, rate limiting, and a dead letter queue for failed tickets

Claude adds production-grade resilience patterns without you having to specify the implementation details.

Total time: ~20 minutes for a fully working, production-ready AI support agent.

---

Quick Reference: Claude Code Keyboard Shortcuts

---

Best Practices to Get the Most Out of Claude Code

1. Always start with CLAUDE.md. Run /init on any new or existing project. The more Claude knows about your codebase upfront, the better every interaction will be.

2. Use Plan Mode for big tasks. Whenever you're starting something complex — a new feature, a refactor, a new service — switch to Plan Mode first. Let Claude think before it acts.

3. Clear context often. Use /clear when switching between tasks. Carrying irrelevant history bloats your context and degrades Claude's focus.

4. Invest in Skills. Build a library of .claude/commands/ files for your team's most common workflows — code review, test generation, documentation, security audits. These pay dividends every single day.

5. Set up MCP for your stack. Connect Claude to your database, GitHub, and monitoring tools. Once connected, Claude can debug real production issues rather than working in isolation.

6. Use Hooks for consistency. Auto-linting, auto-testing, auto-formatting — hooks guarantee these happen whether you remember to ask or not.

7. Review everything. Claude Code is remarkably capable, but always review generated code before shipping to production. Use /review to have Claude do a first pass, then do your own review.

---

Conclusion

Claude Code represents a genuine shift in how software gets built. It's not a smarter autocomplete — it's a full agentic development system that can plan, execute, debug, and ship features with a level of autonomy that simply didn't exist two years ago.

Start with the basics: install it, run /init on your project, and build your first CLAUDE.md. Then gradually layer in MCPs, Skills, and Hooks as you get comfortable. Before long, you'll find yourself orchestrating Claude to do the heavy lifting while you focus on what matters most — product decisions, architecture, and the things that actually require a human.

The best developers of the next decade won't just write great code. They'll be great at directing intelligent systems that write great code for them.

Welcome to that future. It's already here.