Claude Code: Best practices for agentic coding

anthropic.com · article · 2025-04-18 source ↗ Reader 🖥️

practical · expository prescriptive guide — A best-practices guide: it argues 'you should do X' for agentic coding with Claude Code, grounding each recommendation in claims about how the tool and model behave. Organized as six numbered sections (customize setup, give more tools, common workflows, optimize workflow, headless mode, multi-Claude) of experience-derived patterns rather than a single sustained argument.

Structure

Key terms

• CLAUDE.md Agent Context Files (CLAUDE.md / AGENTS.md)
  A special markdown file Claude Code automatically pulls into context at the start of a conversation, holding persistent project context (bash commands, core files, code style, testing instructions, repo etiquette, environment setup, warnings); placeable at repo root, parent dirs, child dirs, or home folder, and meant to be treated and iterated on like a prompt
• agentic coding
  Software development in which an assistant like Claude Code autonomously reads, searches, plans, edits, runs, and iterates on code across multiple steps with tool access, rather than emitting a single completion
• extended thinking Extended Thinking / Reasoning
  A mode giving Claude additional computation time to evaluate alternatives, triggered by escalating keywords 'think' < 'think hard' < 'think harder' < 'ultrathink' that map directly to progressively larger thinking-budget allocations
• explore, plan, code, commit
  A versatile workflow in which the user first has Claude read/research relevant material (explicitly not coding yet), then make a plan (optionally with extended thinking), then implement, then commit — because skipping the first two steps makes Claude jump straight to code
• test-driven development Test-Driven Development
  An Anthropic-favorite agent workflow: have Claude write tests from expected input/output pairs first (avoiding mock implementations), confirm they fail, commit them, then write code that iterates until all tests pass without modifying the tests — the tests are the verifiable target Claude iterates against
• allowed tools / allowlist
  The curated set of tools Claude Code may run without asking; by default it requests permission for anything that could modify the system (file writes, many bash commands, MCP tools), and the user loosens this deliberately conservative deny-by-default posture only for actions that are safe or easily undone
• subagents Multi-Agent Orchestration
  Secondary Claude instances the main agent spawns to verify details or investigate specific questions — used especially early in a task to preserve the main context window without much efficiency loss, and to check that an implementation isn't overfitting to its tests
• headless mode
  Non-interactive invocation of Claude Code via the -p flag for CI, pre-commit hooks, build scripts, and automation — with --output-format stream-json for structured output; does not persist between sessions and must be triggered each time
• course correct
  Actively steering Claude mid-task rather than letting it run autonomously — asking for a plan before code, pressing Escape to interrupt while preserving context, double-tapping Escape to rewind history and edit a prior prompt, or asking Claude to undo changes
• safe YOLO mode
  Running claude --dangerously-skip-permissions to bypass all permission checks and let Claude work uninterrupted — recommended only inside a container without internet access to bound the risk of data loss or exfiltration via prompt injection
• git worktrees
  Multiple branches of one repo checked out into separate directories sharing history, letting several Claude sessions run simultaneously on independent, non-overlapping tasks without merge conflicts — a lighter-weight alternative to multiple full checkouts
• MCP MCP (Model Context Protocol)
  The Model Context Protocol, which Claude Code speaks as both server and client; as a client it connects to any number of MCP servers (via project config, global config, or a checked-in .mcp.json) to gain their tools

Propositions

• explicitClaude Code is intentionally low-level and unopinionated — near-raw model access without a forced workflow — which makes it flexible, scriptable, and safe but imposes a best-practices learning curve on new users.conf: high
• explicitA CLAUDE.md file, automatically pulled into context when a conversation starts, is the primary place to give Claude persistent project context: common commands, core files, code style, testing instructions, repo etiquette, environment setup, and project-specific warnings.conf: high
  supportsCharlie Hills 🦩's Post · p1 — This guide is the canonical source for CLAUDE.md as an auto-loaded file carrying persistent per-session, per-project rules.
• explicitCLAUDE.md files should be treated and refined like any frequently used prompt — kept concise and iterated on (via the prompt improver and emphasis such as IMPORTANT/YOU MUST) — because adding extensive content without iterating on its effectiveness is a common mistake that hurts instruction-following.conf: high
  supportsYour AGENTS.md might be a big problem · p7 — The guide's warning that adding extensive content without iterating is a common mistake anticipates Pocock's thesis that fewer, well-chosen instructions beat a larger exhaustive rule set.
• implicitThe model's effective performance on your codebase is bounded by the harness you assemble around it — CLAUDE.md context, the curated tool allow-list, MCP servers, and custom bash scripts and slash commands — not by the raw model weights alone, so configuring that context-and-tool layer is the user's highest-leverage action.conf: high
  supportsAgent Harness Engineering · p1 — This canonical 2025 guide's whole premise — that a deliberately low-level model rewards the context/tools you engineer around it — is a concrete, early instance of 'a decent model with a great harness beats a great model with a bad harness.'
  supportsAgent Harness Engineering · p2 — The guide's insistence that you must supply CLAUDE.md, tools, and workflow to get good results is exactly the claim that the gap between what the model can do and what users see is largely a harness gap.
• explicitYou should curate an explicit allow-list of tools, loosening Claude Code's deliberately conservative, deny-by-default permission posture only for actions that are safe or easily undone (e.g. file edits, git commit).conf: high
• explicitdevelopedFor most problems, follow explore → plan → code → commit: have Claude read and research first (explicitly not coding yet, using subagents for hard questions), make a plan, only then implement, then commit — because without the research-and-plan steps Claude tends to jump straight to coding, which degrades results on problems needing deeper thought.conf: high
  supportsAgent Skills · p1 — The observation that Claude jumps straight to coding without explicit research-and-plan steps is a concrete instance of Osmani's claim that a coding agent's default is the shortest path to 'done,' skipping planning and verification.
  extends ←No Vibes Allowed: Solving Hard Problems in Complex Codebases – Dex Horthy, HumanLayer · p7 — Both describe essentially the same explore/research → plan → implement workflow; this talk adds the explicit context-budget rationale (staying in the smart zone) and compaction discipline as the reason the sequencing works.
• explicitExtended thinking is triggered by escalating keywords — 'think' < 'think hard' < 'think harder' < 'ultrathink' — that map directly to progressively larger thinking-budget allocations, giving Claude more computation to evaluate alternatives.conf: high
  supportsI benchmarked CC's caveman plugin against 'be brief'. The token math is wild. · p8 — Documenting a keyword-controlled thinking budget as a lever distinct from visible output supports the caveman analysis that models with separate reasoning tokens would not suffer chain-of-thought amputation from output compression.
• implicitThinking budget should scale with problem difficulty: deliberately spend more reasoning on hard planning steps and less on routine work, dialing the budget via the escalating think-keywords.conf: high
  supportsPrompting Claude Fable 5 · p5 — The think-keyword ladder (think < think hard < ultrathink) is the 2025 coarse precursor to Fable 5's `effort` setting — both hold that reasoning allocation should scale with task difficulty as the primary intelligence/cost lever.
  supports[MODEL] Claude Code is unusable for complex engineering tasks with the Feb updates #42796 · p2 — Anthropic's own guide framing extended thinking as the lever for harder, deeper problems supports the issue's claim that extended thinking tokens are structurally required for multi-step research and careful code modification.
• explicitcontestedTest-driven development becomes even more powerful with agents: have Claude write tests from expected input/output pairs first (avoiding mocks), confirm they fail, commit them, then write code that iterates until all tests pass — without modifying the tests.conf: high
  contradicts ←Software Teaming in the Age of AI with James Herr and Woody Zuill · p11 — extract-claude-code-best-practices#p9 claims TDD 'becomes even more powerful with agents' (write tests first, iterate until they pass without modifying them); Woody's practitioner experience directly contradicts this — LLMs have no design intent when writing/using tests, and under pressure hardcode outputs rather than generalizing, so TDD's design function does not transfer.
• implicitcorroboratedA clear, machine-checkable target to iterate against — a test case, a visual mock/screenshot, or another expected output — is what makes Claude's iteration converge on quality; given such a target it can make changes, evaluate results, and incrementally improve until it succeeds.conf: high
  supports ←How we Claude Code · p9 — Supports and instantiates the best-practices claim that a clear, machine-checkable target (a visual mock/screenshot) drives convergent iteration — the four-HTML-design-direction demo is a direct, worked example of exactly this pattern applied to UI design.
• explicitcorroboratedActive human course-correction early and often — forcing a plan before code, pressing Escape to interrupt, double-Escape to rewind and edit a prior prompt, and asking Claude to undo — generally produces better solutions faster than letting Claude run autonomously to completion.conf: high
  supports ←10 Things Developers Want from their Agentic IDEs in 2025 · p10 — Both point to Claude Code's rewind/checkpoint mechanism as the concrete implementation of the rollback capability developers want.
• implicitcorroboratedContext is a finite, degradable resource — during long sessions the window fills with irrelevant conversation, files, and commands that reduce performance and distract Claude — so it must be managed deliberately: /clear between tasks, context-quarantining subagents, and external Markdown checklists/scratchpads for multi-step work.conf: high
  supportsCharlie Hills 🦩's Post · p4 — This guide is the canonical source of the claim that long sessions degrade output because context fills with irrelevant content, and prescribes /clear as the remedy.
  supportsHarness design for long-running application development · p2 — Recommending /clear plus a scratchpad handoff and context-quarantining subagents is a coarse precursor to the harness paper's structured context-reset-over-compaction finding.
  supports ←The Orchestrator's Tax · p6 — Restates and specializes the general 'context is a finite, degradable resource' claim into the multi-agent case: the orchestrator specifically is the part of the system that must not be polluted.
• explicitSpecific, detailed instructions — naming the edge case, pointing to an example file, saying 'avoid mocks' — markedly raise Claude's first-attempt success rate over vague prompts, because Claude can infer intent but cannot read minds.conf: high
• explicitRunning multiple Claude instances in parallel — one writing while another reviews or tests, or several git worktrees/checkouts on independent tasks — outperforms a single Claude handling everything, because separate context windows behave like separate engineers.conf: high
• implicitSeparating generation from verification into distinct instances beats a single agent judging its own work, because a reviewer with separate context is not anchored to the author's reasoning.conf: high
  supportsAgent Harness Engineering · p7 — The 'one Claude writes, another verifies' pattern is a concrete, earlier instance of separating generation from evaluation into distinct agents because self-grading skews positive.
  supportsHarness design for long-running application development · p3 — Separating a verifier with fresh context anticipates the harness paper's finding that a standalone skeptical evaluator is more tractable than making a generator critical of its own work.
• explicitdevelopedHeadless mode (claude -p) embeds Claude Code programmatically into CI, hooks, and pipelines — fanning out across large batches (e.g. thousands of file migrations, each returning OK/FAIL) or pipelining structured JSON output into downstream commands.conf: high
  extends ←How building software is changing at Anthropic · p12 — Jarred's interactive fan-out of a single hard migration across many parallel Claude agents is the same 'fanning out' pattern as Claude Code's headless-mode batch fan-out across CI pipelines, applied to a much less mechanical, higher-judgment task.
• implicitThe directory placement of CLAUDE.md is itself a context-budgeting mechanism: files in parent directories are pulled into context automatically at session start, while files in child directories are pulled in only on demand when Claude works with those subtrees, scoping instructions to where they are relevant.conf: high
  supportsYour AGENTS.md might be a big problem · p6 — The guide documents the exact loading mechanism — child-directory CLAUDE.md files pulled in only on demand — that grounds Pocock's claim that nesting genuinely defers instruction-budget cost.
• explicitcontestedYou should use the # key to have Claude append new instructions to the relevant CLAUDE.md as you work, and commit those changes so teammates benefit — steadily accreting project knowledge into the file over time.conf: high
  contradictsYour AGENTS.md might be a big problem · p2 — This guide actively recommends the #-key habit of appending a rule to CLAUDE.md after issues arise; Pocock identifies exactly this reactive accretion as the mechanism that produces performance-degrading AGENTS.md bloat — a genuine tension between knowledge accretion and instruction-budget discipline.

Arguments

Narratives

• The explore-plan-code-commit workflow: ask Claude to read relevant files/images/URLs without coding (using subagents for hard sub-questions), have it make a plan with extended thinking and optionally save it as a doc/GitHub issue to reset to, then implement, then commit and open a PR.
  → The guide's flagship worked workflow, demonstrating that inserting explicit research and planning phases before coding is what improves results on hard problems.
• The agentic TDD workflow: Claude writes tests from input/output pairs (no mocks), runs them to confirm they fail, commits the tests, then writes code that loops — run, adjust, re-run — until all tests pass without touching the tests, with a subagent checking it isn't overfitting.
  → Concretely instruments the 'clear target to iterate against' principle, showing tests as the verifiable signal the agent's self-correction loop converges on.
• The screenshot-iterate workflow: give Claude a way to take browser screenshots (Puppeteer/iOS-simulator MCP) plus a visual mock, ask it to implement the design, screenshot the result, and iterate 2-3 times until it matches the mock.
  → Shows the same iterate-against-a-target principle in a non-test modality, generalizing the feedback signal from tests to visual output.
• The lint-fix checklist workflow: tell Claude to run the lint command and write every error (file + line) to a Markdown checklist, then work through them one by one, verifying and checking off each before moving on.
  → Demonstrates externalizing state into a scratchpad to preserve performance across a long, exhaustive multi-step task — an antidote to context degradation.
• The headless fan-out: have Claude write a script to list, say, 2,000 files to migrate from React to Vue, then loop calling claude -p per file with a scoped toolset, each returning the string OK or FAIL, refining the prompt across runs.
  → Illustrates using headless mode to turn the agent into a programmatic batch worker for large migrations, scaling beyond interactive use.
• The multi-Claude write/verify loop: one Claude writes code, then /clear or a second terminal Claude reviews it, then a third reads both code and review and edits accordingly — optionally with the instances passing notes via separate scratchpad files.
  → Concretely realizes the generation/verification separation, showing separate context windows acting like separate engineers.

Questions addressed

• ✅ How should I configure Claude Code so it performs well on my codebase?
  Create and iteratively tune CLAUDE.md files, curate the tool allow-list, install gh, and expose bash tools, MCP servers, and custom slash commands.
• ✅ When and how much should the model think before acting?
  Trigger extended thinking with escalating keywords (think < think hard < think harder < ultrathink) mapped to larger thinking budgets, chosen by problem difficulty.
• ✅ How do I keep a long session from degrading in quality?
  Use /clear between tasks, offload investigation to subagents, and externalize multi-step state into Markdown checklists/scratchpads.
• ✅ How do I keep the agent from jumping to a wrong or premature solution?
  Use explore-plan-code-commit, be specific, and course-correct early with plan-first, Escape/double-Escape, and undo.
• ✅ How do I scale beyond a single interactive session?
  Use headless mode (fan-out and pipelining) and multi-Claude workflows across separate terminals, checkouts, or git worktrees.
• ⭕ Which model, or which effort/thinking level, should I use for which step — and can this be routed automatically?
  The guide treats 'Claude' as a single model; it never addresses model selection, per-step model allocation, or automatic routing.
• ⭕ How much do these practices cost (tokens, rate limits) and when is the harness overhead worth it?
  Cost, rate limits, and cost/benefit thresholds for multi-Claude and headless fan-out are not discussed.

Gaps

• incompleteNo model-selection or routing guidance. The guide treats 'Claude' as one undifferentiated model and never addresses which model or thinking/effort level to use for which step (e.g. plan with a stronger model, implement with a cheaper one), nor automatic model routing — a lever the rest of the 2026 corpus treats as first-class. Being dated 2025-04-18, it predates the effort-knob and routing discourse.
  Read next: Read against extract-charlie-hills-32-things-claude-code#p5 (Opus-plan / Sonnet-implement allocation), the model-routing concept, and extract-prompting-claude-fable-5#p5 (the effort setting as primary intelligence/latency/cost control).
• incompleteThe think-keyword thinking budget is presented as folklore: no numbers for how much budget each level allocates, no account of the cost/latency trade-off of higher budgets, and — being 2025 — no notion of a separate reasoning-token budget distinct from visible output. A reader cannot calibrate when 'ultrathink' is worth its cost.
  Read next: Read against extract-prompting-claude-fable-5#p5 (the graduated effort setting), extract-claude-code-github-issue (thinking tokens as load-bearing and rationed), and the extended-thinking concept.
• incompleteEverything is asserted from Anthropic-internal and community experience with no comparative or quantitative evidence: no A/B of CLAUDE.md-vs-none, no measured effect of subagents on context availability, no failure-rate or effect-size data for any recommended practice. It is impossible to tell which practices generalize versus which are idiosyncratic to Anthropic's workflows.
  Read next: Look for controlled Claude Code workflow comparisons and benchmark data (e.g. extract-cc-caveman-benchmark for token measurement); read against extract-charlie-hills-32-things-claude-code#g1, which flags the same evidence gap for a parallel tips list.
• incompleteThe CLAUDE.md guidance omits the failure mode later corpus work centers on: bloat. It recommends the #-key 'append a rule' habit and running files through the prompt improver, but gives no instruction-budget ceiling, no progressive-disclosure/nesting strategy beyond raw directory placement, and no account of how many instructions a model can actually follow before adherence degrades.
  Read next: Read against extract-pocock-agents-md-problem (the ~150-200 instruction ceiling and nesting-as-progressive-disclosure), the progressive-disclosure concept, and extract-agent-harness-engineering#p4 (every line should trace to a specific failure).
  closed byAudit your Agent files — Directly supplies what that gap said was missing: an account of the bloat failure mode the earlier best-practices piece omitted, a progressive-disclosure account for skills (listing budget defaulting to 1% of context, body loaded only on invocation), and a concrete audit-cadence workflow (archive, /doctor, remove, test, decide) in place of the unbounded 'append a rule' habit.
• incompleteCost and economics are absent. Multi-Claude parallelism, headless fan-out over thousands of files, and repeated 2-3x iteration all multiply token spend, yet the guide never mentions cost, usage/rate limits, or the threshold at which harness overhead pays for itself.
  Read next: Read against extract-anthropic-harness-design-long-running-application-development#p13 (the harness-vs-solo 20x cost multiplier and when it is justified), the ai-unit-economics and usage-limits-rationing concepts.
• incompleteNo treatment of how the practices vary by context — greenfield vs legacy, language, codebase size, solo vs team. Every recommendation is presented as universal, with the implicit assumption that what works inside Anthropic transfers everywhere.
  Read next: Look for domain-specific and team-based Claude Code usage guides; read against extract-charlie-hills-32-things-claude-code#g3, which flags the same universality assumption.
  closed byHow Microsoft Developers Use AI in Real-World Coding | BRK103 — Same partial closure as above: a first-person, solo-developer, legacy-codebase account of how AI-assisted practice actually varies by context (throwaway vs. long-lived code), though still not team-based and not Claude-Code-specific.

Closes gaps elsewhere

• Your AGENTS.md might be a big problem · g2 — Pocock's progressive-disclosure remedy depends on agents loading nested files only when relevant, but leaves the retrieval mechanism unexplained. This canonical Anthropic guide documents it directly: CLAUDE.md files in parent directories are pulled into context automatically at session start, while files in child directories are pulled in only on demand when Claude works with files in those subtrees — confirming that nested placement genuinely defers cost rather than loading everything.

Related documents

• Agent Skills
• Agent Harness Engineering
  Agent Harness Capability Provisioning (right-sizing to the task) Agent Context Files (CLAUDE.md / AGENTS.md) Multi-Agent Orchestration
• [FULL WORKSHOP] AI Coding For Real Engineers - Matt Pocock, AI Hero
  Capability Provisioning (right-sizing to the task) Feedback Loops Multi-Agent Orchestration Test-Driven Development
• The Anatomy of an Agent Harness
  Agent Harness Context Engineering Feedback Loops Multi-Agent Orchestration
• Charlie Hills 🦩's Post
  Capability Provisioning (right-sizing to the task) Claude Code Agent Context Files (CLAUDE.md / AGENTS.md) Multi-Agent Orchestration
• [MODEL] Claude Code is unusable for complex engineering tasks with the Feb updates #42796
  Capability Provisioning (right-sizing to the task) Claude Code Extended Thinking / Reasoning Multi-Agent Orchestration
• Developer Newsletter: New models, Claude Tag, and dynamic workflows
  Agent Harness Claude Code MCP (Model Context Protocol) Multi-Agent Orchestration
• Prompting Claude Fable 5
  Agent Harness Capability Provisioning (right-sizing to the task) Context Engineering Multi-Agent Orchestration
• Just Talk To It - the no-bs Way of Agentic Engineering
  Agent Harness Agent Context Files (CLAUDE.md / AGENTS.md) MCP (Model Context Protocol) Multi-Agent Orchestration
• Technology Radar, Volume 34
  Agent Harness Feedback Loops MCP (Model Context Protocol) Multi-Agent Orchestration