betaFeedback

WorksComputer Science

What Open-Source Projects Tell Their Coding Agents: A Census of AGENTS.md and CLAUDE.md

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.

Introduction

Human contributors learn a project’s norms through review: which commands to run, what a pull request must contain, when a change is done. Coding agents, which now work in open-source repositories at scale [35, 29], often start a task without that history, so projects write the norms down for them, mostly in two root files: AGENTS.md, an open format that calls itself a README for agents [1], and CLAUDE.md, which Claude Code reads [3]. Whether such files help agents is contested [22, 30], so it matters what projects put in them. Existing studies characterise them on repositories already tied to agent use [11] or screen broad samples under other definitions, with adoption estimates from 5% of mature repositories [Mohsenimofidi et al., 2026] to 21.7% of agent-using ones [15]. What popular projects write, statement by statement, where that text comes from and what it varies with is not known.

We answer these questions with a census of 22,854 public GitHub repositories returned by GitHub’s search API in thirteen languages with at least 1,000 stars and recent activity, and treat each repository’s AGENTS.md and CLAUDE.md as one instruction set. We ask who has agent instructions (RQ1), what they contain (RQ2), how instructions are expressed (RQ3), where their content comes from (RQ4) and what it varies with (RQ5). Analysing the files together, down to individual statements, lets us examine both the requirements projects give their agents and the traces of generators, tools and shared text in those requirements. We combine this account with adoption and file-history measurements, prespecified hypothesis tests and exploratory associations with project characteristics. We release file-version pointers, annotations, taxonomies and aggregate results, without redistributing the corpus texts.

Related work

Agent instruction files. Chatlatanagulchai et al. [ [11] coded the files of AIDev repositories into a taxonomy of instruction types, and Chatlatanagulchai et al. [ [10] and Santos et al. [2026] studied CLAUDE.md files on their own. Mohsenimofidi et al. [2026] found context files in few mature repositories and identified several instruction styles; Galster et al. [ [18] catalogued the configuration mechanisms of current agents and observed a bottom-up convergence on AGENTS.md; Cardoen et al. [ [8] and Chakrabarti [ [9] followed files over time; dos Santos et al. [ [14] defined configuration smells; and Cursor rules have been studied separately [26] (Sun et al. 2026). We differ in population and unit: a census of popular, active repositories not selected for agent use, with each repository’s files analysed together at the level of statements.

Do instructions help? Controlled studies, mostly preprints, report mixed effects of instruction files on agents’ success and cost [22, 30, 27], and observational work links file features to merge rates [4]. Adherence varies little with layout [31]. Preprints report that negative constraints help, although random rules helped as much as curated ones [Zhang et al., 2026], and that rules naming concrete commands or paths carry most of the gains in agent skills [Wang et al., 2026]. We make no effect claims but measure, across a population, features this work names: prohibitions, concrete requirements, rationale and conditions.

Rule taxonomies. Taxonomies of agent rules classify topics and levels [7], polarity [Zhang et al., 2026], security rules [Yan, 2026] and values guidance [Treude et al., 2026]. Our codebook adds how statements instruct (binding force, conditions, rationale, addressee, actionability) and, for collaboration subjects, which concrete elements rules require.

AI contributions and attribution. Mining studies measure agent activity through commit trailers and pull requests and warn that the trace is incomplete and easily misread [Robbes et al., 2026a,b, Khosravani and Mockus, 2026, Yu et al., 2026]. Projects increasingly publish policies on AI contributions [20, 25, 12], and developers sometimes admit AI use in commits [Xiao et al., 2026, Tufano et al., 2026]. Agent instructions are where such policy is written for the agent itself.

Repository meta-files and LLM coding. Conventionally named files such as READMEs, contribution guidelines and codes of conduct are an established object of mining research [34, 16] (Tourani et al. 2017), including how templates spread and diverge [23]; prompts in code have been studied as artefacts too [33]. We follow this tradition in tracing where instruction text comes from. Language models used as annotators can beat crowd workers in accuracy and are more consistent than human coders [21], but on classification they often reach only fair agreement with humans [Ziems et al., 2024].

Data and methods

Population, census and collection

We enumerated public GitHub repositories that, on 2026-10-16, had at least 1,000 stars, had been pushed to within the preceding 90 days, were neither forks nor archived, and had one of thirteen primary languages: Python, JavaScript, TypeScript, Java, C#, C++, C, Go, Rust, PHP, Ruby, Kotlin or Swift. GitHub’s search API returned 22,854 such repositories. We checked every one of them for a root AGENTS.md or CLAUDE.md, exact case, on the default branch, and call a repository with one an adopter. The frame is defined by popularity and activity, rather than prior evidence of agent use.

We collected files, metadata, activity and file histories through GitHub’s GraphQL and REST APIs without cloning. Adopter files were read at the snapshot commit. A commit is AI-marked if its message or author e-mail carries a coding agent’s co-author trailer or signature. Such markers capture only part of AI-assisted work, because tools and projects differ in whether they add them.

The object of study is a repository’s instruction set: everything its root AGENTS.md and CLAUDE.md say, taken together, with symbolic links and thin imports resolved so that no text counts twice. Structural features use the joined text of each set (5,998 documents); content is coded per file (6,578 files that do not merely defer to the other) and pooled per repository.

Document structure and an existing taxonomy

We measured document size, Markdown structure, directive words, named tools and agents, and generator-associated signatures. For comparison with earlier work, we applied the 16 instruction types of Chatlatanagulchai et al. [ [11], calibrated against that study’s 324 human-labelled files and corrected for over-labelling [37], so that our population can be compared with theirs (Section A.7).

Statement extraction and annotation

Categories. We developed a codebook through model-assisted open coding of 350 documents sampled by language, star tier and file composition. We consolidated the proposed codes and checked for missing categories in two rounds on 80 unseen documents, followed by critique and revision. The resulting codebook has 10 dimensions and 48 values. A statement’s function distinguishes descriptions, references and rules, and whether a rule governs code, workflow, the agent or the instruction files.

Statements. We used Haiku to segment files into statements, each expressing one claim or instruction regardless of line boundaries. Each statement carries its verbatim spans, a self-contained restatement, a free-text subject and its elements: the parts it lists or requires. This gave 341,852 statements, 99.4% with spans found verbatim. A directive is a statement with binding force, from a mandatory rule to a permission; descriptions and plain references are not directives. We also developed a subject taxonomy and, for four collaboration subjects, element categories and their stance: required, prohibited or mentioned. The model-assisted procedure is in Section A.1.5.

Coding and estimation. We coded statements in context for subject and all codebook dimensions, using Haiku for the corpus and Sonnet for a stratified sample (1,198 files coded). The sample carries the headline estimates, because Sonnet and Opus agree closely (κ\kappa 0.76–0.89 by dimension) while Haiku agrees less with Sonnet (0.47–0.81; Cohen, [13]). For a code cc the share of repositories whose instruction set contains it is

p^c=∑r∈Swr1[c∈r]∑r∈Swr,wr=1πr,(1)\widehat{p}_c = \frac{\sum_{r \in S} w_r \mathbb{1}[c \in r]}{\sum_{r \in S} w_r}, \qquad w_r = \frac{1}{\pi_r}, \tag*{(1)}

over the 992 sample repositories SS whose files Sonnet coded completely, with πr\pi_r the repository’s inclusion probability (the sample was drawn by file), and intervals from a weighted cluster bootstrap over repositories. Mean shares per repository are computed in the same way. The element tables and the correlations use Haiku’s codes for all files, uncorrected; calibrated census estimates are in Section A.1.

Human review. A human reviewer (the author) coded 60 statements before seeing model annotations, then checked their boundaries, restatements, extracted elements and subjects. These came from a stratified draw from validation files with fully matching source spans. The reviewer accepted most sampled boundaries, restatements and extracted elements, but agreement on subject categories was limited. These checks do not validate every subsequent category or stance assignment; the procedure and detailed results are in Appendix § 10.§ 2.

Prespecified tests and exploratory associations

We related repository-level content, from raw Haiku codes, to project characteristics. Counts are modelled with negative binomial regression,

log⁡E[Yr]=log⁡mr+βTxr+γTzr,(2)\log\mathbb{E}[Y_r] = \log m_r + \beta^{\mathsf{T}} x_r + \gamma^{\mathsf{T}} z_r, \tag*{(2)}

where YrY_r counts statements of one kind in repository rr (rules, prohibitions, …), mrm_r is its reference total (statements or rules), xrx_r are the standardised predictors under test and zrz_r the controls: age, language and star tier, except when the latter two encode the predictor under test. Exploratory models instead include stars as a predictor and add project type. Continuous predictors are standardised after transformation. Indicators, such as whether an instruction set covers an area, use the logit with the log number of statements among the controls. Standard errors are heteroskedasticity-robust (HC1), and the false discovery rate is controlled by the Benjamini–Hochberg procedure [5] within each family.

We committed six hypotheses and their analysis plan before fitting the hypothesis-testing models, after inspecting descriptive results. The paired file comparison was informed by a pooled difference already seen. The tests use 5,587 repositories with at least 5 coded statements (11 tests). A hypothesis counts as supported only if all its tests have the predicted direction and an adjusted p<0.05p < 0.05. Exploratory analyses relate the content of 5,586 instruction sets to project type, language, stars, human authors, activity, age and the AI-marked share (99 tests), and compare adopters with 4,699 repositories without agent files, matched by star tier and language. We classified project type using Haiku on repository metadata alone. Specifications and sensitivity procedures are in Sections A.1.6 and A.1.7; deviations are in Section A.11.

Language models as instruments

We used Sonnet for initial code discovery and Opus for consolidation in Claude Code. Segmentation, coding and classification used Anthropic’s Claude Haiku 5.5, Sonnet 5.5 and Opus 5.5 through Amazon Bedrock in October 2026, with structured output constrained to the codes and the instruction to treat every file as data. Coding cost $13.83 for the existing-taxonomy comparison and $195.68 for statement extraction and annotation. Further settings are in Section A.1.8.

Results

RQ1: Who has agent instructions?

One in four popular, active repositories gives its coding agents written instructions, and adoption rises with popularity in every tier. Where both file names exist, CLAUDE.md usually points to AGENTS.md.

Of the 22,854 repositories, 6,006 (26.3%) have a root AGENTS.md, a root CLAUDE.md, or both. Adoption rises from 23.2% in the lowest star tier to 59.6% of the 89 repositories with the most stars (Figure 1A), and ranges by language from 40.8% of TypeScript to 13.0% of C repositories (Table 4). Counting the other instruction formats we listed, 29.1% have at least one; only 646 repositories use another format without a root file.

Figure 1. Adoption rises with popularity, and new adopters increasingly start with AGENTS.md. (A) Share of repositories with agent instructions by star tier (census of 22,854). (B) New adopters per month by their first surviving agent file; the dashed line marks Claude Code’s support for AGENTS.md (2026-09-18); the last bar is a partial month.

LanguageReposAGENTS.mdCLAUDE.mdEither
TypeScript4,04834.4%24.5%40.8%
Rust1,70628.1%18.9%32.7%
Go2,26424.5%16.6%28.9%
Swift47423.4%17.9%28.1%
Kotlin61121.1%14.9%26.0%
Java1,26220.9%12.4%24.6%
Python5,01519.5%14.9%24.3%
C#96418.2%12.0%23.5%
PHP80414.6%9.1%18.9%
JavaScript2,21113.0%10.1%17.5%
C++1,78514.7%7.7%17.4%
Ruby43815.1%8.9%17.1%
C1,27210.7%6.3%13.0%

Table 4. Repositories with each agent file, by primary language. Census of 22,854 repositories.

One instruction set, two file names. 2,566 adopters have only AGENTS.md, 1,052 only CLAUDE.md, and 2,388 both. Of those with both, most point one file at the other: CLAUDE.md defers to AGENTS.md through a link, an import or a pointer in 1,540 repositories, the reverse in 182, and only 598 keep two files with content of their own. New adopters have moved from starting with CLAUDE.md (73.7% from January to August 2025) to starting with AGENTS.md (Figure 1B; 17.1% CLAUDE.md-first since May 2026). Renames, which path history misses, explain 3.8% of the AGENTS.md-first cases (95% CI 2.6–5.3), too few to change the trend. This confirms at population scale the convergence that Galster et al. [ [19] found in cross-file references (Section A.5).

RQ2: What do agent instructions contain?

Almost every instruction set contains rules. Code conventions, building, agent workflow, documentation and testing each appear as rule subjects in most repositories. Collaboration rules name concrete requirements, from test plans to commit formats.

The median instruction set has 818 words (10th and 90th percentiles 163 and 3,010). 98.2% contain at least one rule (95% CI 97.3–98.9), and on average a repository’s statements are 52.6% rules, 29.8% descriptions and 17.6% references, such as commands and pointers (Sonnet’s codes, Eq. (1)). These are model-defined categories: human agreement is 82–83% for description versus rule (references excluded) and 43–50% for subject areas (Section A.2). The rules govern the code and its artefacts in 88.7% of repositories, the workflow in 85.4%, the agent’s own behaviour in 79.3%, and the instruction files themselves in 52.7%.

Figure 2 shows what the rules are about. Code conventions and quality (74.4%), build, environment and delivery (72.6%) and agent workflow and conduct (67.3%) lead, followed by documentation and testing. Project knowledge appears in 86.2% of instruction sets, while 54.3% contain a rule on that area. The most common specific rule subjects are verification before declaring work done (49.7%), test writing (48.2%) and the instruction files themselves (44.3%), each in under half of repositories and with overlapping intervals.

Figure 2. Rules most often concern code conventions, building and agent workflow. Share of repositories whose instruction set has at least one rule (blue, 95% bootstrap intervals) and any statement (grey) in each subject area. Sonnet’s codes on 992 sample repositories, reweighted to the population.

What the rules require. For four collaboration subjects, rules name concrete parts (Table 1; Haiku’s codes, uncorrected). Rules on pull-request descriptions most often require a test plan (27.2% of the files with such rules), the project’s template and linked issues; rules on commit messages require the Conventional Commits format (36.7%). Rules on test writing prohibit trivial tests (8.1%) and weakening tests to make them pass (4.9%), and code-review rules disagree on style (7.0% ask reviewers to check it, 7.7% not to nitpick it). AI attribution splits projects: 7.5% of the repositories with commit-message rules prohibit it (95% CI 6.3–8.9) and 59 require it, while for pull requests 5.8% require disclosure of AI use and 1.9% prohibit it, mostly in different repositories.

Category% requiring% prohibiting
Pull-request descriptions
test plan / verification evidence27.24.4
use and complete the PR template24.21.6
linked issues and related PRs23.31.3
title format (type, tag or scope prefix)19.31.7
summary of the change17.80.1
screenshots and visual evidence15.61.1
motivation and problem12.90.2
concision, length limits, excluded noise9.34.8
AI-use disclosure and attribution5.71.9
Commit messages
Category% requiring% prohibiting
Conventional Commits / structured header36.71.8
allowed commit types23.50.6
subject mood, case, punctuation15.11.3
scope prefix14.90.8
issue / PR reference11.41.7
subject length limit10.00.0
sign-off and human authorship5.91.9
AI / agent attribution3.57.4

Table 1. Selected elements of rules on pull-request descriptions and commit messages: share of the files with a rule on the subject that require or prohibit each element (Haiku, full corpus, uncorrected). All categories are in the appendix.

RQ3: How are agent instructions expressed?

Instruction sets speak to an unnamed agent in plain imperatives. Mandatory rules and prohibitions each appear in most instruction sets, but unmarked imperatives are more common. Most directives give no reason.

In Figure 3, 80.9% of instruction sets mark at least one rule as mandatory and 77.8% prohibit something, yet prohibitions are on average 15.8% of a repository’s directives, and unmarked imperatives are the most common form. 82.9% give a reason at least once, but 74.0% of directives carry none, and only 10.8% of repositories cite an incident or evidence. Rules are often tied to a moment in the workflow (54.7%) or state an exception (53.7%). Almost every directive addresses the agent generically; 8.6% of repositories name a specific agent somewhere, and 8.3% address human contributors. Vague directives appear in 40.5% of repositories but are only 3.5% of directives.

Figure 3. Most instruction sets contain marked rules, prohibitions and reasons somewhere, but each is a small share of their directives. Share of repositories with at least one directive of each kind (dots, 95% bootstrap intervals) and its mean share of a repository’s directives or statements (diamonds). Sonnet’s codes on the sample, reweighted.

RQ4: Where does the content come from?

One in three instruction sets shows a trace of a generator, a tool, another project or an AI-marked creation, and four in five are edited after creation.

Traces of origin. For each of the 5,998 instruction sets we combined the traces left in the text with the history of the files that carry it (Table 8 in the appendix). 19.4% carry a trace in the text itself. Of the 5,942 instruction sets with a file history of their own, 33.1% carry a trace in the text or were created in an AI-marked commit. These are traces of reuse or assistance, not a classification of whole files as human- or machine-written.

TraceReposShare
generator signature (claude /init line or variant, Codex /init headings)948 of 5,99815.8%
of which claude /init’s opening line, verbatim69211.5%
tool-inserted block (Next.js, Turborepo, Nx, Laravel Boost, beads)931.6%
paragraph shared verbatim with files of ≥2\ge2 other owners2053.4%
of which with no generator signature or tool block1041.7%
whole file near-duplicate of another owner’s file601.0%
any text trace1,166 of 5,99819.4%
text file created in an AI-marked commit1,054 of 5,94217.7%
AI-marked commit after creation2,163 of 5,94236.4%
any AI-marked commit2,475 of 5,94241.7%
changed after creation (more than one commit)4,860 of 5,94281.8%
CLAUDE.md converted into a bridge to AGENTS.md396 of 5,9986.6%
any text trace or AI-created1,967 of 5,94233.1%

Table 8. Traces of origin per instruction set. Shares of all instruction sets for text traces and of those with a file history for history traces. Traces identify signatures, shared text or marked commits; they do not establish authorship.

Generator signatures. 948 instruction sets (15.8%) match a signature associated with an /init command. Most common is the opening line of Claude /init, in 692 (11.5%); the heading set of Codex’s /init appears in 146. The share falls with popularity, from 17.1% of instruction sets in the lowest star tier to 9.4% in the highest. Detection is uneven across tools: claude /init leaves a verbatim line, Codex’s /init only a set of headings, and other tools no signature at all, so these shares mainly measure Claude Code’s generator.

Tools that write into agent files. 93 instruction sets (1.6%) contain a block that a framework or tool writes into the file itself. The Next.js development server inserts one in 44; it warns the model that the framework’s APIs may differ from its training data. Turborepo, Nx, Laravel Boost and the beads issue tracker write similar blocks.

Shared text across projects. 3.4% of instruction sets share a paragraph verbatim with the files of at least two other owners. About half of these also carry generator text or a tool block; the remaining 104 instruction sets (1.7%) share text without either signature, including a common set of behavioural guidelines for coding agents (32 instruction sets). Shared text may come from another project or a common source. Whole-file similarity is less frequent: 1.0% of instruction sets are near-duplicates of another owner’s file.

AI-marked creation. 17.7% of the instruction sets were created in an AI-marked commit, and 41.7% have at least one AI-marked commit. An AI-marked edit after creation appears in 36.4%. Counted by file, the creating commit is AI-marked for 13.5% of AGENTS.md and 22.7% of CLAUDE.md files, and 24.5% of the 106,279 commits that touched agent files are AI-marked. These markers do not establish which text the agent wrote, and they mostly capture one tool: among adopters with any AI-marked commit in their latest 100 commits, 88.0% have a Claude marker, and tools differ in whether they add a trailer by default.

Maintenance. 81.8% of instruction sets were edited after creation. Those with generator signatures were edited about as often as those without (82.4% versus 81.7%); neither share is adjusted for age. By file, 80.0% of AGENTS.md and 67.7% of CLAUDE.md files have more than one commit. By comparison, Mohsenimofidi et al. [2026] found that half of their AGENTS.md files had never changed.

RQ5: What does content vary with?

The prespecified tests associate popularity with pull-request and AI-policy rules, and compiled language with build instructions. Exploratory analyses link activity to process-oriented content and find LLM and agent projects over-represented among adopters.

Prespecified tests. Of the six hypotheses specified before fitting the association models (Table 2), three are supported: more-starred repositories more often have rules on pull requests or AI contribution policy (H6; OR 1.36 per standard deviation of log stars), compiled-language repositories more often state how to build and run the project (H3; OR 1.68), and CLAUDE.md is more descriptive than AGENTS.md in the same repository (H5). More merged pull requests go with more workflow rules and fewer descriptions, but more human authors go with slightly fewer workflow rules, so H2 is mixed. The AI-share (H1) and emphasis (H4) hypotheses are not supported, with small significant effects against the prediction (IRR 0.977 and OR 0.93). H3, H6 and the pull-request part of H2 hold on the Sonnet sample and when either of the two largest languages is left out. The paired file comparison was informed by earlier pooled differences; the percentage-point estimate and other post hoc checks are distinguished in Section A.11.

HypothesisVerdictEffect (95% CI)
H1 AI-marked share: more agent rules, permission/escalation rules and prohibitionsnot supportedIRR 0.977 (0.959–0.996), 0.992 (0.963–1.021), 0.981 (0.965–0.997)
H2 Collaboration: more workflow rules, fewer descriptionsmixed (2 of 4)merged PRs: workflow IRR 1.027 (1.009–1.046), descriptions 0.876 (0.858–0.894); human authors: workflow 0.975 (0.959–0.992, opposite), descriptions 0.993 (n.s.)
H3 Compiled languages: more build/run statementssupportedOR 1.68 (1.48–1.91)
H4 Emphasis: more rules on agent failure modesnot supportedOR 0.93 (0.88–0.99)
H5 CLAUDE.md more descriptive than AGENTS.md, same reposupported+6.3 pp (4.2–8.4); Wilcoxon pp = 1.3e-7
H6 Stars: more pull-request or AI-policy rulessupportedOR 1.36 (1.29–1.44)

Table 2. Prespecified hypotheses: verdicts and principal effects. Ratios are per standard deviation of continuous predictors; H3 compares compiled with other languages, and H5 is a paired percentage-point difference. Benjamini–Hochberg correction covers 11 tests. 5,587 repositories; H5 uses 484 pairs.

Exploratory associations. In the exploratory models, 49 of 99 tests pass the false-discovery correction (Table 13). Activity is associated with the largest number of tested content outcomes (Figure 4A): per standard deviation of log-transformed commits in the past year, the odds of covering version control (OR 1.50), documentation, agent tooling and agent workflow are higher, and those of covering project knowledge lower (0.77). Older repositories more often cover testing (OR 1.37 per standard deviation of age).

Figure 4. Activity goes with process- and agent-oriented content, and AI projects are over-represented among adopters. (A) Exploratory models: odds ratio of covering each area per standard deviation of log(1 + commits in the past year), with other predictors held fixed (blue: significant after Benjamini–Hochberg, grey: not; Haiku’s codes, 5,586 instruction sets). (B) Adopters against 4,699 matched repositories without agent files, by project type, within star tier and language; the square adds controls for age and activity and excludes agent-tooling projects. Project types are model-classified and indicative.

Table 13: Exploratory models: tests per predictor that pass Benjamini–Hochberg within the exploratory family (99 tests). Content models use 5,586 instruction sets; the adopter-versus-control row uses 5,286 adopters and 4,699 controls.

PredictorSignificant / tests
commits in 12 months11 / 13
age9 / 13
project type (joint)6 / 13
language (joint)6 / 13
human authors4 / 13
AI-marked share4 / 13
stars3 / 13
adopter vs control, by type6 / 8

Table 13.

Who adopts. We classified project type using Haiku on repository metadata. It agrees with Sonnet (κ\kappa 0.82) but much less with the human reviewer’s blind check (κ\kappa 0.43, 95% CI 0.23–0.63), so type contrasts are indicative; AI focus is more reliable (κ\kappa 0.80). Projects about LLMs, generative AI or agents are 27.9% of adopters against 13.3% of matched controls, an odds ratio of 2.76 within star tier and language (Figure 4B). In a post hoc check the association shrinks to 1.54 (95% CI 1.28–1.84) when age and activity are held fixed and agent-tooling projects are excluded, but remains positive. Libraries (OR 0.58) and documentation repositories (0.50) are under-represented among adopters. Project-type frequencies and matched comparisons are in Table 10 and Table 14.

Derived typeAdopters % (n=6,006n = 6{,}006)Controls % (n=5,920n = 5{,}920)
data / ML / AI (any AI focus)32.218.6
library / framework23.032.0
application22.322.3
CLI / developer tool10.713.2
infrastructure / DevOps8.06.0
docs / learning2.66.0
other or unclear1.21.7

Table 10. Project types of all adopters and all classified controls (model-classified by Claude Haiku 5.5 from repository metadata; indicative, see Section 4.5).

Table 14: Adopters and matched controls by project type (within star tier and language strata; controls reweighted to the adopters’ strata). Types are model-classified and indicative.

TypeAdopters %Controls %Odds ratio (95% CI)p (FDR)
data / ML / AI32.218.62.38 (2.15–2.64)< 0.001
LLMs / generative AI / agents (AI focus)27.913.32.76 (2.48–3.08)< 0.001
infrastructure8.66.61.38 (1.17–1.61)< 0.001
application21.921.91.00 (0.91–1.11)0.96
developer tool10.913.60.77 (0.68–0.87)< 0.001
library / framework23.033.30.58 (0.53–0.64)< 0.001
docs / learning2.34.50.50 (0.39–0.62)< 0.001

Table 14.

Threats to validity

Construct validity. We measure the presence and content of root AGENTS.md and CLAUDE.md files, not agent use or the instructions agents receive at run time. Nested agent files are excluded; other formats are counted only in RQ1. AI-marked commits capture only part of AI-assisted work, depend on whether a tool adds a trailer, and are depressed in projects that ban trailers. Project type is classified from self-written metadata and agrees only moderately with a human reading.

Measurement. Content categories were discovered and applied by language models. They are reproducible across models but diverge from the human reviewer’s reading, including on broad subject areas. The review covers 60 statements with fully matching source spans, from validation files; it excludes languages the reviewer could not read and stopped early. Its acceptance rates describe this sample, not corpus-wide accuracy. Topic and element-stance results are model-defined. Annotation error can bias their associations with project characteristics. Generator signatures and shared text are evidence of possible reuse or assistance, with unknown false-positive rates; AI-marked commits do not identify which text an agent wrote. The models analysed files of their vendor’s format; they may treat Claude-specific conventions differently from others, which we could not test directly.

Internal validity. History covers only files that survive at the snapshot, and path history does not follow renames; a rename check bounds the second effect. Claude Code began reading AGENTS.md four weeks before the snapshot, so recent shares may reflect that change. All correlations are cross-sectional, and activity counts may include commits made by agents.

External validity and inference. The population is popular, recently active repositories in thirteen languages on one snapshot date; stars can be gamed and differ by language [24, 6]. With almost six thousand repositories, small effects in the exploratory models become significant; the results are exploratory leads, controlled for false discoveries only within their family.

Discussion

Instructions as onboarding with expectations. Agent instructions read like a compact onboarding document: what the project is, which commands to run, and how to work. Verification before declaring work done, test writing, the instruction files themselves and code design are among the most common specific rule subjects, yet each appears in under half of repositories. Projects share broad concerns more than individual requirements. Project knowledge appears in 86.2% of instruction sets, with rules on that area in 54.3%. The files give an agent starting a task both project context and expectations for its work.

Concrete, but mostly unexplained. Rules on collaboration artefacts name specific requirements, such as a test plan, linked issues or a commit format; in agent skills, a preprint finds that concrete instructions of this kind carry most of the measured gains [Wang et al., 2026]. Yet most directives give no reason, few cite an incident, and marked obligations and prohibitions are a minority of directives. Whether reasons or emphasis change what agents do remains open.

Reused, assisted and maintained. A third of instruction sets carry a generator-associated signature, tool-inserted block, shared text or AI-marked creation commit. Frameworks even write into these files themselves. Four in five sets are edited after creation. Studies that compare developer-written with generated files [22] therefore face a practical complication: a file can combine tool-supplied text, reused guidelines and later project edits.

One instruction set. Most repositories with both file names link one to the other, usually with AGENTS.md as the substantive file and CLAUDE.md as a pointer. Counting each file as an independent observation would duplicate many repositories; resolving links and imports reveals what the agent is asked to read.

AI attribution has no shared norm. Projects that regulate AI attribution in commit messages more often prohibit it than require it, while rules on pull-request descriptions more often require disclosure, mostly in other projects. Trailer-based measures of AI use inherit this disagreement: projects with equal AI use can leave different traces if one prohibits attribution and the other permits it.

What content varies with. In exploratory models, activity is associated with more of the tested content outcomes than other project characteristics: active projects more often cover version control, documentation and how the agent should work. LLM and agent projects remain over-represented among adopters after age, activity and agent-tooling projects are accounted for. This fits early adoption by the community closest to the tools, but adoption may also shape how projects describe themselves. The cross-sectional data cannot establish the direction of these associations, and activity counts may themselves include agent commits.

A method lesson. The models agreed with one another much more closely than with the human reviewer. Agreement among models alone therefore offers limited assurance that their categories match a human interpretation. The difference is especially important for topics: even the broad subject areas had low human agreement, while agreement was higher for the distinction between descriptions and rules.

Future work. Whether repositories follow their own instructions, for example their AI-attribution rules, can be measured from their commits, and the exploratory associations need confirmatory tests on fresh data.

Conclusion

One in four repositories in our census of popular, active GitHub projects in thirteen languages has root instructions for coding agents. These files put project knowledge beside concrete expectations about code, testing and collaboration. They also expose unsettled norms: projects disagree about AI attribution, and most directives offer no explanation. Generator signatures, shared text and tool-inserted blocks reveal the role of reusable text, while file histories show that projects keep editing the instructions. Exploratory analyses associate activity with process-oriented content and find LLM and agent projects over-represented among adopters. The census and released annotations provide a basis for studying how this practice develops, and whether agents follow the expectations projects write down.

AI-use statement

We used Claude Haiku, Sonnet and Opus 5.5 for segmentation, annotation, project classification and taxonomy development (§ 3.3 and § 3.5). Claude Code assisted with analysis code and drafting; OpenAI Codex and GPT models assisted with revision and review. The author designed the study, made the analytic decisions, reviewed and updated the source code, edited the text, and is responsible for the content.

Data availability

We release, for every repository in the census, its identifier and adoption status, and for every analysed file its repository, path and the commit it was read at, so that the corpus can be reconstructed. We also release the statement-level annotations, taxonomies and aggregate outputs, without redistributing third-party file texts. The dataset is available on Hugging Face.

Method details and further tables

Method details

This section gives the full procedure behind § 3.

Estimators. The existing-taxonomy comparison corrects the share qq of files that the model labels with a type for the model’s sensitivity Se and specificity Sp on all 324 reference files, clipped to [0,1][0,1] [37]:

p^=q+Sp−1Se+Sp−1.(3)\hat{p} = \frac{q + \mathrm{Sp} - 1}{\mathrm{Se} + \mathrm{Sp} - 1}. \tag*{(3)}

For statement-level distributions in the full corpus, Haiku’s code distribution πH\pi_H is mapped to Sonnet’s with the confusion matrix Pjk=Pr⁡(Sonnet=k∣Haiku=j)P_{jk} = \Pr(\text{Sonnet} = k \mid\text{Haiku} = j) estimated on the overlap,

π^S=PTπH.(4)\hat{\pi}_S = P^{\mathsf{T}}\pi_H. \tag*{(4)}

For the presence of a code in a repository, with qq the share of repositories where Haiku finds it and p1p_1, p0p_0 the probabilities that Sonnet finds it given that Haiku does or does not, the calibrated share is p^=p1q+p0(1−q)\hat{p}=p_1q+p_0(1-q). Each calibration is used for a dimension only where it lowers the error on a held-out half of the overlap.

Population and census

The population is every public GitHub repository that, on the snapshot date of 2026-10-16, met four criteria:

  • at least 1,000 stars;

  • a push within the preceding 90 days (on or after 2026-07-18);

  • neither a fork nor archived;

  • one of thirteen primary languages as determined by GitHub Linguist: Python, JavaScript, TypeScript, Java, C#, C++, C, Go, Rust, PHP, Ruby, Kotlin or Swift.

We enumerated it with GitHub’s search API, splitting the star range until each query fell under the search result cap. This yielded 22,854 repositories. The frame is therefore what GitHub’s search index returns for these criteria. A push counts on any branch and includes pushes by bots.

Census. We checked every repository in the frame for an agent file: a file named exactly AGENTS.md or CLAUDE.md at the root of the default branch. We call a repository with one an adopter. This measures the presence of a file, not whether or how coding agents are used. Nested files, case variants and other formats are not agent files under this definition; we count the other formats separately below.

Studies of agent files have mostly drawn on repositories already associated with coding agents, such as the AIDev dataset [29, 11]. Others screened broad populations under different frames and file definitions [17, 8, 28]. Ours is a census of popular, active repositories that is not conditioned on agent use.

Collection. All data came through GitHub’s GraphQL and REST APIs; no repository was cloned. For adopters, files were read at the snapshot commit. Symbolic links were resolved to their target’s text, and the direction of each link was recorded. We also collected repository metadata and activity over the 365 days before the snapshot, including the human authors and AI-marked commits among the latest 100 commits on the default branch.

A commit is AI-marked if its message or author e-mail carries a co-author trailer or signature of a coding agent (Claude, Codex, Copilot, Cursor, Devin, Aider or Gemini). AI-marked commits are a lower bound on AI-assisted commits. A trailer exists only when a tool or person adds one, and a project can forbid them § 4.

How the two files relate. Each adopter receives one label from an ordered set of rules; the first match wins. The rules test, in order:

  1. whether only one file exists;

  2. whether one file is a symbolic link to the other, and in which direction;

  3. whether both files link to a third file;

  4. whether CLAUDE.md consists of @AGENTS.md imports or is a short pointer to AGENTS.md (at most 300 characters);

  5. whether it imports AGENTS.md and adds its own content;

  6. whether AGENTS.md defers to CLAUDE.md;

  7. whether the two files are identical copies.

Otherwise the files are separate, split by whether one mentions the other. Varying the character threshold from 100 to 2,000 leaves the ratio of deference between the two files unchanged. It does move the count of repositories with two files of their own content § 4.

History. For each of the 8,393 agent files with a resolvable history, we walked the commit history of its path on the default branch back from the snapshot commit. We recorded the first and last commits, the number of commits, and whether the creating commit was AI-marked. Two limits apply:

  • History covers only files that exist at the snapshot.

  • Path history does not follow renames. A file renamed from another name appears to start at the rename.

Trends over time are therefore trends among surviving files, and an AGENTS.md renamed from CLAUDE.md counts as AGENTS.md-first.

Other formats. For every repository in the population we listed the root and the directories .github/, .cursor/rules/ and .claude/, one level deep. This counts the other instruction formats of current coding agents, such as .github/copilot-instructions.md, GEMINI.md and Cursor rules. Adopters were listed at the snapshot commit; the other repositories were listed at their current HEAD a few hours later.

Units of analysis

The object of study is a repository’s instruction set: everything its root AGENTS.md and CLAUDE.md say, taken together. Symbolic links and thin imports are resolved to their target, so the same text is never counted twice. The two file names serve the same purpose, and we compare them only in one short subsection (Section 4.1). Each result states its unit.

Repositories for adoption and for the repository-level analyses of § 3.4.

Documents for structural features: the text of one instruction set, 5,998 in all. Two files with their own content are joined.

Files for the existing-taxonomy and statement annotations: every non-link file with text that does not merely defer to the other file (6,578 files). File codes are aggregated to the instruction set for repository-level results.

Statements for statement-level analysis: the semantic statements into which each file is segmented (§ 3.3).

Structure and wording

We computed deterministic features of each document from its Markdown structure: size, headings, lists, code blocks, links and tables. Wording features use prose only, with code removed. They count:

  • directive words: prohibitions such as never and do not, mandates such as must and always, and soft guidance such as should and prefer;

  • capitalised emphasis;

  • named tools and named agents;

  • the signatures of known generators such as claude /init.

Readability is the Flesch reading ease, and near-duplicate documents were found with MinHash.

We used model-assisted checks of detector matches in context and corrected or dropped three detectors. The counts are lexical, not a semantic classification.

The prior codebook

To compare our population with earlier work, we applied the 16 instruction types of Chatlatanagulchai et al. [ [11] to the 6,578 files. Each file is split into sections at its first- and second-level headings, and overlong sections are split further. We used Haiku 5.5 to label each section with the types it contains, and a file’s labels are the union of its sections’ labels.

We calibrated the prompt against the reference study’s own human labels: 324 files with stored text, split into fixed halves of 162. The prompt was revised on one half and is reported on the other. The model assigns more types than the human coders did, so we correct prevalence for its measured sensitivity and specificity with the Rogan–Gladen estimator [37].

Statements, subjects and elements

We used language models to discover categories and annotate the files, with human review of sampled statements. The reviewer coded these statements before seeing the model annotations. The results distinguish acceptance of extracted text from agreement with the models’ interpretation.

Discovering the categories.

  • Open coding. We used Sonnet in Claude Code to generate preliminary codes in 14 batches covering 350 documents. The documents were stratified by language, star tier and file composition, with purposive outliers added. Each batch returned supporting quotations with line numbers.

  • Building the codebook. We used Opus to consolidate the proposed codes, then tested for missing categories in two rounds on 80 unseen documents. We revised the codebook, used a further model critique to look for inconsistencies, and fixed the version used for annotation.

  • Result. The codebook has 10 dimensions and 48 values.

The central dimension is the function of a statement (14 values). For reporting, each function maps to one answer of two coarse questions: what is it? (a description, a reference or a rule) and, for rules, what does it govern? (the code and its artefacts, the workflow, the agent’s own behaviour, or the instruction files). The full codebook is released with the dataset.

Statements. We used Haiku to segment each file into statements: units of meaning that a careful reader would sum up as one claim or instruction. A lead-in stays with its list, and independent rules under one heading are separated. Statements are cut by meaning, never by lines or punctuation. For each statement the model returned:

  • its verbatim spans;

  • a self-contained restatement;

  • a free-text subject;

  • its elements: the parts it lists or requires, such as the items a pull-request description must contain.

This gave 341,852 statements in 6,577 files. In 99.4% of them the spans were found verbatim in the source; this checks that spans are copied text, not that the segmentation is right.

Subjects. We used Opus to propose a two-level subject taxonomy from 2,500 random statements. We checked its coverage by assigning 1,500 fresh statements using Haiku, and 0.6% fell into other. The taxonomy has 57 subjects in 10 areas. It was used as proposed, without a revision round.

Coding. Each statement was coded on the codebook’s dimensions and its subject, in context: each request held consecutive statements with their spans and restatements, plus the surrounding text.

  • Corpus annotation. We used Haiku to code the corpus.

  • Sample annotation. We used Sonnet on a sample of 1,200 files, stratified by file name, star tier and language (1,198 coded, 61,772 statements).

  • Reliability was measured on 43 validation files (2,151 statements) coded by all three models. Opus and Sonnet agree at Cohen’s κ\kappa 0.76–0.89 by dimension [13]. Haiku agrees with Sonnet at κ\kappa 0.47–0.81.

  • Intervals. Statement-level distributions use 1,000 cluster-bootstrap resamples over files. Headline repository-level estimates instead use inverse-inclusion weights and a bootstrap over repositories, as in Eq. (1).

  • Corpus-wide distributions use Haiku’s codes, corrected toward Sonnet’s with the confusion matrix P(Sonnet code∣Haiku code)P(\text{Sonnet code} \mid\text{Haiku code}).

    • The matrix was fitted on a seeded half of the overlap files and tested on the other half, for single-code dimensions.

  • The correction lowered the error on every such dimension, so it is used throughout, refitted on the whole overlap.

  • The corrected distributions are point estimates without intervals.

Haiku coded 339,810 statements. In 75 files the model left some statements out of its responses, and those statements are excluded.

Elements. For subjects whose rules name concrete parts, we built element taxonomies.

  • Subjects. We chose four: pull-request descriptions, commit messages, test writing and code review. Each was checked to be one that Haiku identifies with a precision of at least 0.8 against Sonnet on the sample overlap. Two other candidates fell below that threshold and were not analysed.

  • Categories. For each subject, we used Opus to propose categories from 1,500 sampled elements of its rule statements.

  • Assignment. We used Haiku to assign each element a category and its stance: required, prohibited, or only mentioned. Stance is judged per element, because one statement can require some parts and prohibit others.

  • Rules without elements. A rule statement without elements counts as one element, because list items are often segmented as separate statements.

Subject selection was checked against Sonnet; element categories and stances are model assignments.

The human-review procedure and agreement results are reported in Section A.2.

Prespecified hypothesis tests

After inspecting descriptive results, we committed the hypotheses, outcomes, predictors, models, multiple-testing correction and robustness checks before fitting the hypothesis-testing models (commit a08c5b7).

Sample. The unit is the repository. The sample has 5,587 adopters with at least 5 coded statements, excluding those whose default-branch head predates 2026-07-18.

Outcomes and predictors.

  • Outcomes are counts or indicators built from Haiku’s statement codes, uncorrected, per repository. Annotation error can bias these associations.

  • Predictors: the share of AI-marked commits among the latest 100 commits, human authors, merged pull requests, compiled language, rate of emphasis, and stars.

Models and tests.

  • Models. Counts use negative binomial regression with an offset; indicators use logistic regression.

  • Controls. Every model controls for language, star tier and repository age, except that language is dropped where compiled language is the predictor, and star tier where stars are the predictor. Models of indicators also control for the number of statements.

  • Inference. Tests are two-sided, with heteroskedasticity-robust (HC1) standard errors. Effects are incidence-rate or odds ratios per standard deviation of continuous predictors; the compiled-language indicator compares compiled with other languages. Skewed count predictors use log transformations before standardisation.

  • The paired hypothesis. One hypothesis compares AGENTS.md with CLAUDE.md within repositories that keep two files with real content. It uses 484 repositories whose two files each have at least 5 coded statements, and a Wilcoxon signed-rank test. It was prespecified as informed, because pooled differences between the two file names had already been seen.

  • Multiple testing. The Benjamini–Hochberg procedure [5] controls the false discovery rate at q=0.05q = 0.05 over the 11 prespecified tests.

  • Verdict. A hypothesis is supported if every one of its tests has the predicted direction and an adjusted p<0.05p < 0.05, and mixed if only some do.

  • Other analyses. Exploratory analyses form a separate family and are labelled as such. Checks added after the results were seen are labelled post hoc.

  • Robustness. We repeated the tests:

    • on the Sonnet sample with Sonnet’s codes;

    • with an alternative AI measure, namely AI-marked commits on the agent files themselves;

    • leaving out each of the two largest languages.

Exploratory associations with project characteristics

We planned the exploratory analyses before computing their results, specifying definitions, outcomes, models and the test family. These analyses search for associations rather than test directional hypotheses.

Content per instruction set. Statement codes are pooled over a repository’s coded files, counting identical copies once. For each code we report the share of repositories with at least one statement or rule with it, and the mean share of a repository’s statements. Headline estimates use Sonnet’s codes on the 992 sample repositories whose whole instruction set Sonnet coded, weighted by the inverse of their inclusion probability, because the sample was drawn by file. Intervals come from a weighted cluster bootstrap over repositories. Census estimates use Haiku’s codes, calibrated to Sonnet’s where that lowers the error on a held-out half of the sample.

Project type. We used Haiku 5.5 to classify adopters and matched controls from repository metadata alone (name, description, topics, primary language and homepage), never from its agent files, using a fixed codebook of software types and a separate AI focus. We repeated the classification with Sonnet 5.5 on a random sample, and the human reviewer checked a stratified sample before seeing model labels, with each repository’s README and latest release available (Section 4.5).

Models. The models and profiles use the 5,586 instruction sets with at least 5 statements and Haiku’s raw codes, as in the prespecified tests. Content outcomes (area presence, the mix of kinds, the share of marked and prohibited rules, and length) are regressed on project type, language, stars, human authors, commits in the past year, age and the AI-marked share, using the same regression families, with log statement count added for binary outcomes. Adopters are compared with the matched controls by project type within star tier and language strata. Benjamini–Hochberg controls the false discovery rate within the exploratory family of 99 tests. The models are repeated with active weeks added, and on the Sonnet sample (927 repositories) with Sonnet’s codes.

Language models as instruments

  • Category discovery. We used Sonnet in Claude Code for preliminary codes and Opus for consolidation, revision and critique.

  • Segmentation, coding and taxonomies. These ran through Amazon Bedrock in October 2026, with Anthropic’s Claude Haiku 5.5, Sonnet 5.5 and Opus 5.5.

  • Request settings. Requests used structured output constrained to the codebook’s codes, low reasoning effort for coding, and prompt caching.

  • Treatment of the corpus. Every prompt told the model to treat the files as data, not as instructions to follow.

  • Refusals. Some requests for offensive-security repositories were refused. Uncoded files and statements were excluded from the relevant estimates.

Human review and agreement with model annotations

Review procedure. The reviewer was the study’s author. The review covered three aspects.

  1. Design decisions. After reviewing model output, we replaced syntactic units with semantic statements, introduced the two coarse questions, and added subjects and elements.

  1. Spot checks of the models’ reading. Statements were drawn from the validation files, stratified by kind and subject area, and limited to statements whose spans were all verbatim. The reviewer coded 60 of the 100 drawn, then stopped because the work took longer than planned. The presentation order was random. Five statements in languages the reviewer could not read were skipped. For each statement the reviewer checked whether it was cut correctly and whether its restatement, elements and free-text subject were right.

  1. Coding before seeing model annotations. Before seeing the model’s reading, the reviewer answered the two coarse questions, ticked every function label that fitted, and coded binding force, polarity and subject. Answers were fixed before the model annotations were revealed. The reviewer changed answers afterwards for 7 statements, and only the frozen answers are scored.

Extraction and agreement. The reviewer accepted the boundaries of 92% of the 60 reviewed statements, the restatements and extracted elements of 93%, and the free-text subjects of 95% (Table 3). The blind reading agrees with the models on description versus rule in 82–83% of statements when references are excluded, but only at κ\kappa 0.33–0.40 on the three kinds and in 43–50% on the subject area and 32–37% on the subject. The reviewer rarely used reference: a command list with comments read as a rule, because in this genre one line often describes, refers and instructs at once. The models agree with each other far better than with this human reading, as in the comparison with the reference study’s coders (κ\kappa 0.67–0.80 between models against 0.46–0.52 with humans), a pattern noted for LLM annotation in other fields [21] (Ziems et al. 2024). These checks support extraction in the reviewed sample; subject categories and element-category and stance assignments remain model-defined.

CheckResult (n = 60)
Statement cut correctly55 (92%; Wilson 95% CI 82–96%); 5 “part missing”
Restatement faithful56 (93%; 87–94%); 4 “loses meaning”
Listed parts (elements) right56 (93%); 4 “some missing”
Free-text subject fits57 (95%)
Independent blind reading vs the modelsAgreement (n = 60)
Description vs rule (references left out)82–83% (Haiku 40/48, Sonnet 37/45, Opus 39/47)
Three kinds62–67% (κ\kappa 0.33–0.40)
Subject area (10)43–50% (26–30 of 60)
Subject (57)32–37% (19–22 of 60)

Table 3. Human review of 60 statements. Top: checks of extracted statements. Bottom: agreement of the blind reading with Haiku, Sonnet and Opus (ranges across models).

Scope of the checks. A single coder gives no measure of agreement between humans. Wilson intervals in Table 3 are descriptive summaries of these checks, without adjustment for stratification or clustering by source file. Acceptance of extracted text does not validate the later element-category or stance assignments. The three-way kind, functions, binding force and subjects remain model-defined categories.

Adoption by language

Other formats

FormatReposShareAlso has /AGENTS.md
/AGENTS.md4,95421.7%—
/CLAUDE.md3,44015.1%69.4%
.github/copilot-instructions.md1,0244.5%52.3%
.cursor/rules/ (≥ 1 .md/.mdc)3471.5%64.6%
.github/instructions/2731.2%59.0%
/GEMINI.md1790.8%83.2%
.claude/CLAUDE.md1500.7%56.7%
/.cursorrules940.4%66.0%
case variant (e.g. agents.md) at root470.2%8.5%
/.windsurfrules200.1%95.0%
any of the above6,65229.1%

Table 5. Agent instruction formats in the 22,854 repositories, listed one level deep. The last column is the share of repositories with the format that also have a root AGENTS.md.

The two file names

Relations. Table 6 gives the relation of the two files in every repository with an agent file. When one file defers to the other, CLAUDE.md defers to AGENTS.md in 1,540 repositories and the reverse holds in 182.

RelationshipReposShare
AGENTS.md only2,54942.4%
AGENTS.md only (symlink to another file)170.3%
CLAUDE.md only1,04017.3%
CLAUDE.md only (symlink to another file)120.2%
both: CLAUDE.md is a symlink to AGENTS.md62910.5%
both: AGENTS.md is a symlink to CLAUDE.md1552.6%
both: symlinks to the same other file280.5%
both: CLAUDE.md is thin @AGENTS.md import (≤ 300 chars)77112.8%
both: CLAUDE.md imports @AGENTS.md and adds its own content1011.7%
both: CLAUDE.md is a short pointer to AGENTS.md1402.3%
both: AGENTS.md only imports or points to CLAUDE.md270.4%
both: identical copies400.7%
both: separate files, CLAUDE.md mentions AGENTS.md1712.8%
both: separate files, AGENTS.md mentions CLAUDE.md641.1%
both: separate files2624.4%

Table 6. How the two files relate in the 6,006 repositories with an agent file. The rules are applied in order (§ 3.1).

  • Symbolic links point from CLAUDE.md to AGENTS.md in 629 repositories, against 155 the other way.

  • 872 use an @AGENTS.md import.

  • The ratio of deference stays near eight to one at every thin-import threshold from 100 to 2,000 characters. The number of repositories with two files of their own content ranges from 450 to 775 over the same thresholds.

Content moving between file names. In 396 repositories that started with CLAUDE.md, that file was later turned into a bridge to AGENTS.md; in 337 of them it had content of its own before. 66.9% of these conversions happened in the commit that created AGENTS.md, so the content typically moved to AGENTS.md as the bridge was made. Conversions are less often AI-marked (19.9%) than the other CLAUDE.md commits in the same repositories (26.2%).

Order and shift over time. In the 2,388 repositories with both files, the files arrived in the same commit in 41.8%, CLAUDE.md came first in 35.1%, and AGENTS.md came first in 22.8%. Table 7 gives the first file of new adopters by period.

PeriodNew adoptersFirst file AGENTS.mdFirst file CLAUDE.mdBoth at once
2025-01 – 2025-0853623.9%73.7%2.4%
2025-09 – 2025-1275954.2%36.8%9.1%
2026-01 – 2026-042,17848.3%35.9%15.8%
2026-05 – 2026-10-162,53260.0%17.1%22.9%

Table 7. New adopters by the date of their first surviving agent file, and which file came first.

  • Renames. Path history does not follow renames. In a random sample of 800 repositories whose first file is AGENTS.md, 3.8% (95% CI 2.6–5.3) had in fact started with CLAUDE.md. Even at the upper bound for the latest period, the CLAUDE.md-first share there would rise to at most 21%.

  • Claude Code’s support for AGENTS.md. Claude Code v2.1.277, released on 2026-09-18, began reading AGENTS.md when no CLAUDE.md is present [2 b]. In the 29 days before it, 60.8% of new adopters started with AGENTS.md; in the 29 days after, 68.6%. This fits the existing trend and does not show an effect of the release.

Origins per instruction set

Table 8 lists the traces behind Section 4.4. Text traces cover all 5,998 instruction sets; history traces cover the 5,942 whose text-carrying files have a history of their own. A generator signature is the opening line of claude /init (verbatim or with the agent’s name changed) or the heading set of Codex’s /init. A tool-inserted block is recognised by the delimiter that the tool writes. A shared paragraph has at least 80 characters and appears verbatim in the files of at least 3 owners; generator lines and licence text are not counted. Near-duplicates have a MinHash Jaccard similarity of at least 0.8.

The prior codebook: our population against the reference study

TypeOurs, rawOurs, correctedReferenceVerdict
AI Integration72.5%71% (59–92)22% (17–28)more common in ours
Documentation and References83.7%72% (62–85)29% (24–36)more common in ours
Development Process78.0%91% (82–100)68% (62–74)more common in ours
DevOps38.9%29% (23–36)17% (12–22)more common in ours
Security41.8%28% (22–33)17% (13–23)more common in ours
UI/UX24.3%20% (14–32)6% (4–10)more common in ours
Project Management17.4%20% (13–44)5% (3–9)more common in ours
Testing80.4%67% (51–75)83% (77–87)less common in ours
Build and Run78.5%49% (27–61)71% (64–76)less common in ours
System Overview65.1%48% (37–56)57% (50–63)similar (intervals overlap)
Architecture73.5%70% (63–75)71% (64–76)similar
Implementation Details74.3%69% (54–80)71% (64–76)similar
Configuration & Environment63.3%39% (25–50)43% (37–50)similar
Maintenance53.9%84% (55–100)51% (44–57)unclear (very wide interval)
Debugging31.0%17% (6–27)23% (18–29)similar
Performance32.3%15% (8–21)13% (9–18)similar

Table 9. Share of files with each instruction type of Chatlatanagulchai et al. [2026]: ours raw, ours corrected for over-labelling with the Rogan–Gladen estimator (95% intervals), and the reference study’s human coding of its AGENTS.md and CLAUDE.md files. The samples differ in frame and date, so a difference shows that the populations differ, not why.

Project types

Content and project characteristics

Kind% of repos with ≥ 1Mean share of statementsCensus (Haiku, corr.)
rule98.2 (97.3–98.9)52.6 (50.9–54.4)53.0
reference89.7 (87.8–91.6)17.6 (16.5–18.8)16.2
description88.6 (86.6–90.5)29.8 (28.3–31.3)30.7

Table 11. Kinds of statement per instruction set: Sonnet’s codes on 992 sample repositories, reweighted, with 95% bootstrap intervals; the last column is the corrected Haiku census.

Area% with a rule (95% CI)% with any statement
code conventions and quality74.4 (71.4–77.3)77.0
build, environment and delivery72.6 (69.4–75.7)87.6
agent workflow and conduct67.3 (64.0–70.3)68.5
documentation61.7 (58.4–65.1)77.3
testing60.2 (56.8–63.4)76.7
version control and collaboration58.0 (54.3–61.7)60.9
project knowledge54.3 (50.8–57.6)86.2
technical domains53.2 (49.6–56.8)61.6
agent tooling22.6 (19.3–26.0)29.1

Table 12. Subject areas: share of repositories with at least one rule (95% CI) and with any statement (the data of Figure 2).

Table 15: The human reviewer’s blind check of Haiku’s project types on 29 repositories.

FieldPI agrees with HaikuWilson 95% CICohen’s κ\kappa (95% CI)
AI focus27 / 29 (93.1%)78–98%0.80 (0.44–1.00)
type16 / 29 (55.2%)38–72%0.43 (0.23–0.63)
derived seven-way type17 / 29 (58.6%)41–74%0.50 (0.30–0.70)

Table 15.

Table 16: Repositories with agent instructions by star tier (the data of Figure 1A).

StarsReposAGENTS.mdCLAUDE.mdEither
100k+8952.8%31.5%59.6%
10k–100k3,05932.3%21.5%37.0%
5k–10k3,08726.1%17.9%31.2%
1k–5k16,61918.7%13.2%23.2%

Table 16.

Element taxonomies

All element categories for the four collaboration subjects, with Haiku’s codes on the full corpus (uncorrected; stance judged per element). Definitions and examples are released with the data.

Category% requiring% prohibiting
Test plan / verification evidence27.24.4
Use and complete the PR template24.21.6
Linked issue and related PR references23.31.3
Title format / type, tag or scope prefix19.31.7
Summary of the change and its behavior effect17.80.1
Screenshots, recordings and visual evidence15.61.1
Motivation, problem statement and root cause12.90.2
Concision, length limits and excluded noise9.34.8
Breaking changes, compatibility and migration impact8.60.4
Structure, formatting and language8.63.0
PR creation workflow and agent authorship permission8.53.5
Other7.71.4
Design decisions, trade-offs and reviewer guidance7.40.2
Title wording, length and style6.51.1
General description quality6.20.4
Labels, branch target and PR metadata5.80.4
AI-use disclosure and agent attribution5.71.9
Risks, limitations, unverified items and follow-ups5.40.3
PR scope and size5.11.0
Accuracy and kept in sync with the final diff4.71.0
Release notes, changelog and changeset entries3.50.3

Table 17. Pull-request descriptions: share of the 1,345 files with a rule on the subject that require or prohibit each element.

Category% requiring% prohibiting
Conventional Commits / structured header format36.71.8
Allowed commit types and when to use each23.50.6
Subject mood, case and punctuation15.11.3
Scope / component / area prefix14.90.8
Body presence, layout and wrapping12.61.2
Rationale and change description in the message12.62.0
Issue, ticket or PR reference11.41.7
Subject / header length limit10.00.0
Follow project conventions, tooling and PR-title alignment6.60.2
General clarity and quality6.50.5
One logical change per commit6.30.1
Sign-off, signing and human authorship5.91.9
Message language5.00.1
Other3.61.2
AI / agent attribution3.57.4
Breaking-change marker3.20.3
Other trailers and control markers3.21.6
Inline markup and mentions1.60.5
Emoji / gitmoji prefixes1.30.6
Process noise and non-public content0.32.1

Table 18. Commit messages: share of the 1,739 files with a rule on the subject that require or prohibit each element.

Category% requiring% prohibiting
Tests must accompany changes (and exemptions)28.21.9
Frameworks, libraries, helpers and selectors19.52.2
Test structure, granularity and conventions17.42.4
Required scenarios, edge cases and error paths16.80.1
Choice of test type / level15.51.7
Regression test for bug fixes14.30.3
Fixtures, factories and test data13.12.5
Mocking and test doubles policy12.55.4
Assertion strength and precision12.42.7
Other12.12.8
Determinism, timing and portability10.74.3
Test file location and file naming10.40.7
Test naming, descriptions and comments10.31.7
Test isolation, shared state and cleanup9.12.0
Test observable behavior, not implementation8.74.6
Test-first / TDD workflow6.50.3
Snapshots and golden files4.71.5
General test quality4.60.3
Coverage metrics and thresholds4.30.5
Test worthiness / no trivial or tautological tests3.68.1
No skipping, weakening or deleting tests3.14.9

Table 19. Test writing: share of the 2,586 files with a rule on the subject that require or prohibit each element.

Category% requiring% prohibiting
Review process, reviewers, tools and gating22.22.7
Correctness, edge cases and error handling20.22.0
Context gathering and review method17.71.5
Project guidelines, checklists and repo-specific checks17.51.2
Evidence, verification and confidence of findings14.51.5
Review report format, verdict, tone and language14.51.0
Test coverage and test quality13.01.5
Handling received review feedback and threads13.02.0
Architecture, simplicity and maintainability12.52.2
Security and privacy12.22.0
Finding content: location, impact and suggested fix11.20.7
Severity levels and blocking vs optional11.01.7
Scope: diff-introduced issues, scope creep and PR splitting10.24.2
Backward compatibility and breaking changes9.50.7
Style, naming, formatting and readability7.07.7
Performance and efficiency6.00.5
General review quality / follow the review process5.70.5
Concurrency, resource leaks and lifecycle5.50.7
Documentation, changelog and release notes5.20.5
Agent permissions, posting and AI disclosure4.53.2
Other1.71.2

Table 20. Code review: share of the 401 files with a rule on the subject that require or prohibit each element.

Deviations from the analysis plan

  1. The planned mixed logistic model for the paired hypothesis was replaced by a GEE logistic model with repository clusters; the mixed model was unstable at this size.

  1. The exploratory set differs from the prespecified list. File length uses stars only. The composition analysis is a main effect rather than an interaction. The per-language subject profiles were not run.

  1. The paired test first included repositories whose two files are identical copies, and repositories excluded by the activity criterion. It was corrected to the prespecified population before reporting; no other test was affected.

  1. Post hoc checks, labelled as such, were added after the results were seen:

  • the AI-share hypothesis without the 141 repositories whose files prohibit AI attribution;

  • single-predictor models for the collaboration hypothesis;

  • the paired effect in percentage points, with a bootstrap interval.

References

  1. [1]AGENTS.md. AGENTS.md: A simple, open format for guiding coding agents, 2026. URL https://agents.md/. Accessed 2026-10-16.
  2. [2]Anthropic. Claude Code CHANGELOG, version 2.1.277: “Added AGENTS.md support”, 2026a. URL https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md. v2.1.277 published to npm 2026-09-18; accessed 2026-10-16.
  3. [3]Anthropic. How Claude remembers your project (Claude Code documentation), 2026b. URL https://code.claude.com/docs/en/memory. Accessed 2026-10-16.
  4. [4]Ali Arabat and Mohammed Sayagh. Toward Instructions-as-Code: Understanding the Impact of Instruction Files on Agentic Pull Requests. In Proceedings of the 23rd International Conference on Mining Software Repositories, MSR ’26, pages 969–973. ACM, April 2026. doi: 10.1145/3793302.3793601. URL http://dx.doi.org/10.1145/3793302.3793601.
  5. [5]Yoav Benjamini and Yosef Hochberg. Controlling the False Discovery Rate: A Practical and Powerful Approach to Multiple Testing. Journal of the Royal Statistical Society: Series B (Methodological), 57(1):289–300, 1995. doi: 10.1111/j.2517-6161.1995.tb02031.x.DOI
  6. [6]Hudson Borges, Andre Hora, and Marco Tulio Valente. Understanding the Factors That Impact the Popularity of GitHub Repositories. In 2016 IEEE International Conference on Software Maintenance and Evolution (ICSME), pages 334–344. IEEE, October 2016. doi: 10.1109/icsme.2016.31. URL http://dx.doi.org/10.1109/ICSME.2016.31.
  7. [7]Guangzong Cai, Ruiyin Li, Peng Liang, Zengyang Li, and Mojtaba Shahin. Rule Taxonomy and Evolution in AI IDEs: A Mining and Survey Study, 2026. URL https://arxiv.org/abs/2606.12231.
  8. [8]Guillaume Cardoen, Tom Mens, and Alexandre Decan. GHAgentFiles: A dataset of coding agent file histories in GitHub repositories. Author version, ORBi UMONS, 2026. URL https://orbi.umons.ac.be/bitstream/20.500.12907/56423/1/main.pdf.DOI
  9. [9]Kushal Chakrabarti. Why Does CLAUDE.md Keep Growing? Catastrophic Remembering in Agentic Coding, 2026. URL https://arxiv.org/abs/2608.11095.
  10. [10]Worawalan Chatlatanagulchai, Kundjanasith Thonglek, Brittany Reid, Yutaro Kashiwa, Pattara Leelaprute, Arnon Rungsawang, Bundit Manaskasem­sak, and Hajimu Iida. On the Use of Agentic Coding Manifestos: An Empirical Study of Claude Code, pages 543–551. Springer Nature Switzerland, November 2025. ISBN 9783032120892. doi: 10.1007/978-3-032-12089-2_40. URL http://dx.doi.org/10.1007/978-3-032-12089-2_40.
  11. [11]Worawalan Chatlatanagulchai, Hao Li, Yutaro Kashiwa, Brittany Reid, Kundjanasith Thonglek, Pattara Leelaprute, Arnon Rungsawang, Bundit Manaskasemsak, Bram Adams, Ahmed E. Hassan, and Hajimu Iida. Agent READMEs: An Empirical Study of Context Files for Agentic Coding. ACM Transactions on Software Engineering and Methodology, September 2026. ISSN 1557-7392. doi: 10.1145/3840295. URL http://dx.doi.org/10.1145/3840295.
  12. [12]Yunqi Chen, Thomas Zimmermann, and Bianca Trinkенreich. Making AI Visible, Not Vanished: How AI Policies Reshape Developer Experience on GitHub, 2026. URL https://arxiv.org/abs/2608.03329.
  13. [13]Jacob Cohen. A Coefficient of Agreement for Nominal Scales. Educational and Psychological Measurement, 20(1):37–46, 1960. doi: 10.1177/001316446002000104.DOI
  14. [14]Helio Victor F. dos Santos, Vitor Costa, Joao Eduardo Montandon, Luciana Lourdes Silva, and Marco Tulio Valente. Configuration Smells in AGENTS.md Files: Common Mistakes in Configuring Coding Agents, 2026. URL https://arxiv.org/abs/2606.15828.
  15. [15]Jessica Díaz, Jorge Pérez, and Sergio Gil-Borrás. Methodological Harness in Agentic Software Engineering: An Empirical Study on Mining Software Repositories, 2026. URL https://arxiv.org/abs/2609.32014.
  16. [16]Omar Elzhary, Margaret-Anne Storey, Neil Ernst, and Andy Zaidman. Do as I Do, Not as I Say: Do Contribution Guidelines Match the GitHub Contribution Process? In 2019 IEEE International Conference on Software Maintenance and Evolution (ICSME), pages 286–290. IEEE, September 2019. doi: 10.1109/icsme.2019.00043. URL http://dx.doi.org/10.1109/ICSME.2019.00043.
  17. [17]Matthias Galster, Seyedmoein Mohsenimofidi, Levi Böhme, Jai Lal Lulla, Muhammad Auwal Abubakar, Christoph Treude, and Sebastian Baltes. A Dataset of Agentic AI Coding Tool Configurations. In Proceedings of the 3rd ACM International Conference on AI-Powered Software, Aware ’26, pages 314–322. ACM, July 2026a. doi: 10.1145/3805760.3814922. URL http://dx.doi.org/10.1145/3805760.3814922.
  18. [18]Matthias Galster, Seyedmoein Mohsenimofidi, Jai Lal Lulla, Muhammad Auwal Abubakar, Christoph Treude, and Sebastian Baltes. Configuring Agentic AI Coding Tools: An Exploratory Study. In Proceedings of the 3rd ACM International Conference on AI-Powered Software, AIware ’26, pages 11–20. ACM, July 2026b. doi: 10.1145/3805760.3814887. URL http://dx.doi.org/10.1145/3805760.3814887.
  19. [19]Matthias Galster, Seyedmoein Mohsenimofidi, Jai Lal Lulla, Muhammad Auwal Abubakar, Christoph Treude, and Sebastian Baltes. Harness Engineering for Agentic AI Coding Tools: An Exploratory Study, 2026c. URL https://arxiv.org/abs/2602.14690.
  20. [20]Haoyu Gao, Peerachai Banyongrakкul, Hao Guan, Mansooreh Zahedi, and Christoph Treude. On Autopilot? An Empirical Study of Human-AI Teaming and Review Practices in Open Source, 2026. URL https://arxiv.org/abs/2601.13754.
  21. [21]Fabrizio Gilardi, Meysam Alizadeh, and Maël Kubli. ChatGPT Outperforms Crowd Workers for Text-Annotation Tasks. Proceedings of the National Academy of Sciences, 120(30):e2305016120, 2023. doi: 10.1073/pnas.2305016120.DOI
  22. [22]Thibaud Gloaguen, Niels Mündler-Sahзhara, Mark Niklas Müller, Veselin Raychev, and Martin Vechev. Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?, 2026. URL https://arxiv.org/abs/2602.11988.
  23. [23]Hideaki Hata, Raula Gaikovina Kula, Takashi Ishio, and Christoph Treude. Same File, Different Changes: The Potential of Meta-Maintenance on GitHub. In 2021 IEEE/ACM 43rd International Conference on Software Engineering (ICSE), pages 773–784. IEEE, May 2021. doi: 10.1109/icse43902.2021.00076. URL http://dx.doi.org/10.1109/ICSE43902.2021.00076.
  24. [24]Hao He, Haoqin Yang, Philipp Burckhardt, Alexandros Kapravelos, Bogdan Vasilescu, and Christian Kästner. Six Million (Suspected) Fake Stars on GitHub: A Growing Spiral of Popularity Contests, Spams, and Malware. In Proceedings of the 2026 IEEE/ACM 48th International Conference on Software Engineering, ICSE ’26, pages 1469–1481. ACM, April 2026. doi: 10.1145/3744916.3764531. URL http://dx.doi.org/10.1145/3744916.3764531.
  25. [25]Andre Hora and Romain Robbes. AI Policy, Disclosure, and Human in the Loop: How Are Contribution Guidelines Adapting to GenAI?, 2026. URL https://arxiv.org/abs/2605.16706.
  26. [26]Shaokang Jiang and Daye Nam. Beyond the Prompt: An Empirical Study of Cursor Rules. In Proceedings of the 23rd International Conference on Mining Software Repositories, MSR ’26, pages 397–409. ACM, April 2026. doi: 10.1145/3793302.3793367. URL http://dx.doi.org/10.1145/3793302.3793367.
  27. [27]Prakhar Khatri. Do Context Files Help Coding Agents? A Two-Agent Ablation Study on Real Repositories, 2026. URL https://arxiv.org/abs/2607.27250.
  28. [28]Arsham Khosravani and Audris Mockus. Detecting AI Coding Agents in Open Source: A Validated Multi-Method Census of 180 Million Repositories, 2026. URL https://arxiv.org/abs/2606.24429.
  29. [29]Hao Li, Haoxiang Zhang, and Ahmed E. Hassan. AIDev: Studying AI Coding Agents on GitHub. In Proceedings of the 23rd International Conference on Mining Software Repositories, MSR ’26, pages 1029–1033. ACM, April 2026. doi: 10.1145/3793302.3797249. URL http://dx.doi.org/10.1145/3793302.3797249.
  30. [30]Jai Lal Lulla, Seyedmoein Mohsenmonfidi, Matthias Galster, Jie M. Zhang, Sebastian Baltes, and Christoph Treude. On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents, 2026. URL https://arxiv.org/abs/2601.20404.
  31. [31]Damon McMillan. Instruction Adherence in Coding Agent Configuration Files: A Factorial Study of Four File-Structure Variables, 2026. URL https://arxiv.org/abs/2605.10039.
  32. [33]Kaiser Pister, Dhruba Jyoti Paul, Ishan Joshi, and Patrick Brophy. PromptSet: A Programmer’s Prompting Dataset. In Proceedings of the 1st International Workshop on Large Language Models for Code, LLM4Code ’24, pages 62–69. ACM, April 2024. doi: 10.1145/3643795.3648395. URL http://dx.doi.org/10.1145/3643795.3648395.
  33. [34]Gede Artha Azriadi Prana, Christoph Treude, Ferdian Thung, Thushari Atapattu, and David Lo. Categorizing the Content of GitHub README Files. Empirical Software Engineering, 24(3): 1296–1327, October 2018. ISSN 1573-7616. doi: 10.1007/s10664-018-9660-3. URL http://dx.doi.org/10.1007/s10664-018-9660-3.
  34. [35]Romain Robbes, Théo Matricon, Thomas Degueule, Andre Hora, and Stefano Zacchiroli. Agentic Much? Adoption of Coding Agents on GitHub. ACM Transactions on Software Engineering and Methodology, June 2026a. ISSN 1557-7392. doi: 10.1145/3822180. URL http://dx.doi.org/10.1145/3822180.
  35. [37]Walter J. Rogan and Beth Gladen. Estimating Prevalence from the Results of a Screening Test. American Journal of Epidemiology, 107(1):71–76, 1978. doi: 10.1093/oxfordjournals.aje.a112510.DOI

Paper details

vlnc:W_t8d3xm2a
Version
v1 · latest
Published
Fresh — added to the Hub within the last 30 days
Added
License
CC BY 4.0
Usage

views · 0

downloads · 0

A view counts once per browser per day, a download each time the PDF is requested.

  • Computer Science

Claude Haiku, Sonnet, Claude Opus 5.5 (bare), Claude Code, Codex, GPT (multiple versions)

View statement
Looking for related papers…
Contents