Claude Code: Best practices for agentic coding
Anthropic's playbook for agentic coding with Claude Code: tune CLAUDE.md, give the agent verifiable targets, run parallel sessions that check each other.
When agentic coding goes wrong, the complaint is usually that the model got confused. This guide’s premise is different: the model ran out of room. Every file read, failed attempt, and vague instruction spends the same context window the model thinks with — so nearly every practice here either protects that window or turns a vague goal into a checkable target.
Source
Claude Code: Best practices for agentic coding
By: Anthropic (Boris Cherny)
Published: Apr 18 2025
Type: Engineering article
This is worth keeping because it’s the vendor’s own field manual — patterns distilled from Anthropic’s internal teams and the wider user community, not marketing. The original post has since grown into the maintained Claude Code documentation, which keeps expanding; the April 2025 version it grew from is the tighter read.
Everything orbits the context window
Claude Code is a command-line tool for agentic coding, born as a research project and deliberately low-level: close to raw model access, with no workflow imposed on you. That design is why it has a learning curve, and why this post exists at all — it collects the habits people developed after climbing the curve, offered with the explicit caveat that “nothing in this list is set in stone nor universally applicable.”
The first habit is tuning the environment. CLAUDE.md is a file pulled into every conversation automatically, which makes it the place for what the model can’t infer from the code: build and test commands, style rules that differ from defaults, repo etiquette, environment quirks. It can live at the repo root (checked into git so the team shares it), in parent or child directories for monorepos, or in ~/.claude for all your sessions, and /init generates a starter file. Mine might look like:
# Commands
- Run the single package's tests, not the whole suite
# Rules
- Never edit files under db/migrationsThe post’s more interesting claim is that this file should be maintained like a prompt, not a document. Instructions get ignored when the file bloats; emphasis like “IMPORTANT” rescues single lines that keep getting missed; and the # key appends a lesson to the file mid-session while it’s still fresh. Permissions get the same tuning. The default asks before anything that modifies your system, and allowlists (/allowed-tools, settings files, or the --allowedTools flag) buy back flow for actions you trust, like file edits or git commit. Installing the gh CLI is recommended outright, because CLI tools turn out to be the context-cheap way to interact with external services.
The second habit is giving the agent more to work with. Claude Code inherits your shell, so custom scripts just need documenting — or a pointer to their --help. It speaks MCP as both client and server, and team-wide servers belong in a checked-in .mcp.json so everyone gets them by default. Repeated workflows become custom slash commands: a markdown file in .claude/commands whose $ARGUMENTS placeholder turns an issue number into a full investigate-test-commit-PR routine.
Then come the workflows. The general-purpose one is explore, plan, code, commit: tell Claude to read the relevant files and explicitly not write code yet, lean on subagents early for investigation so the main context stays clean, then get a plan — the post maps escalating “think” phrases to bigger thinking budgets, up to “ultrathink” — and save it somewhere durable as a reset point before implementing and committing. For test-verifiable work there’s a TDD variant: write tests from expected input/output pairs, confirm they fail, commit them, then let Claude iterate on code until they pass without touching the tests, with a subagent double-checking that the implementation isn’t overfitting to them. For UI work the target is visual: give a mock plus a way to take screenshots (the Puppeteer MCP server, or pasted images) and iterate until the result matches, with outputs typically improving over two or three rounds.
Two smaller workflows round this out. “Safe YOLO mode” runs --dangerously-skip-permissions for uninterrupted execution — inside a container without internet access, because the post names data loss and data exfiltration via prompt injection as real risks of letting it run loose. And codebase Q&A — just asking the questions you’d ask a colleague, like how logging works or why line 333 calls foo() — has become Anthropic’s core onboarding workflow, cutting ramp-up time and the load on other engineers. Many Anthropic engineers reportedly hand 90%+ of their git interactions to the tool: history archaeology, commit messages, conflict resolution. GitHub interactions follow the same shape, from pull requests to one-shot fixes of review comments.
The optimization section is where the context theme becomes explicit. Specificity beats brevity in prompts, and their before/after pairs show the pattern: name the edge case, point at git history, reference an existing widget as the template. Images, file paths, and URLs all feed the model cheaply. Course-correct early — Esc interrupts mid-thought, double-Esc rewrites an earlier prompt, and undo reverts a bad turn — and run /clear between unrelated tasks so old context stops leaking into new work.
Large jobs get a scratchpad. A markdown checklist or GitHub issue holds the state instead of the conversation: a lint sweep becomes “write every error with file and line to a file, then work it one by one.” Data arrives by paste, by pipe (cat error.log | claude), or by letting Claude fetch it itself with bash, MCP tools, or file reads.
Headless mode takes the same tool into automation: claude -p "prompt" with streaming JSON output for CI, pre-commit hooks, and scripts. The public Claude Code repository uses this to label incoming issues automatically, and the post also suggests it as a subjective linter that catches typos, stale comments, and misleading names — the things rules-based linters can’t.
The last section multiplies the agent instead of the effort. One Claude writes while another, in a fresh context, reviews — separate contexts turn out to be an advantage, the same reason a reviewer who didn’t write the code is more objective, and instances can split work as test-writer and implementation-writer. Parallel independent tasks run in separate checkouts or lighter git worktrees, each isolated but sharing history. For migrations, headless mode fans out: a script generates the task list, then loops claude -p per file with scoped --allowedTools and an OK-or-FAIL contract, with the prompt refined on the first few files before the full run. The same calls pipeline into existing systems via JSON output.
What holds it all together isn’t visible in any single section: vague goals and polluted context are the same problem, because both leave the model guessing. The guide attacks both at every level — file, prompt, session, fleet.
My take
This is a context-engineering manual disguised as a product guide. Strip out the commands and nearly every practice is one of two verbs: protect the window (plan before coding, subagents for research, /clear between tasks, scratchpads outside the conversation) or convert intent into a checkable target (tests, mocks, checklists, OK/FAIL contracts). The tell is safe YOLO mode — even removing the human gets recast as an environmental constraint, a network-less container, rather than trust in the model. There’s a second shift underneath: the unit of work stops being a session and becomes a fleet, with worktrees, writer/reviewer pairs, and fan-out loops, which moves the engineer from typing code to designing the harness. Two cautions. It’s the vendor’s guide to the vendor’s tool, so commands like /clear and --dangerously-skip-permissions are product-specific, and the adoption claims (“90%+ of git interactions,” the onboarding wins) are self-reported. The transferable part is the method, and it would survive a change of tool: verifiable targets, context hygiene, fresh eyes on finished work.
Where this is useful
- Onboarding onto any large, unfamiliar codebase — the Q&A pattern beats reading for ramp-up, whatever agent you use.
- Team setup:
CLAUDE.md,.mcp.json, and slash commands checked into git, so every session starts warm. - Mechanical migrations at scale — fan-out with an OK/FAIL contract per file, refined on a pilot batch first.
- Less applicable verbatim to other tools — the commands are Claude Code’s, but checks, context hygiene, and fresh-context review carry over.
Apply this: Before your next agent session, write the acceptance check into the first prompt — which test to run, which screenshot to match — and keep the task list in a scratchpad file. If you can’t name the check, the agent can’t pass it.
What I want to remember
Remember: An agent saying it succeeded is not evidence. Make it show a check that returns pass or fail, and treat the context window as a budget — every read, correction, and failed attempt is spent from the place it thinks with.