Claude Code Field Guide

CHAPTER 01

What Claude Code is, and how it differs from chat

Claude Code is a command-line tool that puts Claude inside your project. Instead of pasting code into a chat window, you open a terminal in your repository and describe what you want. Claude reads your files, runs commands, edits code, runs the tests, and reports back. You watch, redirect, or walk away.

The mental shift is this: a chatbot answers questions and waits. Claude Code is an agent. It works in a loop of read, think, act, check, and keeps going until the task is done or it needs you. That autonomy is why it's useful, and it's also why the rest of this guide spends so much time on how to give it good instructions and how to keep it on a leash you're comfortable with.

You'll interact with it through a single prompt line in your terminal. Three prefixes matter from day one:

Claude Code also exists as a desktop app, a VS Code and JetBrains extension, a web version, and a GitHub Action. This guide sticks to the terminal because everything you learn there transfers to the others.

CHAPTER 02

Install and log in

You need a terminal, a project to work in, and either a Claude subscription (Pro, Max, Team, or Enterprise) or a Claude Console account with API credits. The native installer is the recommended route and updates itself in the background.

1. Run the installer for your platform
   macOS, Linux, WSL

   $ curl -fsSL https://claude.ai/install.sh | bash

   Windows PowerShell

   PS> irm https://claude.ai/install.ps1 | iex

   Prefer a package manager? brew install --cask claude-code on macOS or winget install Anthropic.ClaudeCode on Windows both work, but they don't auto-update, so remember to upgrade occasionally. On Windows, install Git for Windows too so Claude gets a real Bash shell.

2. Confirm it worked

   $ claude --version
   2.1.xxx (Claude Code)

3. Open your project and start Claude

   $ cd ~/projects/my-app
   $ claude

   The first launch opens your browser to sign in. Once you're through, credentials are stored and you won't be asked again. If you ever need to switch accounts, type /login inside a session.

CHAPTER 03

Your first session

Above the prompt you'll see the version, the current model, and the working directory. Start by asking questions. Claude reads whatever files it needs; you don't have to feed them in.

> what does this project do?

This is a Flask API for managing bookings. The entry point is app.py,
routes live in routes/, and models/ holds the SQLAlchemy models. Tests
run with pytest from tests/. There's a Dockerfile for deployment...

> where is the main entry point?
> explain the folder structure
> how is authentication handled?

Now make a change. Describe the outcome, not the keystrokes:

> add a hello world function to the main file

Claude finds the right file and shows you the edit as a diff. Depending on your plan and permission mode (Chapter 5), it will either ask you to approve the change or just make it. Either way you see exactly what happened.

A realistic first task

Pick something small you actually need done. The prompts below are the shape to aim for: a location, a behavior, and what "done" looks like.

> there's a bug where users can submit empty forms. find where the
  registration form is validated and fix it, then run the tests

> write unit tests for the functions in utils/dates.py, following the
  style of the existing tests in tests/

> update the README with installation instructions

For each of these, Claude will locate the relevant code, read enough surrounding context to understand it, make the change, and run tests if it can find them.

Leaving and coming back

Type /exit or press Ctrl+D twice to quit. Every conversation is saved locally, so you can pick up later without re-explaining anything:

$ claude -c       # continue the most recent session in this folder
$ claude -r       # pick from a list of previous sessions

Inside a session, /resume does the same thing. If you name sessions with /rename, the list is much easier to search later.

CHAPTER 04

Talking to Claude well

Claude can infer a lot, but it can't read your mind. The single biggest lever you have is specificity: which file, which scenario, what constraint, what a good result looks like. Compare:

Vague prompts aren't wrong when you're exploring. "What would you improve in this file?" can surface things you'd never think to ask. Just expect to course-correct afterward.

Give Claude a way to check its own work

This is the practice that separates a session you babysit from one you can walk away from. Claude stops when the work looks done. If you give it something that returns pass or fail (a test suite, a build, a linter, a script that compares output), it will run the check, read the result, and iterate until it passes.

> write a validateEmail function. test cases: user@example.com is
  valid, "invalid" is not, user@.com is not. run the tests after
  implementing and fix any failures

Ask for evidence rather than assertions: the test output, the command it ran, a screenshot. Reading evidence is faster than re-running things yourself.

Point at files with @

Type @ and a path menu opens. Pick a file and its full contents go into the message before Claude answers. A directory reference gives a file listing, not contents.

> explain the logic in @src/utils/auth.js
> what's the structure of @src/components?
> make @api/orders.py follow the same error handling as @api/users.py

Run shell commands with !

Start a line with ! to run a command yourself. The output lands in the conversation, so Claude can respond to it.

> !npm test
... 3 failing ...
> fix those three failures

Paste images, pipe data

Drag an image into the terminal, or paste one with Ctrl+V (Alt+V on Windows and WSL). Screenshots of errors, design mockups, and diagrams all work. You can also pipe anything in from the shell:

$ cat error.log | claude
$ git log --oneline -20 | claude -p "summarize these recent commits"

Ask Claude about Claude Code

Claude always has the latest documentation for itself. When you're unsure how something works, just ask: "how do I use MCP with Claude Code?" or "can Claude Code create pull requests?" For an interactive walkthrough with animated demos, run /powerup.

CHAPTER 05

Permissions and plan mode

A permission mode sets what Claude may do without asking you first. You can change it at any moment by pressing Shift+Tab; the current mode is shown in the status bar.

On Pro, Max, and Team plans, interactive sessions start in auto mode: a second model reviews each action and blocks only what looks risky, such as scope escalation or unknown infrastructure. On other plans, sessions start in Manual mode. There's also a bypassPermissions mode that skips every check; it belongs only inside a disposable container or VM.

Plan mode: explore, then plan, then code

Letting Claude jump straight into editing is how you end up with a clean solution to the wrong problem. For anything non-trivial, use plan mode to separate thinking from doing:

1. Enter plan mode with Shift+Tab until the status bar shows ⏸ plan mode on, or type /plan, or launch with claude --permission-mode plan.
2. Explore. "Read src/auth and understand how we handle sessions and login. Also look at how environment variables hold secrets." Claude reads and answers, but changes nothing.
3. Ask for a plan. "I want to add Google OAuth. What files need to change? What's the session flow? Create a plan." Press Ctrl+G to open the plan in your editor and edit it directly.
4. Approve and implement. Approve the plan (or press Shift+Tab to leave plan mode) and say: "implement the OAuth flow from your plan. write tests for the callback handler, run the suite, and fix failures."

Fewer prompts without giving up control

In Manual mode you'll be asked before every write and shell command, and after the tenth approval you're clicking through rather than reviewing. Two tools cut the interruptions: /permissions lets you pre-approve specific things you trust, such as npm run lint or git commit, and /sandbox turns on OS-level isolation so commands can run freely inside defined boundaries.

CHAPTER 06

Steering and undoing

Conversations are persistent and reversible, and the best results come from tight feedback loops. Correct Claude the moment you see it drift, not after it has finished.

Why context management is the whole game

Claude's context window holds your entire conversation: every message, every file it read, every command's output. It fills up faster than you'd expect, and as it fills, Claude gets worse: it starts forgetting earlier instructions and making more mistakes. Almost every best practice traces back to this one constraint.

Run /context at any time to see a colored grid of what's using space. Claude compacts automatically as you approach the limit, but you'll get better results by staying ahead of it: /clear between unrelated tasks, and scope investigations narrowly so Claude doesn't read three hundred files looking for something.

Checkpoints aren't git

Rewind restores files that Claude changed through its editing tools. It doesn't capture changes made by shell commands or other programs. It's a safety net for experimenting ("try the risky approach; if it doesn't work I'll rewind"), not a replacement for committing your work.

CHAPTER 07

Git, tests, and pull requests

Git becomes conversational. Claude runs the underlying commands and shows you what it did.

> what files have I changed?
> create a new branch called feature/booking-limits
> commit my changes with a descriptive message
> show me the last 5 commits
> help me resolve the merge conflicts in routes/bookings.py

Install the GitHub CLI (gh) if you use GitHub. Claude knows how to use it to open pull requests, read issues, and respond to review comments. Without it, Claude falls back to the raw API and tends to hit rate limits.

> summarize the changes I've made to the booking module
> create a pr
> enhance the PR description with more context about the rate limiting

Review the PR before you submit it, and ask Claude to call out risks: "what could this change break?" Later, claude --from-pr 1234 reopens the session that created a PR.

A full feature, start to finish

Here's what a complete cycle looks like once the pieces are in place. Notice each prompt tells Claude how to verify its own work.

> we need to cap each user at 10 active bookings. read models/booking.py
  and routes/bookings.py and propose a plan. don't change anything yet

Plan: 1) add a MAX_ACTIVE_BOOKINGS constant... 2) check the count in
create_booking before insert... 3) return 409 with a clear message...
4) tests for the boundary at 9, 10, and 11...

[ approve plan · Shift+Tab to leave plan mode ]

> implement it. run pytest tests/test_bookings.py and fix any failures
> commit with a descriptive message and open a PR

Working on two things at once

Each session in a repo shares the same working directory, so two sessions editing the same files collide. Worktrees fix that by giving each session its own checkout on its own branch:

$ claude --worktree feature-auth      # terminal 1
$ claude --worktree fix-flaky-test   # terminal 2

A useful pattern once you're comfortable: have one session write code and a second, fresh session review it. A reviewer that didn't write the code is far less forgiving of it.

CHAPTER 08

CLAUDE.md: give your project a memory

Every session starts with a fresh context window. CLAUDE.md is a plain markdown file that Claude reads at the start of every conversation. It's where you write down what you'd otherwise re-explain each time: the build commands, the conventions, the gotchas.

Generate a starting point and refine from there:

> /init

Claude analyzes your codebase and writes a first draft with the build commands, test instructions, and conventions it can discover. Then add the things it can't discover. A good project CLAUDE.md looks something like this:

# Commands
- Run tests: `pytest -x` (single file: `pytest tests/test_x.py`)
- Type check: `mypy .` before committing
- Start dev server: `flask --app app run --debug`

# Code style
- Use f-strings, not `.format()`
- Routes return `jsonify(...)`; never return raw dicts
- Prefer running single test files, not the whole suite

# Workflow
- Branch names: `feature/short-name` or `fix/short-name`
- Never commit directly to main
- The bookings tests need a local Redis running on 6379

Where it lives

All of these are loaded together. If you launch Claude in a subfolder, it also reads any CLAUDE.md in the folders above it, and it picks up ones in subfolders as it works there. Run /context and check the "Memory files" list to confirm what loaded, or /memory to open and edit them.

What to include, what to cut

CLAUDE.md is context, not configuration. Claude reads it and tries to follow it, and the longer and vaguer it gets, the less reliably that happens. Aim for under 200 lines. For each line, ask: would removing this cause Claude to make a mistake? If not, cut it.

Be concrete enough to verify. "Use 2-space indentation" works; "format code properly" doesn't. If Claude keeps ignoring one particular rule, add "IMPORTANT" to that line alone. If you emphasize everything, nothing stands out.

Add to it whenever Claude makes the same mistake twice, or when you type the same correction you typed last session. You can ask Claude to do the writing: "add this to CLAUDE.md."

CHAPTER 09

Commands and shortcuts you'll actually use

Type / on an empty line to see everything available, and ? on an empty line to toggle the shortcut help panel. This is the subset worth memorizing.

From your shell

Inside a session

Keyboard

You can queue messages while Claude is working: just keep typing and press Enter. They're sent in order when Claude finishes its current step.

CHAPTER 10

Extending it: skills, hooks, and MCP

You won't need any of these in your first week. When you do, here is what each one is for, in one line each: skills are reusable instructions you invoke by name; hooks are shell commands that run automatically at fixed moments; MCP servers connect Claude to outside tools like GitHub, Notion, or a database. Plugins bundle any of these for easy installation.

Skills

A skill is a folder containing a SKILL.md. Put it in .claude/skills/ for one project or ~/.claude/skills/ for all of them. Claude applies a skill automatically when its description matches what you're doing, or you invoke it directly with /skill-name.

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.

1. Use `gh issue view` to get the issue details
2. Search the codebase for relevant files
3. Implement the fix
4. Write and run tests to verify it
5. Commit with a descriptive message, push, and open a PR

Now /fix-issue 1234 runs the whole workflow. The disable-model-invocation: true line means only you can trigger it, which is what you want for anything with side effects.

Hooks

CLAUDE.md instructions are advisory. Hooks are guaranteed: they're shell commands Claude Code runs at specific lifecycle events, whether or not Claude would have chosen to. Use them for things that must happen every time with no exceptions. This one formats every file Claude edits:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Other common events are PreToolUse (validate or block an action before it runs), Stop (run a check before Claude declares a task finished), and Notification (ping you when Claude is waiting). You don't have to write them by hand. Try: "write a hook that runs eslint after every file edit" or "write a hook that blocks writes to the migrations folder." Run /hooks to see what's configured.

MCP servers

MCP (Model Context Protocol) is how Claude talks to external services. Once a server is connected, Claude can query your issue tracker, read a Figma file, or run SQL against your database as part of a task.

$ claude mcp add --transport http notion https://mcp.notion.com/mcp
$ claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
    --header "Authorization: Bearer YOUR_GITHUB_PAT"
$ claude mcp list
$ claude mcp remove notion

Add --scope project to save a server into a .mcp.json file you can commit and share with your team. Inside a session, /mcp shows connection status and handles sign-in for servers that use OAuth. Reference a server's data directly with @github:repos/owner/repo/issues.

Before reaching for MCP, check whether a command-line tool already exists. gh, aws, gcloud, and similar CLIs are the most context-efficient way for Claude to work with a service, and Claude is good at learning unfamiliar ones from --help.

Subagents

When Claude explores a big codebase, every file it reads eats your context. Say "use a subagent to investigate how our auth system handles token refresh" and the exploration happens in a separate context window; only the findings come back. The same trick works for review: a subagent that sees only the diff, not the reasoning that produced it, is a more honest critic.

CHAPTER 11

Habits that pay off

These come from Anthropic's own engineering teams and from people using Claude Code across many languages and codebases. None of them are rules; they're defaults that work until you know better.

• Give Claude a check it can run. Tests, a build, a screenshot to compare. It's the difference between a session you watch and one you walk away from.
• Explore, plan, then code. Plan mode for anything you couldn't describe as a one-line diff.
• Be specific. Name the file, the scenario, the constraint, and what done looks like.
• Course-correct early. Esc the moment it drifts. After two failed corrections, /clear and rewrite the prompt.
• Clear between tasks. Irrelevant context makes Claude worse. /clear is free.
• Keep CLAUDE.md short and true. Prune it when things go wrong. Check it into git so it compounds.
• Ask the questions you'd ask a senior engineer. "How does logging work here?" "Why does this call foo() instead of bar()?" No special prompting needed.
• For big features, get interviewed first. "I want to build X. Interview me in detail about implementation, edge cases, and tradeoffs, then write a complete spec to SPEC.md." Then start a fresh session to build it.

Failure patterns to recognize

CHAPTER 12

Where to go next

You now know enough to be productive. The fastest way to get better from here is to use it on real work and notice what happens: when the output is great, look at what you did (the prompt, the context, the mode); when it struggles, ask whether the context was noisy, the prompt vague, or the task too big for one pass.

• Quickstart and Common workflows: the official recipes this guide draws on.
• Best practices: the long-form version of Chapter 11.
• CLAUDE.md and memory, Permission modes, Keyboard reference.
• Skills, Hooks, MCP: when you're ready to extend it.
• Inside a session: /powerup for interactive lessons, /tips for something new each time, and just ask Claude "how do I...".