What Open-Source Projects Tell Their Coding Agents: A Census of AGENTS.md and CLAUDE.md
On this page
arXiv:2610.31715v2 Announce Type: replace-cross Abstract: Coding agents can be guided with instruction files in a repository. We examine this emerging practice through a census of 22,854 popular, active GitHub repositories in thirteen languages, treating each repository’s root ‘AGENTS$.$md’ and ‘CLAUDE$.$md’ as one instruction set. Agent instructions appear in 26.3% of repositories and 59.6% of the most-starred; where both files exist, ‘CLAUDE$.$md’ usually points to ‘AGENTS$.$md’. We analyse 341,852 statements using model-assisted annotation and human review. The annotations reveal a practical mix of project knowledge and rules about code, building and workflow. Collaboration rules name concrete requirements, from test plans to commit formats, yet 74.0% of directives give no reason. Projects disagree on AI attribution: commit-message rules more often prohibit it than require it, while pull-request rules more often require disclosure. A third of instruction sets have a generator-associated signature, a tool-inserted block, shared text or an AI-marked creation commit; four in five are edited after creation. Prespecified tests associate repository popularity with rules on pull requests and AI contributions. Exploratory analyses link activity to process-oriented content and show that LLM and agent projects are over-represented among adopters. The models agree much more closely with each other than with the human reviewer’s topic assignments, a caution for automated annotation. We release the annotations, taxonomies and pointers to the analysed file versions.
Why It Matters
A census of 22,854 GitHub repositories shows that instruction files such as AGENTS.md and CLAUDE.md have become a widespread convention for steering coding agents—present in a quarter of repositories and most of the most-starred ones. The study maps what projects actually tell agents about code, builds, workflows, and AI attribution, and warns that automated annotation can diverge sharply from human judgment. It is direct evidence of how agent guidance is being standardized across the open-source ecosystem. See Agents, Tools, and Agent Frameworks, Open-Source and Open-Weight Models, Agents, Autonomy, and Tool Use, and The Generative and Agentic Era.
Sources
Back to Recent News · Sub-article index.