Claude Code Tutorial: Complete Beginner's Guide

Claude Code is Anthropic's command-line AI coding assistant. It lives in your terminal, can read and edit files, run commands, search your codebase, manage Git, and build entire features through conversation. This tutorial takes you from zero to productive with Claude Code.

Step 1: Install Claude Code

Install Claude Code globally using npm:

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

Verify the installation:

claude --version

Authenticate with your API key or Claude subscription:

claude
# Follow the authentication prompts

Step 2: Start Your First Session

Navigate to any project directory and start Claude Code:

cd my-project
claude

You'll see a prompt where you can type natural language commands. Claude Code automatically reads your project structure and key files like package.json, CLAUDE.md, and README.md to understand your codebase.

Try these first commands

# Understand the project
> Explain the architecture of this project

# Find something specific
> Where is the authentication logic?

# Make a change
> Add a /health endpoint that returns the current timestamp

# Fix a bug
> The login form doesn't validate email addresses. Add validation.

Claude Code will read relevant files, make edits, and can even run commands to verify its changes work.

Step 3: Understand the Tools

Claude Code uses "tools" to interact with your system. Understanding them helps you work more effectively:

You don't invoke these directly -- Claude Code decides which tools to use based on your request. But knowing they exist helps you phrase requests effectively.

Step 4: File Editing Workflow

Claude Code can edit files in two ways:

Precise edits (Edit tool)

For targeted changes, Claude uses search-and-replace on specific lines. This is safe and predictable -- it only changes exactly what needs to change.

> Change the default page size from 10 to 25 in the pagination component

Full file writes (Write tool)

For new files or complete rewrites, Claude creates the entire file. This is used for scaffolding new components, tests, or config files.

> Create a new UserProfile component that displays name, email, avatar, and a bio field

Step 5: Running Commands

Claude Code can execute terminal commands using the Bash tool. This is powerful for:

• Running tests: "Run the test suite and fix any failures"
• Installing packages: "Install zod and add validation to the form"
• Git operations: "Create a branch called feature/user-settings and commit my changes"
• Building: "Build the project and fix any TypeScript errors"
• Database: "Run the database migrations"

Claude Code shows you the command before running it and waits for approval (unless you've enabled auto-accept for Bash commands).

Step 6: Set Up CLAUDE.md

The most important file for getting good results is CLAUDE.md. This is a markdown file in your project root that Claude reads automatically. Use it to set conventions:

# CLAUDE.md

## Project Overview
E-commerce platform built with Next.js, TypeScript, and PostgreSQL.

## Commands
- `npm run dev` -- start dev server on port 3000
- `npm test` -- run Jest tests
- `npm run lint` -- run ESLint

## Conventions
- Use named exports, not default exports
- All API routes use Zod for input validation
- Use date-fns for date formatting (not moment)
- CSS modules for component styles

## Testing
- Co-locate tests next to source files (Button.test.tsx)
- Use React Testing Library, not Enzyme
- Mock external APIs with msw

This single file dramatically improves Claude Code's output quality because it doesn't have to guess your preferences. See the system prompt guide for more on customizing Claude's behavior.

Step 7: Essential Slash Commands

Claude Code has built-in slash commands you can type at the prompt:

The most important one to know is /compact. Long sessions accumulate context that can slow Claude down and increase costs. Running /compact summarizes the conversation and frees up context space. For more, see the slash commands reference.

Step 8: Git Integration

Claude Code has excellent Git integration. You can ask it to handle your entire Git workflow:

# Stage and commit with a good message
> Commit my changes with a descriptive message

# Create a PR
> Push this branch and create a pull request with a summary of all changes

# Review changes
> Show me what changed since the last commit and explain each change

# Handle conflicts
> I have merge conflicts after rebasing. Help me resolve them.

Claude Code understands your commit history, can generate meaningful commit messages, and creates well-formatted pull requests. See the GitHub guide for the full workflow.

Step 9: Multi-file Operations

One of Claude Code's biggest strengths is making coordinated changes across many files. Unlike IDE-based tools that work file-by-file, Claude Code understands your entire project:

# Rename across the codebase
> Rename the User model to Account everywhere -- model, routes, tests, types, and imports

# Add a feature that touches many files
> Add a "last seen" timestamp to users. Update the schema, API, frontend display, and tests.

# Consistent refactoring
> Convert all callback-style error handling to try/catch with custom error classes

For large refactors, Claude Code can use sub-agents to work on multiple files in parallel, significantly speeding up broad changes.

Step 10: Headless Mode & Automation

Claude Code isn't limited to interactive use. The -p flag runs a single prompt without an interactive session:

# One-shot tasks
claude -p "Fix all TypeScript errors in the project"
claude -p "Add JSDoc comments to all exported functions in src/utils/"

# Pipe output
claude -p "Explain what this project does in 3 sentences" | pbcopy

# Use in scripts
claude -p "Generate a changelog from the last 10 commits" > CHANGELOG.md

You can also pipe data into Claude Code:

# Analyze test output
npm test 2>&1 | claude -p "Analyze these test results and fix any failures"

# Process logs
cat error.log | claude -p "Summarize the errors and suggest fixes"

Step 11: Working with Images

Claude Code can analyze images, screenshots, and diagrams. Drag and drop an image into the terminal, or reference a file path:

> Look at screenshot.png and build a component that matches this design

> This wireframe shows the new dashboard layout. Implement it using our existing components.

This is particularly powerful for frontend development and vibe coding -- paste a design and let Claude build it.

Step 12: Cost Management

Claude Code uses the Claude API, which charges per token. To manage costs:

• Use /cost to check your current session usage
• Use /compact regularly to reduce context size
• Use /model to switch to cheaper models (Haiku) for simple tasks
• Set a --max-cost flag to cap spending per session
• Use headless mode (-p) for focused, one-shot tasks instead of long interactive sessions

See the pricing guide for detailed cost breakdowns.

Common Beginner Mistakes

Not using CLAUDE.md

This is the single biggest quality improvement. Without it, Claude guesses your conventions and often guesses wrong.

Writing prompts that are too long

Keep instructions focused. Instead of one massive prompt, break work into steps. Let Claude finish one thing, verify it, then ask for the next.

Not reviewing changes

Always review what Claude produces, especially for security-sensitive code. Claude Code shows diffs before applying changes -- read them.

Forgetting to /compact

Long sessions without compacting lead to degraded output quality and higher costs. Compact after completing each major task.

Next Steps

You now have a solid foundation for using Claude Code. Here's where to go from here:

• Best Practices -- deepen your CLAUDE.md and workflow patterns
• Vibe Coding Guide -- build entire apps through natural language
• Hooks Guide -- automate workflows with event-driven scripts
• Agents Guide -- run autonomous coding tasks
• Testing Guide -- test-driven development with Claude Code
• Cheat Sheet -- quick reference for all commands