AI AI Tools Guidebook
AI Tool Tutorials

Claude Code Beginner Guide: Setup, First Refactor, and Mistakes to Avoid

What Claude Code is, how to install it, and how to ship your first refactor — the setup steps, prompt patterns, and common beginner mistakes.

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

What this covers

A linear path from “never used Claude Code” to “shipped your first reviewed refactor”, aimed at developers who already write code but haven’t yet handed work to an agent. The pain: people install Claude Code, ask it to “clean up the repo”, get a 40-file diff they cannot review, and lose trust in the tool. This guide forces a slower opening — install, write a tight CLAUDE.md, run a planning prompt, then execute in named steps — so the first session ends with a small clean PR instead of a regret.

Key tools and concepts:

  • Claude Code: Anthropic’s command-line AI coding agent that can read, edit, and run code in your terminal.
  • CLAUDE.md: The project-root memory file Claude Code auto-loads; treats it like a system prompt.
  • Plan mode / planning prompt: Asking the agent to produce a plan before touching code, so you can review intent before diffs.

Who this is for

Developers comfortable with the command line. Especially valuable if you have already used Copilot or Cursor but want agentic multi-step changes — Claude Code is a different mental model. For browser-side prototypes you can iterate on without a terminal, look at a deep Claude Artifacts workflow instead.

When to reach for it

Reach for Claude Code when the change touches multiple files, requires running tests, or needs the agent to read the repo before editing. If a single inline completion would do, see agent vs autocomplete before reaching for Claude Code. Strong fits: renames across files, dependency upgrades, adding tests to legacy code, scripted refactors.

Before you start

  • Have a working dev environment for the project: tests pass, lint passes, you can build. Claude Code amplifies whatever state the repo is in — including breakage.
  • Pick a small, low-risk target for the first run: 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. You want a clean baseline so the agent’s diff is unambiguous.
  • Have a CLAUDE.md ready (template in step 2). Even a 20-line file changes the quality of the first session dramatically.

Step by step

  1. Install per official docs (npm install -g @anthropic-ai/claude-code typically). Run claude --version to confirm.
  2. In the project root, write CLAUDE.md with codebase notes — see AI coding context management for what belongs in that file. At minimum: language/framework, test command, lint command, paths to avoid.
  3. Run claude and ask plan-first: Plan a refactor of src/auth.ts — extract the JWT validation into its own module. Do not write code yet; list files to change, new files to create, and tests to add. If you are new to the repo, do a workflow for AI codebase tours first so you know what you are refactoring.
  4. Review the plan carefully. Look for files the agent should not touch, missing test updates, or scope creep. Push back: “Don’t change database.ts — that is out of scope.”
  5. Execute step by step: ask for one change at a time, run tests after each, commit before moving on. The unit of safety is a clean commit, not a full task.
  6. End the session by asking the agent to summarize what changed and what is still incomplete. Paste that into your PR description.

First-run exercise

  1. Pick a single function in a single file that has obvious smell — 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 tests again; they should still pass.
  4. Commit. Note what worked, what surprised you, and any prompt you want to keep.

Quality check

  • Run the test suite after each agent step. A clean run is your only objective signal the change is safe.
  • Read the diff line by line on the first 3 sessions. Once you trust the agent on a pattern, you can skim; before that, read.
  • Watch for the agent quietly editing files outside scope — diff against main to confirm the blast radius.
  • Re-read CLAUDE.md after every session and add the constraint you wish you’d written before the session started.

How to reuse this workflow

  • Treat each successful task as a template: save the planning prompt, the constraints you added, and the test command.
  • Build a personal cheat-sheet of phrases that worked: “do not write code yet”, “edit in place, do not rebuild”, “list out-of-scope files”.
  • Maintain CLAUDE.md as living memory — when the agent does the wrong thing twice, add a forbidden rule.
  • Rerun the same prompt every few weeks on different files; you will spot model behavior drift.

CLAUDE.md → planning prompt → review plan → small step → run tests → commit → repeat. The agent is fastest when forced to be slow.

FAQ

  • How is Claude Code different from Cursor?: Cursor is an IDE with AI inline; Claude Code is an agent that drives the shell. Different ergonomics, see Claude Code vs Cursor.
  • Can I use Claude Code without a CLAUDE.md?: Yes, but quality drops fast on real projects. Even a 20-line file helps.
  • Will it run destructive commands?: It asks before running anything risky by default; review every prompt rather than auto-approving.
  • What if the agent gets stuck or stalls?: Cancel, narrow the scope, and restart. Do not spam retry; see Claude retry rate limit.
  • How much does it cost in practice?: On real refactors expect $1-5 per session at consumer rates; lots of token use happens reading code it already read.

Common mistakes

  • Skipping the plan step and asking for code immediately — you get a diff you cannot review.
  • No CLAUDE.md — the agent reinvents project conventions and your style guide every chat.
  • Letting it commit unreviewed — even good diffs hide one quiet wrong line.
  • Asking for too-big tasks (“refactor the whole module”) instead of named small steps.
  • Spamming retry when the agent stalls on “Claude is at capacity” — that lengthens the cooldown (Claude retry rate limit).
  • Treating Claude Code’s output as authoritative on architecture decisions — it is fast at execution, less reliable at “should we”.

Tags: #AI coding #Tutorial #Claude Code

Related Articles