Where files live, how context actually fills, the habits that compound, and the recipes that turn an autonomous coding agent into a tool you actually trust. Distilled from the official docs, written for people who'd rather ship than read.
If you've poked around Claude Code and seen the .claude directory tree, the docs make it look like a lot. It isn't. Most days you'll touch two files. Everything else is opt-in.
.claude/ in your project. Commit it. Share it with your team.~/.claude/ in your home directory. Personal config, applies across every project.Project stuff travels with the repo. Home stuff travels with you.
CLAUDE.md is the instructions file loaded every session. Use it for "here's how this codebase works" content: project conventions, gotchas, build commands, anything you'd otherwise repeat in every prompt.
Three rules that matter:
/init first. It generates a starter CLAUDE.md from your codebase./doctor now does a setup checkup that, among other things, flags CLAUDE.md content Claude could work out from the code itself. Worth running once a month.Already have an AGENTS.md? Recent versions of Claude Code read it as the project instructions when the repo has no CLAUDE.md, so a repo set up for Codex or other agents works as-is. If both files exist, only CLAUDE.md loads by default; import AGENTS.md from CLAUDE.md, or change the Project instructions setting in /config, if you want both.
settings.json is the configuration knob: permissions, hooks, env vars, model defaults. Do these two files. The rest is opt-in.
The model lineup turned over almost completely since this guide first went up. As of September 2026 the current Claude models are the Claude 5 family plus Haiku 4.5, and the default got a big upgrade. For most work you can leave /model alone.
| Model | Alias / ID | Reach for it when | Context |
|---|---|---|---|
| Fable 5.1 | fableclaude-fable-5-1 | The hardest, longest-running work: root-causing an outage, architecture calls, a task you'd normally split across several sittings. | 1M |
| Opus 5.5 | opusclaude-opus-5-5 | The default. Day-to-day agentic coding, refactors, reviews, long sessions. | 1M |
| Sonnet 5 | sonnetclaude-sonnet-5 | Routine, well-specified edits where speed and cost matter more than depth. | 1M |
| Haiku 4.5 | haikuclaude-haiku-4-5-20251001 | Cheap, fast subagents: search, summarizing, mechanical checks. | 200K |
model: for a read-only search subagent./model opens the picker; /model fable or claude --model sonnet switches directly. Aliases track the newest version, so pin a full ID if you need stability. Opus 5.5 needs Claude Code v2.1.280 or later, so run claude update if you don't see it./effort sets how hard the model thinks: low through xhigh and max. Opus 5.5 defaults to medium (it thinks more per turn at a given level than Opus 5 did); the others default to high. For a single hard turn, put ultrathink in the prompt instead of changing the session.opusplan still exists: Opus in plan mode, Sonnet for execution.Rule of thumb, straight from Anthropic's own advice: stay on the default model at default effort. If Claude clearly had the right context and still got it wrong, move up a model. If it got it wrong by skipping a file or not running the tests, raise effort instead.
Almost every best practice traces back to one thing.
Claude's context window fills fast, and performance degrades as it fills.
If you don't internalize this, nothing else in this guide will stick. Every file read, every command output, every back-and-forth costs tokens. When the window gets full, Claude starts forgetting earlier instructions and making mistakes.
Most people think a fresh Claude Code session starts empty. It doesn't. Before your first prompt, the context window already holds a baseline of startup content.
Subagents have their own context window. When you delegate "investigate how token refresh works" to a subagent, it reads 30 files in its context. Only the summary comes back to yours. This is why subagents are the single most powerful pattern in Claude Code, not just a nicety. Part 07 covers this in depth.
/compact replaces conversation with a structured summary. Most startup content reloads automatically afterward. Skill listings are the one exception (re-loaded but counted again). Use this when a session is too valuable to /clear but too cluttered to keep going.
The rest of this guide is essentially: how to manage context aggressively so you never feel the degradation.
Tests, screenshots, expected outputs. Without verification, Claude produces plausible-looking code that doesn't handle edge cases, and you become the only feedback loop. With verification, Claude catches its own mistakes before you see them. This is the single highest-leverage thing you can do.
For anything non-trivial, use plan mode first (claude --permission-mode plan or Shift+Tab mid-session). Let Claude read files and answer questions before making changes. Get a written plan, then switch to default mode and implement against it. Skip planning only when you could describe the diff in one sentence.
Reference exact files with @. Point to existing patterns ("look at HotDogWidget.php as a model and follow that"). Describe symptoms with the likely location and what "fixed" looks like. Vague prompts have their place during exploration. For actual work, specificity cuts iterations.
Prompt patterns for everyday tasks. Each works in any Claude Code surface. Adapt the wording to your project.
gh pr create auto-link the session, so claude --from-pr <number> takes you back later. Always ask Claude to flag risks before submitting. For changes that matter, /code-review ultra (alias /ultrareview, research preview) sends a fleet of reviewer agents to a cloud sandbox and only reports findings it could reproduce. It needs a claude.ai login and isn't available on Bedrock, Vertex or Foundry.
ctrl+v paste, or pass a path. Useful for error screenshots, design mockups, schemas, diagrams. "generate CSS to match this design mockup" works surprisingly well.
@src/utils/auth.js includes the file's full content. @src/components gives a directory listing. @github:repos/owner/repo/issues pulls from a connected MCP server. Multiple references work in one message: "compare @file1.js and @file2.js."
/schedule): Anthropic infra, runs while your machine is off./loop: in-session polling. Leave off the interval and Claude paces itself./goal: not a schedule, but a stop condition. Claude keeps taking turns until it's met ("every call site compiles and tests pass")..claude/ directory sits alongside other tools' configs without conflict.
Esc stops Claude mid-action without losing context.Esc Esc or /rewind opens the rewind menu to roll back conversation, code, or both./clear resets context between unrelated tasks. Use this often.If you've corrected Claude twice on the same issue, the context is polluted with failed approaches. /clear and start over with a better prompt that bakes in what you learned. A clean session almost always beats a long one.
Once you understand how context fills, the cost-saving patterns become obvious. These are the ones with the biggest ROI:
/clear between unrelated tasks. Two 80% sessions beat one 200% session that's been compacted twice./compact <instructions> when you can't /clear. Try "focus on the API changes and modified files" to keep what matters./btw for side questions. The answer appears in a dismissible overlay and never enters conversation history.@ references over copy-paste. Cleaner than dumping content, and the file path stays as a stable reference.gh, aws, gcloud return structured, compact output. Untyped curl chains don't.Claude Code saves every conversation locally. claude --continue picks up the most recent session in the current directory. claude --resume opens a picker. Name important sessions with /rename so you can find them later.
claude --permission-mode planClaude reads files and proposes a plan but makes no edits until you approve. Press Shift+Tab mid-session to toggle into plan mode. Press Ctrl+G to open the plan in your text editor for direct edits before Claude proceeds.
claude --worktree feature-authEach worktree is a separate checkout on its own branch. Run the same command with a different name in another terminal to start an isolated parallel session. Edits don't collide. Useful for the Writer/Reviewer pattern: one Claude implements, a second reviews with fresh context. --worktree also takes a PR number or URL and checks that PR out for you.
claude agentsAgent view (still labelled a research preview) is one screen for every background session on your machine, grouped into needs input, working and completed. Type a task at the bottom to dispatch it, peek at a row to reply, attach when you want the full conversation. The sessions keep running after you close the view. Good fits are tasks you'd otherwise babysit: a flaky-test hunt, a PR review, a small bug fix, each on its own row.
claude --bg "…" starts a background session straight from the shell and returns immediately./fork copies the current conversation into a new background session (its own worktree) while you keep working in this one. It used to launch an in-session subagent; that's now /subtask./resume lists background sessions too, marked bg.git log --oneline -20 | claude -p "summarize these recent commits"Non-interactive mode plugs Claude into CI, pre-commit hooks, and shell loops. Pair with --allowedTools to scope what it can do. Output formats: plain text, JSON, streaming JSON.
If subagents were just a power-user feature, they'd belong further down this guide. They aren't. Subagents are how you keep the main conversation usable on any task that involves more than a couple of files, and they're the single biggest cost lever in Claude Code. This is the section worth reading twice.
Three reasons, in order of how often they actually matter day-to-day:
model field on a subagent overrides the session default.You don't need to define anything to start. Claude Code ships with these and Claude delegates to them automatically.
Explore with model: haiku. It overrides the built-in.Watch them work with /tasks, which lists running subagents (and the model each is on) and lets you open a transcript or stop one.
A subagent is a markdown file with YAML frontmatter. Drop it in .claude/agents/ (project) or ~/.claude/agents/ (personal). That's the entire mechanism.
---
name: code-reviewer
description: Expert code review specialist. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
memory: project
---
You are a senior code reviewer ensuring high standards of code quality and security.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Review checklist:
- Code is clear and readable
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
Provide feedback by priority: Critical / Warnings / Suggestions.
Include specific examples of how to fix each issue.The body is the system prompt. The frontmatter is configuration. Easiest way to start: ask Claude to write one ("create a project subagent in .claude/agents/ that reviews diffs for security issues, read-only tools"), then open the file and check the frontmatter. The /agents wizard is gone as of v2.1.198; asking Claude or editing the file directly is the path now. Claude Code watches the agents folders, so edits apply on the next delegation without a restart.
The docs list 18 fields. These are the ones worth knowing.
Read, Grep, Glob, Bash). Or use disallowedTools as a denylist. Locking a code reviewer to read-only is one line of YAML.haiku, sonnet, opus, fable, a full model ID, or inherit. A read-only investigator on Haiku costs a fraction of one on Opus and is usually fast enough.project, user, or local. Gives the subagent a MEMORY.md it reads at startup and updates as it learns. Use project as the default so learnings ship with the repo.worktree to give the subagent its own git checkout. Safe place to try risky changes. Auto-cleaned if no changes are made.true to always run concurrent with the main conversation. Ctrl+B backgrounds a running task on demand.default, acceptEdits, auto, dontAsk, bypassPermissions, or plan. Inherits from parent in most cases. Use sparingly.low through max, depending on the model). Overrides the session's /effort. Low effort on a search agent is another quiet cost saver.When memory is set, the subagent gets a directory it owns. It reads MEMORY.md at startup and updates it as it works. Over time, this becomes institutional knowledge: codebase patterns, recurring bugs, architectural decisions, library locations.
Two prompts make this real:
Or bake it into the system prompt so it happens automatically:
Update your agent memory as you discover codepaths, patterns, library
locations, and key architectural decisions. Write concise notes about
what you found and where.This is how a code-reviewer becomes more useful in month three than month one. It compounds.
Subagents aren't free. They start fresh, take time to spin up, and their results have to fit back into your main context. Stay in the main conversation when:
For a quick question about something already in your conversation, use /btw instead. It sees full context, has no tool access, and the answer never enters history.
Nesting is back on. Subagents can now spawn subagents of their own, up to three layers below the main conversation by default, and only the top-level summary comes back to you. Handy for a reviewer that fans out one verifier per finding. If you'd rather keep delegation flat, set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 in the env block of settings.json.
Dynamic workflows are the step up. Instead of Claude deciding turn by turn what to delegate, Claude writes a JavaScript script that orchestrates dozens to hundreds of subagents, and a runtime executes it in the background while your session stays usable. Intermediate results live in the script, not your context, and the run is resumable. Think codebase-wide bug sweep, a 500-file migration, or research where sources need cross-checking.
ultracode in the prompt. /effort ultracode lets Claude decide on every task in the session, which gets expensive fast./workflows shows each run's progress and per-agent token use, and lets you pause, resume or save it./config.Watch the meter. A workflow run can burn meaningfully more tokens than doing the same task in conversation, and it all counts toward your plan limits. Try it on one directory before you point it at the whole repo.
Add these when you have a real reason. Not before. The hardest part is knowing which mechanism fits which need.
The biggest source of confusion in Claude Code is having seven different ways to give Claude information. Here's the short version:
The most common mistake: stuffing everything into CLAUDE.md. If a piece of context only applies sometimes, it's a skill. If it must happen every time without fail, it's a hook. If it reads many files, it's a subagent. CLAUDE.md is for the always-relevant baseline.
migrations/, validate SQL before execution).gh, aws, gcloud, sentry-cli are the most context-efficient way to talk to external services. Install them and tell Claude they're available.claude mcp add connect Notion, Figma, your database, your monitoring stack./plugin bundle skills, hooks, subagents, and MCP servers. Code intelligence plugins are especially worth it for typed languages.The directory shows what can exist. These commands show what's actually live in your session.
/effort./checkup.managed-settings.json) deployed by your org. Can't override. Lives at the system level, varies by OS. Worth knowing exists before you waste an hour wondering why your settings aren't sticking.--permission-mode or --settings.settings.json.When something doesn't behave the way you expect, walk this list.
/clear between tasks./clear and write a better prompt that bakes in what you learned.The commands you'll actually reach for, in one place.
CLAUDE.md and settings.json. Keep CLAUDE.md short./clear between tasks. Use subagents for read-heavy work. Course-correct fast./context and /memory show you why.Everything else is detail.