One in four popular GitHub repositories now carries agent instructions, and most of the rules come without reasons

The author checked 22,854 public GitHub repositories with at least 1,000 stars and a push in the previous 90 days, across thirteen languages, for a root AGENTS.md or CLAUDE.md. He found one in 6,006 of them (26.3%). Adoption rose from 23.2% in the lowest star tier to 59.6% of the 89 most-starred repositories. Where both files exist, CLAUDE.md usually defers to AGENTS.md: 1,540 point that way, 182 the reverse, and 598 keep two files with content of their own. The paper dates Claude Code's AGENTS.md support to September 18, 2026.

The content is practical. Across 341,852 annotated statements, the most common specific rule subjects were verification before declaring work done (49.7% of repositories), test writing (48.2%) and the instruction files themselves (44.3%). Rules often name concrete requirements, such as a test plan in pull-request descriptions (27.2% of files with such rules). Yet 74.0% of directives give no reason, and only 10.8% of repositories cite an incident or evidence. Projects also disagree on AI attribution: among repositories with commit-message rules, 7.5% prohibit it and 59 require it, while 5.8% of those with pull-request rules require disclosure of AI use.

Two other findings bear on how the files get made. About a third of instruction sets (33.1% of those with a file history) carry a generator signature, a tool-inserted block, text shared with other owners, or an AI-marked creation commit, and 81.8% were edited after creation. Generator signatures from /init commands appear in 948 sets (15.8%), 692 of them the opening line of claude /init.

The caveats are the author's own. The categories were assigned by Anthropic models and checked by one human reviewer on 60 statements; the models agreed with each other much more closely than with that reviewer, and human agreement on subject areas was 43 to 50%. The data is a single snapshot, so the associations are not causal, and the study does not test whether agents follow the files. The annotations and file pointers are released.

Why it matters: If you write an instruction file, this gives you a baseline of what peers include: verification and test rules are the common core, and most directives carry no stated reason. The paper makes no claim that reasons change agent behavior, so adding them is a judgment call, not an evidence-backed fix. It does show that a file is likely to be a living document, edited after creation in four of five cases, and that a CLAUDE.md alone no longer matches where new adopters start.