Get Started with Claude Code

What is Claude Code?

Claude Code might feel like it changes too much too fast, or that you don't understand what it's doing. That's completely normal. Here's the truth before anything else:

You are always in control. Claude Code never changes a file without showing you what it plans to do and asking for your approval first. You can ask it to explain anything. If Claude writes code you don't understand, just ask: "explain what you just did" — it will walk you through it.

Claude Code is an AI coding assistant that runs in your terminal. Unlike a chatbot where you ask questions and get text back, Claude Code can actually read your project files, write and edit code, run commands, and work across multiple files at once.

The key difference from other AI tools: it understands your entire codebase. You don't have to paste code into a chat window and explain the context every time. Claude already knows how your project is structured, what files exist, and how they connect.

Think of it as a very capable colleague sitting next to you who has read every file in your project. You describe what you want in plain English. It works out how to do it, shows you the plan, and only makes changes when you say yes.

Getting Started

Installation

Claude Code has a native installer. Open your terminal and run the appropriate command for your system:

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

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

# Verify it worked
claude --version

If the version command gives an error, close and reopen your terminal first — that fixes most installation issues. You'll need a Claude.ai subscription (Pro, Max, Teams, or Enterprise) or an Anthropic API account. The first time you run claude, it opens a browser window to log you in.

Starting your first session

Navigate to your project folder in the terminal, then start Claude:

cd my-project
claude

You'll see a welcome screen. Claude has already read your project files. Try asking it what the project does:

what does this project do?

Claude will read your files and give you a summary of the codebase. This is a good way to verify it's working and to get oriented in an unfamiliar project.

The permission system

Claude Code never silently edits your files. Before making any change, it shows you what it plans to do and waits for your approval. When Claude wants to edit a file, you'll see a diff — lines in red are being removed, lines in green are being added. You have three options:

• Yes — approve this specific change and continue
• No — skip this change; Claude will try a different approach
• Ask Claude to explain — type your question before approving

For larger tasks, use Plan Mode. Claude maps out everything it intends to do across all files, shows you the full list, and waits for a single approval before touching anything:

/plan
Refactor the authentication module to use JWT instead of sessions.
Identify every file that will change and describe what you'll do to each.

Plan Mode is the single best tool for reducing anxiety about Claude making unexpected changes. Use it for anything bigger than a one-file edit.

Daily working rhythm

The cleanest workflow: do one meaningful task per session. When the task is done, commit the work, close the session, and start fresh for the next task. This keeps context tight and results consistent.

# Starting a session
cd my-project
claude
# Tell Claude what you're working on:
# "I'm adding user profile editing. Start with @src/profile/"

# Before a big task — set a safety net
git add . && git commit -m "checkpoint: before adding rate limiting"
/plan [describe task]
# Review the plan. Ask questions. Only then approve.

# Ending a session cleanly
# Ask: "summarise what we did and what the next step is"
# Paste answer into CLAUDE.md
git add . && git commit -m "feat: add rate limiting"
/clear  # or close terminal

How It Works

You don't need to understand the internals to use Claude Code effectively. But knowing the basics changes how you use it — and explains why it behaves the way it does.

The simple picture: sophisticated autocomplete

Forget the word "AI" for a moment. Start with this: a language model is an extremely sophisticated autocomplete. You give it some text, it tells you what word is most likely to come next. That's the whole job.

Your phone's keyboard does autocomplete too — you type "Happy birth" and it suggests "day." A language model does the same thing, just vastly more powerfully. The difference is scale and training data, not a fundamentally different idea. When Claude "writes code," it is completing a sequence. Every single thing these systems do reduces to: given what came before, what comes next?

Tokens — what Claude actually reads

Computers don't natively understand words — they understand numbers. So the first thing any language model must do is convert text into numbers using a process called tokenization. Text gets chopped into chunks of roughly 3–4 characters each, and every possible chunk gets a number from a big lookup table.

• The word "function" might become the number 12453
• "import numpy as np" might become four tokens: four separate numbers
• About 750 words = roughly 1,000 tokens (a useful rule of thumb)

From this point on, the model never sees text — it only sees a list of numbers. This matters for you because API pricing is per-token: every word you write in a prompt, every line of code Claude reads, every response it generates costs tokens.

The context window — Claude's working memory

Every Claude Code session has a context window — a fixed amount of information it can hold at once. Think of it like working memory. At the start of a session it's empty and sharp. As you chat, every message, every file Claude reads, every response it gives fills that window up.

The three things that fill up context:

• Conversation history — every message you and Claude exchange stays in context until you /clear
• File reads — every time Claude reads a file, that file's contents go into context
• Command output — when Claude runs tests or shell commands, the output is added to context

When context fills up, older content gets pushed out or compressed. Sessions that accumulate thirty messages, dozens of file reads, and multiple test runs behave very differently from fresh ones. This is why quality degrades in long sessions — and why /clear is your most important maintenance habit.

Temperature — why Claude isn't deterministic

At the end of each generation step, the model has a probability score for every possible next token. "return" might be 78% likely, "pass" at 12%, everything else splits the remainder. Temperature controls whether you always pick the most probable option or allow lower-ranked options to occasionally win.

Low temperature (near 0): always the most likely token — deterministic, best for code. High temperature (near 1): samples proportionally from many options — natural variation, useful for creative tasks. Claude Code uses lower temperature for code generation by default, which is why the same prompt tends to produce similar code on repeat runs.

How knowledge gets into Claude

The model was trained on essentially everything ever published on the internet — web pages, books, GitHub, academic papers, Stack Overflow. Nobody programmed "how to write Python" into it. It learned Python because predicting code text accurately requires understanding code deeply. The knowledge is implicit — spread across hundreds of billions of parameters, not stored in any one place.

This also means Claude's knowledge has a cutoff date. For current library documentation, use @URL to give Claude the live docs:

Implement S3 file uploads using the official SDK.
Reference the current docs at @https://docs.aws.amazon.com/sdk-for-javascript/
Don't rely on your training data for this — read the actual docs.

Prompting Effectively

The most important skill with Claude Code isn't knowing commands — it's learning how to describe what you want clearly. Claude is very good at inferring intent, but it's even better when you give it context and explain your reasoning.

The golden rule

Imagine handing your prompt to a smart new team member who has never seen your codebase and has no memory of your last conversation. Would they know exactly what to do? If not, add more context.

Most prompts that produce poor results are missing one or more of these four things:

Weak vs strong prompts

The difference is context and constraints:

# Too vague — Claude will guess at your intent
fix the login bug

# Complete — Claude knows exactly what to do
The login form is throwing a 401 error when the password contains special
characters. Fix it without changing the session management logic.
The relevant files are @src/auth/login.js and @src/middleware/session.js.

# Too vague
add a forgot password feature

# Complete
Add a forgot password flow. Users enter their email on /auth/forgot, receive
a link via SendGrid (already configured), and the link opens /auth/reset?token=xxx
where they set a new password. Use the existing User model. Don't touch the
login page. Show me the plan first.

Prompt techniques that consistently work

1. Ask it to plan before it acts. For anything that touches more than one file, ask Claude to show you its plan before making a single change. This is the single highest-value habit.

/plan
Refactor the authentication module to use JWT instead of sessions.
Identify every file that will change and describe what you'll do to each one.

2. Tell it what not to do. Claude is thorough and might refactor surrounding code, rename variables for consistency, or clean up things you didn't ask about. If you want surgical changes, be explicit:

Fix the email validation in the signup form.
Only change the validateEmail function. Do not touch anything else in this file.
Do not rename any variables or reformat the code.

3. Use examples to show what you want. One good example is worth ten adjectives:

Write a new API endpoint for orders. Follow the same pattern as the existing
products endpoint in @src/api/products.js — same error handling, same response
shape, same middleware order.

4. Break large tasks into steps. Giving Claude five tasks at once produces messier results than five clean sequential tasks. After each step, review and commit before giving the next one.

5. Give Claude permission to say it doesn't know. Claude will sometimes fill gaps with plausible-but-wrong answers. Add this line to prompts where accuracy matters:

If you're not sure about any part of this, tell me rather than guessing.
I'd rather know what you're uncertain about than get confident-sounding wrong code.

6. Use interview mode for complex features. For large features where you're not sure what's needed, ask Claude to interview you before writing anything:

Referencing specific files

You can point Claude directly at a file using the @ symbol. This keeps context lean and focuses Claude on exactly what matters:

look at @src/auth/login.js and explain what the token refresh logic does

The bug is in the checkout flow. The relevant files are:
@src/api/checkout.js
@src/models/Cart.js
@src/utils/pricing.js
Don't read anything else unless you need to.

Front-load your constraints

Start your prompt with the most important context. Claude reads prompts top-to-bottom, and constraints buried at the bottom carry less weight:

CLAUDE.md — Your Project's System Prompt

Every time you start a new Claude Code session, Claude starts fresh — it re-reads your files but has no memory of your past conversations, preferences, or the decisions you've made. CLAUDE.md solves this.

CLAUDE.md is a plain text file that lives at the root of your project. Claude reads it automatically at the start of every session. Think of it as a one-page onboarding document for a new developer who joins your project — except this developer reads it perfectly every single time.

In AI terms, CLAUDE.md is your "system prompt" — the persistent set of instructions that shape how Claude behaves throughout the session, before you've typed a single word. Getting this right is one of the highest-leverage things you can do.

How to create it

Claude Code can generate a starter version for you by analyzing your project:

/init

Claude analyzes your build system, test framework, file structure, and common patterns, then writes a draft. Read it, trim anything obvious, add your own rules.

The template that works

Keep it short — under 60 lines if possible. When it gets too long, Claude starts to skim it. Important rules get missed. Every line should be something Claude would NOT know just by reading your code:

The session handoff routine

This habit makes resuming work feel seamless. At the end of every work session, before you close Claude Code:

Next session, Claude reads CLAUDE.md first thing and knows exactly where you left off. Your opening prompt can be as simple as: "Continue where we left off. The current state is in CLAUDE.md."

What kills a CLAUDE.md

• Too long: Once CLAUDE.md exceeds 60–80 lines, Claude starts to skim it. Delete the obvious things Claude can already infer from your code.
• Too vague: Instructions like "write clean code" do nothing. Claude already tries to do that. Every line should be something Claude would NOT know without being told.
• Never updated: A stale CLAUDE.md with outdated commands or wrong file paths actively misleads Claude. Update it whenever something significant changes.
• Old handoff notes: Delete the "Current work in progress" section once the task is fully done and merged. Don't let CLAUDE.md become a graveyard of old notes.

Working with Git

Git feels scary because you're worried about breaking the team's code, or creating a mess someone else has to clean up. That fear is completely normal. Here's the truth: you always work on your own branch, your code is completely separate from everyone else's until you deliberately merge it, and git saves everything — there is almost no action in git that cannot be undone.

The mental model

Think of git as a very detailed "track changes" for your entire project. Every time you tell git to save (a "commit"), it takes a snapshot of everything. You can go back to any snapshot at any time.

Git thinks about files in three zones:

Run git status constantly — it tells you which zone everything is in and what to do next. Think of it as "look at the map before you walk."

The daily save loop

Git does not automatically save your changes — you have to tell it to. Think of it like sending a package: stage = put items in the box, commit = seal and label it, push = send it to GitHub.

Write commit messages as if finishing the sentence "This commit will…" — "add user login form," "fix broken header on mobile." Avoid vague messages like "stuff," "changes," "fix," "wip."

Always work on a branch

Never work directly on main. Always create a branch for your work:

Good branch names: feature/signup-page, fix/broken-button, update/homepage-text. Avoid: test, my-branch, changes, stuff.

Git is your safety net for Claude

The rule: commit before you give Claude a large task. If Claude's changes aren't what you wanted, you can always reset to your last commit. Without a commit, undoing changes is much harder.

Merge conflicts — what they actually are

Merge conflicts sound frightening but are just git asking a question: "two people changed the same line — whose version do you want?" That's all they are. When you see conflict markers:

Between <<<<<<< and ======= is your version. Between ======= and >>>>>>> is their version. Delete the markers and keep the version you want (or blend both). Then: git add . followed by git commit.

You can ask Claude to help with merge conflicts: "there's a conflict in auth.js — help me resolve it." Claude reads both versions, understands the intent, and suggests a sensible merge. You still approve the result.

Stash — switching tasks without losing work

You're mid-feature and suddenly need to switch branches. Stash is a temporary drawer for your work:

Skills & MCP Servers

A language model, by itself, is completely isolated from the world. It cannot look at a clock. It cannot read a file you haven't pasted in. It cannot check whether the code it just wrote actually runs. It cannot search the web. Tools and MCP servers are what break these limitations — one at a time, explicitly, under your control.

How tools actually work

Here's the exact physical sequence when Claude "uses a tool": the model generates its response one token at a time and at some point produces a structured block saying "I want to call this function with these arguments." The API intercepts this, stops generating, returns to you. Your code actually executes the function. Then the result gets fed back to Claude as the next message, and it continues.

The critical insight: the model never calls anything. It outputs text that looks like a function call. Your code (or the Claude Code harness) reads that text, executes the real function, and feeds the result back. "Tool use" means the model is writing a note that says "please use this tool on my behalf," and you are the one who actually uses it.

Skills (slash commands)

A skill is a reusable instruction set that you activate with a slash command. Instead of typing the same long prompt every time you do a code review, you install a skill and type /code-review. Skills live in ~/.claude/skills/ as markdown files. You can write your own or install community ones.

MCP Servers

MCP (Model Context Protocol) servers give Claude new capabilities by connecting it to external systems. Think of MCP as a standardized plug format — you connect a server once and Claude can use it like any other tool.

• GitHub MCP — Claude can create PRs, read issues, and manage repos directly
• Context7 — Claude gets live library docs injected into every prompt; no more hallucinated APIs
• Playwright MCP — Claude can control a real browser, fill forms, take screenshots
• Memory MCP — persistent knowledge graph across sessions; Claude remembers things between restarts
• Filesystem — secure sandboxed file access beyond the current directory

Parallel tool calls

Modern Claude can output multiple tool calls in a single response when the results don't depend on each other. When you ask Claude to "compare auth.py with test_auth.py," it reads both files simultaneously rather than sequentially — cutting latency roughly in half. This happens automatically; you don't need to configure it.

Advanced Patterns

Context engineering

For the first two years of AI tools, the dominant skill was prompt engineering: how to write the system prompt to get the behavior you want. This framing breaks for agents. An agent operating over many steps generates more and more data at each step — tool results, observations, error messages. By step 20 of a 40-step task, the model is reading thousands of tokens of accumulated history that may have nothing to do with what it needs to do right now.

Context engineering is the art of curating and maintaining the optimal set of tokens during inference — keeping the right information in the window at the right time.

Research shows models pay more attention to the beginning and end of long contexts than the middle. Information stuffed into the middle of a long context receives disproportionately low attention weight — even if it's important. This is not a bug — it's a structural property of how transformers compute attention. Adding more context does not reliably improve performance; beyond a point it actively degrades it.

The practical principle: just-in-time context. Instead of pre-loading everything that might be relevant, give Claude lightweight references — file paths, query specs, URL pointers — and let it load content on demand. Claude Code already works this way by default.

Multi-agent workflows

An "agent" is Claude with permission to take actions autonomously — reading and writing files, running commands, making decisions — without asking for approval on every step. Multi-agent workflows run several specialized agents in parallel or sequence to tackle complex tasks.

When Anthropic built a multi-agent research system, they found two consistent failure modes without the right infrastructure:

• One-shotting: the agent tries to implement everything at once rather than working incrementally, runs out of context mid-implementation, and produces a half-finished system.
• Premature completion: after implementing some features, the agent "looks around," sees partial progress, and declares the task complete.

Both failures have the same root cause: the agent had no external representation of "what needs to be done" and "what is actually done." The fix is explicit scaffolding:

Key principles for safe agentic work:

• Always work on a branch, never main, when running autonomous agents
• Set a clear stopping condition — "stop when tests pass" or "stop after implementing feature X"
• Maintain a feature list file so the agent knows what's done and what's next
• Use /plan before execution for anything that touches more than five files
• Review the diff before merging any agent-generated changes

The "think" tool and extended thinking

For hard problems that benefit from careful reasoning before acting, Claude has two modes:

• Extended thinking — Claude generates private reasoning tokens before the visible response. The thinking is hidden from you but the model uses it to explore dead ends and verify reasoning before committing to an answer. Enable with Option+T (Mac) or Alt+T (Windows/Linux). Adds latency and cost — use for genuinely hard problems.
• Chain-of-thought — you explicitly ask Claude to reason step by step before answering. The reasoning appears in the visible response. No extra cost or configuration: just add "think step by step" or "explain your reasoning before writing any code."

Managing long-horizon tasks

For tasks spanning multiple sessions — large refactors, feature-complete implementations — the approach that works is treating git and progress files as the agent's memory:

When conversation history is automatically compacted, specific details from early in the session are lost. If any piece of information is genuinely critical for the whole task, don't rely on it surviving compaction — write it to a file that can be re-read when needed.

Saving Money

Claude Code is powerful but not free. You pay for every token sent to and received from the Anthropic API. Understanding where the money goes is the first step to reducing costs.

The big cost drivers

• Your system prompt (CLAUDE.md) — sent on every single request. A 500-token CLAUDE.md at 200 requests per day adds up fast.
• Long conversations — the entire history is re-sent each turn. An hour-long session can have 50,000+ input tokens by the end.
• Reading large files — Claude reading a 1,000-line file costs 10,000+ tokens.
• Agent loops — many round trips, each with accumulated context.
• Tool definitions — a large MCP server might contribute 50,000 tokens of tool definitions before Claude reads a single user message.

Free savings (habits)

• Use /clear frequently — fresh context costs far less than accumulated context
• Point Claude to specific files — "look at @src/auth.ts" costs less than "look at all my files"
• Keep CLAUDE.md concise — every extra word costs money, multiplied by every request
• Ask for plans, not implementations — text is cheap, code generation is expensive
• Remove unused MCP servers — each one adds token overhead to every request

Prompt caching

Anthropic offers prompt caching — if you send the same prefix (your CLAUDE.md) repeatedly, they cache it server-side and charge you only 10% of the normal price for cached tokens. The catch: you have to opt in and send the right cache-control headers with every request. Claude Code doesn't do this automatically. Most users never set it up.

Model selection

Claude Sonnet is the default — it's the best at coding. But not every task needs it. Use smaller models for simple work:

• Sonnet — complex code, architecture decisions, debugging hard problems
• Haiku — simple questions, formatting, documentation, repetitive tasks (~10x cheaper)

Rough cost estimates

Quick Reference

Slash commands

Keyboard shortcuts

Prompting quick reference

Git quick reference

Common frustrations and fixes

File structure reference