Developers report stale agents.md files derailing coding-agent runs

• Project instruction files have become a runtime dependency, and the failure mode now looks like self-inflicted prompt injection, a phrase that came from swyx after Sol spent eight hours obeying a bad agents.md constraint.
• Practitioners are cutting always-on docs back to the parts code cannot encode: alternatives, domain language, ADRs, glossaries, and navigation pointers, a split visible in mattpocockuk's docs thread and zeeg's stale-specs report.
• Long-context drift now has a research label: behavioral state decay, where facts remain in the trajectory but stop shaping action, according to AlphaSignalAI's summary of the Meta paper.
• The emerging repair pattern is structured state, not bigger markdown: decision tickets, domain-modeling passes, selective reminders, adversarial review loops, and small policies show up across mattpocockuk's Wayfinder thread, the memory-agent benchmark post, and zeeg's Garfield review transcript.
• The cost of getting this wrong is no longer theoretical: zeeg's usage screenshots showed thousands of dollars in agent spend, while theo's Codex cost breakdown tied runaway usage to long contexts, nested subagents, and high-reasoning modes.

AGENTS.md is formal enough that the official format site calls it a README for agents and says it is used by over 60k open-source projects. OpenAI's Codex guide says Codex builds an instruction chain once per run, includes at most one instruction file per directory, and caps combined project docs at 32 KiB by default. Anthropic's Claude Code steering guide says root CLAUDE.md loads at session start, stays in context, and charges every line whether relevant or not. Meta's Remember When It Matters paper gives the research vocabulary for the same operator complaint: agents can still have the fact in context while their next action drifts away from it.

The sharpest field report came from swyx, who said a stale agents.md entry caused Sol to spend eight hours refining stage 0 because /goal would not let it stop and the file would not let it proceed.

The mechanics were simple:

• A five-stage task started under /goal.
• A prior agent committed the instruction that stage 0 was the target.
• The next run treated that local instruction as controlling state.
• The transcript had to be read back hours to find the bad premise.

A related report from dbreunig described a large-company setup where a coding agent loaded every shared skill any employee had pushed, injecting 300-plus skills on every call.

Ethan Mollick's anti-slop markdown complaint adds the social version of the same bug: a viral agent instruction file meant to prevent slop looked AI-written enough that he expected it to steer outputs toward the thing it was trying to avoid.

Zeeg's months-long experiment with colocated repo specs ended with deletion, not refinement. In zeeg's report, the specs cost compute to keep current, became outdated enough to mislead the agent, and failed to preserve intent when the model copy-pasted nearby patterns.

The replacement stack was smaller and more operational:

• policies/, lightweight and no-prose.
• openspec/, still present but not treated as context docs.
• Custom skills for third-party APIs and docs.
• agents.md primarily as a resource map.
• Inline code comments for intent.

The specs were not hidden from the model. Zeeg said in a follow-up that they were referenced and visible in a treemap, so the failure was not pure retrieval loss.

The same pattern showed up in smaller form in a Cursor subreddit post, where a user said unplanned vibe-coding accumulated abstractions and unclear logic until control of the codebase started slipping.

The strongest counter-position came from mattpocockuk, who argued for deleting docs that explain code and spending the saved token budget on making the code self-explanatory.

He kept three exceptions:

• Alternatives considered and domain language, which his follow-up grouped as ADRs and glossaries.
• Navigation pointers, which another reply called thin chains of links that form the roads the AI uses through a codebase.
• Context pointers, which a reply about progressive disclosure described as decoupled from the function of the code.

That matches Anthropic's Claude Code memory docs, which say Claude treats CLAUDE.md and auto memory as context, not enforced configuration, and points to PreToolUse hooks for blocking actions regardless of the model's choice.

The Wayfinder thread moved the problem earlier in the workflow. mattpocockuk's proposal said /wayfinder was doing less shared-language work than /grill-with-docs, so the first mapping session might need an explicit /domain-modeling step before making the map.

The proposed reason was propagation: once new entities are named, that language bleeds into every downstream ticket before those tickets are created.

Wayfinder creates decision tickets rather than implementation tickets, according to mattpocockuk's explanation, so the map can remember decisions and support cross-team collaboration. The resulting TikTok creator spec was posted after a morning Wayfinder session with one human-in-the-loop task left and the rest ready for AFK work.

Armin Ronacher's Tower Keeps Rising essay put the same thing in organization terms: large software projects are limited by how well people coordinate their understanding, not only by how fast individuals can change code.

GergelyOrosz sketched the operational triangle: deeper context plus longer agent runs means more compounding errors, with reliability improving when context and run length shrink.

Matt Pocock's dumb-zone report put a debugging bill on the same effect: a deep run through a complex build cost 90 minutes, then kept going wrong. In a reply, he clarified that the session was above 150K tokens.

Dexhorthy pushed back on a fixed threshold, saying the frontier shifts on every new model and that some 300K-plus sessions stay on track depending on the work.

Meta's paper narrows the claim. In AlphaSignalAI's summary, the facts survive in the trajectory, but early requirements, failed commands, diagnoses, and open subgoals stop controlling later actions.

The memory-agent result is Christmas come early for context-rot nerds: the paper does not fix drift by dumping more memory into every turn.

The architecture in the memory-agent post is a sidecar:

• Read the last eight messages.
• Update a structured memory bank.
• Choose one targeted reminder.
• Stay silent when unnecessary.
• Inject any reminder only into the next call.

The memory bank separates status, knowledge, and procedural memory, according to the structured-bank post. Benchmark gains in the results post were 8.3 points on Terminal-Bench and 6.8 points on tau2-Bench with Opus 4.6 handling memory for Sonnet 4.5.

Silence was an action, not an absence. The ablation post reported 64.3% tau2-Bench macro average for selective reminders, compared with 63.5% for always-on injection, 61.5% for full-bank exposure, and 62.1% for Mem0 retrieval.

The caveat lives in the training post: triggered steps can roughly double cost, the linked repository was empty, and the paper did not release trained weights.

The stale-instructions complaint is not limited to repo files. Mollick said the iOS ChatGPT remote setup docs did not match the desktop ChatGPT menus, then hit a Codex presentation skill that loaded a generic slide deck as its example.

The annoying part was coupling. Mollick's follow-up said the presentation skill contained important tool-use information, but editing it might be overwritten in the next Codex update and might interact unpredictably with a second presentation skill.

The community workaround is turning big instruction blobs into smaller loaded surfaces. Paulius Zdanavičius said he cut 63 skills by 40% tokens by auditing frontmatter invocation, deleting duplicated claims, using progressive disclosure, and cleaning dangling scripts. Brian Scanlan's Fin skills post described a small curated set of Claude Code skills and hooks used by hundreds of engineers.

Once project memory becomes suspect, verification moves into loops. Realmcore said an agent grinding for days made him conclude that adversarially reviewed code and a linter-like layer were required.

Swyx's big-project stack in one workflow post split roles across planning, critique, implementation, and review:

• Sol Ultra to plan.
• Fable 5 to critique.
• Sonnet 5, Terra Ultra, or SWE 1.7 to implement.
• Devin review to review.
• Grill-style decision elicitation upfront.

Zeeg's Garfield transcript shows what that looks like when industrialized: one review loop classified tracks for behavior/spec, repo instructions, validation, docs, dead code, delayering, type boundaries, dependencies, comments, implementation minimalism, interface design, and testing.

The bill can bite. Zeeg's screenshots showed $1,683.91 over 10,215 Codex requests on one view and $9,323.44 over 77,701 requests on another. Theo's cost breakdown attributed one Codex burn pattern to 2x pricing after 272K tokens, Ultra subagents spawning as Ultra, and a subagent layer that copied the full long context.

The small-file version of the pattern is still alive. In sqs's Amp screenshot, an agent edited the root AGENTS.md to add one Zod rule: derive TypeScript types from matching schemas with z.infer instead of duplicating schema shapes.

OpenAI's Codex AGENTS.md guide gives the operational boundary for that kind of rule: Codex rebuilds the instruction chain on every run and at the start of each TUI session, and its troubleshooting section says stale-looking instructions are fixed by restarting Codex in the target directory.