Claude Code: The Complete Guide

Claude Code is Anthropic's agentic coding CLI: a terminal tool that reads your repository, edits files, runs shell commands, and works through multi-step tasks instead of only completing the current line. This guide covers what it actually does session to session — installation, CLAUDE.md, plan mode, hooks, MCP, subagents, and memory — built from running it in production on the Next.js repository this site itself is written in, including the two mistakes in that repo's own configuration that had to be caught and fixed.

Key takeaways

• Claude Code works through visible tool calls — Read, Edit, Bash, and others — that you review before they run, not a black box that silently rewrites files.
• CLAUDE.md is delivered as a user message the model reads, not enforced configuration; a hook is the only mechanism that guarantees an action happens every time.
• Plan mode separates "figure out the approach" from "write the code," and is the highest-leverage habit for any task with more than one reasonable way to solve it.
• Subagents fork a task into an isolated context so exploratory tool output doesn't fill the main session's context window.
• MCP servers and hooks extend what Claude Code can reach and what it's forced to do, respectively — they solve different problems and aren't interchangeable.

What is Claude Code

Claude Code is a command-line tool, not an IDE plugin — you run claude from a project's root directory and interact with it in plain English inside the terminal you already use. Under the hood, every action it takes is a discrete tool call: reading a file, editing a file, running a bash command, searching the codebase. Each of those calls is visible in the session, which is the mechanical reason a Claude Code session reads more like a pair programmer narrating its steps than an autocomplete engine guessing your next token.

That tool-call model is what makes Claude Code agentic rather than merely generative: it can run npm run typecheck after an edit, read the error, and fix the specific line that failed, in one uninterrupted task — without you copy-pasting output back into a chat window. The trade-off is that it needs real information about your specific project to do that well, which is what CLAUDE.md exists to supply.

Most of what makes a Claude Code guide useful isn't the CLI's basic command surface — that part is small enough to learn in one session. It's the handful of configuration layers that determine whether a given session produces expert-level output or a plausible-looking first draft: how much project context it starts with, whether it stops to confirm an approach before writing code, and which rules are actually enforced versus merely suggested. The rest of this guide works through each of those layers in the order they matter in practice.

Installing and starting a Claude Code session

Claude Code installs as a CLI and runs from your terminal against the current working directory, so the first real decision is where you launch it from — typically a project's root, so it has the whole repository in scope. On a brand-new project, the first command worth running is /init, which scans the repo and drafts a starting CLAUDE.md from what it can infer: the package manager, the test command, the obvious framework. That draft is a starting point, not a finished file — see how to set up CLAUDE.md for the structure that survives real use instead of just the first session.

From there, a session is conversational: describe the task, Claude proposes and takes action, you review the diff. Multi-step tasks — "add a field, migrate the schema, update the three call sites" — run inside one session with the model tracking its own progress, rather than requiring you to restate context after every single file.

Claude Code also runs non-interactively, in a print mode built for scripts rather than a live terminal conversation — the mechanism that makes it usable inside a CI job instead of only an interactive session you drive by hand. That's a different operating mode from everything else in this guide: no back-and-forth, no plan-mode confirmation, just a single prompt in and a result out, which is why it needs tighter scoping and more guardrails than an interactive session does. Connecting Claude Code to a deployment pipeline covers what that setup actually looks like.

CLAUDE.md: the file Claude Code reads first

CLAUDE.md is a markdown file at your project root that Claude Code loads automatically at the start of every session, holding the facts it can't infer from the code itself — build commands, architectural decisions, and traps specific to your repository. It's delivered as a message Claude reads, not compiled configuration, so adherence is probabilistic rather than absolute: a vague instruction like "write clean code" competes for attention with everything else in context, while a specific one — "never build while the dev server is running, it corrupts the chunk manifest" — tends to get followed because it's concrete and actionable.

The CLAUDE.md running this exact site is 135 lines across ten sections, and two of the instructions that made it into that file exist because Claude Code got something wrong first: a real next build run against a live next dev server once took every route down with a 500 error that looked exactly like an application bug, and a markdown image syntax that silently produced a build-time error until the rule banning it went into the file. See the mistakes worth avoiding in a CLAUDE.md file for the fuller pattern — a rule that exists because something specific broke is worth more than a rule written speculatively.

Plan mode: when to use it

Plan mode makes Claude Code propose an approach and stop before writing any code, so you approve the plan instead of reviewing a diff after the fact. It's the difference between catching a wrong architectural assumption in a two-sentence plan versus catching it in a 400-line diff you now have to unwind. Use it whenever a task has more than one reasonable way to solve it — a refactor, a new feature that touches several files, anything where "just start editing" risks committing to the wrong shape before you've seen it stated plainly.

Skip plan mode for genuinely mechanical work — a one-line bug fix, a rename, a config value change — where there's exactly one correct edit and a plan step just adds a round trip. The full decision rule, including how plan mode interacts with a large CLAUDE.md and when it's worth forcing even for small tasks, is in Claude Code plan mode: when and how to use it.

Slash commands and skills

Slash commands are shortcuts for repeatable prompts — typing /init or a project-defined command runs a pre-written instruction instead of you retyping it every session. Skills go further: a skill is a packaged set of instructions for a specific kind of task that Claude loads into a turn when the request matches what the skill covers, rather than you having to remember and paste the right process every time. Both exist to keep a team's repeatable workflows consistent across sessions and across different people running Claude Code against the same repository.

Subagents: forking work without losing context

A subagent runs a task in an isolated context that inherits the parent session's understanding but keeps its own tool output — file reads, search results, command output — out of the main conversation. That matters because context is finite: a broad, exploratory search across a large codebase can produce far more raw output than the final answer actually needs, and running it as a subagent means only the distilled result comes back, not every intermediate grep.

The practical rule is to fork when you want the answer but not the paper trail — an open-ended "where does X happen and why" question benefits from a subagent; a task where you'll need the exact tool output again later usually doesn't. Subagents can also run in parallel when the questions they're answering don't depend on each other, which is where the context savings compound: three independent investigations run as three forks return three short summaries instead of three long transcripts stacked into one session.

Hooks: automation Claude cannot skip

A hook is a shell command that the harness runs automatically in response to an event — a tool call, a session start, a specific trigger — independent of anything the model decides in that moment. That distinction matters because CLAUDE.md is a request the model usually follows, while a hook always fires. If a rule must hold without exception — a formatter that always runs after a file edit, a check that always blocks a specific command — a hook enforces it in a way a written instruction in CLAUDE.md structurally cannot, because CLAUDE.md competes with everything else in the context window for the model's attention.

Hooks and CLAUDE.md rules aren't competing mechanisms — they're suited to different failure modes. A rule that Claude usually gets right on its own belongs in CLAUDE.md, where it costs nothing to state and adds useful context around the edge cases. A rule that would be genuinely bad if skipped even once — running a formatter, blocking a destructive command, refusing a push to a protected branch — belongs in a hook specifically because it doesn't depend on the model choosing correctly in the moment.

MCP and connecting external tools

The Model Context Protocol (MCP) is how Claude Code connects to external tools and data sources beyond what the base CLI ships with — a database, an internal API, a project management tool — exposed as additional tools the model can call in the same way it calls Read or Bash. Where a hook enforces that something always happens, an MCP server extends what Claude Code can reach in the first place; a project that needs both usually configures them for different problems rather than picking one over the other.

An MCP server is configured once per project or once per machine, then shows up as regular tools inside every session from then on — the model doesn't need to be told an MCP tool exists, it discovers it the same way it discovers Read and Bash. The judgment call is scope: connecting a database MCP server with write access to a production database is a materially different risk than a read-only docs lookup, and that risk lives in what the server itself is allowed to do, not in anything Claude Code's configuration controls.

Memory: what persists between sessions

CLAUDE.md is written by a human and loaded every session unchanged. A separate memory system lets Claude accumulate its own learnings across sessions — corrections a user gave, preferences confirmed by repeated approval — stored per project and summarized into an index file that loads alongside CLAUDE.md at the start of a new session. The distinction worth internalizing: CLAUDE.md is what you decided the model should always know; memory is what the model has learned from working with you specifically, and both are context rather than enforced configuration.

Claude Code pricing and plan tiers

Claude Code is included starting at Claude Pro, not on the free tier — Anthropic's own pricing page lists it as a Pro-and-above feature, alongside session limits that scale by tier. The exact numbers, including where Max's 5x and 20x tiers diverge and what a five-hour session limit means for a working day, are covered in what AI coding assistants actually cost rather than repeated here, since pricing changes fast enough that maintaining it in two places guarantees one of them goes stale.

Claude Code vs Cursor and Copilot

Claude Code's core difference from Cursor and Copilot is the interface it runs in: a terminal-first CLI against your whole repository, versus an IDE-embedded experience optimized for inline, file-scoped edits. That's not a value judgment — it's a workflow fit question, and the honest answer depends on the shape of the work. Cross-repo refactors, migration tasks, and anything that benefits from running real commands as part of the task lean toward Claude Code's model. Tight, visual, file-at-a-time iteration — watching a diff render inline as you nudge it — leans toward an editor-native tool like Cursor. The full breakdown, including where each one's workflow actually broke down in real use, is in Claude Code vs Cursor: terminal vs editor workflows.

Real mistakes running Claude Code in production

Two failures from this exact repository are worth stating plainly, because a guide that only shows what worked isn't credible. The first: running next build while next dev was still active silently corrupted the shared .next chunk manifest, and every route — including public pages that had nothing to do with the change being built — started returning 500 errors. It looked exactly like an application bug for the better part of an hour before the actual cause (two processes writing to the same build directory) was identified. That failure is now a standing rule in the project's own CLAUDE.md, specifically so it can't happen twice.

The second: next-mdx-remote v6 in RSC mode silently drops any JSX attribute written as an expression — width={1200} arrives as undefined with no warning, no error, just a component silently missing a prop it needed. The fix was mechanical once found — write width="1200" as a string — but finding it required noticing a layout shift that had no accompanying error message anywhere in the build output. Both mistakes are now written into the project's own standards specifically because they're the kind of failure that looks like something else until you've hit it once.

A worked example: shipping a change end to end

The production pattern behind this exact article is a reasonable stand-in for how a multi-step Claude Code task runs in practice. Content on this site follows a fixed pipeline: a roadmap document decides what gets written and in what order, a second standards document decides how, and every article is checked against both before it ships. That's not a hypothetical process description — it's the literal sequence this article was produced under, and it maps directly onto how Claude Code handles any task with more than one correct-looking output.

The session starts by reading the governing documents rather than guessing at conventions — equivalent to Claude Code reading CLAUDE.md before touching a single file. Ambiguity about scope gets surfaced and resolved before drafting starts, the same function plan mode serves for a code change: agree on the approach before spending effort on the output. The draft gets checked against a fixed rule set — heading structure, frontmatter schema, banned phrasing — the same role a linter or npm run typecheck plays after a code edit: a mechanical check that catches what review by eye misses. And the last step, before anything ships, is verifying the build actually succeeds, not just that the content looks right in isolation.

The pattern that generalizes: front-load the constraints (CLAUDE.md, a style guide, a schema), separate deciding the approach from producing the output, and verify mechanically before treating something as done. A Claude Code guide that only describes the CLI's commands misses this part — the commands are the easy half.

Best practices

1. Write CLAUDE.md rules from real failures, not speculation. A rule that exists because something specific broke gets followed; a generic aspiration competes for attention and usually loses.
2. Default to plan mode on anything with more than one reasonable approach. Catching a wrong assumption in a two-sentence plan is cheaper than catching it in a full diff.
3. Put non-negotiable rules in a hook, not just in CLAUDE.md. Context-based instructions are followed probabilistically; a hook fires every time.
4. Fork exploratory work into a subagent when you don't need the intermediate output again. It keeps the main session's context usable for longer.
5. Re-verify a standards document against the actual code before trusting it. Docs drift from implementation; the code is the authority when they disagree.

Common mistakes

1. Treating CLAUDE.md as enforced configuration. It's a message the model reads and usually follows — not a guarantee. Rules that must always hold belong in a hook.
2. Skipping plan mode on genuinely ambiguous tasks. The fastest way to a 400-line diff that has to be unwound is starting to edit before the approach is agreed.
3. Writing JSX expression attributes in MDX content Claude Code generates for a next-mdx-remote v6 pipeline. They're silently dropped — string attributes only.
4. Running a production build against a live dev server. Shared build directories corrupt, and the resulting errors look nothing like their actual cause.
5. Letting CLAUDE.md grow past what's actually load-bearing. Every line competes for the model's attention with every other line; unused instructions dilute the ones that matter.

Conclusion

Claude Code rewards project-specific setup more than any single command does — a CLAUDE.md built from real failures, plan mode used on genuinely ambiguous tasks, and hooks for the rules that can't be optional. Start with /init, cut the draft down to what your code can't already tell it, and add a rule the first time something breaks in a way that looks like it shouldn't have. For the workflow-fit question against Cursor and Copilot, read the comparison next; for what a metered plan actually costs once a five-hour session limit is in play, check current pricing before budgeting a team around it.

Frequently asked questions

Muhammad Kashif

Founder and editor of Devventa, covering AI coding assistants, Next.js and the modern AI development stack.