{"slug": "your-agents-md-is-holding-you-back", "title": "Your AGENTS.md is holding you back", "summary": "PostHog reports that AI coding agents are now performing worse with excessive context, prompting Anthropic to remove 80% of Claude Code's system prompt and Boris Cherny, creator of Claude Code, to recommend deleting CLAUDE.md every six months. PostHog's AI onboarding wizard was updated to rely on model recommendations instead of default scripts, and the company suggests running `/doctor` commands to trim redundant context, though it warns these tools cannot catch errors like outdated merge queue instructions, which caused a 21-hour period of wrong agent guidance.", "body_md": "[Context engineering](https://posthog.com/newsletter/context-engineering?utm_source=posthog-newsletter&utm_medium=post&utm_campaign=agents-md) used to focus on adding information that base models lacked:\n\nBut then the models kept getting better. Now, the same context your agents couldn’t function without [can make them perform worse](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.6#favor-leaner-prompts).\n\nOur AI onboarding wizard, for example, often landed on the wrong project in monorepos because our scripts pointed to root by default. Now that models are good at inferring repo structure, [we updated it](https://github.com/PostHog/wizard/pull/884) so headless runs take advantage of model recommendations.\n\nThis is the same reason why Anthropic [removed 80% of Claude Code’s system prompt](https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models). Labs are going back on previous advice about rules and repetition; judgment, interfaces, and progressive disclosure are the new best practices instead.\n\nThe goal of context engineering has since shifted toward *subtracting *as much information as you can to get out of the models’ way:\n\nBut figuring out exactly what to subtract isn’t easy when dealing with unpredictable behavior.\n\nWhen asked about his approach, Boris Cherny, the creator of Claude Code, [recommended deleting your CLAUDE.md](https://www.youtube.com/watch?v=qyPCVqFUyDo) every six months to stay on the bleeding edge. [Theo](https://x.com/theo/status/2082009220631953782) recently reported it was worth rewriting his `AGENTS.md`\n\nby hand:\n\nIf you'd rather not start from scratch every time, here are three practical ways to maintain your context while [\"unhobbling\" AI](https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models), from most hands-on to most [autonomous](https://posthog.com/newsletter/agent-autonomy?utm_source=posthog-newsletter&utm_medium=post&utm_campaign=agents-md).\n\n## 1. Run `/doctor`\n\n, but follow up with real eyes\n\nThe simplest way to keep your context healthy is to read and edit it yourself.\n\nMost coding agents have a built-in `/doctor`\n\ncommand to help with this. [Anthropic’s version of it](https://code.claude.com/docs/en/commands#:~:text=v2.1.198%20or%20later-,/doctor,-Skill.%20Run) runs basic health checks, deletes redundant prompts, catches broken settings, finds unused plugins, and optimizes for lazy loading.\n\nThe report also prints a summary of how often you’ve used each file, and how much it can trim. Here’s what that looks like for our website’s main `AGENTS.md`\n\n:\n\n```\n Component: posthog.com/AGENTS.md (= CLAUDE.md symlink)\n  Type: memory file\n  Scope: project (checked in)\n  Uses (total since install): always loaded\n  Used in window?: yes\n  Est. resident tokens: ~1,780\n  Verdict: trim ~350\n```\n\nAcross the `posthog.com`\n\nrepo, it suggested turning off 3 unused plugins and 3 skills across our website repo and estimated saving an average of 6K tokens per session.\n\nThis is decent, but you can’t rely on it to catch everything because it doesn’t check for correctness; it acts only based on what it can derive from your code.\n\nFor example, last month, we started using merge queues and added this line to our `AGENTS.md`\n\n:\n\n“All merges into `master`\n\ngo through the Trunk merge queue. Never run `gh pr merge`\n\n.”\n\nA couple days later, we paused the queue to fix some failing tests and forgot to update that line. Our agents therefore had wrong instructions for 21 hours. During that time, one engineer’s PR got stuck for 10 hours; another lost 45 minutes investigating the cause before [updating the instructions](https://github.com/PostHog/posthog/pull/75873).\n\nWe didn’t use `claude doctor`\n\nin the `posthog`\n\nmonorepo to fix this, but it couldn’t have caught it anyway since merge queue state lives in a GitHub setting rather than in code. Agents don’t know what they don’t know.\n\nTry this:Run`claude doctor`\n\nafter each upgrade and follow up with a manual pass on your`AGENTS.md`\n\n. For each line, if you can’t name the failure it prevents, delete it.\n\n## 2. Test your context like it’s code\n\nAnother tool for maintaining and unhobbling your context is evals.\n\nIt’s just like adding regression tests whenever you fix a bug in code. Every time you update your context to address an agent’s mistake, capture what caused it in the first place as an eval.\n\nFor example, we record technical “gotchas” we see from real PostHog Wizard runs as framework-specific [commandments](https://github.com/PostHog/context-mill/blob/main/context/commandments.yaml) such as:\n\nFor versions 15.3+, initialize PostHog in\n\n`instrumentation-client.ts`\n\nfor the simplest setup.For Phoenix or Plug apps, add\n\n`PostHog.Integrations.Plug`\n\nbefore the router so request context is attached to captured events and errors`posthog-rs`\n\nis the Rust SDK crate; add it with`cargo add posthog-rs`\n\nand construct the client with`posthog_rs::client(options).await`\n\n.\n\nThese get combined with instructions from the `context-mill`\n\n(e.g., “reuse event names the project already uses”) and a set of ~40 clean sample apps to create the evals we use in the [wizard-ci](https://github.com/PostHog/wizard-workbench/tree/main/services/wizard-ci). Here’s how it works:\n\n`wizard-ci`\n\nruns the PostHog Wizard on all ~40 sample apps and creates one PR for each.Those PRs don’t get merged. Instead, a second agent called the\n\n[pr-evaluator](https://github.com/PostHog/wizard-workbench/tree/main/services/pr-evaluator)grades each of them based on the diffs and session logs.The\n\n`pr-evaluator`\n\nleaves metrics and reports on the trigger PR and the`wizard-ci PR`\n\n.\n\n[These reports](https://github.com/PostHog/wizard-workbench/pulls?q=is%3Apr+is%3Aclosed+label%3ACI%2FCD) help us catch issues like the wizard skipping installing PostHog entirely because the model determined it was already complete:\n\n`wizard-ci`\n\nis just one of many context-as-code tools we’ve built in our [wizard-workbench](https://github.com/PostHog/wizard-workbench). The setup is complex since it maintains [our biggest conversion path](https://posthog.com/newsletter/context-engineering?utm_source=posthog-newsletter&utm_medium=post&utm_campaign=agents-md#lesson-6-investing-in-context-pays-off), but the core concept is easy to apply: test your context by saving prompts that check if your agents are doing what you want them to do.\n\nTry this:The next time your agent makes a mistake, paste the prompt that caused it into a`failures.md`\n\n. Re-run those prompts the next time you edit or delete parts of your`AGENTS.md`\n\nas a quick test suite for your highest-cost piece of context.\n\n## 3. Ask agents for feedback directly\n\nAnother option for fixing your context is to just ask. Agents are good at providing feedback about how they would improve your context while they’re using it.\n\nMany developers already do this to update their skills, but you can take it further by putting it in your prompts by default.\n\nFor example, the final instruction for the PostHog Wizard says to [send back a quick remark](https://github.com/PostHog/wizard/blob/ba91f26c418f332f1ede8b6e80fd9fa14bbb22e8/src/lib/agent/runner/sequence/orchestrator/queue-tools.ts#L23) about any errors they encountered in production:\n\n“What information or guidance would have been useful to have in the integration prompt or documentation for this task? Specifically anything that would have prevented tool failures, erroneous edits, or other wasted turns.”\n\nThis gives us a rich feed of live bug reports for cheap – a basic form of AI observability:\n\nWe took this *even further* by feeding them back into our `context-mill`\n\nwith a [loop](https://posthog.com/newsletter/loops?utm_source=posthog-newsletter&utm_medium=post&utm_campaign=agents-md), making it [self-driving](https://posthog.com/self-driving?utm_source=posthog-newsletter&utm_medium=post&utm_campaign=agents-md). But since we can't trust agents at face value, we cluster and verify the underlying issues first. Here's what the feedback clusters looked like for the last month:\n\nHalf of the `other`\n\ncategory is just confirmation messages like “succeeded on the first attempt,” or “`posthog-js`\n\nalready installed”. The other half is a long tail of issues that weren’t common enough to cluster.\n\nOnce the loop identifies a meaningful cluster, it deploys subagents to verify the issue before attempting a fix. For example, to check the `notebook create schema/tool`\n\nissue, a subagent followed the legacy instructions to reproduce the hand-splicing text failure that was addressed in [this PR](https://github.com/PostHog/context-mill/pull/272).\n\nThis approach works best at scale to cluster remarks, but you can still apply the concept to your workflows by simply asking agents to log what context files they used.\n\nWe do this in our `posthog`\n\nmonorepo [PR template](https://github.com/PostHog/posthog/blob/27c2aeee512923e4c9b29045d84a7ec932312ebf/.github/pull_request_template.md?plain=1#L53), which prompts agents to name any skills invoked. We’ve seen other agents use this information to catch and fix skill inconsistencies, like in [this PR](https://github.com/PostHog/posthog/pull/81018) where Claude found an issue while unblocking stalled ClickHouse cleanup PRs.\n\nTry this:Agents face issues all the time. Ask them to provide feedback about your context with a structured prompt about any errors, inconsistencies, or failures they ran into. Over time, you can turn verified reports into a[self-driving]context system.\n\n*Written by Jina Yoon, who would like a word with whoever coined the term “unhobbling.”*\n\n## 🧠 Optimize your HUMANS.md\n\n[A field guide to Claude Fable 5: Finding your unknowns](https://claude.com/blog/a-field-guide-to-claude-fable-finding-your-unknowns)– Thariq Shihipar[Our context warehouse knows your data, the semantic layer tells it what to trust](https://posthog.com/blog/semantic-layer?utm_source=posthog-newsletter&utm_medium=post&utm_campaign=agents-md)– Thiago Rocha Salvatore, Lizzie Epton[The most common questions about developer marketing, answered](https://posthog.com/blog/developer-marketing-questions?utm_source=posthog-newsletter&utm_medium=post&utm_campaign=agents-md)– Joe Martin[Nobody watches their session replays: A study of 7.7 million views](https://posthog.com/blog/nobody-watches-session-replays?utm_source=posthog-newsletter&utm_medium=post&utm_campaign=agents-md)– Natalia Amorim[Treat prompt changes like code deploys](https://luke.geek.nz/azure/eval-gates-for-prompts/)– Luke Murray", "url": "https://wpnews.pro/news/your-agents-md-is-holding-you-back", "canonical_source": "https://newsletter.posthog.com/p/your-agentsmd-is-holding-you-back", "published_at": "2026-08-31 18:01:38+00:00", "updated_at": "2026-08-31 18:21:52.222750+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "large-language-models"], "entities": ["PostHog", "Anthropic", "Claude Code", "Boris Cherny", "OpenAI", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/your-agents-md-is-holding-you-back", "markdown": "https://wpnews.pro/news/your-agents-md-is-holding-you-back.md", "text": "https://wpnews.pro/news/your-agents-md-is-holding-you-back.txt", "jsonld": "https://wpnews.pro/news/your-agents-md-is-holding-you-back.jsonld"}}