DEV Community: John Young

How to Structure CLAUDE.md: It's a Loading Policy, Not a Document

John Young — Mon, 27 Jul 2026 14:14:24 +0000

When a developer filed a bug titled [BUG] Claude Code continually ignores CLAUDE.MD file, Anthropic closed it not-planned and labeled it area:model — bug-tracker shorthand for this is not a defect we can patch (anthropics/claude-code#34197). The report carried its own confession, pasted straight from the session that triggered it:

The rules are clear in the CLAUDE.md and memory files — read them, I know them, and I still violated them.
— GitHub: anthropics/claude-code#34197

If the model knows the rules and breaks them anyway, a longer, sterner CLAUDE.md is not the fix. The fix is structural: CLAUDE.md is not a document you fill, it is a loading policy you configure. Most of what goes wrong is content sitting in the wrong tier — billed to every session whether that session needs it or not.

The Three Loading Tiers Claude Code Already Runs

Before you decide what belongs in a CLAUDE.md, look at where it loads — because Claude Code already sorts your instructions into three tiers, and the tier decides the bill.

CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded in full at launch. Files in subdirectories load on demand when Claude reads files in those directories.
— Claude Code Docs: How Claude remembers your project

That splits your configuration into three tiers with three different costs:

Tier	What lives here	When it loads	Who pays
Always-loaded	Root and ancestor `CLAUDE.md`, `@`-imports, unscoped `.claude/rules/`	In full, at launch	Every session
Pay-per-read	Subdirectory `CLAUDE.md`, path-scoped rules	When Claude reads a matching file	Only sessions that touch that code
Pay-per-trigger	Skills	~100-token blurb always; body on trigger	Only sessions that invoke it

The pay-per-read tier is lazy and file-access-triggered, not a startup scan — Claude Code's creator confirmed as much when he closed a request to make subdirectory loading eager: Claude automatically reads a subdirectory's CLAUDE.md as it works on files in that directory (anthropics/claude-code#4275). The vendor's large-codebases guidance describes the same additive behavior — "root file for the big picture, subdirectory files for local conventions" (Claude by Anthropic: Large codebases). The pay-per-trigger tier is quantified: a skill costs roughly 100 tokens of always-loaded metadata, and its body — under 5k tokens — enters the context window only when the skill fires (Anthropic: Agent Skills overview).

This is context engineering, and Anthropic frames it that way: "Context, therefore, must be treated as a finite resource with diminishing marginal returns," with CLAUDE.md as the part "naively dropped into context up front" while glob and grep retrieve the rest just-in-time (Anthropic: Effective context engineering). The always-loaded tier is exactly that — in context at the start of every session, before you type a word (Claude by Anthropic: Using CLAUDE.md files).

Now take a real file. A developer split a 2,100-line CLAUDE.md into a 150-line core plus five @-imported docs — testing.md (270 lines), typescript.md (305), code-style.md (370), workflow.md (671), and examples.md (278) — the tidy, modular layout every "keep it lean" guide recommends (anthropics/claude-code#11759). Map it onto the table and the tidiness evaporates. @-imports load at launch, so all six files ride the always-loaded tier. The split changed the file browser, not the bill. This corpus recurs in every section below — it already made the naive fix and measured the result.

Verify the Pay-Per-Read Tier on Your Own Surface

The pay-per-read tier is documented design, but it has a reliability caveat — confirm it before you bet directory conventions on it. It has unresolved reports of not firing:

When subdirectory conventions get silently ignored, suspect the surface. Nested loading has been reported broken on the VS Code extension while the CLI reportedly works (anthropics/claude-code#24987). An earlier macOS report was closed not-planned without a fix (anthropics/claude-code#2571).
Before you rely on a nested file, run /memory. It lists every CLAUDE.md, CLAUDE.local.md, and rules file loaded in the current session; if the file you expect isn't listed, Claude can't see it (Claude Code Docs: How Claude remembers your project).
Treat the lazy tiers as just-in-time retrieval, with JIT's failure modes. They pull content in as Claude navigates — powerful, but with quiet ways to break down, which is the subject of a separate post on where lazy retrieval silently fails.

The Over-Specified CLAUDE.md Is a Named Failure Mode

Prune your CLAUDE.md on adherence grounds, not tidiness. Past the file's attention budget, every rule you add subtracts from the ones already there. The rules you actually need to land a change on the first try are the ones that get buried. Anthropic names the pattern directly:

The over-specified CLAUDE.md. If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise.
— Claude Code Docs: Best practices

This is measured, not folklore. IFScale, a benchmark that scales a single prompt from 10 to 500 simultaneous instructions, found that even the best frontier models top out at 68% accuracy once you hit 500 — and their bias toward earlier instructions peaks around 150–200 (arXiv: How Many Instructions Can LLMs Follow at Once?). The instruction ceiling is real and closer than it looks, which is the whole argument of the companion post on the root file's budget.

The mechanism is well-documented and not specific to CLAUDE.md. Chroma's context-rot study across 18 models found performance grows unreliable as input length grows, and that distractors compound:

Even a single distractor reduces performance relative to the baseline (needle only), and adding four distractors compounds this degradation further.
— Chroma: Context Rot

It gets worse with position — models are worst at using information stranded in the middle of a long context (Liu et al.: Lost in the Middle) — and worse with sheer length: one study measured accuracy dropping 13.9–85% as input grew, even when the model could perfectly retrieve every relevant fact (Du et al.: Context Length Alone Hurts LLM Performance). A single irrelevant sentence is enough to derail a problem the model solves cleanly without it (Shi et al.: Distracted by Irrelevant Context); on a controlled reasoning benchmark, step accuracy fell from 26% to 2% as distractors climbed from one to fifteen (arXiv: GSM-DC).

One honest caveat keeps this from overreaching. Truly unrelated filler — text with no plausible bearing on the task — mostly costs latency, not accuracy: one study saturated a 70B model with 15,000 words of generic noise and watched accuracy fall only from 98.5% to 98%, while latency rose 719.64% (Ponnusamy et al.: Context Discipline and Performance). The accuracy damage comes from the plausible-but-inapplicable line — the TypeScript convention that looks relevant during a bash task. So the rule is not "delete everything." It is: treat each non-universal line as a suspect, because the ones that read like they might apply are the ones that do the damage.

That is what makes the corpus above worse than a monolith. Its author measured that 85–90% of the loaded content is irrelevant to most conversations (anthropics/claude-code#11759). Most of its per-session tax buys distraction, not guidance — 2,100 lines competing for an attention budget that starts thinning well before 500 instructions.

Why @imports Won't Save You

When a CLAUDE.md gets too long, the reflex is to break it apart with @path imports and call it lean. That reflex is wrong, and it is wrong in a specific, measurable way: splitting the file is organization, not load reduction.

Bad: the 2,100-line file split into a 150-line core with five @docs/*.md imports. Reads modular. Loads identically — all ~2,100 lines enter context at launch, every session. The author who built exactly this split measured the outcome: "the same tokens as a monolithic file, providing organizational benefits only" (anthropics/claude-code#11759).

Good: the same content moved to tiers that actually gate loading. typescript.md becomes a path-scoped rule that loads only when Claude touches .ts files; workflow.md becomes a skill that loads only when invoked. Now a bash-only session pays for none of it.

The documentation states the mechanic plainly, and states it more than once:

Splitting into @path imports helps organization but does not reduce context, since imported files load at launch.
— Claude Code Docs: How Claude remembers your project

This matters because the wrong model is actively taught. One popular guide frames @-imports as pure leanness — "Put detailed instructions in separate markdown files, then reference them. Claude pulls in the content when relevant" (Builder.io: How to Write a Good CLAUDE.md). "When relevant" is exactly what imports do not do; they load at launch, relevant or not. Even the guides that state the mechanic correctly — imports "do not reduce context usage" because the "content is expanded inline and still counts against the active window" (Bijit Ghosh: The Complete Guide to CLAUDE.md) — stop at the mechanic and never turn it into a placement rule. That rule is the next section.

Route Every Line by the Sessions That Need It

Here is the fix that actually holds. For every line in your CLAUDE.md, ask one question — which sessions need this? — and let the answer pick the tier. That is Anthropic's own instruction: "If an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule instead" (Claude Code Docs: How Claude remembers your project).

Content class	Route to	Loads when
Facts every session needs — build commands, "always do X", critical gotchas	Root `CLAUDE.md`, kept short	In full, at launch
Conventions for one file type or directory — a `.ts` style rule, a package's local rules	Path-scoped rule or nested `CLAUDE.md`	Claude reads a matching file
A procedure or occasional reference — a multi-step workflow, a bank of examples	A skill	Metadata always; body on trigger

The skills row is where the docs are most direct: "CLAUDE.md is loaded every session, so only include things that apply broadly. For domain knowledge or workflows that are only relevant sometimes, use skills instead" (Claude Code Docs: Best practices). Named practitioners land in the same place — a skill "only takes up a few dozen extra tokens, with the full details only loaded in should the user request a task that the skill can help solve" (Simon Willison: Claude Skills). The discipline for the root file is to keep it "concise and universally applicable" (HumanLayer: Skill Issue).

The routing question is therefore not "is this rule good?" but "which sessions should pay for it?"

Run the corpus through it. typescript.md and code-style.md govern specific file types — path-scoped rules matching **/*.ts and your source globs, loaded only when Claude edits those files. testing.md rides along with the test files it describes. workflow.md (671 lines of TDD procedure) and examples.md (278 lines of patterns) are a procedure and a reference bank — skills, bodies loaded only on trigger. Layer boundaries are the natural seams here: what governs one layer routes to that layer's files. What is left of the 150-line core shrinks toward what the root is actually for:

The root file should be pointers and critical gotchas only; everything else drifts into noise.
— Claude by Anthropic: Large codebases

That is not an aspiration. HumanLayer's production root CLAUDE.md runs "less than sixty lines," on the rule to "Prefer pointers to copies" (HumanLayer: Writing a good CLAUDE.md).

On-Demand Is Not Free Once It Fires

Routing to a skill is not a free lunch, and pretending otherwise sets a footgun. A skill's body stays out of context until something triggers it — but once it fires, it stays:

When you or Claude invoke a skill, the rendered SKILL.md content enters the conversation as a single message and stays there for the rest of the session.
— Claude Code Docs: Extend Claude with skills

So a triggered skill is a recurring cost from that point on, not a one-time read. The routing win is real — a bash-only session never pays for your TDD skill — but budget the skill body as if it will load, because in the sessions that need it, it does, and it lingers.

The Measured Cost of a Wrongly Routed Line

Here is the failure mode people underweight. A rule in the wrong tier is not quietly ignored — it is dutifully obeyed, at a price you can measure. A benchmark of repository context files across multiple coding agents found the compliance itself is the cost: the files "tend to reduce task success rates compared to providing no repository context, while also increasing inference cost by over 20%" (Gloaguen et al.: Evaluating AGENTS.md).

The measured penalty, across SWE-bench Lite and a benchmark of developer-written files (Gloaguen et al.: Evaluating AGENTS.md):

What the study measured	Result with a repository context file
Task success / resolution rate	Lower than the no-context baseline
Inference cost	+20–23%
Extra steps per task	+2.45 and +3.92 across the two benchmarks

The mechanism is obedience — "agents generally follow instructions present in the context files" — so a misplaced line is therefore not inert weight; it is an instruction the agent will burn steps satisfying. And the thing most root files try hardest to do — narrate the codebase — is the thing the same study found they fail at. Context files "are not effective at providing a repository overview."

Put the two failure modes together and the corpus's real cost comes into focus. The rules you need get lost in the noise (the over-specified failure), and the rules you don't need get executed anyway (the compliance cost). The 2,100-line always-loaded corpus pays both, every session — including the ones that only touch a bash script — to carry content its own author measured as 85–90% irrelevant. That is pure context burn.

And because it is a per-session cost, it compounds. In an iterative loop that restarts context repeatedly, the misrouted tax is paid on every pass — the recurring-cost problem that breaks playbooks built for one-shot sessions.

A Routing Flowchart for Every Line You Keep

You do not need a quarterly re-prune ritual. You need to run each line you keep through one decision path — and then most of the pruning takes care of itself. Ask these in order:

Is it needed in every session?
→ Root file — but it now competes for the adherence budget that caps out well before 500 instructions. Keep it to pointers and critical gotchas.

Is it needed in one directory or file type?
→ Nested CLAUDE.md or path-scoped rule — the pay-per-read tier. Verify it loads on your surface with /memory first.

Is it a procedure or an occasional reference?
→ Skill — pay-per-trigger. Budget the body anyway; once it fires it sticks for the session.

Do you just want the file shorter?
→ That is organization, not savings. @-imports change nothing — they load at launch.

Can't say which sessions need it?
→ Delete it. Every surviving line binds and bills.

Run the corpus through the gates and it lands where it should have started: a ~150-line root of pointers and gotchas, three path-scoped files next to the code they govern, and two skills that load only when invoked. Same content, a fraction of the per-session tax, and no standing re-prune ritual — Anthropic's own cadence is a configuration review every three to six months, not a weekly file diet (Claude by Anthropic: Large codebases).

You do not have to run this flowchart by hand. I packaged it as a Claude Code skill — agent-engineering-toolkit — that inventories your repo's three tiers, expands every @-import, totals the real always-loaded token cost, and emits the routing report above. It is the audit I ran on my own repos while writing this.

And the skill transfers. The same nearest-file hierarchy is now the cross-tool AGENTS.md convention — "Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions" (AGENTS.md) — with the same discipline attached: keep the root short and push specifics down the tree (Addy Osmani: AGENTS.md). Route by tier once and the discipline is portable.

The pay-per-read and pay-per-trigger tiers you just routed into are just-in-time retrieval by another name — and just-in-time retrieval has failure modes of its own. That is the next thing worth understanding before you push your whole config into the lazy tiers: where lazy retrieval silently breaks.

References

Research and Data

Chroma: Context Rot — Hong, Troynikov, Huber — Across 18 LLMs, model performance grows unreliable as input length grows, and even one topically-plausible distractor measurably degrades it. Backs the degradation-by-analogy argument.
arXiv: How Many Instructions Can LLMs Follow at Once? — The best frontier models reach only 68% accuracy at 500 simultaneous instructions, with the early-instruction bias peaking around 150–200. Backs the instruction-ceiling claim.
Liu et al.: Lost in the Middle — Models are worst at using information stranded in the middle of a long context. Backs the position-dependence point.
Du et al.: Context Length Alone Hurts LLM Performance — Accuracy drops 13.9–85% as input grows even under perfect retrieval, well within claimed context windows. Backs the length-alone degradation point.
Shi et al.: Distracted by Irrelevant Context — A single irrelevant sentence degrades accuracy on problems the model otherwise solves cleanly. Backs the distraction mechanism.
arXiv: GSM-DC — Reasoning Distracted by Irrelevant Context — GPT-4.1 step accuracy falls from 26% to 2% as distractors climb from one to fifteen. Backs distractor compounding.
Ponnusamy et al.: Context Discipline and Performance — A 70B model held 98% accuracy under 15,000 words of generic filler while latency rose 719.64%. Backs the honest caveat that unrelated filler costs latency, not accuracy.
Gloaguen et al.: Evaluating AGENTS.md — Repository context files reduced task success while raising inference cost over 20%, because agents comply with everything the file says, and are not effective at providing a repository overview. Backs the measured-cost section.

Practitioner Guidance

Claude Code Docs: How Claude remembers your project — Ancestor CLAUDE.md files load in full at launch, subdirectory files load on demand when Claude reads files there, and @imports load at launch without reducing context. The loading-policy spec the whole post routes against.
Claude Code Docs: Best practices for Claude Code — "The over-specified CLAUDE.md" is a named failure: too long and Claude ignores half of it, so route sometimes-relevant content to skills. Backs the prune-on-adherence and routing sections.
Claude by Anthropic: How Claude Code works in large codebases — Root file should be pointers and critical gotchas only, Claude loads files additively as it moves through the codebase, and teams should review configuration every three to six months. Backs the root-scope rule and the cadence.
Anthropic: Effective context engineering for AI agents — Context is a finite resource with diminishing marginal returns; CLAUDE.md is dropped in up front while glob and grep retrieve just-in-time. Backs the finite-budget and hybrid-tier framing.
Anthropic: Agent Skills overview — Progressive disclosure: ~100 tokens of metadata always loaded, the under-5k body only when triggered, resources effectively unlimited. Backs the pay-per-trigger cost model.
Claude Code Docs: Extend Claude with skills — A skill's body loads only when used, but once invoked it stays in context for the rest of the session. Backs the routing rule and the on-demand-is-not-free caveat.
Claude by Anthropic: Using CLAUDE.md files — Every conversation starts with the always-loaded context already in place. Backs the every-session recurring-cost framing.
Builder.io: How to Write a Good CLAUDE.md File — Gopinath — Frames @imports as "Claude pulls in the content when relevant," the naive model the loading docs refute. The SERP foil in the @imports section.
Bijit Ghosh: The Complete Guide to CLAUDE.md — States correctly that imports don't reduce context usage, but never turns the mechanic into a placement rule. The gap the post fills.
Simon Willison: Claude Skills are awesome — Each skill costs a few dozen extra tokens until invoked. Named-author validation of metadata-first loading.
HumanLayer: Writing a good CLAUDE.md — Kyle — HumanLayer's root CLAUDE.md runs under sixty lines on the rule to prefer pointers to copies. Backs the trimmed-root target.
HumanLayer: Skill Issue — Harness Engineering for Coding Agents — Keep CLAUDE.md concise and universally applicable. Backs the route-by-scope rule.
AGENTS.md — Agents read the nearest file in the directory tree, so the closest one takes precedence. Backs the cross-tool generalization.
Addy Osmani: Lesson 16 — AGENTS.md — Agents read the nearest file in the current directory or its parents; aim for 150 lines or fewer. Backs the cross-tool close.
anthropics/claude-code#34197 — "Claude ignores my CLAUDE.md" closed not-planned and labeled area:model, locating the failure in model behavior rather than fixable tooling. The hook.
anthropics/claude-code#4275 — Boris Cherny confirms subdirectory CLAUDE.md files load lazily as Claude works on files there. Backs the pay-per-read tier.
anthropics/claude-code#11759 — A 2,100-line CLAUDE.md split across six @-imported files consumed the same tokens as a monolith, ~85–90% irrelevant to most conversations. The running-thread artifact.
anthropics/claude-code#24987 — Subdirectory CLAUDE.md files reported not loading on the VS Code extension while the CLI works. Backs the verify-your-surface caveat.
anthropics/claude-code#2571 — Subdirectory CLAUDE.md files reported not auto-loading on macOS, closed not-planned. Backs the reliability caveat.
agent-engineering-toolkit: audit-claude-md — This post's routing flowchart as a runnable Claude Code skill: tier inventory, @import expansion, token estimates, and a per-section routing report. MIT-licensed, runs standalone.

Author's Judgment (not directly sourced)

The following framings are my own synthesis. They follow logically from the sourced material above, but no source states them directly:

"CLAUDE.md is a loading policy, not a document" — my lens on the mechanics; follows from Anthropic's documented tiers (memory docs), which describe the loading behavior but never frame the file this way.
Applying the context-rot and instruction-density literature to CLAUDE.md — Chroma, IFScale, Liu, Du, Shi, GSM-DC, and Ponnusamy never test CLAUDE.md itself; the transfer is my analogy, disclosed in-prose as "not specific to CLAUDE.md."
The "quarterly re-prune ritual" the flowchart retires — my characterization of the periodic-review habit; Anthropic recommends a three-to-six-month configuration review but does not frame it as a symptom of wrong routing.

Loop Engineering Breaks Your Single-Shot Context Playbook

John Young — Mon, 27 Jul 2026 14:14:08 +0000

An agent was "just an LLM using tools based on environmental feedback in a loop" a year and a half before anyone sold you "loop engineering" (Anthropic: Building Effective AI Agents). The term is new; the primitive isn't — and neither is the trap. The CLAUDE.md budget and just-in-time retrieval you spent last quarter tuning for a single invocation don't fail louder when the unit of work becomes many. They fail quieter, and pointing more autonomy at the same bloated context makes it worse, not better.

Loop Engineering Is the Primitive You Already Had

Before you buy loop engineering as a greenfield discipline, look at what the loop actually is: the thing an agent already was. Anthropic's definition has not moved since December 2024 — agents "are typically just LLMs using tools based on environmental feedback in a loop" (Anthropic: Building Effective AI Agents). Simon Willison was calling the design of that loop "a critical new skill to develop" nine months before the label caught on. His working definition is the same one: an LLM agent is "something that runs tools in a loop to achieve a goal" (Simon Willison: Designing agentic loops). The Claude Agent SDK draws the identical cycle as four steps — "gather context -> take action -> verify work -> repeat" (Anthropic: Building agents with the Claude Agent SDK).

So when Addy Osmani defines the new term — "Loop engineering is replacing yourself as the person who prompts the agent. You design the system that does it instead" (Addy Osmani: Loop Engineering) — read it as a shift in who runs the loop, not the arrival of a new mechanism. The primitive is the same gather/act/verify cycle you have been driving by hand; loop engineering is the decision to stop pressing enter between turns.

The concrete version of "stop pressing enter" is the artifact this whole post keeps returning to: the unattended overnight loop.

# The Ralph loop — a fresh context every iteration, state on disk.
while :; do cat PROMPT.md | agent; done

You point it at a PROMPT.md, walk away in the evening, and read what it built in the morning — the technique Geoffrey Huntley popularized as "Ralph" (Geoffrey Huntley: Ralph Wiggum as a "software engineer"). Nothing in that line is new. It is your single-invocation agent, wrapped in while :; do ... done and handed the keys.

The frame is therefore a migration, not a blank slate: treat loop engineering as your single-invocation habits run many times, not a discipline you learn from zero. That reframe tells you where the breakage lives. It is not in the loop syntax — that is one line. It is in every assumption you baked into the playbook when the unit of work was one invocation and the context window reset the moment the task finished. A loop keeps the seat warm.

This axis is worth naming precisely, because it is easy to confuse with the other one. A loop is one agent iterating sequentially — the same context lineage, turn after turn. Running many agents in parallel is a different problem with different failure modes, the isolation and hand-off concerns I covered in multi-agent context isolation. Loop engineering lives on the sequential axis: not more agents, more iterations of one. Why it matters now is measurable — the length of tasks agents can complete autonomously "with 50% reliability has been doubling approximately every 7 months for the last 6 years" (METR: Measuring AI Ability to Complete Long Tasks). The loops are getting longer, so an assumption that was merely wrong on turn one gets expensive by turn fifty.

Audit Your CLAUDE.md as a Per-Iteration Tax

Re-read every "just in case" line in your CLAUDE.md as a charge you re-pay on every iteration, not a fee you settle once. In a single invocation, a bloated instruction file is a fixed cost. The agent loads it, and either the rule near the bottom gets followed or it falls past the instruction ceiling and gets dropped — silently, once. In a loop, that same file reloads every turn, and each turn stacks its own output on top of it.

An agent running in a loop generates more and more data that could be relevant for the next turn of inference, and this information must be cyclically refined.
— Anthropic: Effective context engineering for AI agents

Refined is the operative word — the context does not refine itself. Left alone it grows by default, because "each invocation requires a full inference pass, and intermediate results pile up in context whether they're useful or not" (Anthropic: Introducing advanced tool use on the Claude Developer Platform). The scale that always-on context can reach is easy to underestimate: Anthropic reports having "seen tool definitions consume 134K tokens before optimization" (Anthropic: Advanced tool use). That figure is tool definitions, not your CLAUDE.md — but it is the same shape of problem, an always-on block riding every inference pass whether or not this turn needs it.

Here is the audit, applied line by line to the file your overnight loop is pointed at:

When a line is architecture the agent can read from the repo → cut it. It is context burn re-paid every iteration for something a grep would surface on demand.
When a line is a "just in case" preference no real failure ever earned → cut it. In one invocation it was one distractor; across fifty iterations it is fifty.
When a line is a genuine constraint that must hold → keep it, phrase it as a runnable check, and move it as high in the file as it will go, because position decays.
When a line is a hard safety boundary → it does not belong in an advisory file at all; a loop with no human at the keyboard is exactly the run where "the agent usually respects this" is not good enough.

The reliability cost of skipping that audit is measured, not asserted. Chroma's study across 18 models and 194,480 calls found that "models do not use their context uniformly; instead, their performance grows increasingly unreliable as input length grows" (Chroma: Context Rot). This is not a lone vendor's marketing line — Chroma coined context rot, and Anthropic documents the same finding on its own product surface: "As token count grows, accuracy and recall degrade, a phenomenon known as context rot" (Anthropic: Context windows). A single invocation pays context rot once; a loop pays it on every turn, and the bill compounds with the output the loop keeps adding.

Presentation Over Presence: Cut for Turn 50

The instinct when a loop misbehaves is to add a line — spell out the rule the agent missed. That optimizes for presence: the rule is now technically in the file. But presence is the wrong target. Chroma's sharper finding is that "whether relevant information is present in a model's context is not all that matters; what matters more is how that information is presented" (Chroma: Context Rot). On turn one, a 300-line CLAUDE.md and a 60-line one both technically contain your rule. By turn fifty, with the loop's own output layered on top, the 60-line file is the one where the rule is still legible. Cut and order for how the file reads deep into the run, not for whether the rule is present at the start.

A Clean One-Shot Demo Is the Weakest Evidence You Have

Author's judgment. That a loop fails quieter than the demo — not just more often — is my inference, not a measured result. It follows from two sourced premises: models self-condition on their own prior errors (Sinha et al.), and autonomous runs carry "the potential for compounding errors" (Anthropic). The clean first turn is the least informative data point you have about the fiftieth.

A flawless single run is the worst evidence you can bring to a decision about autonomy, because per-step reliability is a different quantity from single-turn reliability, and the gap is measured.

the per-step accuracy of models degrades as the number of steps increases. This is not just due to long-context limitations — curiously, we observe a self-conditioning effect — models become more likely to make mistakes when the context contains their errors from prior turns.
— Sinha et al.: The Illusion of Diminishing Returns

Their sharpest data point cuts directly against extrapolating from a clean demo: "larger models can correctly execute significantly more turns even when small models have near-perfect single-turn accuracy." Single-turn accuracy does not predict how many turns a model survives.

Carry that result with its caveats, because the honest version is more useful than the scary one. It was measured on a synthetic running-sum task, not a literal tool loop; the same authors find "thinking mitigates self-conditioning"; and, counterintuitively, larger models are more prone to self-conditioning, not less. So the claim is not "big models get dumb in loops." It is narrower and harder to dodge: single-shot accuracy doesn't predict loop reliability, and the mechanism that breaks the extrapolation is the model reading its own earlier mistakes as ground truth.

Here is that mechanism on the running artifact. The overnight loop makes a bad call at iteration 12 — say it edits auth.go against a misread of the token-refresh flow and commits it. Every iteration after 12 opens a fresh context, reads the repo as it now stands, and finds that wrong auth.go sitting there as established fact. The loop is no longer debugging its mistake; it is building on it. By 3 a.m. it has spent thirty iterations making the codebase consistent with a decision it never should have made — and the terminal shows steady, confident progress the whole time. That is the compounding-errors path Anthropic warns about (Anthropic: Building Effective AI Agents), running unattended. The blast radius of one bad call is no longer a single turn you can catch; it is every turn that reads the commit.

This is why the demo lies by omission. Geoffrey Huntley, who popularized the overnight loop, is blunt about its nondeterminism: Ralph goes off track, and you can wake up to a broken codebase that doesn't compile unless you build in programmatic verification rather than letting the model grade its own work (Geoffrey Huntley: Ralph Wiggum as a "software engineer"). The demo you were shown is the run that shipped clean on the first try and got kept. The runs that went off track do not get recorded — which is precisely why a clean one-shot demo is the weakest evidence in the room.

Budget the Two Fields a Single Prompt Never Had

A single prompt has two things a loop does not: a natural end, and a memory that lasts exactly as long as the task. The task finished, the window cleared, and "done" handled both. A loop inherits neither for free — so before you walk away, write a stop spec and a state file.

Start with the stop. Anthropic's baseline is that "the task often terminates upon completion, but it's also common to include stopping conditions (such as a maximum number of iterations) to maintain control" (Anthropic: Building Effective AI Agents). The field guide that covers this most concretely names three, and an unattended loop needs all of them:

Max iteration count — a hard ceiling on turns, full stop. Your while :; do ... done has no upper bound; give it one.
No-progress detection — if a pass produces no measurable change against the check, halt instead of grinding.
A token or dollar budget — a hard spend ceiling that ends the run (Truong Phung: The Agentic Loop / Loop Engineering: A Practical Field Guide).

The hardened version of the running artifact is only a few lines longer, and every added line is a brake:

# The overnight loop, with the two fields a single prompt never needed.
for i in $(seq 1 "$MAX_ITERS"); do          # (1) max-iteration ceiling
  cat PROMPT.md progress.txt | agent        # externalized state, reloaded each turn
  ./run_checks.sh || true                   # the verification the model doesn't self-grade
  git add -A
  git commit -m "iter $i" || break          # (2) nothing to commit -> no progress -> stop
done
# (3) the spend ceiling lives on the wrapper: a wall-clock or token budget that kills the run.

The cap makes the run bounded; the failed commit makes each pass verifiable — nothing changed against the check, so the loop stops instead of grinding on. That is what turns an open-ended loop into bounded, verifiable work.

Then the state. Anthropic's harness work names it exactly: "the core challenge of long-running agents is that they must work in discrete sessions, and each new session begins with no memory of what came before" (Anthropic: Effective harnesses for long-running agents). Their conclusion is the one that breaks the single-prompt playbook: "even a frontier coding model like Opus 4.5... will fall short of building a production-quality web app if it's only given a high-level prompt." The fix is not a better prompt; it is state on disk — Anthropic reconstructs it "with the claude-progress.txt file alongside the git history," and the field guide reduces it to a line worth taping to your monitor: "the agent forgets; the repo doesn't" (Truong Phung).

Carry one version caveat so you don't over-learn the memoryless framing. On newer models the strict "no memory of what came before" is softer than it sounds. Server-side compaction and the Agent SDK's "compact feature automatically summarizes previous messages when the context limit approaches" (Anthropic: Building agents with the Claude Agent SDK) both blunt the hard session boundary. The mechanism is version-dependent; the discipline is not. Externalized state is what survives a window reset regardless of how gracefully your model compacts, so write the progress.txt either way.

State also changes what retrieval means, and this is where the loop reopens a problem you thought you had scoped. Just-in-time retrieval, in a single invocation, is one agent resolving pointers at runtime — and it has its own quiet failure modes (where JIT retrieval silently breaks). A loop adds a second retrieval axis with no single-shot analog: pulling the right slice of its own past sessions back into a fresh window. Anthropic's managed-agent architecture makes that axis explicit: the session is "a context object that lives outside Claude's context window." A getEvents() interface "allows the brain to interrogate context by selecting positional slices of the event stream" to pick up where it last stopped (Anthropic: Scaling Managed Agents). That is cross-iteration retrieval, and it is its own discipline. Keep the run's progress log separate from your durable skills and rules, because they answer different questions: what did this run do, versus what should every run know.

Re-Check Every Assumption Before You Press Go

Do not scale autonomy on a playbook you have not re-derived for many invocations. Every assumption in the table below was safe when the unit of work was one invocation; each one changes when the unit becomes many. Before the overnight loop runs unattended, walk each row and confirm you have an answer — this is the migration made into a checklist.

That checklist is runnable: loop-preflight greps your wrapper for the three brakes, the state file, and the check you don't let the model self-grade, then prices the always-on context your loop re-pays every iteration.

Single-shot assumption	What changes across many invocations	Check before you walk away
Loop engineering is a new skill to learn	It is the gather/act/verify primitive you already ran, now unattended	Are you migrating your single-invocation habits, or starting from a blank slate you don't need?
CLAUDE.md is a one-time cost paid at load	It reloads every turn and stacks the loop's own output on top, so context rot compounds	Did you cut the file for how it reads on turn 50, and move every real constraint above the fold?
A clean demo predicts reliability	Per-step accuracy decays and the model conditions on its own earlier mistakes, quietly	Have you budgeted for the run that builds on a 2 a.m. error in `auth.go`, not the one you were shown?
"Done" ends the task and the window clears it	Nothing terminates the loop and nothing survives the reset	Is there a max-iteration cap, no-progress detection, a spend ceiling, and a `progress.txt`?

The through-line is one sentence. A loop is many invocations, not one — so the question before you press go is not "is my prompt good?" but "does every assumption I tuned for a single invocation still hold on turn fifty?" The single-invocation playbook was not wrong; it was scoped. Loop engineering is what you get when you re-derive it for the unit of work you actually shipped — and the reader who runs that migration keeps the overnight wins instead of the overnight surprises.

I write one long-form piece at a time on context engineering and agent reliability. If re-deriving the playbook every time the unit of work changes isn't how you want to spend the quarter, subscribe and the next one lands in your inbox.

References

Research and Data

Chroma: Context Rot — How Increasing Input Tokens Impacts LLM Performance (Hong, Troynikov, Huber) — Across 18 models and 194,480 calls, performance grows increasingly unreliable as input length grows, and presentation matters more than presence. Backs the per-iteration rot and "presentation over presence" sections.
Sinha, Arun, Goel, Staab, Geiping: The Illusion of Diminishing Returns — Measuring Long Horizon Execution in LLMs — Per-step accuracy decays and models self-condition on their own prior errors; larger models are more prone and thinking mitigates it. Measured on a synthetic running-sum task. Backs "a loop is a different reliability regime."
METR: Measuring AI Ability to Complete Long Tasks — Task length agents complete autonomously with 50% reliability has been doubling roughly every 7 months. The "why now" for taking loops seriously.

Practitioner Guidance

Anthropic: Building Effective AI Agents — An agent is "just LLMs using tools ... in a loop"; the compounding-errors warning; stopping conditions such as a maximum number of iterations. Backs loop-as-primitive and the stop spec.
Simon Willison: Designing agentic loops — Designing the loop is "a critical new skill," and an agent "runs tools in a loop to achieve a goal" — the term's lineage predating its coinage. Backs loop-as-primitive.
Addy Osmani: Loop Engineering — Defines loop engineering as replacing yourself as the person who prompts the agent. The term the post reframes.
Anthropic: Effective context engineering for AI agents — A looping agent generates more and more data that must be cyclically refined; names context rot and attributes it to Chroma. Backs "the context accumulates every turn."
Anthropic: Context windows — Accuracy and recall degrade as token count grows (context rot), so curation matters as much as capacity. Official-docs corroboration.
Anthropic: Introducing advanced tool use on the Claude Developer Platform — Intermediate results pile up in context whether useful or not; tool definitions have consumed 134K tokens before optimization. The 134K figure is tool definitions, used only as an analog for always-on bloat.
Anthropic: Effective harnesses for long-running agents — Long-running agents work in discrete sessions with no memory of what came before; a high-level prompt alone fails; state reconstructed from a claude-progress.txt file alongside git history. Backs externalized state.
Anthropic: Scaling Managed Agents — The session is a context object that lives outside the context window; getEvents() selects positional slices of the event stream. Backs cross-iteration retrieval as its own discipline.
Anthropic: Building agents with the Claude Agent SDK — The gather/act/verify/repeat cycle and the compact feature that summarizes previous messages as the window fills. Backs loop-as-primitive and the compaction caveat.
Geoffrey Huntley: Ralph Wiggum as a "software engineer" — The unattended overnight loop with a fresh context each iteration and state in files; verify success programmatically rather than trusting the model to self-assess. The running artifact and the honest failure mode.
Truong Phung (DEV Community): The Agentic Loop / Loop Engineering: A Practical Field Guide — The three hard stops (max iterations, no-progress detection, spend budget) and disk-backed state: "the agent forgets; the repo doesn't." Backs the stop-and-state section.
agent-engineering-toolkit: loop-preflight — A preflight script plus Claude Code skill that checks an unattended loop wrapper for the max-iteration, no-progress, and spend brakes, externalized state, and a non-self-graded check, and prices the always-on context re-paid every iteration. Every check is a pattern grep and says so — MISSING means no recognizable pattern was found, not proof the guard is absent.

Author's Judgment (not directly sourced)

The following claim is my own synthesis. It follows logically from the sourced material above, but no source states it directly:

"A loop fails quieter than the demo, not just more often" — Inferred from Sinha et al.'s self-conditioning result (the model reads its own earlier errors as ground truth) and Anthropic's compounding-errors warning. Neither source states the "less visibly" framing; that is my inference.

The Anatomy of a Perfect AI Agent Task

John Young — Mon, 27 Apr 2026 20:30:03 +0000

A well-crafted task for an AI coding agent is essentially context engineering — you're deliberately curating the minimum set of information the agent needs to produce the right output on the first try. Rather than pre-loading everything up front, the best approach combines focused instructions with enough pointers that the agent can pull in additional context just-in-time as it works (Anthropic — Effective Context Engineering). Below is a breakdown of every element that matters, why it matters, and a full example at the end that ties it all together.

When to Use This

The seven elements below describe the upper-bound shape of a non-trivial task spec, not a baseline checklist. For trivial work — fixing a typo, renaming a variable, anything where the agent has no real risk of getting it wrong — skip the elaborate spec. (The companion sizing post uses "describable in one sentence" as a sizing test, not a triviality test — well-sized tasks often fit in one sentence yet still warrant a full spec when there are constraints, edge cases, or pitfalls to communicate. The worked example below is one such task.) Even for non-trivial tasks, treat these elements as a maximum rather than a minimum: frontier LLMs reliably follow only ~150–200 instructions before performance degrades, and every irrelevant detail dilutes the signal of the rest (HumanLayer: Writing a Good CLAUDE.md).

1. State the Goal, Not the Steps

Lead with the outcome you want, not a micro-managed sequence of instructions. Agents perform better when they understand the "why" and can plan their own approach.

Bad: "Open user.go, find the CreateUser function, add a field called PhoneNumber..."
Good: "Add phone number support to user registration, including validation, storage, and API response."

"The best task descriptions share three properties: they state the goal, provide constraints, and define done."
— Claude Directory: Context Engineering for Claude Code

2. Provide Architectural Context the Agent Can't Infer

The agent can read your code. What it can't read is the reasoning behind your architectural decisions, team conventions, or the "why" behind structural choices. Include only what's not derivable from the codebase itself.

Include things like:

Why the architecture is shaped a certain way (e.g., "We use the repository pattern to keep DB logic out of handlers")
Relevant files and entry points (saves the agent from searching blindly and burning context window)
Technology choices and versions (e.g., "Go 1.22, sqlc for query generation, chi router")
Domain-specific terminology the agent might misinterpret

"Claude already knows what your project is after reading a few files. What it needs is information it can't derive from reading code."
— Claude Directory: Context Engineering

That said, there's a discipline to this — more context is not always better. Research suggests frontier LLMs can reliably follow roughly 150–200 instructions before performance degrades, and broader context-rot studies show models attend to context less reliably as input grows (Chroma: Context Rot — Hong et al., 2025). Every irrelevant detail you add dilutes the signal of the details that actually matter.

"Your CLAUDE.md file should contain as few instructions as possible — ideally only ones which are universally applicable. An LLM will perform better when its context window is full of focused, relevant context compared to when it has a lot of irrelevant context."
— HumanLayer: Writing a Good CLAUDE.md

3. Define Explicit Constraints and Non-Goals

This is where most tasks fall apart. Without boundaries, agents will happily refactor your auth layer while you asked them to add a field to a struct.

Constraints: What rules must be followed (e.g., "Do not change the public API contract," "Use the existing validate package, do not introduce a new dependency")
Non-goals: What is explicitly out of scope (e.g., "Do not modify the frontend," "Do not refactor existing tests")

"Without constraints, AI might miss pagination for list APIs, use field injection instead of constructor injection, or not adhere to your project's package structure."
— JetBrains: Coding Guidelines for AI Agents

4. Provide Concrete Examples and Reference Implementations

One of the highest-leverage things you can do. Point the agent at an existing implementation in your codebase that follows the pattern you want replicated.

"Follow the same pattern as internal/order/handler.go for the new endpoint."
"See migrations/003_add_email.sql for the migration format we use."

"Include helpful examples for reference. ❌ 'Implement tests for class ImageProcessor' → ✅ 'Implement tests for class ImageProcessor. Check text_processor.py for test organization examples.'"
— Augment Code: Best Practices for AI Coding Agents

5. Define "Done" with Acceptance Criteria

If you don't define what "done" looks like, the agent will decide for you — and you probably won't agree.

Acceptance criteria should be:

Observable (can be verified by running something)
Specific (not "should work correctly")
Testable (ideally map to test cases)

"Create a set of tests that will determine if the generated code works based on your requirements."
— Google Cloud: Five Best Practices for AI Coding Assistants

6. Include Verification Commands

Tell the agent exactly how to confirm its own work. This is the difference between "I think it works" and "it passes the build."

go test ./internal/user/...
go vet ./...
golangci-lint run
curl -X POST localhost:8080/api/v1/users -d '{"phone": "+1234567890"}' | jq .

"Claude Code's best practices emphasize including Bash commands for verification. This gives Claude persistent context it can't infer from code alone."
— Claude Code Docs: Best Practices

7. Call Out Edge Cases and Known Pitfalls

You know things about your system the agent doesn't. If there's a footgun, flag it. If there's a non-obvious coupling between modules, say so.

"The user_id column has a unique constraint — the migration must handle existing duplicates."
"The Validate() method is called both at the handler level and inside the repository. Don't double-validate."

The Full Example

A non-trivial feature decomposes into a handful of well-sized tasks. Take adding an optional phone number to user registration — accepted on signup, persisted on the user record, and returned by the user API. That feature splits into four tasks, one per architectural layer:

Migration — Add a nullable phone_number column with reversible up/down SQL.
Model + sqlc — Update the User struct and regenerate sqlc queries.
Service + validation — Add ValidatePhone to UserService using validate.PhoneE164, with unit tests.
Handler + integration — Wire the field through POST and GET /api/v1/users and add integration tests.

The third is spec'd out in full below as the worked example. It's the strongest illustration of the seven elements at the right scope: the diff fits in one sentence, it stays inside a single layer, the agent reads ~5 files, the change lands well under the 200 LOC ceiling, and it can be verified independently — passing every gate of the companion sizing post's decision flowchart.

## Task Spec: Add E.164 phone validation to UserService

### Goal
Phone numbers submitted to user registration must be rejected at the service layer when they aren't valid E.164. This task delivers that check; handler wiring and DB persistence are separate tasks.

### Architectural Context
- Semantic validation belongs in the service, not the handler. Handler does null/shape; service owns format and bounds.
- `UserService.ValidateEmail` is the canonical example of this split — match its shape.

### Relevant Files
- `internal/user/service.go` — add `ValidatePhone` here.
- `internal/user/service_test.go` — add tests here.
- `internal/pkg/validate/phone.go` — read-only reference for `PhoneE164` and `validate.Error`.

### Reference Implementation
Mirror `UserService.ValidateEmail` in `service.go`:
- Signature: `func (s *UserService) ValidatePhone(phone *string) error`.
- Nil pointer → return nil. Empty string → return error.
- Return the `*validate.Error` from `PhoneE164` unwrapped — no `fmt.Errorf`.
- Copy the table-driven layout from `TestUserService_ValidateEmail`.

### Constraints
- Use `validate.PhoneE164`. No regex, no new dependencies.
- Don't touch `UserRepository` or its mock — validation is pure.
- Don't wrap the error; the handler relies on `errors.As(&validate.Error{})` to map it to HTTP 422.

### Non-Goals
No handler, migration, sqlc, or integration-test changes. No edits to `ValidateEmail` or other unrelated methods.

### Edge Cases
- `phone == nil` → return nil (field not provided).
- `*phone == ""` → return `validate.Error` (malformed input).
- Strict E.164: `1234567890` (no leading `+`) must fail.
- The handler already checks the JSON field is present and is a string — don't re-check those concerns here.

### Acceptance Criteria
1. `ValidatePhone(phone *string) error` on `UserService`.
2. `nil` phone → returns nil.
3. Empty or non-E.164 → returns `*validate.Error` (verifiable via `errors.As`).
4. Valid E.164 (e.g., `+14155552671`) → returns nil.
5. At least four test cases: valid, invalid, nil, empty.
6. Only `service.go` and `service_test.go` change.

### Verification
    go test ./internal/user/... -v -run TestValidatePhone
    go vet ./...
    golangci-lint run ./internal/user/...

The spec above is available as a copy-paste template with a lint script that fails on missing sections in the agent-engineering-toolkit.

Why This Works

Element	Purpose
Goal	Anchors the agent on what and why, not how
Architectural context	Provides knowledge the agent can't infer from code
Relevant files	Eliminates unnecessary exploration and context burn
Reference implementation	"Do it like this" is worth 1,000 words of description
Constraints + non-goals	Prevents scope creep and unsolicited refactors
Edge cases	Surfaces domain knowledge only you have
Acceptance criteria	Defines "done" in observable, testable terms
Verification commands	Lets the agent self-check before declaring victory

References

Anthropic — Effective Context Engineering for AI Agents — Why just-in-time context retrieval and focused instructions outperform pre-loading everything into the prompt.
Claude Code Docs — Best Practices — Including verification commands and CLAUDE.md conventions so the agent can self-check its work.
Claude Directory — Context Engineering for Claude Code — The task trifecta: state the goal, provide constraints, define done.
Augment Code — Best Practices for Using AI Coding Agents — Pointing agents at reference implementations and reviewing changes after each sub-task.
JetBrains — Coding Guidelines for Your AI Agents — How missing constraints lead agents to skip pagination, misuse injection patterns, and ignore project conventions.
Google Cloud — Five Best Practices for AI Coding Assistants — Planning-first workflow and using tests as acceptance criteria for generated code.
HumanLayer — Writing a Good CLAUDE.md — Why fewer, focused instructions outperform instruction overload, and the ~150–200 instruction ceiling for frontier models.
Chroma — Context Rot (Hong et al., 2025) — Empirical study across 18 LLMs showing that attention to context degrades non-uniformly as input length grows.
agent-engineering-toolkit: task-spec — Copy-paste task-spec skeleton matching this post's worked example, plus a lint script that fails on missing sections and flags vague acceptance criteria.