AI coding agents are becoming critical to software development, but the configuration files that guide them, such as Agents.md or Claude.md, can be “smelly.”

That means they can contain structural flaws, redundancies, or counterproductive workflows that bloat context, waste tokens, and make coding agents less reliable.

Researchers from the Department of Computer Science at Brazil’s Federal University of Minas Gerais hope to shed light on this problem, presenting what they call the “first catalog of smells” for coding agent configuration files. The most odorous? Lint and skill leakage, context bloat, and conflicting instructions.

“Our results show that these smells are widespread in practice,” the researchers wrote. Consequently, they “may directly influence how coding agents interpret project conventions, prioritize instructions, and perform development tasks.”

Smelly configs in the harness make models misbehave

Agents like Claude Code, Codex, Cursor, and Gemini are increasingly taking over software engineering tasks like code generation and review, test creation, bug fixing, software migration, and documentation writing.

Essentially, they are a combination of a large language model (LLM) and a harness; the model is the brain, the harness provides a loop that executes actions and allows agents to call the tools they need to fulfill a task. These might include web search engines, issue-tracking platforms, and test runners.

Agents’ behavior is guided by config files such as Agents.md and Claude.md, which provide instructions around project workflows, testing requirements, and domain-specific knowledge. This helps maintain consistency across separate tasks and sessions. Typically, these config files are loaded at the start of a session as part of a prompt and are maintained throughout the task.

But the researchers found that these configurations are riddled with smells; 91 of 100 popular open-source repositories containing Agent.md or Claude.md files had at least one smell.

The six strongest odors:

• Lint leakage (appearing in 62% of files)
• Context bloat (42%)
• Skill leakage (35%)
• Conflicting instructions (28%)
• Init fossilization (24%)
• Blind reference (16%)

The scent of waste

Lint leakage occurs when instructions in config files needlessly include rules that are already enforced by analysis tools like code formatters or linters (which filter out bugs, security vulnerabilities, inconsistencies, and programmatic errors, by, for example, restating generic style guide recommendations, formatting rules, line length, naming conventions, or import ordering).

This repetition increases a model’s context size and wastes tokens, the researchers pointed out. It “can divert the model from focusing on more important project-specific concerns, such as architectural constraints, domain rules, or safety policies.”

Context bloat means that configurations are excessively large and overloaded with rules, examples, or details that are unnecessary or low priority. This drives up token usage, ultimately raising costs and distracting the model from higher priority instructions.

With skill leakage, rarely-used or task-specific instructions are unnecessarily included in the configuration, rather than in separate dedicated skill or task files. This specialized knowledge is dragged into every session, even when the model doesn’t need it to perform its task. Thus, the context window becomes larger, more expensive, and difficult to maintain, the researchers noted.

“Furthermore, such rules may compete for attention with the rules that are actually critical for the project,” they wrote.

Just as it sounds, conflicting instructions means that file rules contradict one another, leading to ambiguity; the model essentially gets “confused” and has to choose arbitrarily. This can lead to inconsistency and unstable results.

Init fossilization occurs when files are generated once but never reviewed or edited again, so they include stale or irrelevant rules because they don’t reflect changes in the codebase. “As a result, the configuration tends to accumulate noise, increase context consumption, and reduce the overall effectiveness of the agent over time,” the researchers explained.

Finally, blind references point to files or docs without explaining what they’re for. Consequently, the agent might simply ignore them, leading to problems if they’re critical to a task, load unnecessary materials to gather context, taking up tokens and space, or fail to prioritize important information.

Additionally, the researchers discovered that smells often co-occur in the same file and trigger the appearance of others; for instance, skill leaking and conflicting instructions can increase the likelihood of context bloat by 83% because they add extemporaneous or irrelevant information.

How to air out smells

While these smells are “widespread in practice,” there are ways to air them out.

For example, to reduce lint leakage, stylistic constraints such as formatting, and import ordering should be removed from prompts. Let programmatic tools handle them; spending budget on style rules is a waste, the researchers noted.

To cut down on context bloat, Claude.md and Agents.md files should remain concise and provide project-specific guidance. For instance, Anthropic recommends a target of fewer than 200 lines per Claude.md file.

To limit skill leakage, developers should provide specific instructions in config files about the project build, test running, code conventions, and other important context. Task-specific instructions should be kept in separate markdown files with descriptive names, the researchers advise.

Additionally, to avoid conflicting instructions, builders should periodically review config files to remove instructions that are contradictory or outdated. Similarly, reducing init fossilization requires continuous updating of files, the researchers explained. This is particularly important in cases where an agent makes the same mistake twice in a row, a code review reveals a detail the agent should have already known, or when developers find themselves prompting corrections and clarifications already addressed in a previous session.

Finally, to minimize blind references, developers should tell agents when and why to read files, and include references with concise explanations of the document’s role, the information it contains, and scenarios where it should be used. For instance, text may reference an external dependency, include a link to its GitHub repository, and provide a brief explanation of its purpose. “Then the agent is able to understand the role of the dependency without needing to load or inspect the external repository directly,” the researchers explained.

Ultimately, they concluded, configuration files are “key artifacts” in agentic software development, and when they get smelly, there’s a problem. Therefore, “their quality deserves effort and attention.”