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

arXiv: https://arxiv.org/abs/2606.15828 · HTML: https://mlsanity.com/paper/2606.15828/

## Key facts

- Cited by 1 papers in the map (data through 14 Oct 2026).
- Placed in Software engineering coding agents, one of 16 directions in LLM agents and tool use.
- Builds on 21 of its 37 references that are in the map.
- First posted on arXiv 14 Jun 2026.

## Placed in

- LLM agents and tool use / [Software engineering coding agents](https://mlsanity.com/agents/software-engineering-coding-agents/)

## Builds on (most cited first, 21 of 21)

- [Evaluating Large Language Models Trained on Code](https://mlsanity.com/paper/2107.03374/) (2021)
- [SWE-bench: Can Language Models Resolve Real-World GitHub Issues?](https://mlsanity.com/paper/2310.06770/) (2023)
- [The Rise and Potential of Large Language Model Based Agents: A Survey](https://mlsanity.com/paper/2309.07864/) (2023)
- [Large Language Models for Software Engineering: A Systematic Literature Review](https://mlsanity.com/paper/2308.10620/) (2023)
- [Using an LLM to Help With Code Understanding](https://mlsanity.com/paper/2307.08177/) (2023)
- [Automated Unit Test Improvement using Large Language Models at Meta](https://mlsanity.com/paper/2402.09171/) (2024)
- [Using Large Language Models to Generate JUnit Tests: An Empirical Study](https://mlsanity.com/paper/2305.00418/) (2023)
- [LLaMA-Reviewer: Advancing Code Review Automation with Large Language Models through Parameter-Efficient Fine-Tuning](https://mlsanity.com/paper/2308.11148/) (2023)
- [Guidelines for including grey literature and conducting multivocal literature reviews in software engineering](https://mlsanity.com/paper/1707.02553/) (2017)
- [Using Transfer Learning for Code-Related Tasks](https://mlsanity.com/paper/2206.08574/) (2022)
- [Migrating Code At Scale With LLMs At Google](https://mlsanity.com/paper/2504.09691/) (2025)
- [On the Use of Agentic Coding Manifests: An Empirical Study of Claude Code](https://mlsanity.com/paper/2509.14744/) (2025)
- [Decoding the Configuration of AI Coding Agents: Insights from Claude Code Projects](https://mlsanity.com/paper/2511.09268/) (2025)
- [PromptSet: A Programmer's Prompting Dataset](https://mlsanity.com/paper/2402.16932/) (2024)
- [Bug Analysis in Jupyter Notebook Projects: An Empirical Study](https://mlsanity.com/paper/2210.06893/) (2022)
- [Fixing Dockerfile Smells: An Empirical Study](https://mlsanity.com/paper/2208.09097/) (2022)
- [Using Copilot Agent Mode to Automate Library Migration: A Quantitative Assessment](https://mlsanity.com/paper/2510.26699/) (2025)
- [On the Prevalence, Impact, and Evolution of SQL Code Smells in Data-Intensive Systems](https://mlsanity.com/paper/2201.02215/) (2022)
- [On the Quality of AI-Generated Source Code Comments: A Comprehensive Evaluation](https://mlsanity.com/paper/2408.14007/) (2024)
- [Code Smells in Elixir: Early Results from a Grey Literature Review](https://mlsanity.com/paper/2203.08877/) (2022)
- [Cache-Related Smells in GitLab CI/CD: Comprehensive Catalog, Automated Detection, and Empirical Evidence](https://mlsanity.com/paper/2604.17890/) (2026)

## Built on by (most cited first, 1 of 1)

- [Understanding the Architecture of Coding Agents: An Exploratory Study Using a Research Prototype](https://mlsanity.com/paper/2608.10934/) (2026)

## Abstract (arXiv)

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.