AGENTS.md Configuration Smells: 91% of Popular Repos Get One of Six Wrong

AGENTS.md and CLAUDE.md files are the standard way teams steer coding agents. They are also, per new research out of UFMG, mostly wrong in the same few ways. A study accepted at SCAM 2026 (IEEE's Source Code Analysis and Manipulation conference) catalogs the first taxonomy of configuration smells for agent instruction files, then measures how common they are in 100 popular open-source repositories. The headline number: 91 of 100 files exhibit at least one of the six smells. Only nine were clean.

The paper, "Configuration Smells in AGENTS.md Files: Common Mistakes in Configuring Coding Agents" (arXiv:2606.15828), revised July 30, builds the catalog from a grey literature review of 14 practitioner articles (six published by companies including Anthropic and GitHub) plus a manual pass over 383 pull requests touching agent config files. The authors then proposed automated detection heuristics and ran them across the top-100 most-starred repos with an AGENTS.md or CLAUDE.md in the root, catching 207 smell instances.

The six smells, ranked by prevalence#

Lint Leakage was the most common smell, and the most damning example is a validation in the wild: the AGENTS.md in google/adk-python carried a full Python Style Guide (2-space indentation, 80-char line limit, naming conventions, docstring requirements). After the study's January 2026 dataset snapshot, the maintainers moved that section into a separate skill file. Rules like "use snake_case" are deterministic work that Biome, ESLint, or Ruff already do for free; repeating them in the agent file burns context and competes with architecture-level instructions for the model's attention.

Context Bloat used a 200-line threshold, the same number Anthropic recommends for CLAUDE.md files. The smallest bloated file was 216 lines; the largest, the javascript-obfuscator project's CLAUDE.md, ran 1,477 lines across 27 sections. One reviewed pull request explicitly reduced a config file from 598 to 149 lines because "modern LLMs tend to perform better with configuration files containing approximately 150 to 200 lines."

Skill Leakage shows the tension with the skills ecosystem: instructions for rare tasks (one example: quickemu's "Adding a new OS to quickget" checklist) sit in the always-loaded file instead of in skill files loaded on demand. The authors classified the leaked content: testing guidance led (10 cases), followed by workflow rules (8), scaffolding (4), infrastructure (4), and architecture (3).

Conflicting Instructions had the lowest detection precision (57%), which makes sense: contradictions require reading intent, not structure. The paper's example from inkline demands components in both packages/ui/components and packages/components. Both can be followed; neither can be satisfied at once.

Init Fossilization is the /init trap: the file is generated once and never touched. The heuristic was brutal and simple (a single commit), and the check that these repos were simply dormant failed: no fossilized project had zero commits after file creation, and two had more than 1,500.

Blind References point at documents without explaining why or when to read them. The paper quotes practitioner guidance directly: if you just mention the path, "Claude will often ignore it. You have to pitch the agent on why and when to read the file."

The smells compound#

The co-occurrence analysis (Apriori association rules over the 91 smelly files) found the interesting pattern: bad configs get worse together. Conflicting Instructions plus Skill Leakage predicts Context Bloat with 83% confidence (lift 1.81). Skill Leakage predicts Lint Leakage at 76%. Context Bloat and Lint Leakage co-occurred in 12 files. Long files are not just long; they tend to be internally inconsistent and full of tool-checkable style rules.

What this means for how we write agent configs#

This study is the natural companion to the earlier ablation showing context-injection strategy does not move coding agent correctness: that result says what the file contains may not matter much for pass rates, while this one says what it contains is often actively wasteful. Both readings point the same direction, towards leaner files. The practical checklist that falls out of the paper:

• Delete every rule a linter or formatter enforces. The pre-commit hook is the enforcement; the agent file does not need to be.
• Keep files under 200 lines, and treat growth as debt. Split rare-task instructions into skill files (see how we cover skills-based routing in why skills beat prompts and the governance side in agent skills package manager).
• Review the file on a schedule, not just when the agent fails. Init Fossilization is the default state of /init output, which connects to why config files are now a supply-chain surface worth taking seriously (agent config files are executable supply chain).
• Annotate every referenced doc with one line on what it contains and when to read it.
• Diff old and new instructions against each other, since constraint decay tends to leave contradictory rules behind.

The study's own detection heuristics are open (replication package at doi:10.5281/zenodo.20600327), so a config-smell linter for AGENTS.md is now a buildable tool, not a research question. For teams running agents on shared repos, running that check on the file you already have is the cheapest agent-quality win available this week.

Continue Reading#

• AGENTS.md Files Don't Move Coding Agent Correctness: A 288-Run Ablation
• How to Write CLAUDE.md: The Complete Guide
• Agent Skills Package Manager: Governance for the Skill Economy
• Agent Context Reduction: Cutting Tokens Without Losing Behavior
• Why Skills Beat Prompts for Coding Agents

Sources#

• Configuration Smells in AGENTS.md Files (arXiv:2606.15828v5)
• Full text (arXiv HTML, v5, 30 Jul 2026)
• Replication package (Zenodo)