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

2026-06-16 · Source: cs.SE updates on arXiv.org · Field: Technology & Digital — Artificial Intelligence & Machine Learning, Software Development & Engineering · Depth: Expert, extended

Summary

A study identifies six common configuration "smells" in AGENTS.md and CLAUDE.md files, which guide coding agents in automating software engineering tasks. Researchers conducted a grey literature review and repository mining to catalog these issues, then evaluated their prevalence across 100 popular open-source repositories. Findings reveal that configuration smells are widespread, affecting 91% of analyzed files. Lint Leakage was the most common, present in 62% of files, followed by Context Bloat (42%) and Skill Leakage (35%). The study also highlights frequent co-occurrence patterns, particularly among Context Bloat, Skill Leakage, and Conflicting Instructions, suggesting that multiple issues often compromise agent performance. Automated heuristics, including LLM-based detection, were proposed and validated for identifying these smells.

Key takeaway

For AI Engineers or ML Engineers configuring coding agents, proactively addressing configuration "smells" in AGENTS.md or CLAUDE.md files is crucial. Regularly review your agent's configuration for issues like Context Bloat, Lint Leakage, and Conflicting Instructions to optimize performance, reduce token costs, and ensure consistent agent behavior. Consider implementing automated detection tools to maintain configuration file quality and prevent performance degradation.

Key insights

Configuration "smells" in AGENTS.md/CLAUDE.md files are widespread, increasing costs and reducing coding agent effectiveness.

Principles

• Agent configuration files should be concise and focused on essential guidance.
• Avoid duplicating rules already enforced by linters or formatters.
• External references require descriptive context for agents to prioritize information.

Method

Six configuration smells were identified via grey literature review and repository mining, then detected in 100 open-source projects using LLM-based heuristics and line-of-code thresholds.

In practice

• Target under 200 lines for AGENTS.md/CLAUDE.md files.
• Move task-specific instructions to separate "skill" files.
• Periodically review configurations to remove outdated or conflicting instructions.

Topics

• Coding Agents
• Configuration Management
• LLM Context
• Code Smells
• Software Engineering
• AGENTS.md

Code references

• openai/codex
• n8n-io/n8n
• langchain-ai/langchain
• vercel/ai
• javascript-obfuscator/javascript-obfuscator

Best for: Research Scientist, AI Scientist, Machine Learning Engineer, AI Engineer

Related on AIssential

• Writing a Good AGENTS.md — Effective `AGENTS.md` files are concise, human-written, and focus on essential, non-redundant information.
• Do AGENTS.md/CLAUDE.md Files Help Coding Agents? A New Paper Challenges this — Context files for coding agents often increase cost and steps without improving task success in well-documented repositories.
• Quoting Andrew Kelley — LLM-generated code exhibits a detectable "digital smell" due to distinct error patterns and stylistic differences.
• the history of agents.md, the problems with agents.md and what makes a good one — Effective LLM agent configuration requires model-specific, concise "agents.md" files to optimize behavior and context window usage.
• [AINews] The Claude Code Source Leak — The Claude Code leak reveals advanced agent architecture, emphasizing memory management, subagents, and robust operational features.
• The Impact of Configuring Agentic AI Coding Tools on Build-vs-Buy Decisions: A Study Protocol — Configuring agentic AI coding tools impacts their build-versus-buy decisions, affecting security and maintainability.

Open in AIssential →

Editorial summary, takeaway, and curation by AIssential. Original article published by cs.SE updates on arXiv.org.