The Complete Claude Code Guide: From Setup to AI-Powered Dev Workflows (2026)

Claude Code is having its "ChatGPT moment." According to a SemiAnalysis report, 4% of all public GitHub commits are now written by Claude Code, with projections reaching 20% by the end of 2026. Yet most tutorials either stop at "install and say hello" or simply rehash the official docs. This guide draws from my daily experience running Shareuhack to walk you through the full journey, from setup to advanced automation, including cost control and security practices that rarely get covered.

TL;DR

Claude Code is a terminal-native AI dev agent, built for developers who prefer CLI and full codebase control
Real productivity gains come from the combination of CLAUDE.md + Skills + Hooks + MCP, not just "chatting to write code"
Costs are manageable: the Max plan at $100/month works for most people; API usage averages around $6/day
It doesn't compete with Cursor. Use both: Claude Code for architecture and refactoring, Cursor for real-time editing
Security awareness is essential: CVEs disclosed in February 2026 revealed attack vectors through Hooks and MCP

What Is Claude Code? Why It's More Than "Just Another AI Tool"

When most people first hear about Claude Code, they assume it's like GitHub Copilot or Cursor, an autocomplete assistant that lives inside your editor.

It's not. Claude Code is a terminal-native AI development agent. You talk to it in your terminal, and it directly reads your file system, runs terminal commands, modifies code, executes tests, and makes git commits. It's not an assistant embedded in an IDE. It's an agent that can autonomously operate your entire development environment.

The biggest shock when I first switched from Cursor to Claude Code was this: Copilot and Cursor work on a "you write, AI assists" model. Claude Code works on a "you describe what you want, AI does it" model. In practice, I can tell it "add rate limiting to this API, write the tests, confirm they pass, then commit" and go make coffee. When I come back, the work is done.

According to Constellation Research, Claude Code's annualized revenue hit $2.5B in February 2026, doubling since the start of the year. Eight of the Fortune 10 are enterprise Claude customers. This isn't an experimental tool; it's infrastructure that's reshaping how software gets built.

Why is now a good time to get started? Because Claude Code's ecosystem finally matured in early 2026. Skills let you create custom slash commands. Hooks let you automate repetitive actions. MCP (Model Context Protocol) connects it to external services. Sub Agents let you break down complex tasks. Combined, these features transform Claude Code from a chat tool into a full AI development framework.

10-Minute Setup: Getting Started from Scratch

System Requirements

macOS, Linux, or Windows (via WSL2)
Node.js 18+
An Anthropic account (Claude Pro/Max subscription or API Key)

Installation Steps

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Navigate to your project directory
cd your-project

# Launch Claude Code
claude

On first launch, you'll be guided through authentication. You'll see a terminal interface where you can talk to Claude using natural language.

Authentication: Subscription vs API Key

This is the first decision that trips up most newcomers:

	Claude Pro/Max Subscription	API Key
Billing	Fixed monthly fee	Pay per token usage
Price	$20-200/month	Usage-based, ~$6/day average
Cost Predictability	High	Low
Best For	Individual devs, daily use	Light use, CI/CD, teams
Usage Limits	Yes (plan multiplier)	Unlimited (pay as you go)

My recommendation: Start with Pro at $20/month as an individual developer. Upgrade to Max if you need more capacity. Save API Keys for scenarios that require precise cost control (e.g., CI pipelines or shared team usage).

Your First Conversation

After installation, run claude in your project directory and try this:

> Give me an overview of this project's structure, main tech stack, and architecture

Claude Code will automatically read your package.json, tsconfig.json, directory structure, and more, then give you a comprehensive project overview. If it correctly identifies your project, congratulations, you're all set.

Common Installation Issues

Node version too old: nvm install 18 && nvm use 18
Global install permission issues: Use sudo npm install -g or try npx @anthropic-ai/claude-code
Corporate proxy environment: Set the HTTPS_PROXY environment variable

Deep-Diving into CLAUDE.md: Making AI Truly Understand Your Project

CLAUDE.md is Claude Code's most underrated feature. Most tutorials only show you how to run /init to generate a default file, but that's just the starting point.

What Is CLAUDE.md?

CLAUDE.md is a Markdown file that Claude Code reads every time it starts up. Think of it as a "project spec sheet for your AI." It tells Claude about your project conventions, coding style, architectural decisions, and things to avoid.

Three-Layer Architecture

Claude Code supports three levels of CLAUDE.md, merged from top to bottom:

Global (~/.claude/CLAUDE.md): Universal rules that apply to all projects
Project root (./CLAUDE.md): Rules specific to this project
Subdirectory (./src/components/CLAUDE.md): Rules for specific modules

What Should You Write?

The default content from /init is usually too generic. Based on my experience running Shareuhack, an effective CLAUDE.md should include:

Architectural decisions: Tell Claude what framework you use, your routing pattern, and how data flows.

## Tech Stack
- Next.js Pages Router (not App Router)
- Velite for content management
- Primary language: Traditional Chinese, with en/ja support

Coding style conventions: What naming conventions do you prefer? Import order?

## Conventions
- Use TypeScript strict mode
- React components use PascalCase
- No `any` type allowed

Explicit prohibitions: This is more important than telling the AI what to do.

## Prohibited
- Do not auto-commit
- Do not modify .env files
- Do not refactor without tests

Common task patterns: The things you most frequently ask Claude to do.

## Common Tasks
- New article: Create _posts/[slug]/index.zh-TW.md
- New component: Place in components/ directory

Pro tip: CLAUDE.md can also reference other files. For example, See content/content-guideline.md for writing rules. Claude will automatically read the referenced file when needed.

Unlocking Advanced Features: Skills, Hooks, MCP, and Sub Agents

This section covers territory that's almost entirely missing from English-language tutorials. Honestly, it took me two to three weeks to figure out how these four features work together. But once configured, they elevate Claude Code from a "chat tool" to an "AI development framework." The productivity gain is qualitative, not just quantitative.

Skills: Custom Slash Commands

Skills let you package repeatable workflows into slash commands. For example, I built a set of Skills for Shareuhack:

/research [topic]: Launches a market research workflow
/write [slug]: Writes an article based on an outline
/translate [slug]: Translates an article into English and Japanese
/content-review [slug]: Reviews article quality

Each Skill is a Markdown file stored in the .claude/skills/ directory. The format is straightforward:

# Skill Name
Describe what this Skill does.

## Steps
1. Read [a specific file]
2. Execute [a specific operation]
3. Output results to [a specific location]

Claude Code follows the Skill's instructions to automatically execute multi-step complex tasks. Essentially, you're "teaching" your domain expertise to the AI, and next time a single slash command reproduces the entire workflow.

Hooks: Event-Driven Automation

If you're tired of Claude Code constantly popping up permission confirmations, Hooks are the answer.

Hooks let you automatically run scripts when specific events occur. There are four Hook types:

Hook	Trigger	Common Use
PreToolUse	Before Claude uses a tool	Auto-approve specific operations
PostToolUse	After Claude uses a tool	Auto-lint, auto-format
Notification	When Claude sends a notification	Send to Slack/Telegram
Stop	When Claude finishes a task	Auto-run tests

Practical example: Set up auto-linting in .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Now every time Claude modifies a file, ESLint automatically fixes formatting issues.

MCP Servers: Connecting External Services

MCP (Model Context Protocol) is an open protocol from Anthropic that lets Claude Code connect to external tools and services.

Popular MCP Servers:

GitHub MCP: Manage PRs and Issues directly from Claude Code
Sentry MCP: Query error logs and pinpoint bugs
Database MCP: Query databases without leaving the terminal
Slack MCP: Send messages and read channel content

Configuration goes in .claude/settings.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your-token" }
    }
  }
}

Security note: MCP Servers can execute arbitrary operations. Only install servers you trust, and verify their source. More on this in the security section below.

Sub Agents: Multi-Agent Collaboration

Sub Agents let Claude Code spawn subtasks, each with its own independent context. This solves two problems:

Noise isolation: Search results and large datasets don't pollute the main conversation's context
Parallel processing: Multiple independent tasks can run simultaneously

For example, while writing an article, I have Claude Code spawn a Sub Agent for fact-checking while the main conversation continues working on article structure. The Sub Agent returns a concise results table rather than dumping the entire search process into the main context.

This matters for token cost control too: a Sub Agent's context is independent and gets released when it's done, so it doesn't permanently consume the main conversation's context window.

Cost Control in Practice: Max Plan, API, or a Hybrid Approach?

Cost is the most anxiety-inducing topic when developers discuss Claude Code. According to the Claude Code official documentation, developers using the API spend an average of $6/day, with 90% spending under $12/day. But without cost discipline, a complex debug session can easily burn through $100 in an hour.

Plan Overview

	Pro $20/mo	Max 5x $100/mo	Max 20x $200/mo	API (Pay-as-you-go)
Usage Limit	Baseline	5x Pro	20x Pro	Unlimited
Monthly Cost Predictability	High	High	High	Low
Best For	Light/occasional use	Most individual devs	Heavy all-day users	CI/CD, teams, precise control
Claude Code Access	Yes (limited)	Standard	High volume	Full

Source: Claude Pricing Page

Decision Framework: Which Plan Should You Choose?

Using less than 1 hour per day?
  → Pro $20/month (test the waters) or API (pay-as-you-go)

Using 1-4 hours per day?
  → Max 5x $100/month (the sweet spot for most people)

Using it all day?
  → Max 20x $200/month

Team or CI/CD environment?
  → API Key (precise budget allocation and usage tracking)

Monitoring Usage: /cost and /stats

If you're on an API plan, type /cost during a conversation to see your current session's token usage and actual cost. Make it a habit to check after every long session. If you're a Pro/Max subscriber, /cost data isn't relevant to your bill (it's covered by your monthly fee). Use /stats instead to view usage patterns and trends.

5 Practical Tips to Save Tokens

Write a thorough CLAUDE.md: The more precise your instructions, the less back-and-forth the AI needs, which means fewer tokens consumed
Break down large tasks: "Refactor the entire project" burns massive tokens. "Refactor module A" then "refactor module B" is far more efficient
Leverage Sub Agents: Isolate high-token tasks like searching and fact-checking into Sub Agents
Use /compact to compress conversations: Run /compact mid-conversation and Claude will compress the history context
Be explicit about scope: "Only modify the render function in src/components/Header.tsx" is far more precise than "fix the Header"

My Real-World Spending

Running Shareuhack as an example: I'm on the Max plan. A typical workday involves content writing, code changes, SEO optimization, and bug fixes. The monthly cost is a fixed $100 with no risk of a surprise bill from an extended debugging session. For me, cost predictability matters more than absolute cost.

Claude Code vs Cursor: Not Either/Or, But How to Combine Them

"Which is better, Claude Code or Cursor?" is the most frequently asked question. Having used both extensively, my answer is: they're not even the same category of tool.

The Fundamental Difference

Claude Code is a CLI agent: you give it instructions in the terminal, and it autonomously completes tasks. Cursor is an IDE integration: you write code in the editor, and it assists in real time.

According to builder.io's independent benchmark, Claude Code completed the same benchmark tasks using less than one-fifth the tokens of Cursor (33K vs 188K). But that doesn't mean Claude Code is necessarily "better." It means they operate in fundamentally different modes.

Scenario Comparison

Scenario	Claude Code	Cursor
Large-scale refactoring, cross-file changes	Strong	Medium
Real-time inline editing, autocomplete	None	Strong
Terminal operations (git, build, deploy)	Strong	Weak
Visual diff review	Medium	Strong
Automated workflows (Skills/Hooks)	Strong	None
Non-engineer friendliness	Low	High
Starting new projects from scratch	Strong	Medium
Small, precise edits	Medium	Strong

Recommended Workflow

Here's how my daily workflow looks:

Claude Code: Handles architecture-level tasks. For example, "add a new API endpoint with routing, handler, and tests." It creates multiple files at once, runs tests, and confirms they pass.
Cursor: Handles real-time editing. For example, while reviewing code that Claude Code produced, I make small tweaks in Cursor: adjusting names, fixing formatting.

You can run both simultaneously. Claude Code runs in the terminal while Cursor displays file changes alongside it. They don't conflict.

For a deeper dive into how different AI coding tools compare, check out my comprehensive comparison.

Security: Risks You Must Know and How to Mitigate Them

On February 25, 2026, Check Point Research disclosed two serious vulnerabilities in Claude Code. This is essential knowledge before using Claude Code:

Recent CVE Vulnerabilities

CVE-2025-59536 (CVSS 8.7, High): An attacker can place crafted Hooks or MCP configuration files in a malicious repo. When you clone and open that repo with Claude Code, the malicious instructions execute automatically.

CVE-2026-21852 (CVSS 5.3, Medium): Affects versions prior to v2.0.65. A malicious repo can override ANTHROPIC_BASE_URL to exfiltrate API keys before the user confirms trust. Less severe than the above CVE, but still warrants updating.

Both vulnerabilities have been patched by Anthropic. Make sure your Claude Code is up to date: npm update -g @anthropic-ai/claude-code.

Source: The Hacker News

Principle of Least Privilege

Claude Code has three permission modes:

Default: Prompts for confirmation on every risky operation. Safe but verbose
Relaxed: Loosens some restrictions, reducing confirmation popups
--dangerously-skip-permissions: Skips all permission checks. Only use in Docker or sandboxed environments

My recommendation: Use Default or Relaxed for daily work, and pair it with Hooks to auto-approve operations you trust. Never use --dangerously-skip-permissions on your local machine.

Pre-Clone Trust Checklist

Before opening any external repo with Claude Code:

Verify the repo source is trustworthy (official org, well-known developer)
Check the .claude/ directory for suspicious Hooks or MCP configurations
Review CLAUDE.md for suspicious instructions (e.g., shell command execution)
Update Claude Code to the latest version

Sensitive File Protection

Claude Code reads your project files to understand your code, which means it could also access passwords, API keys, and other sensitive data. You need to explicitly tell it which files are off-limits.

The simplest approach: copy the following into .claude/settings.json (create the file if it doesn't exist):

{
  "permissions": {
    "deny": [
      "Read(./.env*)",
      "Read(./secrets/**)",
      "Read(./**/*.pem)",
      "Read(./**/*.key)",
      "Write(./.env*)",
      "Edit(./.env*)"
    ]
  }
}

This configuration blocks Claude from reading any file starting with .env (including .env.local, .env.production), everything inside the secrets/ folder, and all .pem and .key certificate files. Denied files won't even appear in Claude's file listing, eliminating the risk at the root.

Advanced: For finer control (e.g., scanning file contents for AWS keys), you can add Hook scripts. Use exit 2 to return errors so Claude knows it's blocked, and read the JSON from stdin to get the file path. Running Claude Code in a Docker container with your project directory mounted as read-only is the highest security option. Keep real passwords and keys in external tools like 1Password CLI, Doppler, or GitHub Secrets rather than storing them in your project.

For more security best practices, see the AI Agent Security Framework Guide.

Risk Disclosure

Before fully committing to Claude Code, you should be aware of these risks:

Code quality needs verification mechanisms. Claude Code produces good code most of the time, but on real large-scale codebases, it occasionally disconnects linked services, creates duplicate files, or claims a task is complete when it isn't. The fix isn't to simply label it a "junior developer." Instead, build review mechanisms: use Hooks to auto-run tests, use Sub Agents for cross-checking, or pair it with Codex or Cursor for code review. With these safety nets in place, AI completion rates improve significantly.

Usage limits can change. In early 2026, Anthropic abruptly tightened weekly usage limits, causing widespread frustration and cancellations. The "5x" and "20x" in Max plans are multipliers relative to Pro, but Pro's baseline itself isn't fixed.

Vendor lock-in risk. If your entire development workflow deeply relies on Claude Code's Skills and Hooks, switching to another tool won't be cheap. Keep your CLAUDE.md and Skills well-documented for potential future migration.

Privacy considerations. Your code gets uploaded to Anthropic's servers for processing. According to Anthropic's policy, this data isn't used for model training, but if your project involves highly confidential code, this risk needs evaluation.

Learning curve. Setting up Skills, Hooks, and MCP takes time. If you only need basic code completion, Cursor has a much lower barrier to entry. Claude Code's value lies in advanced automation, but that requires upfront investment.

FAQ

Can I use Claude Code and Cursor at the same time?

Yes, they don't conflict at all. Claude Code runs in the terminal, while Cursor is a standalone IDE (based on VS Code). You can have both open simultaneously: Claude Code handles large tasks, Cursor handles real-time editing. Many developers, myself included, use this exact setup daily.

Can a non-technical PM use Claude Code?

Yes, but the experience isn't as friendly as Cursor. Claude Code is a CLI tool, so you need basic terminal skills (cd, ls, etc.). If you have zero terminal experience, start with Cursor. If you know the basics, Claude Code's natural language interface is actually quite PM-friendly. In fact, many things I do with Claude Code, like writing articles, conducting market research, and managing pipelines, don't require writing code at all. Check out how I built a one-person product team with Claude.

Will my code be used to train AI models?

It depends on your plan. Data submitted through API and enterprise plans (Claude for Work) is not used for model training, per Anthropic's commercial terms. For Pro/Max personal subscriptions, it's more nuanced: after the August 2025 policy update, Anthropic asks you to choose whether to allow your data to be used for model training improvements. If you don't respond within the deadline, it's treated as consent. You can check or change this setting anytime in your Privacy Settings. Regardless of plan, your code is uploaded to Anthropic's servers for processing (this is how it works). If your project involves confidential code, consider using the API or enterprise plan.

What are the exact usage limits for Max plans? What happens when you exceed them?

Anthropic doesn't publicly disclose exact token limits for Max plans. They describe it as "5x" or "20x" relative to Pro. When you hit the limit, you'll be unable to use it by default until the limit resets. However, you can enable Extra Usage to automatically switch to pay-as-you-go pricing after exceeding your plan's limits, so you're never cut off.

What programming languages does Claude Code support?

Claude Code supports all major programming languages, including TypeScript, JavaScript, Python, Rust, Go, Java, C++, Ruby, PHP, and more. It's not language-specific because it directly reads your source files and understands their content. In practice, it performs best with TypeScript and Python, as these have the broadest coverage in training data.

Conclusion

Claude Code isn't just another AI coding tool. It's an AI agent framework that can autonomously operate your development environment.

If all you need is code completion, Cursor is sufficient. But if you want to describe requirements in natural language and have AI handle the full workflow, from creating files to running tests, or even build an automated development pipeline, Claude Code is the most mature option available today.

Here's how I'd recommend getting started:

Today: Install Claude Code, try the Pro plan at $20/month
Week 1: Write a thorough CLAUDE.md so Claude truly understands your project
Week 2: Build 1-2 Skills to automate your most frequent tasks
Week 3: Set up Hooks to reduce permission prompts and add security protections
Beyond: Explore MCP Servers and Sub Agents, gradually building your AI development framework

Your first AI-assisted project starts with opening the terminal and typing npm install -g @anthropic-ai/claude-code.