A new preprint offers the first quantitative evidence that committing AI configuration files to a repository is associated with lower defect costs after coding-agent adoption: among agent-adopting projects, those without committed configuration showed roughly twice the growth in code complexity and 1.7x the growth in static-analysis warnings. But it is a single-author, unreviewed, correlational study, so the answer to the title is “probably yes, and cheap enough to do anyway, but not proven.”
What the study actually measured
The paper, arXiv:2608.25241, appeared in feeds on 2026-09-15 as a revised second version (v1 on 2026-08-26, v2 on 2026-09-14) by a single author, Shyam Agarwal. Like all arXiv submissions, it is not peer-reviewed; arXiv presents submissions “as is,” with contents wholly the responsibility of the submitter. Everything below is author-reported evidence with no independent replication as of 2026-09-15.
The study covers 441 repositories that adopted coding agents, and it introduces RAMP (Repository AI Maturity Profile), a four-level cumulative maturity model for the version-controlled artifacts teams commit to configure AI tools. The levels run from behavioral rules and coding standards at the base, through named agent definitions, up to multi-agent orchestration at the top. Observed practice concentrates in the first three levels; almost nobody is orchestrating multiple agents from committed config yet. The authors report that the levels behave as a cumulative scale across the 441 repos, and that independent human annotation reproduces the repository-level labels on 97% of a held-out sample, which at least suggests the classification scheme is not arbitrary.
One thing to be precise about: RAMP measures committed AI configuration broadly, not AGENTS.md specifically. An AGENTS.md file is the most visible instance of the lowest RAMP levels, but the study’s treatment category includes any version-controlled agent configuration. Conflating the two would overstate what the evidence covers.
Velocity went up for everyone; quality diverged
The headline numbers split into two findings. First, agents accelerate development regardless of maturity: adopting repositories saw 28 to 38 percent more commits after adoption, whether or not they committed configuration. Speed, in this dataset, is not the differentiator.
Quality is. Among agent-first repositories, where the contrast is identified most cleanly, those without committed AI configuration showed roughly twice the increase in cognitive complexity after adoption (+53% versus +27%) and 1.7x the increase in static-analysis warnings. Both groups got more complex and accumulated more warnings; the committed-config group got worse more slowly.
The authors are unusually direct about what this does not establish: “Because maturity is observational, correlated engineering discipline or model capability may explain part of the gap; we present these findings as hypothesis-generating.” The selection story is plausible and hard to rule out. Teams disciplined enough to write, review, and commit agent instructions may simply be better engineering teams, with better review cultures and better tests, and the configuration file is a marker of that discipline rather than a cause of the quality difference. Nothing in the observational design separates the two.
The finding also sits in a live debate rather than settling one. Earlier work covered in Groundy’s reporting on agent adoption and long-term complexity found that agent adoption correlates with longer-term increases in code complexity and quality issues, with the causal mechanism still contested. The RAMP result does not contradict that; it suggests the damage may concentrate in repos that adopt agents without committing any configuration, which is a narrower and more actionable claim.
What AGENTS.md does mechanically
The format side of the question is on firmer ground. AGENTS.md describes itself as “a README for agents”: a dedicated, predictable place for the context and instructions that help coding agents work on a project. The site reports use by over 60,000 open-source projects (a self-reported figure from the format’s own site) and stewardship by the Agentic AI Foundation under the Linux Foundation, with the format emerging from efforts across OpenAI Codex, Amp, Google’s Jules, Cursor, and Factory.
The mechanics that matter for a committing decision:
- No required fields. It is standard Markdown. That lowers the cost of committing one and removes the schema excuse for not reviewing it.
- Nesting for monorepos. Nested AGENTS.md files are supported, and the closest file to the edited code wins conflicts. The main OpenAI repo reportedly has 88 AGENTS.md files.
- Chat prompts override everything. Explicit user instructions in a session take precedence over any committed file, which means committed config is a floor, not a ceiling.
- Test commands are executable intent. If testing commands are listed in AGENTS.md, coding agents will attempt to run those checks and fix failures before finishing a task. This is the mechanism most plausibly behind a quality effect: the file converts “the agent should test its work” from a hope into a default behavior.
That last point is worth dwelling on, because it suggests a mechanism for the correlation that does not depend on disciplined teams writing better prompts. A file that tells the agent to run the test suite and fix failures before finishing changes what the agent does on every session, for every contributor, without anyone remembering to ask. The alternative, per-session prompt hygiene, depends on each engineer’s memory and diligence. Earlier benchmark work on whether context files change agent behavior tested a related question under controlled conditions, holding the agent and model fixed while swapping the context file in and out; that line of evidence is complementary to RAMP’s observational approach.
What belongs in the committed file
The study cannot tell you what to write, but the format’s mechanics plus vendor guidance sketch a workable split. OpenAI’s practical guide to building agents recommends grounding instructions in existing documents (operating procedures, support scripts, policy docs), breaking tasks into smaller steps with one clear action per step, and capturing edge cases with conditional branches. That is vendor guidance from a company with commercial interest in agent adoption, but the practices translate directly into a committed config decision rubric:
| Layer | Belongs there | Why |
|---|---|---|
| Committed AGENTS.md (repo root) | Build/test commands, code style, testing instructions, project structure | Stable, applies to every contributor and session, enables auto-run checks |
| Nested AGENTS.md (per package) | Package-specific conventions, local build quirks | Closest file wins; keeps root file short |
Tool-specific config (.cursorrules, Claude Code settings, Codex TOML) | Tool capabilities, permissions, model choices | Not portable across agents |
| Session chat prompt | Task-specific goals, one-off constraints, overrides | Highest precedence; ephemeral by design |
The third row exists because the ecosystem is still fragmented. The community agency-agents repository compiles the same markdown agent definitions into tool-specific formats for over a dozen coding agents, including Claude Code, Cursor’s .mdc rules, Aider’s CONVENTIONS.md, Windsurf’s .windsurfrules, and Codex TOML. And VS Code’s agent documentation describes a parallel customization stack of custom agents, skills, hooks, and repository-scoped memory that persists across conversations. AGENTS.md is the closest thing to a portable common denominator, but it is not the only layer your tooling reads.
The staleness problem is the real finding
Buried in the preprint is the number that should shape your process more than the headline: 73.8% of committed AI configuration artifacts are committed once and never modified. Adoption is cumulative and forward-only, and in practice, set-and-forget.
This creates a contradiction the quality claim depends on ignoring. Configuration only helps an agent if it is accurate. A stale AGENTS.md that points at a deprecated test command, describes a directory layout from two refactors ago, or contradicts a newer nested file is worse than no file in at least some cases, because the agent will attempt to honor it. And the precedence rules mean a wrong instruction in the repo will be applied consistently, to everyone, until someone edits it. The auditability argument for committing config (it is version-controlled, diffable, reviewable) cuts both ways: a committed file is an auditable artifact, but the data says almost nobody is auditing it.
There is also a security dimension to treating these files as trusted. Groundy’s earlier threat model of malicious AGENTS.md files laid out how instruction files an agent reads autonomously become an attack surface, which is one more reason to route changes through normal code review rather than letting them drift.
What this study cannot settle
Be honest about the evidentiary ceiling:
- Causality. Engineering discipline and model capability are named confounders by the authors themselves. The gap could be partly or wholly selection.
- Replication. One preprint, one author, no peer review, no independent confirmation as of 2026-09-15.
- Specificity. RAMP measures committed configuration broadly; it does not isolate AGENTS.md, and it does not identify which contents (test commands versus style rules versus agent definitions) drive any effect.
- The maintenance benefit. The 73.8% never-modified figure means the review-and-audit upside is aspirational for most repos today, not observed practice.
The verdict
Commit the file. A minimal AGENTS.md with build and test commands, code style, and testing instructions is cheap, portable across most current tools, and plausibly protective on the best evidence available, which now includes a 441-repo quantitative study alongside vendor guidance and the format’s mechanical ability to make agents run your checks before finishing. Just do not present the defect-cost reduction as proven, because it is not; it is one correlational, unrefereed preprint whose own authors call it hypothesis-generating.
The operational change that follows matters more than the file itself: treat AGENTS.md like CI configuration. Changes go through PR review, someone owns it, and it gets audited for staleness on a schedule, because the same study that makes the case for committing config also shows that three quarters of committed config is never touched again. The file is the easy part. The process is where the reported quality benefit, if it is real, will actually live or die.
Frequently Asked Questions
What is the staleness rate for committed AI configuration files?
Buried in the preprint is the number that should shape your process more than the headline: 73.8% of committed AI configuration artifacts are committed once and never modified. Adoption is cumulative and forward-only, and in practice, set-and-forget.
How do nested AGENTS.md files resolve conflicts in monorepos?
Nesting for monorepos. Nested AGENTS.md files are supported, and the closest file to the edited code wins conflicts. The main OpenAI repo reportedly has 88 AGENTS.md files.
What is the precedence of chat prompts compared to committed files?
Chat prompts override everything. Explicit user instructions in a session take precedence over any committed file, which means committed config is a floor, not a ceiling.
