Don't fall for the AGENTS.md trap
A stale AGENTS.md can be worse than no file at all.
— Ayush Thakur, Scott Roe-Meschke, Rajesh Bhatia
Cloudflare recently shared some incredible insights from 11 months of integrating AI into their engineering stack, with 241 billion tokens flowing through their AI Gateway each month, finding that file maintenance matters as much as file generation.
When crafting an AGENTS.md file, it's all too easy to fall into a prologue trap, where you spend time crafting the perfect AGENTS.md, feel a massive sense of accomplishment, and then merge it. But codebases are living documentation.
What happens with an outdated AGENTS.md?
Remember when early AI failure modes were LOUD, obvious syntax errors? Now, the more concerning failures tend to be the convincing lines of generated code that you need to be mindful of.
Cloudflare found that their coding agents regularly submitted pull requests that looked plausible but were fundamentally wrong because the local repo context had drifted. When your team rushes through a large diff, they might not even notice something is amiss. Even worse, if you have an AI reviewer checking that PR using the same stale AGENTS.md, it can speed up the merging of a mistake with maximum confidence. That kind of confusion then easily spreads throughout your entire team.
How Cloudflare solves this problem at scale
Cloudflare's internal dashboard tracking AI tool adoption across the company. Source: The AI engineering stack we built internally.
To fix this, Cloudflare built a massive, multi-layered internal platform:
- The Foundation: They leverage Backstage (an open source service catalog) to map a knowledge graph of more than 16,000 internal entities, from services and APIs to databases and the dependencies between them.
- The Generation: An automated system hooks into Backstage, detects a repo's language/frameworks, maps them to internal engineering rules, and uses an LLM to spin up a tailored AGENTS.md via an automated PR. (They've rolled this out to ~3,900 repos so far).
- The Enforcement: Their internal AI Code Reviewer reads the AGENTS.md on every single merge request. If an engineer's PR introduces architectural drift, the AI catches it and flags that the AGENTS.md needs an update in the same change window.
It's an impressive feat of platform engineering. But most teams can't dedicate the time or budget to build a center of excellence like Cloudflare's. If you spin up a self-hosted Backstage instance, build a custom MCP server portal, engineer a multi-agent CI reviewer, and write an internal standards codex, that can take a year (or more) of dedicated infrastructure plumbing to keep your repos coherent.
Four methods for keeping AGENTS.md current
Strip away Cloudflare's enterprise tooling, and you're left with four methods any team can use to keep an AGENTS.md current:
- Generate the initial file using real, ground-truth signals from the repo (structure, ownership, dependencies).
- Detect drift the moment code conventions and directory structures move out of step with the documentation.
- Propose frictionless updates in a format that's faster for an engineer to accept than writing documentation from scratch.
- Keep it lean. The file needs to remain short and high-signal, as it consumes valuable real estate in the model's context window every time an agent is invoked.
How do we solve this at Dosu?
We are not immune to this problem at Dosu, and we wanted a more reliable, team-focused solution that helps us keep our knowledge up to date, whether AGENTS.md files or other documentation.
We were inspired by the open AGENTS.md spec and Cloudflare's post, and added our own template to Dosu as a native starter template. It's intentionally narrow so agents don't have to infer what matters most to your team. That's all handled for you, based on the integrations that you add to Dosu's knowledge base.
Every template here is ready to use, AGENTS.md included. You can check them out in Dosu today.
Dosu actively watches your pull requests. When a change touches something described in your agent documentation, Dosu flags the drift and opens a suggested edit directly within your PR workflow. You can accept, tweak, or decline it on the fly. We use this flow daily!
We also structure our repository to keep things modular. Our root AGENTS.md file is loaded on every invocation, while specific subsystem files in other folders are loaded on demand. Reusable developer skills and guardrails live cleanly in our .claude/rules/ and .claude/skills/ (a pattern you can also see in Cloudflare's public cloudflare/agents repo).
How to audit your own repos
Before you move on to your next tab, let's do a quick audit. Open your AGENTS.md or README.md from your most used or your largest repository and ask:
- When was the last commit date?
- Try running the exact test command(s) listed there. Do they still work?
- Are all of the modules mentioned up to date (or do some not exist anymore)?
Those answers will give you a sense of how efficiently your coding agents might be performing.
Your agent instructions might already be stale. Dosu watches every pull request and opens a suggested edit the moment your code drifts from your AGENTS.md, yours to accept, tweak, or decline. Start managing drift with Dosu and help your team stay up to date with each change.
Related to this series
- How Fresh Are Your Docs? A CI Signal That Treats Documentation Like a Service. The drift framing applied to docs.
- How to Catch Documentation Drift with Claude Code and GitHub Actions. PR-time enforcement of the same idea.
- AI-Ready Open Source. The AGENTS.md is the highest-value place to start.
Further reading
- The AI engineering stack we built internally. The Cloudflare post that inspired us.
- agents.md. The open spec for the AGENTS.md format.
- cloudflare/agents AGENTS.md. Cloudflare's public example with nested subdirectory files.