AI AI Tools Guidebook
AI Tool Tutorials

Claude Code Beginner Guide: Install, First Refactor, Costs (2026)

Install Claude Code, write a CLAUDE.md, run Plan Mode, and ship your first reviewed refactor. Exact commands, plan/cost details, and the beginner mistakes to skip.

Published: Updated: Author: AI Productivity Guide Team 🌐 查看中文版本

TL;DR

Claude Code is Anthropic’s terminal coding agent. Install it (native installer or npm install -g @anthropic-ai/claude-code), then sign in with a Claude Pro, Max, Team, or Enterprise account — the free Claude.ai plan does not include Claude Code (verified June 2026). Don’t open with “clean up the repo.” Instead: write a short CLAUDE.md, run Plan Mode so the agent proposes changes before touching files, then execute one named step at a time and commit after each. Your first session should end with a small reviewed PR, not a 40-file diff you can’t read.

What Claude Code is, and how it differs

Claude Code is a command-line agent that reads, edits, and runs code in your terminal. It runs Anthropic models only — Sonnet 4.6 (the default workhorse) on Pro, plus Opus 4.7 on Max plans. That matters because the mental model is different from inline tools:

ToolWhat it doesBest for
GitHub CopilotInline autocomplete in the editorSingle-line / single-block completion
CursorAI-native IDE; chat + inline editsFile-level edits with a GUI diff
Claude CodeAgent that drives the shell, runs testsMulti-file, multi-step changes

If a single inline completion would do, read agent vs autocomplete first. Reach for Claude Code when the change touches multiple files, needs the agent to run tests, or requires reading the repo before editing — renames across files, dependency upgrades, adding tests to legacy code, scripted refactors. For browser-side prototyping without a terminal, see a deep Claude Artifacts workflow instead.

What it costs (as of June 2026)

There is no per-session API meter when you sign in with a consumer plan — Claude Code is bundled into your subscription and limited by usage caps, not a token bill:

PlanPrice (USD/mo)Includes Claude Code?ModelsRough capacity
Free$0No—Claude.ai chat only
Pro$20 ($17/mo annual)YesSonnet 4.6~40-80 hrs Sonnet/week
Max 5xfrom $100YesSonnet 4.6 + Opus 4.75x Pro
Max 20x$200YesSonnet 4.6 + Opus 4.720x Pro

Usage runs on a 5-hour rolling window with a weekly ceiling on top; Pro gets roughly 40-80 hours of Sonnet 4.6 per week (heavy refactors burn faster than light edits). Opus 4.7 is reserved for Max plans. If you’d rather pay per token, you can authenticate against the Anthropic API or Amazon Bedrock / Google Vertex instead — at API rates, Opus 4.7 is $5 in / $25 out per 1M tokens and Sonnet 4.6 is $3 / $15. See the official Claude Code overview and Anthropic pricing for current figures.

Before you start

  • Check requirements. Claude Code needs macOS 13.0+, Windows 10 (1809+), or Ubuntu 20.04+/Debian 10+, with 4 GB+ RAM. The npm route additionally needs Node.js 18 or later; the native installer ships its own binary and skips Node entirely.
  • Get the repo green. Tests pass, lint passes, you can build. Claude Code amplifies whatever state the repo is in — including breakage.
  • Pick a small, low-risk target. Rename a poorly named function, add tests to one module, port one file to a new pattern. Not the whole codebase.
  • Commit or stash your current work so the agent’s diff is unambiguous against a clean baseline.

Step by step: setup to first PR

  1. Install. Native installer is now the recommended path: 
    curl -fsSL https://claude.ai/install.sh | bash
    On Windows PowerShell use irm https://claude.ai/install.ps1 | iex. Prefer npm? Run npm install -g @anthropic-ai/claude-code (never with sudo). Then confirm with claude --version, and run claude doctor if anything looks off.
  2. Sign in. Run claude in your project folder and follow the browser login. Use your Pro/Max account; the free tier is rejected here.
  3. Generate a CLAUDE.md. Inside the session, run the /init slash command — Claude scans the repo and drafts a CLAUDE.md with build/test commands and conventions. Edit it down to the essentials: language/framework, test command, lint command, and paths the agent must not touch. See AI coding context management for what belongs there. Even a 20-line file changes session quality dramatically.
  4. Enter Plan Mode before any edit. Press Shift+Tab to cycle the permission mode to plan (the cycle is default → acceptEdits → plan), or start the session with claude --permission-mode plan. In Plan Mode the agent is read-only: it can search and analyze but cannot write files until you approve.
  5. Ask plan-first. A concrete prompt beats “clean up the repo”: 
    Plan a refactor of src/auth.ts: extract JWT validation into its
own module. Do not write code yet. List files to change, new files
to create, and tests to add.
    New to the repo? Do a workflow for AI codebase tours first so you know what you are refactoring.
  6. Review the plan, then push back. Look for files the agent should not touch, missing test updates, or scope creep. Reply plainly: “Don’t change database.ts — that’s out of scope.”
  7. Execute one named step at a time. Approve a single change, run tests, commit, then move on. The unit of safety is a clean commit, not a whole task.
  8. Close the loop. Ask the agent to summarize what changed and what’s still incomplete, and paste that into your PR description.

First-run exercise (20 minutes)

  1. Pick one smelly function in one file — too long, unclear name, no tests.
  2. Ask Claude Code to add tests for the current behavior first. Run them; confirm they pass.
  3. Now ask for a small named refactor: “split this function into validate / transform / save.” Run the tests again; they should still pass.
  4. Commit. Note what worked, what surprised you, and any prompt worth keeping in CLAUDE.md.

Quality check after each session

  • Run the test suite after every agent step. A clean run is your only objective signal the change is safe.
  • Read the diff line by line for your first three sessions. After you trust the agent on a pattern you can skim; before that, read.
  • Watch for edits outside scope — git diff main to confirm the blast radius.
  • Re-read CLAUDE.md and add the one constraint you wish you’d written before this session. When the agent makes the same mistake twice, add a forbidden rule.

FAQ

  • Do I need a paid plan to use Claude Code?: Yes. As of June 2026 the free Claude.ai plan does not include Claude Code. The cheapest path is Claude Pro at $20/mo (or $17/mo billed annually), which runs Sonnet 4.6; Opus 4.7 requires a Max plan ($100 or $200/mo).
  • How is Claude Code different from Cursor?: Cursor is an AI-native IDE with inline edits; Claude Code is an agent that drives your shell and runs tests. Different ergonomics — see Claude Code vs Cursor.
  • Can I use it without a CLAUDE.md?: Yes, but quality drops fast on real projects. Run /init once and trim the result; even a 20-line file helps.
  • Will it run destructive commands?: By default it asks before running anything risky. Stay out of full auto-accept for the first sessions and review every command.
  • What if the agent stalls or hits a limit?: Cancel, narrow the scope, and restart. On a “Claude is at capacity” message, don’t spam retry — it can lengthen the cooldown (Claude retry rate limit).
  • Which model should a beginner use?: Stick with the Pro default (Sonnet 4.6) for everyday refactors. Reach for Opus 4.7 (Max plans) only for harder architectural reasoning where the extra capacity earns its cost.

Common mistakes

  • Skipping Plan Mode and asking for code immediately — you get a diff you can’t review.
  • No CLAUDE.md — the agent reinvents your conventions and style guide every chat.
  • Letting it commit unreviewed — even a good diff hides one quiet wrong line.
  • Asking for too-big tasks (“refactor the whole module”) instead of named small steps.
  • Spamming retry on “Claude is at capacity” — that can lengthen the cooldown (Claude retry rate limit).
  • Treating Claude Code as authoritative on architecture — it executes fast but is weaker on “should we do this at all.”

Tags: #AI coding #Tutorial #Claude Code

Related Articles