Claude Code Best Practices

Sources#

• An open-source spec for Codex orchestration: Symphony.
• Anthropic's Boris Cherny: Why Coding Is Solved, and What Comes Next
• Auto mode for Claude Code
• Best Practices for Claude Code
• Fable's judgement
• Full Walkthrough: Workflow for AI Coding — Matt Pocock
• How Anthropic's product team moves faster than anyone else | Cat Wu (Head of Product, Claude Code)
• Introducing Claude Opus 4.7
• Prompt Design at Scale: How Format, Instruction Count, and Context Length Shape Instruction Adherence and Hallucination in Large Language Models
• Tips & Best Practices
• Tutorial: Team Telegram Assistant

Summary#

Anthropic's official guide to effective Claude Code usage, organized around a single core constraint: the context window fills up fast and performance degrades as it fills. All best practices flow from managing this scarce resource — through verification-driven development, structured context (CLAUDE.md), aggressive session management, and horizontal scaling via parallel sessions.

Details#

Context Window as Primary Constraint#

The context window holds the entire conversation: messages, file reads, command outputs. A single debugging session can consume tens of thousands of tokens. As context fills, Claude "forgets" earlier instructions and makes more mistakes. Every best practice is ultimately about managing this resource. See Context Window Smart Zone for the underlying mechanism (quadratic attention scaling, ~100K-token smart-zone marker).

Model-level amplifiers (introduced with Claude Opus 4.7, still current under Claude Opus 4.8): the updated tokenizer maps the same input to 1.0–1.35× more tokens, and Opus 4.7 "thinks more at higher effort levels" — especially on later turns in agentic settings. Claude Code's default effort has been raised to xhigh. These compound: a session that fit on 4.6 at high may be meaningfully tighter on 4.7 at xhigh. Measure on real traffic before trusting intuition carried over from 4.6. Counter-levers: lower effort, task budgets (API), explicit conciseness prompting, or brevity-style output caps (see Scale-Dependent Prompt Sensitivity).

Verification-Driven Development#

The single highest-leverage practice: give Claude a way to verify its own work. Provide tests, screenshots, expected outputs, or linter commands. Without verification, Claude produces plausible-looking but broken code and the human becomes the only feedback loop.

Key patterns:

• Provide concrete test cases with inputs and expected outputs
• For UI changes, paste screenshots and ask Claude to compare its result
• Address root causes by providing error messages, not just "the build is failing"
• Use the Claude in Chrome extension for automated UI testing

Explore → Plan → Code Workflow#

Separate research from implementation. Use Plan Mode for multi-file changes or unfamiliar code. Skip planning when the scope is clear and the diff can be described in one sentence.

A more aggressive variant: Design Concept Grilling (Matt Pocock's grill-me skill) replaces "ask the agent for a plan" with "let the agent interview you until you reach shared understanding before any plan exists." See also Vertical Slice Tracer Bullets for slicing the resulting PRD into agent-grabbable Kanban tickets, and Deep Modules for Agents for keeping the codebase shape agent-friendly.

Environment Configuration#

• CLAUDE.md: persistent instructions loaded every session. Include only what Claude can't infer from code — bash commands, non-default code style, workflow rules, architectural decisions, gotchas. Prune ruthlessly: if Claude already does something correctly without the instruction, delete it. Per-line pruning is necessary but not sufficient, and the missing constraint is now measured: Instruction Compounding records a capacity floor from Prompt Design at Scale: How Format, Instruction Count, and Context Length Shape Instruction Adherence and Hallucination in Large Language Models (empirical, five models) where all-rules compliance is in steep decline by 40 simultaneous verifiable instructions and at zero by 80, identical across markdown / plain / prose / table rendering. Every rule in that experiment is distinct and individually satisfiable, so no per-line ablation would have caught it. Two corollaries for a CLAUDE.md: the binding unit is instruction count, not tokens, and format is not the lever — placement is the bigger one (moving an identical block between system prompt and user turn moved adherence by up to 8.7pp), with a sign that differs per model and must be tested rather than assumed. Treat like code — review when things go wrong, test by observing behavior changes. Use @path imports for modularity. For founders / solo builders, the stricter discipline of starting each session with the CLAUDE.md as architectural context and ending each session by updating it is the primary defense against Agentic Technical Debt — debt that compounds (not just accumulates) because each session re-derives foundational decisions when context isn't persisted.
• Skills (.claude/skills/): domain knowledge and reusable workflows loaded on demand, not every session. Invoke with /skill-name.
• Subagents (.claude/agents/): specialized assistants running in isolated context with scoped tools. Useful for tasks that read many files without cluttering main context.
• Hooks: deterministic scripts that run at specific points in Claude's workflow. Unlike CLAUDE.md (advisory), hooks guarantee execution.
• MCP servers: connect external tools (Notion, Figma, databases) via claude mcp add.
• Plugins: bundled skills + hooks + subagents + MCP from a marketplace.
• Permissions: auto mode (classifier-based approval, middle ground between default-prompt and --dangerously-skip-permissions), allowlists, or OS-level sandboxing.

Session Management#

• /clear between unrelated tasks — prevents context pollution
• /compact <instructions> — targeted summarization preserving specified context
• /rewind or Esc+Esc — restore conversation, code, or both to any checkpoint
• Subagents for investigation — explore in separate context, report back summaries
• /btw — side questions that never enter conversation history
• After two failed corrections on the same issue, /clear and rewrite the prompt incorporating what you learned

Scaling Patterns#

• Non-interactive mode: claude -p "prompt" for CI, scripts, pre-commit hooks. Supports JSON and streaming output.
• Parallel sessions: desktop app (isolated worktrees), web (isolated VMs), or agent teams (coordinated sessions with shared tasks).
• Writer/Reviewer pattern: one session implements, another reviews with fresh context (no bias toward own code).
• Fan-out: loop claude -p across files for large migrations. Use --allowedTools to scope permissions.
• Auto mode for unattended runs: classifier blocks risky actions, allows routine work. Aborts on repeated blocks in non-interactive mode.
• Loops and routines: /loop (cron-scheduled repeat job, in-CLI) and routines (server-side variant). Drain a Kanban backlog AFK; primary mechanism for amortizing planning over many executions. See Agent Loop Pattern.

Parallel Ecosystems and Cross-Tool Concept Mapping#

Claude Code is one of several converging coding-agent ecosystems. Capability parallels with Hermes Agent (Nous Research) and Codex (OpenAI):

Capability	Claude Code	Hermes	Codex
Project context file	CLAUDE.md	AGENTS.md (project) + SOUL.md (personality, separate)	AGENTS.md
Session compaction	/compact <instructions>	/compress	(via Codex App Server thread compaction)
Mid-session model switch	/model	/model	session-level config
Parallel subagents	Subagents in .claude/agents/	delegate_task	Spawned via Symphony orchestrator
Non-interactive / programmatic	claude -p, Claude Agent SDK	hermes CLI in scripts	Codex App Server (JSON-RPC stdio)
Multi-user team deployment	per-session claude -p	Hermes Gateway (Telegram/Discord/Slack/WhatsApp) with allowlist or DM pairing	Symphony (issue-tracker-driven daemon)
Permission gating	auto mode classifier	per-pattern approvals (once/session/always/deny); skipped under container backend	implementation-defined per Symphony spec
Memory model	conversation + CLAUDE.md	bounded MEMORY.md (~2,200 chars) + USER.md (~1,375 chars)	filesystem-driven

The shared structural insight across all three: agent behavior is configured via repo-versioned markdown files (CLAUDE.md / AGENTS.md / SOUL.md / WORKFLOW.md). This pattern is consistent enough across vendors to look like an emerging standard. (A dedicated Agent Context Files concept page is planned to formalize this.)

The most architectural divergence: Claude Code is session-first with optional non-interactive mode; Hermes Gateway and Symphony are daemon-first when deployed at team scale. The session-vs-daemon split is the dominant deployment-architecture choice in 2026.

Common Failure Patterns#

Pattern	Fix
Kitchen sink session (mixed unrelated tasks)	/clear between tasks
Repeated corrections (>2 failed fixes)	/clear, rewrite prompt with lessons learned
Over-specified CLAUDE.md	Prune; convert to hooks if deterministic
Trust-then-verify gap	Always provide verification criteria
Infinite exploration	Scope narrowly or use subagents

Connections#

• Agent Harness Engineering — Claude Code's CLAUDE.md, skills, and hooks are a practical implementation of the harness engineering patterns described by OpenAI and Anthropic's research teams
• LLM-as-Compiler Knowledge Base — CLAUDE.md files serve as the schema layer in this vault's LLM-as-compiler architecture
• LLM-Driven Vulnerability Research — Claude Code is the runtime for Anthropic's vulnerability research scaffold; all Mythos Preview findings used Claude Code's agentic capabilities
• Client-Side Agent Optimization — directly challenges the "use the strongest model" default: combinations where Claude Opus 4.6 is paired with a cheaper planner beat all-Opus by >40pp on HotpotQA. AgentOpt's httpx interception is compatible with claude -p non-interactive mode
• Scale-Dependent Prompt Sensitivity — complements context-window management: brevity constraints both raise accuracy on overthinking-prone problems and preserve context budget. Verification-driven development is especially important when large-model verbosity can mask reasoning errors
• Claude Code Auto Mode — the full write-up of the "auto mode" permission option mentioned in Environment Configuration and Scaling Patterns
• Claude Opus 4.7 — introduced the literal instruction following and tokenizer inflation that reshape how CLAUDE.md and session management should be written
• Claude Opus 4.8 — the model most Claude Code work now targets (general access since 2026-05-28); a direct 4.7 upgrade, so the context-budget guidance above carries over unchanged. One caveat for the Environment Configuration section: 4.8 is less robust to prompt injection than 4.7, which raises the value of narrow tool permissions
• Hermes Agent — parallel ecosystem from Nous Research; many Claude Code patterns map directly (/compress ↔ /compact, delegate_task ↔ subagents, AGENTS.md ↔ CLAUDE.md); the differences (Gateway daemon, bounded memory files, SOUL.md split) highlight design choices each made
• Codex App Server Protocol — the OpenAI-side analog to claude -p + Claude Agent SDK; both let an external orchestrator drive sessions, but App Server is more explicit about a stable JSON-RPC stdio protocol
• Symphony — the daemon-first deployment archetype; a Claude-Code analog would wire claude -p plus subagents into an issue tracker the same way Symphony wires Codex to Linear
• Ticket-Driven Agent Orchestration — the orchestration pattern that becomes natural once non-interactive mode is solid; bridges single-session best practices into team-scale deployment
• Context Window Smart Zone — the underlying constraint that motivates every context-management practice in this article
• Design Concept Grilling — more aggressive alignment-first variant of explore→plan→code
• Vertical Slice Tracer Bullets — task decomposition pattern that fills the Kanban backlog drained by the loop primitive
• Deep Modules for Agents — codebase shape that makes Claude Code's review and verification patterns reliable; push-vs-pull instruction delivery
• Agent Loop Pattern — /loop and routines as the next-generation primitive replacing per-step prompting
• Harness Shrinkage as Models Improve — why best-practice prompts and CLAUDE.md sections shrink with each model release; Cat Wu's discipline of pruning at every launch
• Claude Code — the entity-level page
• AI Native Product Cadence — these best-practice artifacts are the public output of a team operating at that internal cadence
• Engineer PM Convergence — the engineer-with-product-taste persona this guide implicitly targets
• Agentic Technical Debt — the failure mode CLAUDE.md primarily defends against; specifically named in the founder's playbook
• AI-Native Startup Lifecycle — the founder-stage framing that elevates CLAUDE.md from "best practice" to "MVP survival discipline"
• MCP and Computer Use — the connector substrate behind the "extend Claude Code with custom tools" scaling pattern; MCP and computer use are how external systems become part of the agent's action surface
• Evals as Product Spec — the strict form of "verification-driven development": ten great evals encode what done looks like at the feature level, complementing the workflow-level verification this article prescribes

Derived#

• When to Use Claude Opus 4.6 for Work — context-window-as-primary-constraint framing informs the Claude Code corollary: Opus verbosity consumes budget faster
• Opus 4.6 → 4.7 Changes and Multi-Agent Coding Considerations — subagents, Writer/Reviewer, and scaling-pattern guidance applied to Opus 4.7 multi-agent teams
• Learning to Co-Work with AI: A Software Engineer's Field Guide — best-practices distilled into a per-engineer skill-development field guide (six skill clusters, daily practices, anti-patterns, 90-day plan)
• App Server vs MCP, and the Claude-Side Equivalent: Three Boundaries for Driving Agents — situates claude -p + Agent SDK as the Claude-side bracket around Codex's App Server, with the drive-the-CLI vs build-on-SDK decision rule

Open Questions#

• Does the instruction-count ceiling hold for conditional policy, where only a handful of rules bear on any given turn? Every rule in Eliav's experiment applies to one generation simultaneously; a CLAUDE.md is mostly situational ("when editing migrations, …"), so N=80 is a floor on the harshest possible loading and says nothing about a 200-rule file of which five fire per turn. Falsifiable directly: hold the applicable subset fixed and grow the inapplicable remainder.
• How does the Writer/Reviewer pattern compare to agent-to-agent review (as in OpenAI's Codex workflow)?
• When does subagent overhead exceed the benefit of context isolation? Partially answered 2026-08-03 by Codex from 0 to 10M Users: Building ChatGPT Work - Akshay Nathan, OpenAI (practitioner-opinion, no measurement) — a task-shape criterion rather than a crossover point. Akshay Nathan (OpenAI): multi-agent modes "are best for when you have tasks that are either incredibly complicated, like open explorations, or very paralyzable… but for most tasks, they don't fall into either of those buckets," so the default should be a single agent. Note the overheads he actually names are neither context nor tokens: rate-limit consumption (Ultra "can use more of your limits," which is why OpenAI moved it behind advanced settings post-launch) and human legibility (sub-agent transcripts hidden by default to avoid overwhelming users — see Shared Harness, Differentiated Surfaces). A practitioner counter-practice in the same episode pulls the other way: Vibhu reports telling every long-running task to "use sub-agents where possible" for wall-clock and for cost, fanning out to cheaper models — which Cost-per-Task Over Cost-per-Token argues is the wrong default. Second instance (2026-08-04): Willison runs the same practice with the tier choice itself delegated — "for all coding tasks use your judgement to decide an appropriate lower power model and run that in a subagent" — and reports only that his Fable allowance shrinks more slowly. Two practitioners now default to the fan-out; neither measures it. What remains open is the measured crossover, which no source in the corpus supplies.

Resolved Questions#

• What's the optimal CLAUDE.md length before instructions start getting lost? Is there a measurable threshold? Answered 2026-08-04 by Prompt Design at Scale: How Format, Instruction Count, and Context Length Shape Instruction Adherence and Hallucination in Large Language Models (Eliav, arXiv 2607.19257, empirical) — full treatment at Instruction Compounding. Yes, there is a threshold, and it is count-shaped rather than length-shaped: across five models (including Claude Sonnet 5 and Haiku 4.5), the rate at which every instruction in the prompt is obeyed falls steeply by N≈40 simultaneous verifiable rules and hits zero by N≈80, holding through N=160 and identical across markdown, plain text, prose, and table renderings and across system-prompt vs. user-turn placement. The paper's own prescription is the answer in usable form: 40 simultaneous instructions is a redesign point, not a tuning point — past it, splitting across turns, tools, or a validation pass is the only thing that works, and reformatting is not. This also settles the residual the 2026-08-03 retag left behind (does aggregate size have an independent effect once each line passes ablation?): yes — every rule tested was distinct, non-redundant, and individually satisfiable, so per-line ablation non-inferiority would have cleared all of them and still missed the collapse. Two scope limits carried on the answer: "perfect response" is a strict conjunction, so some of the floor is the arithmetic of ANDing N checks rather than the model dropping the block, and every rule tested is a hard output constraint applied to a single generation. The conditional-policy case a real CLAUDE.md actually presents is now the successor question in Open Questions above.

Sources#

• Best Practices for Claude Code
• Auto mode for Claude Code — permission-mode expansion
• Introducing Claude Opus 4.7 — tokenizer/xhigh-default context-budget implications
• Prompt Design at Scale: How Format, Instruction Count, and Context Length Shape Instruction Adherence and Hallucination in Large Language Models — Netanel Eliav, arXiv 2607.19257, 2026-07-21 (empirical, sole author, single lab, not peer reviewed): the instruction-count ceiling that answers the CLAUDE.md-length question, plus the placement lever. Parse warning: the paper's Table 1 model roster is cell-collapsed in the raw markdown and is not cited anywhere; see the Sources note on Instruction Compounding
• Fable's judgement — Simon Willison, 2026-07-03 (practitioner-opinion): the delegate-coding-to-a-self-chosen-cheaper-subagent practice, cited only against the subagent-overhead question above