'Smelly' Configuration Files Weigh Down AI Agents

AI agents dedicated to coding have become indispensable tools for developers. However, a recent study from the Federal University of Minas Gerais (Brazil) has uncovered a hidden problem: the configuration files that guide these agents — such as Agents.md or Claude.md — often contain structural defects that researchers call 'smells.' These defects cause agents to receive redundant, contradictory, or excessively long instructions, leading to higher token consumption, increased costs, and less reliable responses.

What happened?

The team analyzed 100 popular repositories on GitHub that included Agents.md or Claude.md files, used by agents like Claude Code, Codex, Cursor, and Gemini to define project conventions, workflows, and domain-specific knowledge. The results were striking: 91% of repositories had at least one 'smell,' and 62% suffered from 'lint leakage' — instructions that repeat rules already enforced by automated tools like formatters or linters. This unnecessarily inflates the model's context, wastes tokens, and distracts the agent from more relevant tasks.

Other identified smells include 'context bloat,' present in 42% of files, where overly long configurations include low-priority rules that increase costs and reduce attention to key instructions. 'Skill leakage' (35%) occurs when guidelines that the agent already possesses by default are included, creating redundancy. 'Conflicting instructions' (28%) cause ambiguity, while 'init fossilization' (24%) and 'blind reference' (16%) indicate outdated configurations or references to resources that no longer exist.

Why is it important?

AI agents are increasingly critical in tasks such as code generation, review, test creation, bug fixing, software migration, and documentation writing. They work by combining a large language model (LLM) with a harness that executes actions and calls external tools. Configuration files are loaded at the start of each session and guide the agent's behavior throughout the task. If these files are contaminated with 'smells,' the agent's performance degrades significantly.

The study highlights that these defects not only increase operational costs due to higher token usage but can also cause agents to misinterpret project conventions, prioritize erroneous instructions, and execute tasks suboptimally. In a context where companies increasingly rely on AI agents to accelerate development, the widespread presence of these 'smells' poses a risk to the quality and efficiency of generated software.

Consequences and recommendations

The researchers propose a catalog of six smells as a tool for developers and DevOps teams to audit and clean their configuration files. Practical recommendations include: removing redundant rules already covered by linters, keeping files concise and focused on project-specific guidelines, avoiding contradictory instructions, and periodically reviewing references to prevent broken links or outdated configurations.

Additionally, they suggest that agents themselves could incorporate mechanisms to detect these smells and alert the user, or even automatically optimize configurations. Tools like Claude Code, Cursor, or Codex could benefit from integrating smell analysis into their workflows.

What readers should know

For developers already using AI agents, the lesson is clear: reviewing configuration files is as important as reviewing source code. A well-structured Agents.md or Claude.md file can make the difference between an efficient agent and one that wastes resources and makes mistakes. For companies, this finding underscores the need to establish best practices in AI configuration management, similar to how it's done with traditional code.

The study, titled 'A Catalog of Smells for Coding Agent Configuration Files,' is available on arXiv and represents the first systematic work on this problem. Its authors hope it will serve as a foundation for future research and tools that improve the reliability of coding agents.