A few pages of markdown, and half the complexity growth↗ (external link)

Every repository I work in has a CLAUDE.md at the root. It accumulated the way these files do: a convention the agent kept getting wrong, a deployment gotcha that cost an afternoon, a rule about not doing the clever thing in one particular module. It is a few pages of markdown and I have never been able to say whether it earns its place.

This paper is the first attempt I have seen to measure that class of file. The authors build RAMP — a four-level maturity model scored purely from artifacts a team commits to configure its AI tools, running from behavioural rules and coding standards, through named agent definitions, to multi-agent orchestration — and apply it across 441 repositories. Independent human annotation reproduced the labels on 97% of a held-out sample, which is a better validation step than most instruments of this kind bother with.

Two descriptive findings before the interesting one.

Adoption is cumulative and forward-only: teams add levels, they do not swap between them. And it is set-and-forget — 73.8% of these artifacts are committed once and never modified again. That matches what I see in my own repositories and I do not think it is laziness. A rules file is written at the moment of maximum friction and then only revisited when something breaks loudly.

Now the number. Re-estimating an existing agent-adoption panel within each maturity stratum, agents accelerate development at every level — 28–38% more commits, regardless of configuration. Quality is where the strata separate. Among agent-first repositories, those without committed AI configuration show roughly twice the increase in cognitive complexity (+53% against +27%) and 1.7× the increase in static-analysis warnings.

I would like that to mean my markdown file is doing something. It might. But the authors are careful in a way that people citing this paper next month will not be, so let me be careful with them: maturity here is observational, not assigned. Nobody randomised anyone into writing a rules file. Teams that commit an architecture document are teams that were already going to argue about architecture, and they may well be on better models with more budget. The authors say this outright — correlated engineering discipline or model capability may explain part of the gap — and label the whole thing hypothesis-generating. The honest reading is that committed configuration is a marker of the kind of team whose complexity grows slower, and the causal share is unmeasured.

Which still leaves it the cheapest marker anyone has proposed. Cognitive complexity and static-analysis warnings are also not the outcome you care about; they are the outcome that survives being computed over 441 repositories, and that gap is where I would put the next study.

One thing I will change tomorrow, though, and it comes from the 73.8% rather than from the headline. A file written once at the moment of maximum friction and never touched again is a file describing a codebase that no longer exists. Mine has a deployment note in it that stopped being true in June. If this artifact is load-bearing enough to show up in a complexity metric, it is load-bearing enough to review — and the paper's most quietly damning finding is that almost nobody does.