How to Use Claude Code: The Complete Beginner's Guide

What Claude Code Actually Is (and Isn't)

If you are reading a guide on how to use Claude Code, you have probably already seen the demos. Someone types a sentence into a terminal, and a few seconds later an entire feature appears, tests pass, and a commit is ready. It looks like magic. It is not magic, but it is genuinely different from anything else in the current development toolchain.

Claude Code is an agentic coding assistant that runs in your terminal. Not in your IDE sidebar. Not in a browser chat window. In the same terminal where you run git, npm, and cargo. It reads your files, writes your files, runs your commands, and interacts with your development environment directly.

The mental model shift is important, and it is the thing that trips up most beginners. Traditional coding assistants like GitHub Copilot work by autocomplete. You start typing, and they suggest the next line. Cursor takes this further by letting you edit code through a chat panel inside an IDE. Both are useful tools. But they operate at the level of individual edits.

Claude Code operates at the level of tasks. You do not tell it what to type. You tell it what you want to accomplish. "Add input validation to the signup form." "Investigate why the API returns 500 on large payloads." "Write integration tests for the payment module." Claude reads the relevant files, forms a plan, makes the edits, and (if you let it) runs the tests to verify everything works.

This is delegation, not autocomplete. The distinction matters because it changes how you interact with the tool entirely. With autocomplete, you are still driving. With Claude Code, you are describing the destination and reviewing the route. You stay in control (every file edit requires your approval), but the mechanical work of reading code, understanding context, writing implementations, and checking results shifts to Claude.

That is what this claude code tutorial will teach you. Not just the commands, but the workflow. How to think about tasks in terms Claude can execute efficiently, and how to set up your project so Claude understands your conventions from the first session.

Installing and Setting Up Claude Code

Prerequisites

You need two things before installing Claude Code:

Node.js 18 or later. Claude Code is distributed as an npm package. If you do not have Node.js installed, download it from nodejs.org or use a version manager like nvm. Check your version with node --version.

An Anthropic account with billing. You have two options here. The first is an API key from the Anthropic Console, where you pay per token consumed. The second is a Claude Pro or Max subscription, where Claude Code usage is included in your monthly fee. For daily use, the Max plan at $100/month is almost always more cost-effective than API pricing. I will cover the cost tradeoffs in more detail shortly.

Installation

Open your terminal and run:

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

That is it. The package installs a single global command: claude. Verify it worked:

claude --version

You should see a version number. If you get a "command not found" error, your npm global bin directory is probably not in your PATH. Run npm config get prefix and add the resulting path's bin subdirectory to your shell profile.

First Launch and Authentication

Navigate to any project directory and type:

claude

On first launch, Claude Code will walk you through authentication. If you are using a Claude Pro or Max subscription, it will open a browser window for OAuth sign-in. If you are using an API key, you can set it as an environment variable:

export ANTHROPIC_API_KEY=sk-ant-your-key-here

A realistic first launch looks like this:

$ cd ~/projects/my-web-app
$ claude

╭──────────────────────────────────────╮
│ ✻ Welcome to Claude Code            │
│                                      │
│   /help for commands                 │
│   /model to select a model           │
│                                      │
╰──────────────────────────────────────╯

>

You are now in an interactive session. Claude can see your project directory and is ready to work.

Choosing Your Billing Approach

This decision matters more than most beginners realise.

API key pricing charges per token. Input tokens (what Claude reads) cost less than output tokens (what Claude writes). A typical productive day costs $5 to $15, depending on how many large files Claude needs to read and how many models you use. Heavy usage days can reach $30 or more. This approach gives you full control over model selection and is better for occasional or unpredictable usage.

Claude Max subscription at $100/month gives you generous Claude Code usage with higher-tier models included. If you plan to use Claude Code daily (and you will, once you get comfortable), the subscription is almost always cheaper. There is also a $200/month tier with even higher limits for teams doing heavy development.

For a deeper breakdown of costs and strategies to manage them, see the Claude Code cost optimisation guide.

The Permission Model

Claude Code will not silently modify your files or run commands. Every potentially destructive action triggers a permission prompt. You will see something like this:

Claude wants to edit src/routes/auth.ts

  Allow? (y/n)

This is intentional. You stay in control. Early on, you will approve each action individually. As you build trust, you can configure allowed operations in your project's .claude/settings.json file so that safe, repeated actions (like running tests or reading files) happen without prompting. The Claude Code documentation covers permission configuration in detail.

Your First Session

The best way to understand Claude Code is to use it. Open a terminal, navigate to a project you are working on, and start a session.

Orienting Claude to Your Codebase

Your first prompt should help Claude understand what it is working with:

> Explore this codebase and tell me what it does. Focus on the directory
  structure, the main entry points, and any configuration files.

Claude will use its file tools (Glob, Grep, Read) to scan your project. It reads directory listings, checks package files, examines entry points, and builds a mental model of your project. After a few seconds, you will get a structured summary. Something like:

This is a Node.js Express API with the following structure:

  src/
    routes/       - API route handlers (auth, users, products)
    middleware/    - Auth middleware, error handling, rate limiting
    models/       - Sequelize models for PostgreSQL
    services/     - Business logic layer
    utils/        - Helper functions

  Key files:
    src/index.ts        - Express server setup, port 3000
    .env.example        - Required environment variables
    package.json        - Node 20, TypeScript, Express 4.x

  The API has 12 route files covering authentication (JWT-based),
  user management, and a product catalogue with search.

This is not just orientation for Claude. It is orientation for you. I regularly use this workflow on unfamiliar codebases, open source projects I am reviewing, or code I wrote six months ago and have forgotten about.

Making Your First Change

Now ask Claude to do something concrete:

> Add a health check endpoint at GET /health that returns
  { "status": "ok", "timestamp": "<current ISO timestamp>" }

Claude will:

1. Read the existing route structure to understand your patterns
2. Plan where the endpoint should go (it might create a new file or add to an existing router)
3. Write the implementation, matching your existing code style
4. Show you the diff before applying any changes

You will see the proposed changes with clear additions and deletions:

Claude wants to create src/routes/health.ts:

  + import { Router } from 'express';
  +
  + const router = Router();
  +
  + router.get('/health', (req, res) => {
  +   res.json({
  +     status: 'ok',
  +     timestamp: new Date().toISOString(),
  +   });
  + });
  +
  + export default router;

  Allow? (y/n)

If the code looks right, type y. Claude applies the change and then typically registers the new route in your main app file, showing you that diff as well.

The Read-Plan-Edit-Verify Loop

Every Claude Code interaction follows this pattern, whether you are aware of it or not:

1. Read: Claude examines the relevant files, often more than you would think to check. It looks at related files, tests, imports, and configuration.
2. Plan: Claude decides what changes are needed and in what order. For complex tasks, it will sometimes explain its plan before starting.
3. Edit: Claude makes the changes, one file at a time, showing you each diff for approval.
4. Verify: If your project has tests or linting, Claude can run them to confirm the changes work.

You can (and should) participate at every stage. If Claude's plan seems wrong, say so before it starts editing. If a diff looks off, reject it and explain what you expected instead. Claude adapts well to mid-course corrections.

This loop is the foundation of everything else in this guide. The five workflows below are all variations of it.

Five Workflows You'll Use Every Day

Once the basics click, most development work with Claude Code falls into five patterns. Each one follows the read-plan-edit-verify loop, but with different inputs and expectations.

1. Code Generation

This is the most common workflow. You need new functionality and you describe what it should do.

The prompt:

> Create a REST endpoint for user authentication using Express and JWT.
  It should handle POST /auth/login with email and password, validate
  against the users table, return a JWT token on success, and return
  appropriate error messages on failure. Follow the patterns in the
  existing route files.

What Claude does: It reads your existing routes to understand your project's patterns, checks your models to understand the user schema, examines your middleware to see how other routes handle authentication, and then generates the implementation. This typically involves creating or modifying two to four files: the route handler, possibly a service layer function, a middleware update, and route registration.

What you see: A sequence of diffs, one per file. Each waits for your approval. The implementation will match your existing code style because Claude read your other files first.

The key insight: The phrase "follow the patterns in the existing route files" is doing heavy lifting. It tells Claude to look at your conventions rather than using generic patterns from training data. Always reference your existing code when generating new code.

2. Bug Investigation

This workflow is where Claude Code genuinely outperforms other tools. Bug investigation requires reading many files, tracing execution paths, and forming hypotheses. Claude is tireless at this.

The prompt:

> The login form on /login submits but nothing happens. No error
  message, no redirect, no network error in the console. The form
  just sits there. Investigate and fix.

What Claude does: It starts by finding the login form component, then traces the submission handler, follows the API call to the backend route, checks the response handling, and examines error boundaries. It reads perhaps ten to fifteen files in the process. Eventually, it identifies the issue (maybe the form handler is calling preventDefault but the async function is not awaiting the API call, so the success handler never fires) and proposes a fix.

What you see: Claude explains its investigation process as it goes. "I found the login form in src/components/LoginForm.tsx. The submit handler calls authService.login() but doesn't await the result..." Then it shows you the targeted fix.

The key insight: Describe the symptom, not your theory. "The login form submits but nothing happens" is a better prompt than "I think there's a problem with the async handling in the login form." Let Claude investigate. Its diagnosis is often more thorough than yours because it reads every file in the chain rather than jumping to conclusions.

3. PR Creation

Claude Code has built-in git integration that makes pull request creation remarkably smooth.

The prompt:

> Create a PR for all changes on this branch with a descriptive
  title and body. Include a summary of what changed and why.

What Claude does: It runs git diff against the base branch, reads the changed files to understand the context, drafts a PR title and description, creates the commit (if uncommitted changes exist), pushes the branch, and uses the GitHub CLI to open the pull request.

What you see: Claude shows you the proposed commit message and PR description before creating anything. You approve, and it handles the git operations. The resulting PR has a structured description that actually explains the changes, not just "updated files."

The key insight: Claude writes better PR descriptions than most developers because it reads the actual diff and summarises what changed functionally. This saves reviewers significant time and makes your git history more useful.

4. Code Review

The reverse of PR creation. Point Claude at changes and ask it to find problems.

The prompt:

> Review the changes in PR #47 and flag any issues. Check for bugs,
  security concerns, performance problems, and style inconsistencies.

What Claude does: It checks out the PR branch (or reads the diff), examines every changed file, and looks at surrounding code for context. It then produces a structured review covering bugs it found, potential security issues, performance concerns, and style inconsistencies with the rest of the codebase.

What you see: A detailed review, often catching things that human reviewers miss. Claude is particularly good at spotting missing error handling, SQL injection vulnerabilities in dynamic queries, and race conditions in async code. It also catches when new code does not follow patterns established elsewhere in the project.

The key insight: Claude reads the surrounding codebase, not just the diff. This means it catches inconsistencies that a reviewer who only looks at the changed lines would miss. A function that works correctly in isolation but contradicts a convention used in every other file is something Claude will flag.

5. Test Writing

Writing tests is repetitive work that Claude handles exceptionally well, especially when it can read the implementation first.

The prompt:

> Write unit tests for the UserService class in src/services/user.ts.
  Cover the happy path, validation errors, database failures, and
  edge cases like duplicate emails. Use the same testing patterns
  as the existing test files.

What Claude does: It reads the UserService implementation, examines existing test files to understand your testing patterns (which framework, which assertion style, how you handle mocks), and generates comprehensive tests. It often covers edge cases you would not have thought to test.

What you see: A test file with well-organised describe blocks, clear test names, and realistic test data. Claude typically generates fifteen to thirty tests for a moderately complex service class.

The key insight: "Use the same testing patterns as the existing test files" ensures consistency. Without this, Claude might use a different mocking approach or assertion style than your project expects. Also, after generating tests, ask Claude to run them. It will execute your test runner and fix any failures, which is faster than reviewing test code manually.

CLAUDE.md: Teaching Claude About Your Project

CLAUDE.md is the single most impactful thing you can set up for Claude Code. It is a markdown file in your project root that Claude reads automatically at the start of every session. Think of it as a briefing document. Everything Claude needs to know about your project that it cannot infer from the code itself.

What Goes in CLAUDE.md

The most effective CLAUDE.md files are concise and specific. They cover four categories:

Build and test commands. How to build the project, how to run tests, how to start the development server. Claude needs this to verify its changes.

Architecture decisions. Where things go, what patterns to follow, what to avoid. This is where you encode your team's conventions.

Coding standards. Naming conventions, import ordering, error handling patterns. Anything that is a project rule but not enforced by a linter.

Context that is not obvious from the code. External dependencies, deployment constraints, known limitations.

Here is a realistic CLAUDE.md for a web application:

# Project: Acme Web App

## Build & Run
- `npm run dev` - Start development server (port 3000)
- `npm test` - Run all tests
- `npm run test:unit` - Unit tests only
- `npm run lint` - Run ESLint

## Architecture
- Express API in `src/routes/`, one file per resource
- Business logic in `src/services/`, never in route handlers
- Database access through Sequelize models in `src/models/`
- All responses use the `ApiResponse` wrapper from `src/utils/response.ts`

## Conventions
- TypeScript strict mode. No `any` types.
- Error handling: throw `AppError` from `src/utils/errors.ts`, caught by global middleware
- Naming: camelCase for functions/variables, PascalCase for classes/types
- Tests go next to source files: `user.service.ts` -> `user.service.test.ts`
- Imports: node modules first, then absolute paths, then relative paths

## Important
- Never modify files in `src/generated/` - these are auto-generated from the OpenAPI spec
- The `legacy/` directory is being phased out. Do not add new code there.
- Database migrations must be backwards-compatible (we do rolling deployments)

What NOT to Put in CLAUDE.md

Do not include secrets, API keys, or credentials. Claude does not need your database password to write good code. Do not paste entire file contents. Claude can read files itself, and pasted content goes stale. Do not include information that changes frequently, like current sprint tasks or temporary workarounds. CLAUDE.md should be stable enough to commit to version control.

Keep it under 200 lines. Claude reads the entire file at session start, and every token counts toward your context window. A CLAUDE.md that is essentially a novel wastes context on information Claude may never need. Be an index, not an encyclopedia.

For projects with multiple packages or services, you can place additional CLAUDE.md files in subdirectories. Claude picks up the one closest to where you are working. For complex monorepo setups, the CLAUDE.md for monorepos guide covers advanced strategies.

The Impact

The difference between using Claude Code with and without a CLAUDE.md is stark. Without it, Claude makes reasonable guesses about your conventions. Sometimes those guesses are wrong, and you spend time correcting them. With a good CLAUDE.md, Claude follows your patterns from the first interaction. It puts files in the right directories, uses the right error handling approach, follows your naming conventions, and runs the right test commands.

I estimate that a well-written CLAUDE.md saves five to ten corrections per session. Over weeks, that adds up to hours of reclaimed time.

Common Mistakes and How to Avoid Them

After months of using Claude Code daily and helping other developers get started, the same mistakes appear repeatedly. Each one has a straightforward fix.

1. Being Too Vague

"Fix the bug" is not a useful prompt. Claude does not know which bug you mean, where to look, or what the expected behaviour is. Compare these two prompts:

Vague: "Fix the bug in the signup form."

Specific: "The form validation on /signup does not reject email addresses without an @ symbol. The validation function is in src/utils/validation.ts. It should reject emails that do not match a standard email regex pattern."

The specific version tells Claude exactly what is wrong, where to look, and what the fix should accomplish. It will solve the problem in one turn instead of three.

You do not need to know the exact file path every time. But you should always describe the symptom precisely, indicate where in the application it occurs, and state what the correct behaviour should be.

2. Not Reviewing Diffs

Claude is powerful but not infallible. It occasionally makes changes that are technically correct but do not match your intent. It might add a dependency you did not want, refactor something you did not ask to be refactored, or implement a solution that works but is more complex than necessary.

Always read the diffs before approving. This is not busywork. It is the core of the collaboration model. You bring the judgment. Claude brings the execution speed. Skipping the review step removes your judgment from the loop.

If a diff looks wrong, reject it and explain why. Claude learns from your corrections within the session and adjusts its approach.

3. Ignoring the Cost Model

Long, wandering sessions where Claude reads dozens of large files cost more than focused sessions where you name the specific files and functions relevant to your task. Every file Claude reads adds to your input token count, and that context is re-sent with every subsequent message.

Practical habits that reduce cost without reducing productivity: use /clear between unrelated tasks to reset context. Use /compact to summarise long conversations. Name specific files in your prompts so Claude does not need to search broadly. And choose the right model for the task. Claude Sonnet handles 80% of daily work at a fraction of the cost of Opus.

For a detailed treatment of cost management, see the cost optimisation guide.

4. Fighting the Permission System

Some developers find the permission prompts annoying and look for ways to bypass them entirely. This is the wrong approach. The prompts exist because Claude Code operates directly on your files and terminal. A miscommunicated intent could delete files, overwrite work, or run destructive commands.

The right approach is to configure permissions thoughtfully. In your project's .claude/settings.json, add the commands you trust to the allow list:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm test*)",
      "Bash(npm run lint*)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push --force*)"
    ]
  }
}

This lets Claude read files and run tests without prompting, while still blocking destructive operations. You keep safety without the friction.

5. Treating It Like a Chatbot

Claude Code is not a conversational partner. It is a task executor. Long, open-ended conversations where you gradually refine what you want are inefficient and expensive. Each message re-sends the full conversation history.

Instead, give Claude a complete task in a single prompt. Front-load the context. Name the files, describe the desired outcome, specify constraints, and reference existing patterns. One well-crafted prompt that takes thirty seconds to write will outperform five messages of back-and-forth every time.

Think of it this way: every prompt is a work order. The more complete the work order, the better the result.

What to Learn Next

This guide covers the foundation. Once you are comfortable with the basics, there is a lot more depth available.

Claude Code daily workflows goes beyond the five core workflows into model selection strategies, context management, settings configuration, and the daily routine of a power user. If you find yourself using Claude Code for an hour or more each day, this is the logical next step.

Hooks and automation covers Claude Code's hook system, which lets you trigger custom scripts before or after Claude performs specific actions. Useful for enforcing project standards, running formatters automatically, or integrating with CI/CD pipelines.

Agent teams for parallel work explains how to run multiple Claude Code instances working on different parts of a task simultaneously. This is particularly powerful for large refactoring efforts or feature work that spans many files.

MCP servers for tool integration covers the Model Context Protocol, which lets Claude Code interact with external services like databases, APIs, and custom tools. If you want Claude to query your staging database or check your deployment status, MCP is how you do it.

Cost management strategies provides a detailed breakdown of Claude Code pricing, model selection for cost efficiency, context management techniques, and team billing strategies. Essential reading if you are rolling Claude Code out to a team.

Each of these guides builds on the fundamentals covered here. Start with the daily workflows guide and branch out based on what your projects need. The learning curve is not steep, but the depth is substantial. Six months in, I am still finding new ways to use Claude Code that save meaningful time.

The tool is only as effective as the person directing it. Invest the time to learn the workflows, write a good CLAUDE.md, and develop the habit of writing specific, complete prompts. The productivity difference is not incremental. It is qualitative. Tasks that used to require thirty minutes of mechanical work now take two minutes of describing what you want and reviewing the result.

That is the real answer to how to use Claude Code. Not just the commands, but the mindset. Delegate the execution, own the decisions.