Claude Code Best Practices

Definition

Official Anthropic guidance for using Claude Code effectively (captured from code.claude.com/docs/en/best-practices, 2026-07-31). Organizes workflow into four levers: runnable verification, explore→plan→code→commit, aggressive context management, layered environment configuration, and horizontal scaling.

Key Points

• Give Claude a runnable verification check — the difference between a session you watch and one you walk away from; verification at 4 levels: in-prompt, /goal condition (separate evaluator re-checks each turn), Stop hook (deterministic, ends turn after 8 consecutive blocks), or a verification subagent (fresh model refutes the result). “Have Claude show evidence rather than asserting success.”
• Explore → plan → code → commit, but skip the plan when the diff is one sentence — plan mode adds overhead; “If you could describe the diff in one sentence, skip the plan.”
• The context window is the most important resource — a single debugging session can generate tens of thousands of tokens; levers: /clear, auto-compaction, /compact <instructions>, /rewind, compaction instructions in CLAUDE.md, /btw (side questions that never enter history). After two failed corrections, /clear and restart.
• Configure the environment in layers — concise CLAUDE.md (read every session) + on-demand skills + deterministic hooks + context-isolating subagents + CLI tools/MCP. “Would removing this cause Claude to make mistakes? If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!” CLI tools are “the most context-efficient way to interact with external services.”
• Scale horizontally — claude -p with --output-format json|stream-json for CI; parallel sessions with fresh context for review (Writer/Reviewer); fan-out with --allowedTools "Edit,Bash(git commit *)" (test 2–3 files first); adversarial review in a fresh subagent, scoped to correctness/requirements only (a reviewer told to find gaps always finds some).

Implications

This doc is the official baseline against which the vault’s contested compression tools should be judged: it prescribes context management (compaction, /clear, subagent delegation) rather than lossy output compression — consistent with token-usage-reduction’s core levers and with the paper’s warning that destroyed evidence breaks tasks. The “verify rather than assert” and “fresh-context reviewer” patterns are workflow-level token-reduction: they catch errors when cheap.

Open Questions

• Version-sensitive: /goal, AskUserQuestion, agent teams, worktrees, /btw, /code-review skill, desktop/web, and the Stop-hook “8 consecutive blocks” threshold are all product-version-coupled (captured 2026-07-31).
• “Checkpoints only track changes made through Claude’s file editing tools… not a replacement for git.”

Related

token-usage-reduction — context-window levers the doc prescribes claude-code-memory — CLAUDE.md effectiveness rules (concise, load-every-session) claude-code-sessions — course-correction, /clear, /rename, rewind/checkpoints ai-agents-guide — agentic workflow and delegation context claude-code-system-prompt — the agent these practices configure

Sources

• raw/external/docs-anthropic-com-best-practices-855abde4.md