Library
Claude Code Documentation (June 2026) · 14 of 15
Claude Code Documentation (June 2026)
ai HIGH

Claude Code Rules of Thumb

Claude Code Documentation (June 2026) Anthropic
heuristics context safety parallelism configuration teams

Key Principle

Context is the scarce resource, safety is layered, and parallelism multiplies cost. These one-line heuristics, collected across the Claude Code docs, encode the judgment calls that make the tool reliable.

Why This Matters

Most failures are not capability failures — they are context, scoping, or configuration mistakes. A short list of imperatives, applied consistently, prevents the common ones.

Context Management

  • If you could describe the diff in one sentence, skip the plan; otherwise plan first (Section: Plan mode workflow).
  • Corrected Claude more than twice on the same issue? /clear and restart with a sharper prompt that bakes in what you learned (Section: Course-correct early and often).
  • /clear frequently between unrelated tasks — a long session carrying corrections almost always loses to a clean one with a better prompt.
  • Provide context, don't over-prompt — @-mention files and paste real errors/logs; context beats elaborate phrasing.
  • Keep CLAUDE.md short: for each line ask "would removing this cause Claude to make mistakes?" — "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!" (Section: Write an effective CLAUDE.md).
  • Move on-demand domain knowledge and sometimes-relevant workflows into skills; reserve CLAUDE.md for broadly-applicable, always-on context.
  • Use subagents for investigation — they read many files in a separate window and report only summaries, keeping the main conversation clean.
  • Spend cheap read-only plan-mode tokens to settle the approach before committing expensive edit/test/commit tokens.
  • Time spent making the spec precise pays off more than time spent watching the implementation (Section: Let Claude interview you).
  • Treat named sessions like branches: one persistent context per workstream (/rename oauth-migration).
  • Checkpoints track only Claude's changes — not a git replacement.

Safety & Permissions

  • Permissions gate which tool; sandboxing gates what the tool's process can touch — you need both (Section: Permissions vs. sandboxing).
  • Denying WebFetch doesn't stop curl/wget if Bash is allowed — close that gap with a sandbox network allowlist.
  • Use hooks, not CLAUDE.md, for actions that must happen every time with zero exceptions — hooks are deterministic; CLAUDE.md is advisory.
  • Set disable-model-invocation: true on side-effecting workflows so Claude can't auto-run something destructive that merely seems relevant.
  • Auto mode trusts only your working dir and the repo's configured remotes by default; teach it your infra via autoMode.environment rather than disabling it.
  • The auto-mode classifier reads the same CLAUDE.md Claude loads — a natural-language guardrail ("never force push") steers both.
  • Scope unattended claude -p runs with --allowedTools; nothing prompts you when no human is in the loop.
  • Scope reviewers to gaps affecting correctness or stated requirements — a reviewer told to find gaps will over-report and push you toward over-engineering.

Parallelism & Scaling

  • Pick a parallel surface by who holds the plan, whether workers must talk, and whether tasks touch the same files (Section: Choosing a parallel-execution surface).
  • Wrong surface choice = lost work (no isolation → merge conflicts) or wasted tokens (over-coordinating independent tasks).
  • Isolate tasks that touch the same files with worktrees; agent teams don't isolate teammates, so partition the work by file set.
  • Use agent teams only when cross-talk between workers is actually needed.
  • A fresh context reviews better — it isn't biased toward code it just wrote (Writer/Reviewer pattern).
  • Refine the fan-out prompt on the first 2–3 files, then run the full set — cheap to fix the prompt, expensive to redo thousands.
  • Running several sessions or subagents at once multiplies token usage — check Costs.
  • The longer Claude works unattended, the more an independent fresh-context review matters; add an adversarial review step before calling work done.

Configuration

  • /init to bootstrap CLAUDE.md, then treat it like code: review when things go wrong, prune regularly, test by watching whether behavior shifts.
  • A rule repeatedly violated usually means the file is too long and the rule is getting lost; a question already answered in CLAUDE.md means the phrasing is ambiguous.
  • Prefer a CLI (gh, aws, gcloud) over an MCP server when one exists — CLI calls return compact text and are the most context-efficient integration.
  • Tune CLAUDE.md adherence with emphasis ("IMPORTANT", "YOU MUST") and check it into git so the team contributes.
  • Customize compaction in CLAUDE.md so critical context survives (e.g. "always preserve the full list of modified files and any test commands").
  • Use settings files (not shell exports) for env vars like AWS_PROFILE you don't want leaking to other processes.

Providers & Auth

  • Auth precedence: the first matching credential wins — a stray ANTHROPIC_API_KEY silently overrides your subscription (unset it, confirm with /status).
  • For CI/scripts without browser login, use claude setup-token (CLAUDE_CODE_OAUTH_TOKEN, one year, inference-scoped — not for Remote Control; --bare ignores it).
  • Claude for Teams/Enterprise is the default provider recommendation; choose Bedrock/Vertex/Foundry to inherit cloud compliance and billing.
  • Claude Code on the web, Routines, Code Review, Remote Control, and the Chrome extension need a Claude.ai account — not available through Console API keys or cloud-provider credentials alone.
  • On Bedrock, pin model versions for multi-user deploys (ANTHROPIC_DEFAULT_OPUS_MODEL etc.) — without ANTHROPIC_DEFAULT_OPUS_MODEL, the opus alias resolves to Opus 4.6.
  • For routing by data sensitivity or request-level audit logging, place an LLM gateway between developers and the provider.

Team Use

  • Share durable, copyable artifacts (skills are plain Markdown → instant adoption), not bespoke prompting (Section: Team adoption).
  • Lead with the warm introduction, not the onboarding program; demo on the person's own code.
  • Run /team-onboarding in a project you've spent real time in, then pin the result as a new teammate's first message.
  • A rollout is working when the community sustains itself without you — questions get answered by people other than the champion.

Key Commands & Config

  • Context: /clear, /compact, /rewind, Esc/Esc Esc, Shift+Tab, Ctrl+G
  • Safety: /permissions, /sandbox, /hooks, autoMode.environment, --allowedTools
  • Scaling: claude -p, claude --bg, claude agents, /code-review, worktrees
  • Auth: claude setup-token, /status, CLAUDE_CODE_OAUTH_TOKEN

Rules of Thumb

  • When in doubt, reset context and sharpen the prompt before pushing the same conversation further.
  • Layer safety controls — never rely on a single ring (permissions, sandbox, hooks, managed settings).
  • Match the parallelism surface to the work; don't reach for teams when subagents suffice.

Related References