Claude Code, the practitioner's view.

Setup & layout

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.

The two locations

• .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.

The two files you'll actually edit

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:

1. Run /init first. It generates a starter CLAUDE.md from your codebase.
2. Keep it short. For each line, ask: "Would removing this cause Claude to make mistakes?" If not, cut it.
3. A bloated CLAUDE.md gets ignored. If Claude isn't following a rule, the file is probably too long, not too short.

settings.json is the configuration knob: permissions, hooks, env vars, model defaults. Do these two files. The rest is opt-in.

The mental model

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.

What's already loaded before you type

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.

What happens as Claude works

• Each file read adds tokens. A 500-line file might cost 5K to 10K. Reading 20 files in an investigation can blow past 100K.
• Path-scoped rules auto-load alongside matching files. Useful, but counts toward your budget.
• Hooks fire after each edit and their output enters context too.
• Tool outputs accumulate. Test results, command output, error traces. All of it.

The two big levers

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 06 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.

Three habits that compound

Workflow recipes

Prompt patterns for everyday tasks. Each works in any Claude Code surface. Adapt the wording to your project.

Session control & cost

Course-correct fast

• 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.
• Subagents investigate in their own context window and report back summaries. If you'd otherwise tell Claude to "go read 40 files," delegate it. (Part 06 covers this in depth.)

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.

Token-saving patterns

Once you understand how context fills, the cost-saving patterns become obvious. These are the ones with the biggest ROI:

Resume across sittings

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.

Plan before editing

claude --permission-mode plan

Claude 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.

Run parallel sessions with worktrees

claude --worktree feature-auth

Each 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.

Pipe Claude into scripts

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.

Working with agents

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.

Why they matter

Three reasons, in order of how often they actually matter day-to-day:

1. Context preservation. The subagent reads the 40 files in its own context window. You get the summary. Your main conversation stays sharp for implementation.
2. Cost control. Run read-only investigations on Haiku. Reserve Opus for the actual code. The model field on a subagent overrides the session default.
3. Specialization and safety. A focused system prompt and a restricted tool set produce better, safer output than a generalist with everything turned on.

The built-ins you already have

You don't need to define anything to start. Claude Code ships with these and Claude delegates to them automatically.

Confirm any of these are working with /agents.

Three ways to invoke

How custom agents work

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: run /agents, pick "Generate with Claude," describe what you want, save. The agent is available immediately, no restart needed.

The frontmatter fields that actually matter

The docs document 16 fields. These are the ones worth knowing.

Persistent memory: the underused feature

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:

• Before work: "Review this PR, and check your memory for patterns you've seen before."
• After work: "Save what you learned to your memory."

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.

Patterns that work

• Isolate verbose operations. Test runs, log analysis, doc fetches. The output stays in the subagent. The summary comes back.
• Run parallel research. Independent investigations spawned simultaneously: "research the auth, database, and API modules in parallel using separate subagents."
• Chain subagents. "Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them." Each runs in its own context. Claude passes only the relevant findings between them.
• Cost-tier your fleet. Read-only Haiku agents for investigation. Sonnet for review and refactors. Opus for hard implementation. Define them once, reuse forever.

When NOT to use a subagent

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:

• The task is small and targeted (one-line fix, rename, typo)
• You need iterative back-and-forth or quick refinement
• Multiple phases share significant context (planning → implementation → testing)
• Latency matters and you'll be waiting on the result

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. For workflows that need nested delegation, use Skills or chain subagents from the main conversation. Subagents cannot spawn other subagents.

Best practices, the short list

1. One agent, one job. Focused agents outperform generalists.
2. Write detailed descriptions. Claude uses the description to decide when to delegate.
3. Limit tool access. Read-only agents stay read-only. Write access is a permission, not a default.
4. Check project agents into version control. If your team would benefit from it, ship it with the repo.

Building it out

Add these when you have a real reason. Not before. The hardest part is knowing which mechanism fits which need.

When to use what

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.

Capabilities worth turning on

• Hooks run scripts deterministically at specific points. CLAUDE.md is advisory. Hooks are guarantees. Use them when something must happen every time, no exceptions (lint after every edit, block writes to migrations/, validate SQL before execution).
• CLI tools like gh, aws, gcloud, sentry-cli are the most context-efficient way to talk to external services. Install them and tell Claude they're available.
• MCP servers via claude mcp add connect Notion, Figma, your database, your monitoring stack.
• Permissions: use auto mode to let a classifier handle approvals, allowlist trusted commands, or sandbox for OS-level isolation. Default-prompt-everything is safe but tedious.
• Plugins via /plugin bundle skills, hooks, subagents, and MCP servers. Code intelligence plugins are especially worth it for typed languages.

Reference & cheatsheet

Slash commands for what actually loaded

The directory shows what can exist. These commands show what's actually live in your session.

Settings precedence (top wins)

1. Managed settings (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.
2. CLI flags like --permission-mode or --settings.
3. Environment variables (varies by setting).
4. settings.json.

When something doesn't behave the way you expect, walk this list.

Failure patterns to recognize

The cheatsheet

The commands you'll actually reach for, in one place.

The bottom line

• Edit CLAUDE.md and settings.json. Keep CLAUDE.md short.
• Verify, plan, be specific.
• Context is the constraint. Use /clear between tasks. Use subagents for read-heavy work. Course-correct fast.
• Build a small fleet of focused agents. Cost-tier them by model. Give them persistent memory.
• Pick the right mechanism: CLAUDE.md for always, skills for sometimes, hooks for must-happen, subagents for read-heavy or specialized.
• When something feels off, /context and /memory show you why.

Everything else is detail.