LLM Wiki — Synaptic Lattice

Claude Code Best Practices

Properties1
tagsprompt-engineering, workflow-pattern, tool-origin

Leitura de 4 min

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.

Field Report — Plan Tiers, Hooks, and the 5-Server Stack (2026-04-24)

A 2026-04-24 field report extends the official baseline with three concrete layers. Plan Mode in three tiers: Simple (single-file), Visual (multi-file structure), Deep (multi-service/risky refactors, with read-only planning subagents explicitly denied write/edit). Hooks as deterministic guardrails: a PreToolUse gate that defers any git push to main (session pauses, human approves out-of-band, agent resumes where it stopped — no --dangerously-skip-permissions for nightlies), a PostToolUse one-liner running the formatter after every write (highest-ROI hook: the file is clean before the next turn), and a PermissionDenied logger appending JSONL for denied-operation audits. MCP servers capped at five instead of fifteen — code-graph with session memory, GitHub, filesystem, live web search, version-specific docs — because tool schemas tax every turn (Anthropic’s Tool Search docs: ~50 tools cost 10,000–20,000 tokens/turn without lazy loading, ~85% less with it, but fewer servers still wins). Server-side note: servers can set an anthropic/maxResultSizeChars annotation in _meta to keep large doc pulls inline. Floor/ceiling rule from the same source: minimum viable stack is a short imperative root memory file, two path-scoped rules for the most-touched directories, one formatting hook, three servers (repo, filesystem, library docs), and forced Plan Mode for anything risky — add subagents when a task repeats, skills when a workflow stabilizes, worktrees past two branch switches/hour, headless when the agent should ship while you sleep.

Implications: the hook pair (defer-push + format-on-write) is the cheapest hardening a team can copy today, and the 5-server cap operationalizes the page’s “context window is the most important resource” lever with a number. The Deferred Permissions mechanism is what makes headless CI viable rather than a 3am failure.

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.”
  • Unverified vendor claims in the field report (vexp 65–70% token reduction, “30 minutes vs an afternoon”) need independent measurement before becoming guidance.

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
  • raw/external/freedium-mirror-cfd-i-spent-6-months-tuning-claude-code-here-a23e1587.md

Visão de gráfico

Backlinks