Claude Code — Field Guide
Field Guide · start here

Claude Code, from first principles

Most people meet Claude Code and treat it like a chatbot in a terminal. It isn't. It's a harness — a machine that builds the model's context, runs deterministic code around it, and remembers across sessions. Understand that one idea and everything else falls into place. This guide takes you there in four moves.

≈ 20 min read Distilled from claude-code-best-practice Voices: Boris Cherny · Thariq · Matt Pocock · Dex · Karpathy

The one idea

A chatbot delivers your prompt. Claude Code constructs one.

You run claude in your terminal and talk to the model — but it can also read your files, run shell commands, call tools, and loop until the job is done. The word “prompt” hides the whole trick, because it means two different things:

(a) What you type
"write a recursive flatten function"
≈ 6–60 tokens · you control this
(b) ≈ 15,000 tokens the model actually sees · the harness controls this
CLAUDE.md conventions + matching .claude/rules/*.md modular system-prompt fragments (110+, loaded conditionally) tool definitions · environment (cwd, git status, platform) prior turns · files it read via Read / Grep …and finally, your request

In a chatbot, (a) and (b) are the same thing. In Claude Code they’re radically different — and the gap between them is where all the quality comes from.

The core equation
Output quality = f( effective context, model capability, iteration loop )

You control only a sliver of effective context — your typed prompt. The harness controls all the rest, and the iteration loop entirely. Same model, same sentence, three different worlds:

EnvironmentWhat the model seesResult
Chatbot, no toolsThe sentenceTextbook code, generic style
Claude Code, no readingSentence + CLAUDE.mdMatches your declared conventions
Claude Code, agentic loopSentence + CLAUDE.md + reads adjacent files + runs testsMatches the real codebase, passes tests, handles the edge cases your code handles

The beginner's analogy

Using Claude Code is like hiring someone

Level 1

Prompting

Asking a stranger on the street for directions. You get an answer — but the method is unpredictable, and never the same twice.

Level 2

Agents

Hiring a specialist with a fixed job description. Same question, same approach, every time. The gain is consistency, not intelligence.

Level 3

Skills

That specialist having specific training for specific tasks — exact steps for exact jobs, reusable across many specialists.

Takeaway. For a single atomic question (“write a Fibonacci function”) a chatbot is just as good — prompt quality is everything and the harness adds nothing. Real engineering work is not in that regime. That’s why the harness exists.

The anatomy

Everything lives in a .claude/ folder

The harness is configured by plain markdown and JSON files. Two homes: ~/.claude/ is global (all projects); .claude/ inside a repo is scoped to that project. Project overrides global.

~/.claude/ # global — every session, everywhere <your-repo>/ ├── CLAUDE.md # always-loaded project memory & conventions └── .claude/ ├── agents/ # subagents — <name>.md (own context window) ├── commands/ # slash commands — /name shortcuts ├── skills/ # skills — <name>/SKILL.md (auto-loaded) ├── hooks/ # shell code fired on lifecycle events ├── rules/ # lazy-loaded rule fragments ├── settings.json # permissions · model · hooks · MCP └── .mcp.json # external tool servers (MCP)

The 8 primitives

Eight building blocks — that's the whole vocabulary

Subagents

.claude/agents/*.md

A separate Claude instance with its own context window, tools and model. Spawn one for research/review so the main thread stays clean. Claude auto-invokes it when the request matches its description.

--- name: code-reviewer description: Review diffs. Use PROACTIVELY. tools: Read, Grep, Bash model: sonnet ---

Commands

.claude/commands/*.md

Reusable prompt shortcuts you fire by typing /name. The file body is a prompt template; frontmatter can take $arguments, pin a model, or restrict tools. Never auto-invoked — always explicit.

--- description: Review a PR by number argument-hint: [pr-number] allowed-tools: Bash(gh *), Read --- Review PR #$pr_number …

Skills

.claude/skills/*/SKILL.md

Packaged expertise Claude auto-loads when a task matches its description (a compact skill listing sits in context at ~1% budget). Reusable checklists, recipes, workflows — pulled in without you pasting them.

--- name: dataviz description: Turn data into a chart/dashboard when_to_use: user asks for a chart or plot ---

Memory

CLAUDE.md

Always-loaded project context — “the single most impactful way to improve output.” Ancestors load up the tree at startup; subdirectory CLAUDE.md files load lazily only when you touch those files. Siblings never load.

/repo/CLAUDE.md (always) /repo/frontend/CLAUDE.md (on touch) /repo/backend/CLAUDE.md (skipped)

Settings

settings.json

JSON that controls model, permissions, hooks, MCP, sandbox. Layered: managed > CLI > project-local > project > user. deny rules always win. Arrays like permissions.allow merge across scopes.

"permissions": { "allow": ["Edit(*)","Bash(npm run *)"], "deny": ["Read(.env)"] }

MCP servers

.mcp.json

Plug-in connectors giving Claude live tools — current docs, a real browser, your database. stdio (local process) or http (remote). Start small: one team “went to 15 servers, used only 4.”

"context7": {"command":"npx", "args":["-y","@upstash/context7-mcp"]}

Power-ups

/powerup

Ten short animated in-terminal lessons, each teaching a feature people miss — rewind, plan mode, subagents, the effort dial. The fastest way for a beginner to discover what’s there.

claude /powerup

CLI flags

$ claude …

One-session overrides at launch — resume work, run headless in scripts, swap the model, or isolate in a git worktree. Sit above every file setting but below managed policy.

claude -c # continue claude --model opus --permission-mode plan claude -w # git worktree

The signature pattern

Command → Agent → Skill

The three extension mechanisms compose into one pipeline. Claude prefers the lightest option that fits: Skill (inline) → Agent (separate context) → Command (only when you type /). Here’s the repo’s worked example, a weather orchestrator:

Command
/weather-orchestratorEntry point. Asks “°C or °F?”, then orchestrates.
Agent
weather-agentFetches the temp autonomously in its own context, using a preloaded skill as domain knowledge.
Skill
weather-svg-creatorInvoked inline to render the SVG card + summary from the data already in the conversation.
The subtlety worth learning: a skill attaches two ways. Preloaded (listed in an agent’s skills: frontmatter) — its full text is injected into the agent at startup as reference knowledge. Directly invoked (via the Skill tool) — it runs in the caller’s context to produce output. The weather example shows both on purpose.

Scope & precedence

What lives global vs. project

CategoryScopeWhy
Tasks, agent teamsGlobal-onlyCoordination must outlive any one project
Credentials, OAuthGlobal-onlyNever accidentally committed to a repo
Auto-memoryGlobal-onlyPersonal learning, not team config (though it’s about a project)
CLAUDE.md · settings · rules · agents · commands · skills · hooks · MCPBothTeams share project behavior; project overrides global

Settings precedence, highest→lowest: managed policy → CLI flags → .claude/settings.local.json → .claude/settings.json → ~/.claude/settings.local.json → ~/.claude/settings.json. Above all: deny rules can never be overridden.

This bit us in practice. Governance is decided by the launch directory — the CLAUDE.md that loads is the one where you started claude. Start in the wrong folder and you inherit the wrong rules.

The objection

“Isn't it all just prompts to the model in the end?”

A common, half-right claim: skills, commands, subagents, hooks — they all become tokens the model sees, so a strong prompt alone should be equivalent. At the final inference call, that’s true. For an atomic one-shot task it’s entirely true — and that’s exactly the regime real engineering work is never in. Everywhere else it collapses, because ten harness capabilities operate at layers a prompt can’t reach:

CapabilityWhy a prompt can't replicate it
Context isolationA prompt fills one window; N subagents give ~N× effective context
Tool restrictionsPrompt instructions are advisory and can be ignored; deny rules cannot
Lazy-loaded rules & memoryA prompt is static; it can’t conditionally load based on files touched at runtime
HooksDeterministic shell code at lifecycle events that can block a tool call — even if the model “wants” to run it
Model routingNo token in a prompt can change which model answers (model: haiku/opus)
ParallelismA prompt is sequential; the harness runs concurrent subagents
Cross-session persistenceA prompt dies with the session; memory + settings survive
Permission classificationA prompt can’t add a pre-execution safety layer to itself
The correct mental model
Prompts control what the model is asked to do.
The harness controls what the system does — before tokens arrive, after they’re produced, across sessions, contexts and processes.

“You can write the world’s best recipe. Without a kitchen, you cannot cook at scale.”

on why the harness matters

“Features are not prompts with extra steps. They are harness-level primitives — deterministic execution, context architecture, infrastructure routing.”

the core thesis

The reason context is a skill

“Claude got dumber today” — the real story

Frozen weights ≠ frozen behavior. The weights don’t change after launch, but ~9 layers above them do — and the numbers are bigger than people think.

±8–14%
proven day-to-day output variance (Scale AI)
16%
of Sonnet 4 requests hit by one routing bug (Aug ’25)
~30%
of Claude Code users saw ≥1 degraded message
300–400k
tokens where “context rot” tends to set in (1M model)

Anthropic confirmed three infrastructure bugs in a Sept 2025 postmortem (bad routing, TPU output corruption, a compiler mis-compilation) — real, but transient. The far more common cause of “it got dumber” happens inside your session: context pollution. Earlier mistakes accumulate and the model perpetuates them.

The single highest-leverage habit: when quality feels off, /compact or start a fresh session. Don’t argue with a polluted context — reset it.

The honest boundary

When you don't need any of this

For an atomic, self-contained question — “write me a recursive Fibonacci” — the harness contributes nothing and a plain chatbot is equal. Use the right tool. The harness earns its keep the moment work spans files, sessions, tools, or needs a guarantee a prompt can only request.

Day 0 — get running

Install & authenticate

Install (macOS via Homebrew)

Open Terminal, then:

# install Homebrew first if `brew --version` fails brew install --cask claude-code

Verify

node --version # v18+ claude --version

Log in

Run claude. On first launch pick a method: Claude.ai account (Pro/Max subscription — browser opens, authorize, done) or Anthropic API key (paste a key starting sk-ant-, stored once).

Day 1 — your first conversation

Three levels of control

Level 1
Just promptType claude, ask anything. Great for codebase questions, edits, explaining errors. Method is unpredictable — that’s fine to start.
Level 2
Add an agentSame question, a fixed specialist role → same approach every time. Predictability, not IQ.
Level 3
Add a skillGive the agent exact training — which API, which field, which format. Reusable across agents.
For a true beginner: live at Level 1 for a while. Just prompt in the terminal until you notice a task you keep repeating — that’s your first agent or skill. Try the repo’s demo: claude → /weather-orchestrator.

The practitioner's playbook

What the people who ship all day actually do

Verification — the #1 unlock the ceiling on quality
  • Give Claude a way to verify its own work. A feedback loop 2–3×’s the final quality. Backend → have it run the server end-to-end; frontend → give it a browser; desktop → Computer Use. — Boris
  • “If your codebase doesn’t have feedback loops you’re never going to get decent output. That is the ceiling.” — Matt Pocock
  • Make Claude your reviewer: “Grill me on these changes and don’t open a PR until I pass,” or “Prove to me this works.” — Boris
  • TDD (red-green-refactor) instruments the code before it exists, so the model can’t cheat by wrapping a finished implementation in trivial tests. — Matt Pocock
Context management the smart zone vs the dumb zone
SMART ZONE · <40%
CAUTION 40–60%
DUMB ZONE · >60%
0 — fresh, best work~100k (Matt's marker)300–400k rot →
  • The context window is everything the model sees — system prompt, conversation, every tool call + output, every file read. Fresh context = sharpest attention. — Thariq
  • Beginners: keep it under ~40%; at 60% think about wrapping up. Experienced users read the task and push higher. — Dex
  • Rewind > correcting. Correcting leaves the failed attempt in context; rewind (esc-esc) to just after the file reads, then re-prompt with what you learned — clean context. — Thariq
  • /compact is lossy but keeps momentum (steer it: /compact focus on the auth refactor). /clear + a hand-written brief lets you decide what survives — for high-stakes next steps. — Thariq
  • Persist what matters into static files (research doc, design doc, plan), not into a compaction you have to trust. — Dex
  • Put context usage on your status line (/statusline) — you need to see how close you are to the dumb zone. — Boris & Matt
Plan mode & specs think before it codes
  • Start ~80% of sessions in Plan mode (shift+tab twice). Pour energy into the plan so Claude can one-shot the build. The moment it goes sideways, switch back to plan mode and re-plan. — Boris
  • Plan mode is just one instruction — “please don’t code.” You can literally just say that. — Boris
  • Have one Claude write the plan, spin up a second to review it “as a staff engineer.” — Boris
  • Specs-to-code without reading code doesn’t work. Both Matt and Dex tried it for ~6 months and quit. “The code is your battleground.” — Matt Pocock / Dex
  • Vertical slices, not horizontal layers. AI wants to build all-DB → all-API → all-frontend, so nothing integrates until phase 3. Force thin slices that cross every layer. — Pragmatic Programmer, via Matt & Dex
  • Mind the instruction budget: frontier models reliably follow only ~150–200 instructions; past that they half-attend. Split monoliths into focused prompts (<40 each). — Dex
CLAUDE.md discipline keep it tiny
  • Boris’s personal CLAUDE.md is two lines. Everything else lives in the repo’s shared, git-checked CLAUDE.md the whole team edits. — Boris
  • When it bloats, delete it and start fresh. Do the minimal thing to get the model on track; add back a little only when it drifts. — Boris
  • After every correction: “Update your CLAUDE.md so you don’t make that mistake again.” Claude is eerily good at writing rules for itself. — Boris
  • Beware doc rot. Stale PRDs/plans left in the repo mislead future agents — close them instead of hoarding them. — Matt Pocock
Subagents & parallelism the biggest productivity unlock
  • Spin up 3–5 git worktrees, each its own Claude session. Boris runs “dozens of Claudes at all times.” — Boris
  • The offload test: “Will I need this tool output again, or just the conclusion?” A subagent’s 20 reads and 3 dead-ends get garbage-collected on exit — only its report returns (~94k tokens spent barely move your main context). — Thariq / Matt
  • Calibrate to difficulty: easy = inline; hard research/bug = “use three, five, even 10 subagents in parallel.” Append “use subagents” to throw more compute at a problem. — Boris
  • Uncorrelated fresh contexts are test-time compute — more agents + the right topology = more capability. — Boris
Git, debugging & daily habits the inner loop
  • Worktrees are the standard for parallel work: claude -w, alias tabs 2a/2b/2c to hop in one keystroke, keep a dedicated “analysis” worktree for logs. — Boris
  • Anything you do more than once a day → a slash command checked into .claude/commands/ (e.g. /commit-push-pr). — Boris
  • Just ask Claude to debug it. Good logging is the unlock: “check this object, it messed up this way” and it searches the log and figures it out. Fix scary bugs in plan mode (it searches wide). — Boris
  • Review before you QA — in a fresh context, or the reviewer runs in the dumb zone and is dumber than the implementer. — Matt Pocock
  • New task → new session. — Thariq
  • Use voice. “You speak 3× faster than you type, and your prompts get more detailed.” — Boris
  • Pre-allow permissions (/permissions, check settings into git; /fewer-permission-prompts) instead of --dangerously-skip-permissions. — Boris
Cross-cutting principles how to hold the whole thing
  • “Never bet against the model.” Scaffolding buys ~10–20%, then the next model wipes the gain. Weigh “build it now” vs “wait two months and get it free.” — Boris (the Bitter Lesson)
  • You can outsource the thinking, but not the understanding. You can’t direct agents well on something you don’t understand. — Karpathy
  • Stay in the loop — models are jagged. Opus refactors a 100k-line codebase, then tells you to walk to a car wash 50m away. You own the taste and judgment. — Karpathy
  • 2026 is “the year of no more slop.” Going 10× faster doesn’t matter if you throw it away in 6 months — aim for a sustainable 2–3× with quality intact. — Dex

Workflows & quick reference

RPI — Research → Plan → Implement

A gated pipeline: each phase must pass before the next. The Research gate kills non-viable features before any code is written.

/rpi:research
GO / NO-GOFeasibility + strategy alignment → RESEARCH.md verdict.
/rpi:plan
The roadmapPhases + tasks, plus pm / ux / eng docs.
/rpi:implement
Phase-gated buildEach phase executed and marked PASS / FAIL.

Essential commands to know

CommandDoes
/contextVisualize how full your context window is
/compact · /clearFree up context (lossy) · start fresh (clean slate)
/rewind · esc-escUndo conversation and/or code to an earlier point
/agents · /skills · /mcpManage subagents · skills · tool servers
/memory · /initEdit CLAUDE.md · create one for this project
/usage · /model · /effortCheck limits · switch model · dial reasoning low→max
/powerupTen animated lessons on features you’re missing
claude -c · claude -wContinue last session · start in a git worktree
Distilled from shanraisshan/claude-code-best-practice (MIT) — talks & tips from Boris Cherny, Thariq, Matt Pocock, Dex Horthy and Andrej Karpathy. This is a curated snapshot; the source is living — re-read it for the latest.