Claude Code Tutorial: The Complete Beginner's Guide

I've watched a lot of engineers install Claude Code, type a question, and then sit there unsure what to do next. That's because most Claude Code tutorials are either a 30-second install walkthrough or a 90-minute firehose. Neither is what you actually need.

This is the Claude Code tutorial I wish someone had given me on day one. Install to productive in one sitting. Opinionated, specific, and targeted at working engineers who already know their way around a terminal.

By the end you'll have Claude Code installed, you'll understand why it's fundamentally different from Copilot or Cursor, you'll have shipped your first real session, you'll know the permission model, and you'll have a working CLAUDE.md. That's the starting line. Everything after that is practice.

What Claude Code actually is (and why it's different)

Claude Code is an agentic command-line assistant from Anthropic. That's a phrase with a lot of packed meaning, so let's unpack it by contrasting with the tools you already know.

• GitHub Copilot is an autocomplete engine. It lives in your editor and suggests the next line, next function, next test. It's reactive — it completes what you're already typing.
• Cursor is an AI-enhanced editor. It wraps VS Code and adds chat, edit, and composer features that work across multiple files. It's interactive — you ask, it edits.
• Claude Code is an agent that runs in your terminal. It reads your files, runs commands, edits code, manages git, and can execute multi-step tasks autonomously with your permission. It's agentic — you give it a goal, and it works toward that goal using tools.

That last word matters. Claude Code isn't just "Claude with file access." It's Claude with a set of tools — read files, write files, run shell commands, search the filesystem, use MCP servers — and the ability to decide which tool to use next based on what it's trying to accomplish. That architectural choice is why Claude Code feels so different to use once you get past the first ten minutes.

You can absolutely use Claude Code alongside Cursor or Copilot. I do, most days. But they sit at different layers of the stack, and conflating them is the fastest way to misuse all three.

Installing Claude Code

You have two install paths. Pick one.

# Option 1: the official install script (macOS / Linux)
curl -fsSL https://claude.ai/install.sh | sh
 
# Option 2: via npm, if you already have Node 18+
npm install -g @anthropic-ai/claude-code

Then authenticate. You have two options:

1. Claude Pro or Max — run claude login and it'll open your browser. You'll sign in with the same account you use for claude.ai. This is what I recommend for 90% of engineers.
2. API key — export ANTHROPIC_API_KEY=sk-ant-... and pay-per-token. Useful if you're building automations on top of Claude Code headless mode, or if you hit Max plan rate limits during heavy days.

Verify it works:

claude --version
claude doctor

claude doctor is an underused diagnostic command. If anything's wrong — missing auth, bad config, unreachable MCP server — it'll tell you.

Your first session: interactive mode

Change into any repo you care about and run:

cd ~/code/my-project
claude

That drops you into an interactive REPL. The cursor is waiting for a prompt. Before you type anything, notice two things:

1. Claude Code automatically loaded CLAUDE.md from the current directory (if one exists). More on that in a minute.
2. The bottom of the terminal shows a permission mode — typically "default." That's the mode that asks before Claude touches anything.

Now type a prompt. Start simple:

What does this repo do? Don't modify anything, just explain the structure and the main entry points.

Watch what happens. Claude Code will start using tools — Glob to scan files, Read to open the ones that look important, maybe Grep for specific patterns. Each tool call shows up in your terminal. After a few seconds it comes back with a summary.

That first session is important because it shows you the loop:

1. You give Claude a goal.
2. Claude picks a tool.
3. Claude executes the tool.
4. Claude reads the result.
5. Claude decides whether it's done or needs another tool.
6. Repeat until the goal is met.

Copilot doesn't do this. Cursor's composer does a shallower version of this. Claude Code's agentic loop is the core value prop, and once you see it in action, the rest of this tutorial makes sense.

One-shot mode and piping

Interactive mode is great for conversations. But some tasks are better as a single command, and some are better as part of a Unix pipeline. That's what one-shot mode is for.

# Print a single response and exit
claude -p "Explain what this repo does in 3 bullet points."
 
# Pipe a git diff into Claude
git diff main | claude -p "Review this diff. Flag bugs, security issues, and missing tests."
 
# Generate a commit message from staged changes
git diff --cached | claude -p "Write a conventional commit message. Just the message, no preamble."
 
# Summarize logs
kubectl logs my-pod --tail=1000 | claude -p "Summarize the errors and group by root cause."

The -p flag (or --print) means "one-shot mode." Claude reads stdin, processes, writes to stdout, exits. That makes Claude a first-class citizen of the Unix pipeline. You can | it into jq, xargs, sed, whatever. This is one of Claude Code's most powerful features and almost nobody uses it.

My most-used one-liner, by far:

git diff --cached | claude -p "Write a conventional commit message for this change. Just the message."

I've aliased that to ccc in my zshrc. It replaces git commit -m "..." for me.

The permission model explained

By default, Claude Code asks you to confirm before it uses certain tools — particularly Bash (running commands) and Write / Edit (modifying files). This is a feature, not a bug.

There are a few modes:

• Default — asks for approval the first time Claude wants to use a given tool on a given target, then remembers your choice for the session.
• Accept all — auto-approves tool calls for the rest of the session. Use when you trust the task and don't want to babysit.
• Plan mode — Claude drafts a plan and waits for your approval before executing. Use for big refactors or anything risky.
• Read-only — Claude can inspect files but can't modify anything. Use for reviews, exploration, architecture questions.
• Skip confirmations (--dangerously-skip-permissions) — no prompts. Use only in scripts and CI, never interactively.

Switch modes with Shift-Tab or /permissions. The single biggest unlock for complex work is plan mode: type your request, hit Shift-Tab twice, and Claude will plan before acting. You get to review, adjust, and approve before anything runs. I use it for anything that touches more than a handful of files.

CLAUDE.md: why it exists and a basic example

Without a CLAUDE.md, Claude Code has to guess your conventions. With one, it doesn't. That's the entire value prop in one sentence.

A CLAUDE.md file at the root of your repo gets automatically loaded into every session. It's where you tell Claude:

• What this project is
• What stack you use
• What conventions to follow
• What to always do
• What to never do

Here's a starter template for a TypeScript/Next.js project. Drop it in your repo as CLAUDE.md, edit to match your actual conventions, commit it:

# Project: My Next.js app
 
## Overview
Internal dashboard built with Next.js 14 App Router. Small team.
 
## Tech stack
- Next.js 14 (App Router, Server Components by default)
- TypeScript strict mode, no `any`
- Tailwind CSS, no CSS modules
- Vitest for unit tests, Playwright for e2e
- pnpm (never npm or yarn)
 
## Code standards
- Prefer Server Components. Only use "use client" when interactivity requires it.
- Named exports only (defaults are reserved for page/layout files).
- Co-locate tests next to source: `Button.tsx` → `Button.test.tsx`.
 
## Always do
- Run `pnpm typecheck` before claiming a task is done.
- Use `next/image`, `next/font`, `next/link`.
 
## Never do
- Import server-only code from client components.
- Commit `console.log` or commented-out code.
- Add new dependencies without flagging it in the PR.

That's it. Forty lines. Your next Claude Code session will be noticeably better the moment this file exists. I wrote a full deep-dive on how to write a CLAUDE.md file, with longer examples, nested CLAUDE.md patterns, and common mistakes.

5 things to try in your first 10 minutes

Installed, authenticated, CLAUDE.md dropped in? Here are the first five things I want you to try. They'll give you a real feel for what Claude Code can and can't do.

1. Ask Claude to explain a file you don't understand.

Read src/lib/auth.ts and explain what each exported function does. Don't modify anything.

This is the cheapest, lowest-stakes way to experience Claude Code's file reading. It's also immediately useful — great for onboarding to a new codebase.

2. Generate a test for an existing function.

Write comprehensive Vitest tests for the `validateToken` function in src/lib/auth.ts. Cover happy path, expired tokens, malformed tokens, and missing signature.

Watch Claude read the function, read your existing test files to learn conventions, then write a test file that matches. If it doesn't match — go update your CLAUDE.md.

3. Review your current branch.

Run git diff main..HEAD and review the diff. Flag bugs, security issues, and missing tests. Classify by severity.

Claude will use the Bash tool to run git diff, then analyze. This is the workflow I use before every PR.

4. Fix a lint error.

Run pnpm lint. Fix any errors that show up. Don't change behavior.

This is where you start to feel the multi-step loop: Claude runs the command, parses the output, edits files, runs again to verify.

5. Summarize a long log file.

# Exit interactive mode first (Ctrl-D), then:
tail -n 500 ~/.pm2/logs/my-service-out.log | claude -p "Summarize this log. Group errors by root cause. Flag anything unusual."

This is one-shot piping in action. Notice how it fits into your existing terminal habits.

Where to go from here

You now have Claude Code installed, you've run your first agentic session, you understand the permission model, and you've got a basic CLAUDE.md. That's the starting line.

The next steps, roughly in order:

• Tune your CLAUDE.md as you notice Claude getting conventions wrong. Treat it like a linter config — iterate on it. Full guide here.
• Write a few custom slash commands for your repeated workflows. /review-pr, /write-tests, /new-feature are the three I use daily.
• Add your first MCP server — maybe GitHub, or your Postgres instance. This is where Claude Code starts to feel like an extension of your whole development environment, not just your repo.
• Explore the Agent SDK if you want to build custom agents on top of Claude Code's engine. Here's a guide.
• Compare Claude Code to your current tools if you're still on the fence. I wrote an honest comparison with Cursor and Copilot that covers when to use what.

Most of what I know about Claude Code I learned by using it every day for over a year, making every mistake, and tuning my workflow until it felt like a superpower. The shortcut to skip that year is Claude Camp — a 3-day live cohort bootcamp where I teach this end-to-end, hands-on, on your actual codebase.

If you want the whole ecosystem — Claude Code, MCP, the Agent SDK, the Messages API, multi-agent orchestration — taught in order with live practice, that's what it's for. Otherwise, keep playing with it. Make every mistake. Tune your CLAUDE.md. You'll get there.