Agents are generating garbage docs that become a source for the next agent. How do we stop that?
Treat agent docs as drafts, not sources. Route them through the same review as code, stamp each one with who wrote it and when, make the next agent check claims against the code before it trusts them, and let unconfirmed notes expire. Keep context files short, because a 2026 study found they raised agent cost by over 20% without generally improving success.
You stop it by refusing to let agent docs count as a source until something has checked them. An agent doc is any page an agent wrote that another agent may later retrieve, such as a README, a CLAUDE.md entry, a memory note or a design summary. Treat these as drafts: reviewed like code, labelled with who wrote them and when, checked against the code before the next agent trusts them, and deleted when nobody confirms them. The agent doc loop is what happens when you skip that step: one agent writes a confident but wrong page, the next agent retrieves it as fact, builds on it, and writes another page that repeats the mistake. Each pass makes the error look better sourced. The fix is a gate between what an agent writes and what an agent reads.
| Gate | What it stops | How to set it up |
|---|---|---|
| Review | Unchecked pages entering the docs tree | CODEOWNERS on agent-facing files, owner approval required |
| Provenance | Guesses read as decisions | Writer, date, source task and approver in each page's header |
| Citations | Claims nobody can check | Every claim links a file, function or PR; CI fails on dead paths |
| Expiry | Old notes outliving the code | Unconfirmed pages deleted after a set period |
| Write location | Scratch notes indexed as docs | Session notes go to an unindexed folder or the PR description |
Why agent docs poison the next agent#
An agent's notes read like documentation, so retrieval treats them like documentation. Prose matches a question in prose better than code does, a ranking problem we cover in our wiki says one thing and the code does another.
More text also does not mean better results. A 2026 study of repository context files such as AGENTS.md found that "providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average" (arXiv 2602.11988). The test setup ran agents on SWE-bench tasks with LLM-generated context files and on real issues from repositories with developer-committed ones, and the result held for both. The authors found repository overviews "are not helpful," while notes on "non-standard coding practices" were useful. Many agent-written docs are overviews of exactly that kind. They repeat what the code already says, sometimes a little wrong, and cost tokens on every run.
Review agent docs the way you review code#
The simplest gate is the one you already have. Put agent-facing files (AGENTS.md, CLAUDE.md, docs/, rules folders) behind an owner. GitHub's CODEOWNERS file lets you "define individuals or teams that are responsible for code in a repository," and owners "are automatically requested for review when someone opens a pull request" (GitHub docs). Turn on "Require review from Code Owners" and an agent can propose a doc change but cannot merge one.
Then add a provenance stamp. A provenance stamp is a short header that records where a page came from: the agent, the date, the PR or task that produced it, and the person who approved it. A page with no approver is a draft. Retrieval can skip drafts, or rank them below reviewed pages. It gives the next agent a way to tell a guess from a decision. The CLAUDE.md audit guide walks through pruning what is already there.
Make every claim point at the code#
GitHub built this check into Copilot Memory. Repository facts are stored with "citations pointing to the code that supports the fact," and "Copilot is instructed to check the citations provided with each memory before using it" (GitHub docs). Copilot votes memories up or down after checking them, stops using ones voted down past a threshold, and lets unconfirmed memories expire. "The default expiry period is 90 days," and enterprise and organization owners can set it for repository facts from 7 to 180 days.
Copy that pattern for your own docs. Require each claim in an agent-written page to cite a file, a function or a PR. Add a CI job that fails when a cited path no longer exists. Give generated pages an expiry date, and when it passes, a person confirms the page or it is deleted. An agent note that says "payments retry three times" with a link to retry.ts can be checked in seconds. The same note with no link can only be believed or ignored.
Keep agent output out of the source pool by default#
Decide where agents may write, and make the default somewhere retrieval does not index. Session notes and task summaries belong in a scratch folder or the PR description.
Know what your tools write on their own. Claude Code's auto memory is "notes Claude writes itself based on your corrections and preferences," and the first 200 lines or 25KB of its index load into every session (Claude Code docs). The files are "plain markdown you can edit or delete at any time," and /memory opens them. The same page suggests /doctor prompt-audit to check CLAUDE.md, AGENTS.md and rules files for outdated or conflicting instructions. Put a monthly read of those files on someone's calendar. If agents also ignore the rules you do keep, see why agents ignore CLAUDE.md rules. Our post on tools that stop agents acting on stale documentation covers the wider set of fixes.
Where a context engine fits#
Review and expiry cut the volume of bad pages. They do not decide what is true when a page and the code disagree at query time. That is the job of a context engine. A context engine is a service that indexes code, PRs, tickets, docs and chat together and decides which source is current before answering. The argument is in who decides what is true for AI agents. Unblocked reads code, PRs, issues, docs, Slack and Teams, and incident channels together, and treats the code as the strongest ground truth for how the system behaves now. So an agent-written doc that contradicts the code is weighed against it, and when the two conflict the answer says so instead of passing the page on alone. Jon Samp, Head of Product at Expo, puts the principle behind it plainly: "The people in your company are the ones who know things. They wrote them down, and Unblocked makes the LLM show you what they wrote." (Expo customer story)
It works best on top of these habits. Review what agents write, label it, tie it to the code, and let it expire. Then the next agent reads fewer pages, and the ones it reads can be checked.
