Claude Code Best Practices for Agentic Coding
10 min läsning
Key takeaways
- Put build commands, repo conventions, verification entry points, and a do-not-touch list in a short CLAUDE.md so the agent follows your patterns instead of inventing its own.
- Scope every Claude Code run to one merge request with acceptance criteria the agent can self-check, and run each agent in its own git worktree to prevent overwrites.
- Close the verification loop with tests, type checks, and hooks so wrong output is rejected in seconds rather than discovered in review.
- Default-deny permissions with allowlisted safe commands and gated destructive ones bound the damage an autonomous agent can do.
- Route judgment-heavy tasks like multi-step refactors to Claude Code and mechanical edits to cheaper models to control fleet costs.
Claude Code best practices for agentic coding come down to four disciplines: a CLAUDE.md that pins conventions, tasks scoped with explicit acceptance criteria, a verification loop that runs before anything merges, and permission handling that blocks autonomous damage. Each one maps to a specific failure: drift, overwrite, silent breakage, and token burn. This playbook pairs every practice with the failure it prevents, so your parallel agent fleet stays on target instead of burning your budget fixing the wrong thing.
What does Anthropic officially recommend for agentic coding with Claude Code?
Anthropic's published guidance for Claude Code (Claude Code best practices) covers five practices: put project conventions in a CLAUDE.md file, use plan mode before writing code, keep tasks small and scoped, verify work with tests before merging, and configure permission settings so the agent can't run destructive commands unattended. Each one exists to block a specific failure mode, not as general hygiene.
The four failure modes every practice maps to
Drift: an agent wanders off-task in a big codebase. Plan mode and scoped tasks contain it.
Conventions ignored: the agent writes code that works but violates your patterns. CLAUDE.md is the fix.
Unverified output: confident, wrong code reaches your repo. A test-driven verification loop catches it before merge.
Unsafe autonomy: an agent with broad permissions edits or deletes things you didn't approve. Permission settings and approval prompts bound it.
The rest of this playbook maps each practice to its failure mode in detail, with setups you can copy. More on running agent fleets at Aerunit's blog.
How should you structure CLAUDE.md so the agent stays on task?
CLAUDE.md is the standing instruction set your agent reads at the start of every session. It should hold four things: the commands to build, test, and lint; the conventions your repo actually follows; the entry points for running verification; and an explicit list of what not to touch, like generated files or migration folders. Everything else is noise.
Keep it short enough that the agent actually reads it
Bloat is the failure mode. A 400-line CLAUDE.md reads like a wall, and the agent starts ignoring instructions, including the ones that matter. Treat it like a good README: if a line does not change how the agent behaves, cut it. When agents drift or overwrite each other's work across repositories, the fix is usually tighter instructions plus tighter task scoping, not more of them (see our playbook on cross-repo changes with coding agents).
Per-directory CLAUDE.md files for multi-repo setups
Claude Code picks up CLAUDE.md files from nested directories, so a monorepo can carry one per package and each repo in a fleet carries its own. Put repo-specific test commands and conventions there, and keep shared rules, like commit message format, in the root file. This keeps each agent's context small and relevant to the worktree it is running in.
How do you scope tasks so a Claude Code run doesn't drift?
Scope every run to one merge request. A run that "improves the auth module" will wander; a run that "adds rate limiting to the login endpoint and updates its tests" has a finish line. Teams running dozens of parallel Claude Code and Codex sessions describe the failure plainly: with that many terminal tabs you lose track of which agent is waiting and which one has spent hours fixing the wrong thing. Splitting thinking from doing is the whole trick: run Claude Code in plan mode first, review the plan, then let it execute against an approved checklist. That separation keeps agents from wandering off into a big codebase and getting lost, and it makes drift visible early, when correcting course costs one message instead of three hours and a burned token budget. More worked scoping examples live in our guides.
Write acceptance criteria the agent can self-check
Vague criteria produce confident wrong answers. "Handle errors properly" is untestable by the agent; "return 429 with a Retry-After header when the limit is hit, covered by a test" is something Claude Code can verify itself before it reports done. Phrasing criteria as checks the run can execute, rather than outcomes you will review later, is what turns a review pass into a rubber stamp.
Git worktrees: one agent, one checkout, no overwrites
Run each agent in its own git worktree so parallel sessions never share a working directory. Four agents on one checkout overwrite each other's work, duplicate effort, and burn tokens arguing about who is right; separate worktrees make each run's diff isolated and reviewable as a single merge request. This is also where billing discipline matters: unattended runs retry and re-read files, and API-billed sessions can cost meaningfully more than a flat subscription, so scope tightly and check Anthropic's Claude Code documentation before pointing a fleet at API keys.
Which verification loop catches agent mistakes before they hit your repo?
An agent that finishes fast and fails quietly is worse than one that fails loudly. The fix is a verification loop the agent runs itself: tests, type checks, and lint on every change, so wrong output gets rejected in seconds instead of discovered in review. Anthropic's guidance for agentic coding centers on giving Claude Code concrete, repeatable checks it can iterate against. Without one, "it works" is just the agent's opinion. For a comparison of where Claude Code sits among agentic AI coding tools, see our rundown of agentic AI coding tools.
Hooks: automatic feedback without a human in the loop
Claude Code hooks let you run a command automatically after an event, such as every file edit. Point that hook at your type checker or linter and the agent sees the failure immediately, in the same session, with full context about what it just changed. That closes the loop without an approval prompt and without you watching terminal tabs. It also keeps the token budget honest: a failed type check costs one retry, not three hours of an agent fixing the wrong thing.
What to do when there is no test to run
Legacy repos and glue code often have no suite worth running. Start with the cheapest deterministic check available: does it compile, does the type checker pass, does the linter stay quiet. Then require the agent to state acceptance criteria before it starts and to demonstrate each one with a command and its output. You trade automation for explicitness, which is slower per run but still catches the confident-wrongness problem before a merge request does.
How do you handle permissions and security when an agent edits code autonomously?
Permissions are where friction and risk trade off directly. Too loose and an agent deletes a branch or exfiltrates a token; too tight and you spend your day clicking approval prompts instead of directing work.
Allowlist the safe commands, gate the destructive ones
Start from a default-deny permission profile and allowlist the read-only and build commands each task needs: git status, npm test, grep, your formatter. Gate everything destructive: git push, rm, dependency installs, anything touching .env or migration files. Scope the allowlist per repo, not globally, so a multi-repo fleet can't carry a broad profile from a side project into your main product. Keep secrets out of the worktree entirely and inject them at runtime, since a daemon running many sessions multiplies the number of places a leaked key can hide.
Approval prompts at fleet scale: the human bottleneck
One approval prompt per session is fine. Thirty sessions is a queue, and teams running that many Claude Code and Codex sessions report the real cost is coordination: agents wait for answers or spend hours fixing the wrong thing, and the screen doesn't tell you which is which. Batch approvals by task, not per command, and make acceptance criteria the gate: an agent that can't verify against criteria waits, it doesn't improvise. Aerunit's instant feedback for coding agents exists to cut that wait by surfacing which session is blocked and why.
When is Claude Code the best model choice for agentic coding — and when is it not?
Claude Code earns its token price on tasks where context and judgment compound: multi-step refactors, work in an unfamiliar codebase, and anything where a wrong turn costs an hour of retries. It is the wrong spend for mechanical edits, dependency bumps, and one-file changes a cheaper model handles in a fraction of the tokens.
Cost per merge request: what parallel fleets actually pay
Teams running large fleets of Claude Code and Codex sessions at API prices report per-merge-request costs in the single-digit dollars, which adds up fast at fleet scale. At that rate, model choice is a budget lever: route the judgment-heavy tasks to Claude Code and the mechanical ones to a cheaper model, and the same fleet output costs meaningfully less. The trap is routing by task size instead of task type — a small task in unfamiliar code still needs the strong model.
Mixing models across a fleet without losing quality
| Task type | Model tier | Why |
|---|---|---|
| Multi-step refactor, unfamiliar repo | Claude Code | Long-context reasoning prevents drift |
| Scoped feature with clear acceptance criteria | Either | Verification loop catches mistakes |
| Mechanical edits, bumps, renames | Cheaper/faster model | Low judgment cost, high volume |
Split the thinking from the doing: assign direction and acceptance criteria yourself, then match the model to the doing.
What workflow turns single Claude Code sessions into a repeatable team process?
The team-level version of Anthropic's playbook has three parts: tasks enter from the tracker with acceptance criteria attached, state is tracked per run so you know which agent is waiting versus which is drifting, and failed runs get retried against the same scoped task instead of restarted from scratch. Without that structure, founders running several agents in parallel report the same failure mode: agents overwrite each other's work, duplicate effort, and burn the token budget arguing about who is right.
From terminal tabs to tracked runs
The fix is splitting thinking from doing: a human or a thin daemon distributes scoped tasks, each run gets an ID and a state (waiting, working, blocked), and every merge request maps back to one task. That is what keeps thirty sessions from becoming thirty terminal tabs.
Honest criteria for adding an orchestrator
Judge any orchestrator, Aerunit included, on four questions: Does it read tasks from Linear instead of making you retype them? Does it expose per-run state and retries? Does it enforce a token budget per task? Does it work across multiple repos? Aerunit is built for exactly this loop, but if your fleet is two sessions, a shared doc and git worktrees will do; the orchestrator earns its keep when the coordination cost exceeds the task cost.
Decision checklist: is Claude Code the right agent for this task?
Run each task through five yes/no questions before you hand it to the fleet.
- Is the scope under roughly one day of work? If yes, Claude Code fits. If it needs a week, split it first.
- Do tests exist that can fail? If yes, the verification loop works. If no, a human writes them first or the agent ships unverifiable code.
- Is the blast radius small? Isolated module or feature branch: agent. Auth, payments, migrations: human.
- Does it touch one repo? Single repo: Claude Code or Codex. Cross-repo coordination with shared types or contracts: human sets the contract, agents implement against it.
- Do acceptance criteria fit in a paragraph? If you cannot write them, the task is a thinking task, not a doing task.
Answer yes to all five: send it to an agent. Mixed: agent with tighter approval prompts. Mostly no: it stays with a person.
FAQ
Is Claude Code worth the API cost for a small team, or should we stick with subscription plans?
Route by task type. Teams running fleets at API prices report per-merge-request costs in the single-digit dollars, so reserve Claude Code for judgment-heavy work like multi-step refactors and unfamiliar codebases, and send mechanical edits to a cheaper model. A flat subscription works fine while sessions are attended; API billing makes sense once unattended parallel runs dominate.
Can Claude Code and Codex agents work on the same repo at the same time?
Yes, but never in the same working directory. Give each agent its own git worktree so sessions stay isolated, and scope each run to one merge request. Four agents on a single checkout overwrite each other's work and duplicate effort. Separate worktrees make every diff reviewable independently, and a repo-specific CLAUDE.md keeps each agent's context relevant to its own checkout.
How many Claude Code sessions can one person realistically supervise?
One or two with raw terminal tabs. Teams running dozens of sessions report the bottleneck is coordination: agents wait for approvals or spend hours fixing the wrong thing, and the screen doesn't show which is which. Past a handful of sessions you need per-run state tracking, batched approvals by task, and acceptance criteria the agent can self-check before it reports done.
Do I need a separate orchestration tool, or can Claude Code handle parallel agents itself?
Claude Code handles single sessions well; parallel fleets need coordination it doesn't provide. Two sessions run fine with a shared doc and git worktrees. An orchestrator earns its keep when coordination cost exceeds task cost. Judge any tool on four things: does it read tasks from your tracker, expose per-run state and retries, enforce a token budget per task, and work across multiple repos.