Resolving Fragrant Code Configurations
If your agent is subjected to a strong scent, it’s essential to tidy up your directives. Hazardous or inadequately structured coding patterns are referred to as “code smells,” and it appears that coding agent instructions can be similarly odorous, resulting in token wastage and subpar output.
Deciphering AGENTS.md and CLAUDE.md Files
Coding agents depend on configuration documents that outline anticipated agent actions. These context-enhancing documents are typically formulated in Markdown and designated as CLAUDE.md for users of Anthropic models or AGENTS.md for other users. They encompass various text directives that guide the coding agent regarding preferred behaviors and tool utilization, and they can become excessively verbose. Anthropic recommends limiting text to no more than 200 lines as longer files consume model context and may compromise model coherence.
The Research: Configuration Smells Abound
Researchers from the computer science department of the Federal Institute of Minas Gerais in Brazil recently examined approximately 532,000 files to construct and scrutinize a dataset of 100 prominent open-source projects featuring either an AGENTS.md or a CLAUDE.md file. “Our findings indicate that configuration smells are prevalent,” the authors note. “Lint Leakage was the most frequent smell, impacting 62 percent of the files, followed by Context Bloat (42 percent) and Skill Leakage (35 percent).”
Interpreting Configuration Smells
Linting involves utilizing automated tools to identify programming and stylistic errors in code. Lint Leakage pertains to agent instructions that reiterate rules already imposed by linters, format validators, and static analysis tools. Redundant rules squander tokens by adding unnecessary guidance for tasks already effectively managed by programmatic tools.
Context Bloat, as its name implies, illustrates developers’ tendency to excessively specify code agent actions. “Inflated configuration files escalate token usage, increase costs, and diminish the clarity of essential directives,” the authors remark, pointing to Anthropic’s suggestion of limiting text to 200 lines.
Another prevalent configuration smell, Skill Leakage, transpires when infrequently used tools or practices are incorporated into the AGENTS.md file, which is accessed in every agent session. The agent instructions would be more appropriately kept in a separate skills file (e.g. SKILLs.md) that only loads when necessary. Skill leakage also expands the agent’s context unnecessarily and could divert agents from other tasks.
Additional Agentic Fragrances
Other agentic fragrances include: Blind References, where configuration files cite external documents (e.g. via URLs) without clarifying when that resource is applicable; Init Fossilization, which refers to configuration specifics established during a project’s initialization that are no longer pertinent; and Conflicting Instructions, arising when agent directives are at odds with one another.
The study authors indicate that at least one of these six smells was detected in 91 of the 100 AGENTS.md files analyzed. “These results imply that developers could benefit from tools and catalogs designed to identify configuration problems in agent configuration files,” they conclude in the preprint paper titled “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.
Minimalism is Key
The takeaway here is that minimalism prevails when it comes to code agent configuration files, even to the extent that any addition may be detrimental compared to nothing. Similarly, when ETH Zurich researchers investigated the effect of context files for agents a few months prior, they discovered that developer-generated instructions elevated costs and only enhanced code performance by about 4 percent, while LLM-generated instructions had a slight (3 percent) adverse effect on agent-generated code. They concluded that “unnecessary obligations from context files complicate tasks, and human-written context files should only delineate essential requirements.”
Summary: The Aroma Assessment
Thus, if your AGENTS.md is leaving an unpleasant scent, it might be time to adjust your approach. Keep it concise and straightforward, everyone! No need for your code to reek more than a Geordie lad post a night out on the Toon!
