Claude Code Tutorial: From Install to Your First Real Task

Before You Start

You need three things:

• Node.js 18+ (22 LTS recommended)
• A terminal you are comfortable with (macOS Terminal, iTerm, Windows Terminal with WSL, any Linux terminal)
• A Claude account with either a Pro/Max subscription or API credits

Git is not required but you should have it. Claude Code works best in git repositories because it can track what it changed and roll back if needed.

Installation

Open your terminal and run the native installer. On macOS or Linux:

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | sh

# Verify installation
claude --version

On Windows, use WSL (Windows Subsystem for Linux) and run the same command. The npm installation method is deprecated. Use the native installer.

The first time you run claude, it asks you to authenticate. You pick either a Claude subscription (uses your monthly quota) or API access (bills per token). Claude opens a browser window, you log in, paste the verification code back into your terminal, and you are done. Authentication persists across sessions.

Your First Session

Navigate to a project directory first. This matters. Claude Code can see every file in the directory where you start it and its subdirectories. If you run it from your home directory, Claude sees everything, which wastes context and slows it down.

# Always cd to your project root first
cd ~/projects/my-app

# Start Claude Code
claude

You are now in an interactive session. The interface is simple: a text prompt where you type natural language, and Claude responds with text, file edits, and command executions. No GUI, no sidebar, no tabs. Just a conversation.

Try something simple first:

> what does this project do?

Claude reads your README, package.json, and key source files, then gives you a summary. This is a good sanity check that Claude can see your codebase. If it says it cannot find any files, you started it in the wrong directory.

Commands and Keyboard Shortcuts

Slash commands control Claude Code's behavior. You do not need to memorize them all. These six cover 90% of daily use:

Keyboard shortcuts matter more than slash commands for daily flow:

Tab / Enter     → Send your message
Shift+Tab       → Toggle Plan Mode (research without changes)
Escape          → Cancel current input
Up Arrow        → Recall last message (edit and resend)
Ctrl+C          → Interrupt Claude mid-response

Shift+Tab is the one to internalize. Plan Mode tells Claude to read and think without modifying anything. Use it when you want to understand code before changing it.

Setting Up CLAUDE.md

CLAUDE.md is a markdown file at your project root that Claude reads at the start of every session. It is the single most impactful thing you can configure. Without it, Claude guesses your conventions. With it, Claude knows them.

Run /init to generate a starter. Then open it and add the information Claude cannot infer from your code.

# CLAUDE.md

## Commands
- Build: npm run build
- Test: npm run test
- Dev server: npm run dev (port 3000)
- Lint: npm run lint

## Architecture
- TypeScript strict mode
- API routes in src/app/api/
- Components in src/components/
- Server components by default, client only when needed

## Conventions
- Use named exports, not default exports
- Error handling: return NextResponse with status codes, no throw
- Database: Drizzle ORM, schema in src/lib/db/schema.ts

# CLAUDE.md

## Commands
- Test: pytest -v
- Lint: ruff check .
- Format: ruff format .
- Type check: mypy src/

## Architecture
- Python 3.12, always use type hints
- Pydantic for data validation
- Database models in src/models/
- FastAPI routes in src/routes/

## Conventions
- Use async/await for all IO operations
- Raise HTTPException for error responses
- Tests go in tests/ mirroring the src/ structure

Task 1: Fix a Real Bug

Find a bug in your project. An open GitHub issue, a failing test, a behavior that is not right. The key is to work on something real. Toy examples do not teach the workflow.

Start a fresh session and describe the bug in plain language. Include three things: expected behavior, actual behavior, and any context about where the problem might be.

> The /api/users endpoint returns 500 when called with an expired
> session token. Expected behavior: return 401 with an error message.
> Actual behavior: unhandled exception in src/middleware/auth.ts.
> The error is "Cannot read property 'exp' of undefined".

Watch what Claude does. It reads the auth middleware, identifies that the token parsing fails when the JWT is expired, and proposes a fix. You see the changes as a diff. Type y to accept, n to reject, or a to accept all remaining changes.

> run the tests to make sure this works

# Claude executes your test suite and reports results
# If tests fail, it reads the output and tries again

That is the core loop: describe the problem, review the fix, verify it works. You will repeat this hundreds of times.

Task 2: Build a New Feature

Pick a small feature. A new API endpoint, a utility function, a React component. Something you can finish in one session.

Start a new session. Run /clear or start a fresh claude. Clean context matters. Do not continue from the bug fix session because unrelated context makes Claude less accurate.

> Add a GET /api/health endpoint that returns JSON with:
> - "status": "ok"
> - "timestamp": current ISO timestamp
> - "version": read from package.json

Notice what makes this prompt effective: it specifies the behavior, not the implementation. Claude picks the right pattern for your codebase. If you use Next.js App Router, it creates a route.ts file. If you use Express, it adds a route handler. You did not need to tell it which.

> Create a file at src/app/api/health/route.ts that exports
> an async GET function using NextResponse.json with the
> status field set to "ok"...

Don't dictate implementation. Tell Claude WHAT you want,
not HOW to build it. It knows your codebase.

Claude builds the feature, possibly touching multiple files. Review each change. When it finishes, ask it to run the build or test suite to verify everything compiles.

Working with Multiple Files

This is where Claude Code stands apart from chat-based AI tools. You do not paste code into a chat window. Claude already sees your entire codebase.

> Add an "email" field to the User type in src/types/user.ts
> and update every component and API route that creates
> or displays a User to include this field.

Claude reads the type definition, finds every file that imports User, plans the changes, and applies them in sequence. If adding the field to a component requires updating a form, Claude handles that too. You review the full set of changes as a batch.

For large cross-file changes, use Plan Mode first (Shift+Tab). Let Claude map out everything it will change before it starts editing. Review the plan, then switch to normal mode and say "go ahead."

Session Management: /compact, /clear, and /model

Three commands that keep your sessions productive:

/compact compresses the conversation when context gets long. Claude's context window is 200K tokens. After 20-30 minutes of active work, accumulated context causes Claude to forget earlier instructions. Run /compact proactively, before you notice degradation.

/clear resets the conversation entirely (CLAUDE.md stays loaded). Use it between unrelated tasks. Residual context from a previous task can confuse Claude on the next one. Fresh sessions consistently produce better results than long sessions with accumulated noise.

/model switches between Claude models mid-session. Use Opus for complex refactoring, architectural decisions, or tricky bugs. Use Sonnet (the default) for most coding tasks. Use Haiku for quick lookups, simple edits, and research.

Permission Modes

Claude Code asks before every file edit and command execution by default. This is the right mode for beginners. You see exactly what Claude wants to do, and you approve or deny each action.

As you get comfortable, you can allow specific tools to auto-approve. For example, you might auto-approve file reads but still manually approve file writes and command execution.

# When Claude proposes a change:
y     → Accept this change
n     → Reject this change
a     → Accept all remaining changes in this task

# When Claude wants to run a command:
y     → Run it
n     → Don't run it

Git Integration

Claude Code integrates with git at a deep level. It reads history, creates commits, switches branches, and resolves conflicts.

The most useful workflow:

1. Commit before starting. Create a checkpoint so you can roll back if Claude goes the wrong direction.
2. Make changes with Claude. Work through the task as described above.
3. Review the diff. Ask Claude "show me a git diff" or run git diff yourself.
4. Commit with a message. Ask Claude to commit. It writes descriptive commit messages because it knows exactly what changed and why.

> commit these changes with a descriptive message

# Claude runs:
# git add -A
# git commit -m "Fix expired token handling in auth middleware
#
# The JWT parsing in auth.ts threw an unhandled exception when
# tokens were expired. Added try-catch with proper 401 response."

Think of git as your undo button. If Claude produces something wrong, git checkout . takes you back to your last commit instantly.

Common Beginner Mistakes

Next Steps

You have the foundation. Where you go next depends on what you build.

• Hooks run scripts automatically when Claude edits files or executes commands. Think of them as git hooks for your AI assistant.
• MCP servers connect Claude to external tools and APIs, like databases, design systems, or deployment pipelines.
• Agent teams spawn multiple Claude instances working in parallel on different parts of a task.
• Best practices guide covers context engineering, subagents, Plan Mode workflows, and scaling patterns.

The fastest way to learn Claude Code is to use it on real work. Start every coding session by opening Claude Code instead of your editor. After a week, the workflow will feel invisible.

Frequently Asked Questions

How do I install Claude Code?

Run the native installer from Anthropic's install page on macOS or Linux. On Windows, use WSL. After installation, run claude --version to confirm. The npm installation method is deprecated.

Do I need a paid subscription?

Yes. You need either a Claude Pro or Max subscription (uses your monthly quota) or a Claude Console account with API credits (bills per token). There is no free tier for Claude Code.

What is CLAUDE.md and do I need one?

CLAUDE.md is a project config file that Claude reads at the start of every session. It tells Claude your build commands, style rules, and project conventions. Run /init to create one. You do not strictly need it, but without it, Claude will guess your conventions and get them wrong regularly.

What are the most important commands?

Six commands cover 90% of daily use: /help, /clear, /compact, /model, /init, and /doctor. Use /clear between unrelated tasks and /compact when sessions get long.

How do I write good prompts for Claude Code?

Be specific about the problem, not the implementation. Include expected behavior, actual behavior, and relevant context. Let Claude choose the implementation pattern. "Login fails on expired tokens" is better than "add a try-catch in auth.ts line 42."

Can Claude Code edit multiple files at once?

Yes. Claude sees your entire codebase and makes coordinated changes across files. Say "update the User type and every component that uses it" and Claude handles the cascade.

What is Plan Mode?

Press Shift+Tab to toggle Plan Mode. In Plan Mode, Claude reads code and answers questions without making any changes. Use it to understand code before modifying it, or to review Claude's approach before committing to implementation.

How does Claude Code work with git?

Claude reads git history, creates commits, switches branches, and resolves conflicts. Best practice: commit before every complex task so you have a clean rollback point. Ask Claude to commit when you are happy with changes. It writes better commit messages than most developers because it knows exactly what changed.

Why does Claude get worse in long sessions?

Claude's 200K token context window holds your full conversation. After 20-30 minutes of active work, accumulated context degrades performance. Use /compact to compress the session, or /clear to start fresh. Shorter, focused sessions consistently beat long, unfocused ones.

Should I use the tutorial or the best practices guide?

Start here. This tutorial gets you from zero to productive. Once you are comfortable with the basics, the best practices guide covers optimization: context engineering, subagents, hooks, agent teams, and parallel sessions.