Agentic coding best practices: what works in 2026

Anthropic’s best-practices guide opens with the constraint that governs everything else in agentic coding: a single debugging session or codebase exploration can consume tens of thousands of tokens. The scale of that number is easier to feel against the published context-window sizes. For the 200,000-token window of models such as Claude Sonnet 4.5, every 20,000 tokens of exploration works out to a tenth of the model’s working memory; a tenth gone before the first line of the fix is written. After a year of running coding agents daily against a production monorepo (a FastAPI backend, a React frontend, two native mobile apps, and three content sites), I can report which of the published practices hold up against that constraint, and which ones I had to learn the hard way.

Anthropic’s guidance and OpenAI’s Codex documentation now describe closely matching workflows; the closing section returns to what that convergence indicates. This is a lab-notebook distillation rather than a tutorial. Every external claim links to its source, and everything else is my own experience.

The context window as the central constraint

Anthropic’s guide bases most of its advice on one observation: “Claude’s context window fills up fast, and performance degrades as it fills.” The window holds the entire conversation, including every message, every file the agent reads, and every command output. As it fills, the agent starts forgetting earlier instructions and making more mistakes.

Once this constraint is internalized, most published best practices stop being arbitrary tips and become consequences: (1) instruction files are kept short because they are loaded into every session; (2) research is delegated to subagents because exploration consumes context the main session needs for implementation; (3) context is cleared between tasks because yesterday’s failed approach contaminates today’s attempt; and (4) investigations are scoped narrowly because an unbounded “investigate X” reads hundreds of files.

My working rule is to treat the context window like RAM (random-access memory) on an embedded device, not disk on a server, so everything loaded has to earn its place.

A check the agent can run

The single highest-leverage practice, and the one Anthropic now leads its guide with: “Give Claude a check it can run: tests, a build, a screenshot to compare. It’s the difference between a session you watch and one you walk away from.”

The mechanism is worth walking through. An agent stops when the work looks done. Without a runnable check, “looks done” is the only signal available, and the human becomes the verification loop, with every mistake waiting to be noticed. With a check, the loop closes itself: the agent implements, runs the check, reads the failure, and iterates.

In practice this changed how I phrase almost every task. Instead of “fix the parsing bug”, I ask for a failing test that reproduces the bug, then the fix, then the passing output. Instead of “make the banner responsive”, I ask for the change followed by a screenshot of the staging URL at 375px confirming the banner does not overflow. For deploys, the agent fetches the production URL and greps the rendered HTML for the change, because “the build passed” and “users see it” are different facts.

The second half of the practice matters as much: require evidence, not assertions. An agent that reports “done, tests pass” is asked for the test output. Agents do report success on work that silently failed, therefore reading pasted output is cheaper than discovering the gap in production.

Explore, plan, implement, and when to skip planning

Both vendors now ship an explicit plan-first mode, and the recommended workflow in Anthropic’s guide is a four-phase loop: explore (read files, no changes), then plan, then implement against the plan, then commit and open a pull request.

This workflow has held up in my daily use. The failure mode it prevents, an agent confidently building the wrong thing for twenty minutes, is real and expensive. For anything that touches multiple files or has unclear scope, I gather a written specification first, then a step-by-step plan, and only then let implementation start. The plan document then serves as the verification checklist.

The same guide, however, includes a caveat that took me months to appreciate: “If you could describe the diff in one sentence, skip the plan.” A planning phase on a one-line fix adds overhead without adding safety. The skill that develops over time is calibrating which mode a task needs before starting it.

Instruction files: AGENTS.md and CLAUDE.md

Persistent instruction files are now a cross-vendor convention. AGENTS.md (“a README for agents”) is used by over 60,000 open-source projects and supported by more than 20 tools, including Codex, Cursor, VS Code, and GitHub Copilot. Claude Code reads the equivalent CLAUDE.md at the start of every session, and Codex configures itself from AGENTS.md across its CLI (command-line interface), IDE, and cloud surfaces.

What goes into these files matters less than what stays out. Anthropic’s guidance is blunt: “Bloated CLAUDE.md files cause Claude to ignore your actual instructions”, and the test for every line is “Would removing this cause Claude to make mistakes?” A line that fails the test is cut.

My own file converged on the same shape. What earned a place: build commands the agent cannot guess, non-obvious architecture facts (which server runs what), rules that differ from defaults, and warnings about non-obvious behavior (“this endpoint 308-redirects and drops the POST body”). What was removed: anything derivable from the code, standard conventions, and long explanations, since the agent already knows what clean code is. In addition, domain workflows that apply only some of the time moved out to on-demand skills; loading a deploy runbook into every conversation about page styling wastes context.

The meta-practice is to treat the instruction file like code. When the agent misbehaves, the fix is usually an edit to the file, and more often a shortening than a lengthening.

Advisory rules and deterministic hooks

This is the practice I would defend most strongly, and the one I see discussed least. Instruction files are advisory: the agent reads them and usually complies. Hooks are deterministic: scripts that run at fixed points in the agent loop whether the model complies or not. Anthropic’s documentation draws exactly this line: “Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens.”

My repository currently runs over a dozen hooks, and each one exists because an advisory rule failed at least once. A pre-tool-use hook blocks raw rsync entirely, after an unscoped sync once overwrote another session’s work; “please use the sync script” became a hard exit code. Another hook blocks schema migrations until a preflight invariant script passes, because “always check invariants before DDL (data definition language) changes” is exactly the kind of rule that gets skipped under time pressure. A stop-hook refuses to end a session with uncommitted changes, because in a multi-session repository, uncommitted work is work another session will eventually destroy.

The pattern generalizes: every time an agent violates a written rule with real consequences, I convert that rule into a hook. It should be noted that instructions still have a role for matters of taste; enforcement is reserved for rules whose violation costs something.

Publishing through review gates

Agents are now good enough that publishing their output directly is tempting. I do not allow it for anything that carries my name.

The pattern that works for me is a pull-request gate on everything: the agent researches, writes, and opens a pull request with its claims and sources listed, and a human merge is the only path to production. The merge then triggers deterministic CI (continuous integration) checks, covering the build, link checking, schema validation, and a performance budget, so the human reviews substance while machines review mechanics. (This site works exactly that way; the pipeline that drafted this guide is described in the opening note.)

For code, Anthropic recommends a further step that I have adopted: adversarial review in a fresh context. A reviewer subagent that sees only the diff and the plan, not the reasoning that produced the change, “evaluates the result on its own terms.” Their documentation adds a caveat that matches my experience: a reviewer prompted to find gaps will find gaps, “even when the work is sound.” Scoping the reviewer to correctness rather than style is what prevents over-engineering.

Scaling out to parallel sessions

The official guidance describes several multiplication patterns: headless mode (claude -p) for CI and scripting, fan-out loops over file lists for migrations, parallel sessions in git worktrees, and writer/reviewer session pairs.

These all work; my own logs, however, add a caveat. Parallelism multiplied my throughput and my coordination failures at the same rate. Running multiple concurrent agent sessions against one repository produced enough orphaned files and overwritten work that I moved to a trunk-based discipline: agents commit their own files immediately, push immediately, and never end a session with uncommitted changes. For long batch jobs of thousands of items, a scheduled queue that processes one item at a time from a resumable state file has outlived every parallel orchestrator I have built.

Therefore my scaling advice is sequenced: first make one agent reliable through verification, hooks, and review gates, and only then scale out the parts that cannot collide, meaning separate repositories, separate worktrees, or read-only research. Tool access for all of this increasingly routes through MCP (Model Context Protocol), the open standard both ecosystems support; I have written separately about which MCP servers earn their context cost.

The failure patterns I still catch myself in

Anthropic’s guide names five common failures. Three of them I recognize from my own transcripts, and I add a fourth of my own.

(1) The overloaded session: one conversation accumulates unrelated tasks until the context is noise. The fix is clearing context between tasks, which costs nothing and is nevertheless easy to forget. (2) Correcting over and over: after two failed corrections, the context is polluted with failed approaches, and a fresh session with a better prompt “almost always outperforms a long session with accumulated corrections.” This matches my logs exactly. (3) The trust-then-verify gap: a plausible implementation with unhandled edge cases. The fix is the whole verification section above; in Anthropic’s words, “If you can’t verify it, don’t ship it.” (4) The skipped step, my own addition: letting the agent omit parts of a defined workflow because it sounds confident. Every workflow step I have defined exists because skipping it once cost me something. Agents are systematically overconfident about which steps are optional, therefore the fix is making the steps non-optional, which returns the discussion to hooks.

Where this is heading

The notable feature of mid-2026 is convergence. Two competing vendors now recommend nearly identical practice: instruction files (AGENTS.md and CLAUDE.md), plan-first modes, permission systems with allowlists and sandboxing, hooks, MCP for tool access, and headless modes for automation. Convergence between competitors provides a basis for believing these practices reflect real constraints rather than fashion.

What the official guides say least about, and what in my experience separates production use from demonstrations, is the combination of deterministic enforcement (hooks and CI gates) with human review at the publish boundary. Models will keep improving at the middle of the loop. Consequently the durable leverage sits at the two ends: what goes in as instructions and context, and what comes out through verification and review.

TODO (July 2026): run the next guide rewrite through a fresh-context reviewer subagent scoped to correctness only, feed it ten diffs I have already verified as sound, and count how many findings it still reports. That false-positive count decides whether the reviewer subagent becomes a required gate in this repository’s CI.

---

Changelog: 2026-07-06: register pass (two idioms to plain form, folded one maxim into its sentence). 2026-07-05: revised for voice; the opener now carries the context-window arithmetic, and the failure patterns are numbered in prose. 2026-06-15: first published.