The Manual vs. The Rulebook: A Costly Misunderstanding
Many teams misunderstanding the role of an AGENTS.md file creates a costly operational blind spot. Recent research from engineers at Coldtea reveals a stark reality: only 27% of the top 1,000 GitHub repositories even possess an AGENTS.md file, and a significant majority of these are being leveraged incorrectly. This widespread oversight leaves a critical gap in managing AI contributions.
The core issue lies in confusing an operation manual with a 'rulebook'. Most existing AGENTS.md files function as manuals, focusing on project architecture descriptions or listing exact commands for building and testing. They tell an AI how to operate, but critically, they fail to constrain what it should and should not do.
A true AGENTS.md acts as a rulebook, establishing strict guardrails and explicit negative constraints for AI agents. Without this rulebook, agents operate without boundaries, leading to inconsistent contributions, unexpected behavior, and the introduction of potential bugs. Larger repositories, for example, dedicate almost double the space to "don't" rules, a clear signal of their understanding of this necessity. The absence of clear "must," "always," and "never" directives turns a potentially powerful tool into an unpredictable liability.
The Power of 'Don't': Lessons from Vercel and Bun
Coldtea's research reveals a critical pattern among leading repositories: the most effective AGENTS.md files prioritize explicit negative constraints. Top-100 repositories dedicate nearly double the space to rules about what not to do, compared to smaller projects, with 784 instances of implied "don't" sentences found.
A striking 90% of these high-performing files leverage definitive terms such as 'must,' 'always,' or 'never' to guide AI agents. This isn't accidental; it's a deliberate strategy to prevent unintended actions and maintain code integrity, a hallmark of robust systems.
Specific examples underscore this precision. Vercel's Next.js repository, for instance, explicitly bans 'generated with Claude code' footers from commits. This level of detail ensures AI contributions align perfectly with project standards and human expectations.
Bun's repository offers another powerful illustration with its all-caps warning: 'NEVER run bun test directly - it won't include your changes.' Such direct prohibitions cut through ambiguity, preventing agents from executing detrimental commands that could compromise the build or test environment.
Explicit boundaries are essential because AI agents operate without human context or intuition. They lack the implicit understanding of project history, team norms, or potential side effects. Therefore, you must tell them precisely what files, functions, or patterns to meticulously avoid, acting as a digital guardrail. This proactive approach prevents subtle errors and protects the codebase.
From 33 to 14,000 Words: Finding Your File's Right Size
The sheer variability in AGENTS.md file length reveals a nascent best practice. Consider the extremes: VS Code's entire file spans just 33 words, acting as a simple redirect. Neovim's, barely longer at 35 words, focuses on a single disclosure rule for AI-generated commits. Meanwhile, the OpenHands repository presents a formidable 14,000-word instruction set. This wild spectrum highlights the challenge of defining an optimal blueprint.
Coldtea's research, however, offers a practical north star: a median length of approximately 1,200 words. This figure suggests a pragmatic sweet spot for most projects, balancing sufficient detail for AI contributors with the clarity needed for human oversight and rapid iteration. It's a realistic benchmark for establishing effective agent boundaries without overwhelming verbosity.
Ultimately, your AGENTS.md file’s complexity must directly align with your project’s scale and the specific risks you aim to mitigate with AI assistance. A smaller, focused utility might need minimal guardrails, but a complex, multi-contributor system demands a robust rulebook. For deeper insights into how context files truly help coding agents, explore works like Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?.
Enjoying this? Get one like it in your inbox each morning.
one email a day · unsubscribe in two clicks · no third-party tracking
Your 3-Point Checklist for an Agent-Proof Repo
After analyzing the top 1,000 GitHub repositories, Coldtea’s engineers distilled the essence of effective AGENTS.md files into a crucial three-point checklist. This isn't about suggestions; it’s about providing precise commands for your AI agents, transforming your file into a robust rulebook.
For an agent-proof repository, ensure your AGENTS.md includes:
- At least one explicit 'don't' rule. This critical directive, present in 86% of effective files, establishes clear boundaries for agent behavior. Without these negative constraints, agents often default to assumptions, potentially introducing undesirable changes or "generated" footers, as seen with Vercel's Next.js. This includes clearly defining what the agent is never allowed to touch.
- Meticulously spell out how commits and pull requests must be formatted. Found in 79% of successful files, this ensures project history and standards remain consistent, regardless of whether a human or an AI agent submits the code. Prescriptive formatting prevents chaos in the version control system.
- Exactly how to run tests and lint code. Roughly three quarters (75%) of effective files provide these precise instructions. These aren't optional steps; they are direct commands for the agent to execute, ensuring every contribution adheres to quality gates before integration.
Frequently Asked Questions
What is the main mistake projects make with AGENTS.md files?
The most common mistake is treating AGENTS.md as an operational manual (listing commands) instead of a strict rulebook that tells an AI agent what it must and, more importantly, what it must not do.
What are the key elements of a good AGENTS.md file?
An effective file includes explicit negative constraints ('don't' rules), clear instructions for formatting commits and PRs, and precise guidelines on how to run tests and lint the code.
Do large projects need different AGENTS.md files than small ones?
Yes. Research shows larger, more complex projects have much stricter AGENTS.md files, dedicating almost double the space to negative constraints ('don't' rules) to protect the codebase.
How common are AGENTS.md files in top GitHub repos?
They are still relatively rare. A study of the top 1,000 GitHub repos found that only 27% had an AGENTS.md file, indicating a major opportunity for improvement in guiding AI agents.