Configuration Smells in AGENTS.md Files: Common Mistakes in Configuring Coding Agents

2026-06-14

AI Summary

This study addresses the lack of systematic understanding of common flaws in current coding agent configuration files (e.g., AGENTS.md), which often lead to anomalous behaviors. To bridge this gap, the work proposes the first taxonomy of configuration “bad smells,” identifying six prevalent categories through a gray literature review and mining of open-source repositories. The authors further develop an automated heuristic-based detection approach. Empirical evaluation across 100 popular projects reveals that Lint Leakage (62%), Context Bloat (42%), and Skill Leakage (35%) are the most widespread issues. Moreover, multiple bad smells frequently co-occur, highlighting both the pervasiveness and interrelatedness of these problems. This research fills a critical void in the study of agent configuration quality and provides foundational insights for improving reliability in AI agent setups.

Abstract

Coding agents are increasingly used to automate software engineering tasks. To guide their behavior, these agents commonly rely on configuration files, typically named AGENTS.md or CLAUDE.md, which provide instructions about architecture, workflows, coding conventions, and testing practices. Despite their growing importance, little is known about common problems affecting the definition and maintenance of these files. In this paper, we present the first catalog of smells for coding-agent configuration files. To identify such smells, we first conducted a grey literature review and a repository mining analysis. As a result, we identified six configuration smells and proposed automated heuristics to detect them. To evaluate the prevalence of the proposed smells, we analyzed 100 popular open-source repositories containing either an AGENTS.md or a CLAUDE.md file. Our results show that configuration smells are widespread. Lint Leakage was the most common smell, affecting 62% of the files, followed by Context Bloat (42%) and Skill Leakage (35%). We further show that several smells frequently co-occur, particularly Context Bloat, Skill Leakage, and Conflicting Instructions.

Problem

• configuration smells
• coding agents
• AGENTS.md
• CLAUDE.md
• software engineering automation

Innovation

• configuration smells
• coding agents
• AGENTS.md
• automated detection
• repository mining