Originally published at heycc.cn. This is a mirrored copy — the canonical version is kept up to date at the source.

Claude Code Best Practices 2026: Context, Modes, and Subagents

Most Claude Code advice you read online is a list of disconnected tips. The official guidance is more honest: nearly every best practice traces back to a single constraint. The context window fills up fast, and an LLM's performance degrades as that window fills. Once you internalize that, the rest of the practices stop feeling arbitrary and start feeling like a budget you are spending.

Four areas decide whether that budget is won or lost: managing context, writing a lean CLAUDE.md, choosing the right permission mode, and delegating to subagents. The numbers, flags, and keybindings below come from the official Claude Code docs as of 2026-06-28 — the sourcing rundown and the linked Sources list at the end let you trace each claim back to its page.

The one constraint that explains the rest

Think of every session as having a finite token budget. Three things draw it down before you have typed your first real prompt: your CLAUDE.md files (loaded in full at launch), your auto-memory MEMORY.md index, and then the conversation itself plus every tool result that flows back in. A 400-line CLAUDE.md and a habit of asking Claude to read entire files will quietly burn that budget, and the symptom is not an error — it is Claude getting vaguer, forgetting earlier instructions, and making mistakes it would not have made in a fresh session — the failure mode Anthropic's own engineering team calls context rot.

The size of the effect is quantified, not just anecdotal: Anthropic's context-management writeup reports that in a 100-turn web search evaluation, "context editing enabled agents to complete workflows that would otherwise fail due to context exhaustion — while reducing token consumption by 84%." That number is from one specific eval shape (long-horizon web search), not a universal constant — but it's the concrete evidence behind "treat context as money" below, not just a turn of phrase.

So the meta-rule is: treat context as money. Spend it on the few things that genuinely change Claude's behavior, and claw it back everywhere else using plan mode, subagents, and path-scoped rules. The sections below are organized around that idea.

Keep CLAUDE.md lean: Claude reads it, it doesn't obey it

CLAUDE.md is read at the start of every conversation. That is its power and its trap. The official guidance is to keep it short and human-readable, and to apply one test to every single line: would removing this cause Claude to make mistakes? If the answer is no, delete it. Bloated CLAUDE.md files do not just waste tokens — they cause Claude to ignore the instructions that actually matter, because the signal drowns in noise.

A few concrete rules that hold up in practice:

• Target under 200 lines per file. The docs are blunt about the tradeoff: "Longer files consume more context and reduce adherence." No specific number is attached, so 200 is a working ceiling rather than an official threshold — the underlying point is that every extra line you add is paid for in attention spent elsewhere.
• Be specific enough to verify. "Use 2-space indentation" beats "format code properly." "Run npm test before committing" beats "test your changes." The docs use these exact contrasts because a vague instruction is one Claude can satisfy without actually doing what you meant.
• Run /init to bootstrap it. This analyzes your codebase to detect build systems, test frameworks, and code patterns; if a CLAUDE.md already exists, /init suggests improvements rather than overwriting it. The memory docs also document an opt-in flag: setting CLAUDE_CODE_NEW_INIT=1 switches /init to an interactive multi-phase flow that asks which artifacts to set up (CLAUDE.md, skills, and hooks), explores your codebase with a subagent, and presents a reviewable proposal before writing any files.

CLAUDE.md files load from broadest to most specific scope: managed policy (org-wide), user (~/.claude/CLAUDE.md), project (./CLAUDE.md or ./.claude/CLAUDE.md), and local (./CLAUDE.local.md, which you should gitignore). They concatenate rather than override, so a project rule appears in context after a user rule. You can compose them with @path/to/import syntax, up to a maximum import depth of four hops — though remember imported files still load into context at launch, so importing does not save tokens, it only organizes them.

For larger projects, the better lever is .claude/rules/. These topic files can carry YAML paths frontmatter with glob patterns, so a rule only loads into context when Claude touches a matching file. An API rule scoped to src/api/**/*.ts costs nothing when you are editing the frontend. This is how you keep the always-loaded surface small while still having deep, specific guidance available on demand.

One more thing that trips people up: CLAUDE.md content is delivered as a user message after the system prompt. Claude treats it as guidance it tries to honor, not as a rule the client enforces, so compliance is never guaranteed. If you need an action blocked no matter what Claude decides — say, "never push to main" — do not write it in CLAUDE.md and hope. Use a PreToolUse hook, which executes as a shell command and applies regardless of the model's judgment.

Let auto memory do the rest

Auto memory (on by default, requires Claude Code v2.1.59 or later) lets Claude accumulate knowledge across sessions by writing notes to ~/.claude/projects/<project>/memory/. The first 200 lines or 25KB of MEMORY.md — whichever comes first — load at the start of every conversation, with detailed topic files read on demand. The practical upshot: stop manually pasting the same correction every session. Tell Claude "remember that the API tests need a local Redis instance," and it saves that for next time. Keep CLAUDE.md for deliberate, durable conventions; let auto memory absorb the incidental learnings. To see exactly what is loaded, or to prune it, run /memory. For the full load-order, scopes, and @import mechanics, see our CLAUDE.md and memory guide.

The Explore -> Plan -> Implement -> Commit workflow

The recommended default workflow has four beats. Explore in plan mode so Claude reads files and forms an understanding without touching source. Plan by asking it to write a detailed, reviewable proposal. Implement by switching out of plan mode and letting it code. Commit after verifying the result against the plan.

Plan mode is the workhorse of the first two beats. It tells Claude to research and propose without editing your source — Claude still reads files and runs shell commands to explore, but it does not write. The docs document three ways in: press Shift+Tab to cycle into it, prefix a single prompt with /plan, or start the session with claude --permission-mode plan. Once the plan is ready, the official keybinding Ctrl+G opens the proposed plan in your default text editor so you can revise it directly before Claude proceeds — catching a wrong assumption here is far cheaper than catching it after fifteen file edits.

The nuance that gets lost: planning is not always worth it. For a typo, a log line, or a rename — anything where you could describe the diff in a single sentence — skip the plan and ask Claude to just do it. Knowing when not to plan is itself a discipline the official Explore-Plan-Implement workflow leaves implicit:

Situation	Skip the plan	Use plan mode
Scope of change	One file, obvious fix	Multiple files or unclear blast radius
Can you describe the diff in one sentence?	Yes	No
Risk if wrong	Trivial, easy to revert	Touches shared infra, migrations, or security
What you want from Claude	Just do it	Read, reason, propose, then you approve
Example	Rename a variable, fix a log message	Add a feature across the API and UI layers

Pick the permission mode that matches your trust level

Permission modes control how often Claude pauses to ask before editing a file or running a command. Choosing well is the difference between babysitting every action and getting interrupted only when it matters. Here is the full set, verified against the official mode reference. Note one constant: in every mode except bypassPermissions, writes to protected paths (.git, .claude, shell rc files, and similar) are never auto-approved.

Mode	Runs without asking	Best for
default	Reads only	Getting started, sensitive work
acceptEdits	Reads, file edits, and common filesystem commands (mkdir, touch, rm, rmdir, mv, cp, sed) on in-scope paths	Iterating on code you review after the fact
plan	Reads only	Exploring before you change anything
auto	Everything, with a background safety classifier	Long tasks where you trust the direction
dontAsk	Only pre-approved (allow-listed) tools and read-only Bash	Locked-down CI and scripts
bypassPermissions	Everything, no checks	Isolated containers and VMs only

Shift+Tab cycles the three everyday modes — default -> acceptEdits -> plan. The other three are not in that default cycle; they slot in or attach to startup flags as described below.

Auto mode (requires v2.1.83 or later and a recent model such as Opus 4.6+/Sonnet 4.6) is the most interesting addition. Instead of prompting you, a separate classifier model reviews each action before it runs, blocking anything that escalates beyond your request, targets unrecognized infrastructure, or appears driven by hostile content Claude just read. By default it blocks the genuinely dangerous moves — curl | bash, production deploys and migrations, force-pushing or pushing to main, mass cloud deletions, terraform destroy — while allowing local edits in your working directory and dependency installs from your lock files. It is a research preview: it reduces prompts but does not guarantee safety, so reserve it for tasks where you trust the general direction. A useful detail: boundaries you state in conversation ("don't deploy until I review") are treated as a block signal, but they are re-read from the transcript each check, so context compaction can drop them. For a hard guarantee, add a deny rule.

dontAsk mode auto-denies every tool call that would otherwise prompt, allowing only your permissions.allow rules and read-only Bash. That makes it fully non-interactive — the right choice for CI pipelines where you have pre-declared exactly what Claude may run.

bypassPermissions mode skips checks entirely and should live only in throwaway containers or VMs; Claude Code even refuses to start it as root on Linux and macOS. You cannot switch into it mid-session — start with --permission-mode bypassPermissions (or the equivalent --dangerously-skip-permissions).

A practical default for most people: live in default, drop to plan for anything non-trivial, and reach for acceptEdits only on code you intend to review with git diff afterward.

Delegate to subagents to protect the main context

The last lever is the one that most directly enforces the budget thesis: subagents. A subagent runs a side task in its own context window with its own system prompt and tool access, then returns only a summary. The verbose middle — the test output, the grep hits, the doc dump — stays in the subagent's context and never touches your main conversation. That is the whole point: delegation is context hygiene, not just parallelism.

Claude Code ships three built-in subagents it delegates to automatically. Explore is a fast, read-only agent (Write and Edit are denied) used for file discovery and code search; it deliberately skips your CLAUDE.md to stay cheap, so any rule it must honor has to be restated in the delegating prompt. Plan is the read-only research agent behind plan mode. General-purpose is the full-tool agent for multi-step tasks that need both exploration and modification.

When should you delegate rather than work inline? The test is whether the side task is verbose, self-contained, or needs different tools or permissions than your main thread:

Signal	Keep it inline	Send it to a subagent
Output volume	A few lines you will act on immediately	Hundreds of lines you only need a conclusion from
Coupling to the main task	Tightly coupled, iterative	Self-contained question with a clean answer
Tooling	Same tools and permissions	Needs restricted or different tool access
Parallelism	One thing at a time	Several independent investigations at once
Example	Fix the failing test you are looking at	Audit every module for a deprecated call

You can define your own subagents in YAML with a description, a restricted tool list, and a permissionMode, and Claude will delegate to them when a task matches the description. For the full mechanics — frontmatter fields, scope precedence, and fanning work out across tens or hundreds of agents with dynamic workflows — see the companion Claude Code subagents and workflows guide.

Tracing each claim back to a doc

The memory-related numbers — the MEMORY.md load limit ("first 200 lines or 25KB, whichever comes first"), the v2.1.59 auto-memory minimum, the four CLAUDE.md scopes, the four-hop import depth, the .claude/rules/ paths-frontmatter behavior with the src/api/**/*.ts example, the "delivered as a user message after the system prompt" point, and CLAUDE_CODE_NEW_INIT=1 with its multi-phase /init flow — all come from the Claude Code memory docs and match verbatim or near-verbatim. That same page says longer CLAUDE.md files "reduce adherence" but attaches no measurement, which is why the 200-line figure stays unquantified above. Everything about permission modes — the six-mode set, the Shift+Tab cycle (default -> acceptEdits -> plan), the /plan prefix, the claude --permission-mode plan flag, the Ctrl+G plan-editor keybinding, the acceptEdits command list, and the v2.1.83+ auto-mode requirement — is drawn from the permission-modes reference. The hooks and subagents pages back the PreToolUse enforcement note and the built-in-subagent behavior, respectively. Version numbers and flags are the part most likely to drift over time, so the live pages are the authority if a detail here looks dated.

Sources

• How Claude remembers your project — Claude Code memory docs (official)
• Choose a permission mode — Claude Code docs (official)
• Claude Code hooks guide (PreToolUse enforcement)
• Create custom subagents — Claude Code docs
• Anthropic — Managing context on the Claude Developer Platform