Claude Code guide

Claude Code Tutorial for Beginners

Claude Code is an AI coding agent that works inside your project folder: it reads your files, writes code, runs commands and asks before anything risky. This step-by-step guide takes you from installing it to finishing a first small project, with the commands, habits and fixes beginners need.

Updated November 21, 2026 · About 12 minutes to read

1. What Claude Code is

Claude Code is Anthropic's coding agent. You run it in a terminal (or in VS Code) inside a project folder and talk to it in plain language: "add a dark mode", "why does this test fail?", "explain this file". It reads the code it needs, edits files, runs commands such as tests, and shows you what it wants to do before doing it.

Claude chat (claude.ai)Claude Code
Where it runsIn the browserIn your project folder (terminal, VS Code)
Your filesYou paste code in and copy answers outReads and edits the files itself
CommandsCannot run themRuns tests, installs, git, with your permission
Best forQuestions, snippets, learningBuilding and changing a real project

2. What you need

  • A Claude plan or API account. Claude Code works with a paid Claude subscription (Pro or Max) or with an Anthropic API account billed by usage. There is no free plan for it.
  • A terminal. Terminal on Mac, Windows Terminal or PowerShell on Windows. The terminal inside VS Code works too.
  • Git (recommended). It saves every working version, so a bad change is one command away from being undone. On a Mac run xcode-select --install; on Windows run winget install --id Git.Git -e.
  • An idea, written down. Two or three sentences about what you want to build and for whom. Step 5 turns it into a CLAUDE.md.

3. Install Claude Code

Use the official installer for your system, then open a new terminal window so the claude command is found.

Mac, Linux or WSL (Terminal)
curl -fsSL https://claude.ai/install.sh | bash
Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

If you already use Node.js 18 or newer, npm works too:

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

Check that it works:

claude --version

Prefer an editor? Install the Claude Code extension from the VS Code marketplace. It uses the same claude program and shows proposed changes as diffs in the editor.

4. Start it in a project folder

Claude Code works on the folder you start it in, so always cd into your project first. For a new project, make an empty folder and turn on git:

mkdir habit-buddy
cd habit-buddy
git init
claude

The first time, Claude Code asks you to log in: choose your Claude account (subscription) or an API key, and finish in the browser. It may also ask whether you trust the folder. Then you see a prompt where you type requests in plain language.

For an existing project, cd into it and run claude. A good first message is "Explain what this project does and how it is organized": it reads the code and you learn whether it understood.

5. Give it a CLAUDE.md

CLAUDE.md is a file in the root of your project that Claude Code reads at the start of every session. It holds what the project is, the commands to install, run and test it, and your rules, such as "work in small steps" or "ask before adding a package". Without it you would repeat the same instructions in every chat.

  • Existing project: type /init. Claude Code reads the code and writes a first CLAUDE.md for you to check and shorten.
  • New project: the CLAUDE.md generator asks 4 questions about your idea and writes CLAUDE.md, AGENTS.md (for other agents), a SPEC.md and a step-by-step prompt plan.
  • Edit it later with /memory, or open the file in any editor. Keep it to about one page.

Starting from an idea? Answer 4 questions and get CLAUDE.md, a spec and the prompts for each step.

Open the CLAUDE.md generator →

6. Plan before it codes

The most common beginner mistake is one big request: "build me a habit tracker app". The agent guesses, builds too much, and gets lost halfway. Ask for a plan first.

Press Shift+Tab until the mode line shows plan mode. In plan mode Claude Code reads and thinks but does not change files. Then ask:

Read CLAUDE.md and SPEC.md. Do not write code yet.
Propose the simplest stack for this project and explain why in plain words.
Then list 5 to 8 small build steps. Ask me any questions you have first.

Read the plan. Ask about any word you do not know, change what you do not like, and only then let it start. A plan you understand is worth more than a fast first draft.

7. Let it build, one step at a time

  1. Leave plan mode (Shift+Tab) and ask for step 1 only: "Do step 1 of the plan. Tell me how to check it when you are done."
  2. Answer the permission prompts. Before it edits a file or runs a command, Claude Code shows what it wants to do. Approve once, approve for the rest of the session, or say no and tell it what to do instead.
  3. Check it yourself. Run the app or open the page. If something is wrong, paste the exact error message or describe what you see, not just "it does not work".
  4. Commit when the step works (next section), then ask for the next step.

Want the agent to stop asking for every file edit? Shift+Tab also switches to auto-accept edits. Use it only after you have committed, so you can undo anything you do not like.

8. Review, commit and undo

Treat every working step as a save point. You can ask Claude Code to do it ("commit this with a short message") or run git yourself:

git add -A
git commit -m "Add habit list"

To see what changed before you commit, ask "show me what you changed and why", or run git diff. If a step went wrong and you want the last working version back:

git restore .

Press Esc at any time to stop Claude Code in the middle of a task. Recent versions can also rewind their own edits to an earlier point of the conversation with /rewind.

9. Commands and shortcuts beginners use most

Type or pressWhat it does
/helpLists every command of your version
/initWrites a CLAUDE.md for an existing project
/memoryOpens CLAUDE.md to edit it
/clearStarts a fresh conversation (use it between unrelated tasks)
/compactSummarizes a long conversation so it fits again
/modelSwitches the Claude model
/resume, claude --continueGoes back to an earlier conversation
/permissionsShows and changes what it may do without asking
Shift+TabSwitches between normal, auto-accept edits and plan mode
EscStops the current task
@ + file namePoints it at a file, for example @src/app.js
! + commandRuns a shell command yourself, for example !npm test

Commands change between versions; /help always shows the list for the version you have.

10. Common problems and fixes

ProblemFix
claude: command not foundOpen a new terminal window after installing. If it still fails, run the installer again and check the message at the end; claude doctor checks the installation.
Login or plan errorsRun /login and pick the account with your Claude plan, or check that your API key has credit.
Answers get worse in a long chatStart fresh with /clear between tasks, or /compact to shrink the conversation. Facts it should always know belong in CLAUDE.md.
It goes in circles on a bugStop with Esc. Paste the exact error, say what you expected and what happened, and ask it to add a test or a log line that shows the cause before it changes more code.
It changed files you did not wantUndo with git restore ., then add a rule to CLAUDE.md, for example "Only change files related to the current step".
It wants to add a package or serviceAsk why and what it costs. Add "Ask before adding a package or paid service" to CLAUDE.md.
You hit a usage limitWait for the limit to reset, keep tasks small, and clear the conversation between them so each request sends less.

Want a second opinion on a piece of code? Paste it into the AI Code Checker to have it explained or fixed, or try HTML, CSS and JavaScript in the HTML online editor.

11. Best practices

  1. One task per conversation. Use /clear when you move to something unrelated.
  2. Plan first for anything bigger than a small fix, and read the plan.
  3. Small steps, then commit. Each working step is a save point.
  4. Be specific. Name the file, the expected result and how to check it.
  5. Ask for tests, and ask it to run them before it says a step is done.
  6. Keep CLAUDE.md short and add a rule when it makes the same mistake twice.
  7. Never paste secrets such as API keys or passwords into the chat or into code; use a .env file kept out of git.
  8. Understand what you ship. Ask "explain this in plain words" until you could explain it yourself.

12. What to learn next

  • Skills: folders of instructions and scripts Claude Code loads when a task needs them, for repeated jobs such as releases or reports.
  • Subagents: helpers with their own instructions for focused jobs, such as reviewing code or writing tests.
  • MCP servers: connect Claude Code to other tools and data, such as a database, a browser or your issue tracker.
  • Hooks: commands that run automatically at set moments, for example a formatter after each edit.
  • Non-interactive mode: claude -p "your request" runs one request and prints the answer, useful in scripts.

FAQ

Is Claude Code free?

No. Claude Code needs a paid Claude plan (Pro or Max) or an Anthropic API account that is billed by usage. This tutorial and the CLAUDE.md generator on this site are free.

Do I need to know how to code to use Claude Code?

No, but you should read what it plans and changes. Start every task in plan mode, ask it to explain new ideas in plain words, and commit after each working step so you can always go back.

Does Claude Code work on Windows?

Yes. Install it with the PowerShell command in this guide, or inside WSL, and run it in Windows Terminal or in the VS Code terminal.

What is the difference between Claude Code and the Claude chat?

The chat answers in the browser and you copy the code yourself. Claude Code runs in your project folder: it reads your files, edits them, runs commands and tests, and asks before it does anything risky.

What is CLAUDE.md?

A file in your project that Claude Code reads at the start of every session: what the project is, the commands to run it and the rules to follow. /init writes a first version from an existing project; the CLAUDE.md generator writes one from your app idea.

How do I stop Claude Code or undo a change?

Press Esc to stop it at any time. To undo, use git: commit after each working step, then git restore . brings the files back to the last commit. Recent versions can also rewind their own edits with /rewind.