If AGENTS.md smells ripe, your code won’t live up to the hype

If you're exposing your agent to a strong odor, it's time to clean up your instructions. Risky or poorly structured code patterns are known as "code smells," and it turns out coding agent directives can be similarly redolent, leading to wasted tokens and worse output. Coding agents rely on configuration files that summarize expected agent behavior. These context-enhancing files are commonly written in Markdown and named either CLAUDE.md for those using Anthropic models or AGENTS.md for pretty much everyone else. They include various text instructions that advise the coding agent about desired behavior and tool use. And they can get rather wordy. Anthropic advises no more than 200 lines of text because longer files consume model context and may hinder model coherence. Researchers affiliated with the computer science department of the Federal Institute of Minas Gerais in Brazil recently scoured some 532,000 files to build and analyze a dataset of 100 popular open-source projects containing either an AGENTS.md or a CLAUDE.md file. "Our results show that configuration smells are widespread," the authors state. "Lint Leakage was the most common smell, affecting 62 percent of the files, followed by Context Bloat (42 percent) and Skill Leakage (35 percent)." Linting is the process of running automated tools to check code for programming and style errors. Lint Leakage refers to agent instructions that repeat rules already enforced by linters, format checkers, and static analysis tools. Duplicative rules waste tokens by burdening the underlying model with guidance for a task already handled reliably by programmatic tools. Context Bloat, as its name suggests, describes the tendency of developers to overspecify code agent behavior. "Bloated configuration files increase token consumption, raise costs, and reduce the visibility of important instructions," the authors observe, pointing to Anthropic's recommendation of no more than 200 lines of text. Skill Leakage, another common configuration smell, occurs when rarely used tools or practices get added to the AGENTS.md file, which gets loaded in every agent session. The agent instructions would be better in a separate skills file (e.g. SKILLs.md) that gets loaded only when needed. Skill leakage also expands the agent's context unnecessarily and potentially distracts agents from other things. Other agentic odors include: Blind References, which happens when configuration files reference external documents (e.g. via URLs) without explaining when that resource becomes relevant; Init Fossilization, configuration details set up upon a project's initialization that are no longer relevant; and Conflicting Instructions, which occur when agent directives contradict each other. The study authors say that they found at least one of these six smells in 91 of the 100 AGENTS.md files tested. "These results suggest that developers could benefit from catalogs and tools designed to spot configuration issues in agent configuration files," they conclude in the preprint paper, entitled "Configuration Smells in AGENTS.md Files: Common Mistakes in Configuring Coding Agents." The authors are Helio Victor F. dos Santos, Vitor Costa, Joao Eduardo Montandon, Luciana Lourdes Silva, and Marco Tulio Valente. The message here is that less is more when it comes to code agent configuration files, perhaps even to the point that anything is worse than nothing. Similarly, when ETH Zurich boffins examined the impact of context files for agents a few months ago, they found [PDF] that developer-generated instructions raised costs and only improved code performance about 4 percent, while LLM-generated instructions had a small (3 percent) negative impact on agent-generated code. They concluded "unnecessary requirements from context files make tasks harder, and human-written context files should describe only minimal requirements." (R)