Source: Best practices for Claude Code (Anthropic docs)
Anthropic's official guidance for Claude Code: tell it what it can't see, give it a check to run, enforce hard rules with hooks and deny rules, and bound unattended runs.
Contents
- What: official product documentation (successor to the April 2025 engineering post of the same name, which now redirects here)
- Publisher: Anthropic
- Date: living document, read 2026-11-14
- Original: Best practices for Claude Code
Summary
Frames every instruction to Claude Code as either non-deterministic (prompt, CLAUDE.md, skills: the model decides whether to follow) or deterministic (hooks, deny rules, managed settings, sandbox: the harness enforces). Most session failures come from four causes: missing information the repo doesn’t contain, no way for the agent to check its own work, rules that needed enforcement rather than prompting, or a default (mode, effort, subagents) that costs more than the task is worth. It also lists older advice that current models have made unnecessary.
Key claims
- CLAUDE.md should hold only what the agent cannot discover from code: exact test/typecheck/lint commands, misleading code, decisions made outside the repo, things corrected twice. Target under 200 lines; scope narrow rules to
.claude/rules/withpaths:globs; put procedures in skills (loaded on demand). - If emphasis (“IMPORTANT”) doesn’t make a line stick, the file is too long or the line is a rule that belongs in a hook.
- The single most useful verification step is a pass/fail check the agent can run (tests, build exit code, linter, screenshot diff). Escalation ladder: prompt →
/goal(a separate model checks a condition each turn) →Stophook (exit code 2 sends the agent back; capped at eight consecutive blocks) → independent review in a fresh subagent. - Ask for evidence (the command and its output), not “all tests pass”.
- Deny rules hold in every permission mode, including auto and bypass. Rules match tool calls, not intent: a
Read(./.env)deny catchescat .envbut not a script that opens the file; a WebFetch deny doesn’t stopcurlunless the sandbox is on. - As of 2026-11, interactive terminal and VS Code sessions start in auto mode: a classifier model reviews risky actions (e.g.
curl | bash, production deploys, force pushes, exfiltration, actions that look driven by read content) after deny/ask rules and PreToolUse hooks have applied. After three consecutive (or twenty total) blocks it pauses. - Settings scopes:
~/.claude/settings.jsonand.claude/settings.local.json(personal),.claude/settings.json(repo, shared), managed settings (org, cannot be overridden). - Default model (2026-11): Claude Opus 5.5 at medium effort on most plans and providers; effort, not prompt phrases like “think harder”, controls reasoning depth.
ultrathinkboosts a single turn. - Subagents give parallelism, isolation of noisy output, unbiased review, or restricted tool sets; they do not give a smarter answer and cost tokens and sometimes time.
- Most current models have a 1M-token window with automatic compaction;
/clearbetween unrelated tasks still improves quality and cost. After two failed corrections,/clearand re-prompt. - Checkpoints (
Esctwice //rewind) restore files edited by the agent’s file tools, not files changed only by Bash. - Unattended runs: define done, give a self-check, restrict scope (permission rules,
dontAsk, sandbox, worktree), cap with--max-turns/--max-budget-usd, and have a human approve the result.claude -pwith--bare,--allowedTools,--output-format jsonis the scripting form. - Dropped advice: aggressive context management, ALL CAPS, subagents “for a better answer”, “keep going / don’t be lazy” prompts, describing architecture in CLAUDE.md.