You join a project and open its AGENTS.md before your first task, the way your coding agent will. It starts well: what the project is, how to run the tests. Then it keeps going. Code style. Commit format. A section of lessons learned, each one a mistake someone corrected once. “Always validate input.” “Never edit generated files.” “Keep changes small.” Two hundred lines in, you notice you are skimming.
Your agent does not skim. It reads every line at the start of every session, and then it does what most of us do with a long list of rules: it follows most of them, most of the time.
Researchers have started to study these files. One study catalogued what 2,303 of them contain (opens in a new tab). Another, at ETH Zurich, found (opens in a new tab) that developer-written files raise an agent’s success rate only marginally while adding up to 19% to its cost, and advised that they “describe only minimal requirements”. We asked a different question: of the rules in these files, how many are enforced? To find out, we wrote a script to collect and analyse every agent instruction file in 1,866 of the most popular active projects on GitHub.
One in three popular GitHub projects now ships an instruction file for AI coding agents, and AGENTS.md is the common format. Half of the main files run past 100 lines. In a random sample classified rule by rule, three in five rules could be checked by a script, at least in part, yet fewer than one rule in twenty names the check. Most rules rely on the agent remembering.
The short version
- 627 of 1,866 projects (34%) ship at least one agent instruction file. In TypeScript projects it is 73%; in Perl, 4%.
- AGENTS.md is the common ground. 78% of those projects have one, against 52% with CLAUDE.md and 20% with GitHub Copilot’s instructions.
- Half the main files are longer than 100 lines (302 of 582). The median is 106 lines, about 850 words.
- Three in five rules could be checked by a script, at least in part (157 of 257 in a classified sample).
- Fewer than one rule in twenty names its check (16 of 431 across two classified samples, 3.7%).
- About 30 projects keep two separate rulebooks, an AGENTS.md and a CLAUDE.md with different content.
- Stale maps are rare. About 2% of files point at a path or script that no longer exists.
How we did it
We took the projects in the public GitHub Ranking (opens in a new tab) lists of the most-starred repositories, overall and for 24 languages, on 15 October 2026: 2,424 projects, of which 1,867 had commits this year and 1,866 could be read. For each one we listed every file at the latest commit and read its agent instruction files: AGENTS.md, CLAUDE.md, GEMINI.md, GitHub Copilot’s instructions, and Cursor and Windsurf rules.
A script measured what can be counted exactly: which files exist, how long they are, what their headings cover. Anything that needs judgement, such as whether a line is really a rule or whether a script could check it, was classified one rule at a time on random samples by a separate AI reviewer, independent of the script, and those are the figures we report. The method and its limits are at the end.
One project in three now writes for its agents
627 of the 1,866 projects (34%) have at least one agent instruction file.
AGENTS.md has become the shared format: 489 of the 627 projects (78%) have one, and 214 have nothing else. CLAUDE.md appears in 328, GitHub Copilot’s instructions in 123, Cursor rules in 28 and GEMINI.md in 27. Most projects with a CLAUDE.md also have an AGENTS.md, which matters later.
Adoption depends heavily on the language.
TypeScript leads at 73%, then Go (58%), Rust (52%) and Python (49%). At the other end are Elixir (19%), Haskell (15%) and Perl (4%). Our guess is that this follows where coding agents are used most, but the data cannot show why.
What the files cover
We grouped the headings of each main file by topic.
Three in five files give the commands to build and run, describe the structure of the code and set out its style; about half cover testing. Only about one in eight has a section on security, and one in sixteen on performance. The Agent READMEs study (opens in a new tab) also found both rarely covered, in a different sample: security in 14.8% of files and performance in 14.5%.
How long they are
The median main file is 106 lines and about 850 words, roughly 1,600 tokens by the usual rule of thumb of four characters to a token. The longest tenth run past 3,000 words. 302 of 582 files (52%) are longer than 100 lines, 87 are longer than 300, and the longest is 1,048 lines.
Length has a cost. In a study of 124 pull requests (opens in a new tab), an AGENTS.md cut the median time Codex took by about 29%, but the ETH Zurich study found that context files also make agents take more steps and spend more. Why 100 lines? OpenAI’s Codex team describes (opens in a new tab) giving the agent “a map, not a 1,000-page instruction manual”: an AGENTS.md of roughly 100 lines that points into the docs. Every line in the file competes with the line the agent needs for the task in front of it.
What the rules say
We took a random sample of 300 lines that read as rules and had a separate AI reviewer classify each one. 257 were real rules; the rest were fragments such as “migrations must:” or “Never”, or plain description.
No single topic dominates. Code style is the largest group (16%), followed closely by rules about how the agent should work and communicate (15%) and project-specific correctness, such as which API to call or how a value must be handled (13%). Rules about security, dependencies and generated files are each under 3% of the sample.
How many rules name their check
For each of those 257 rules we asked two questions: could a script, linter, test or CI job catch a violation, and does the rule say which one?
64 rules (25%) could be checked completely, and another 93 (36%) partly, so three in five could have a check behind them. Only 8 of those 157 name it. An earlier sample of 200 lines, classified in a separate review pass, gave the same picture: 8 of 174 rules named a check. Across both samples it is 16 of 431 rules, 3.7%.
The rest rely on the agent remembering. Some are easy to enforce and simply do not say how, like these three from the sample:
- “Don’t use empty destructuring patterns.” (one lint rule)
- “File names should be lower case with words separated by hyphens” (a short script)
- “Do not add
Co-Authored-By: Claudeor any Claude attribution to commit messages.” (a commit hook)
The best files show how cheap the fix is. Homebrew’s AGENTS.md is 72 lines. It opens with the one command to run before asking for input, lists the checks required before each commit, and several of its rules say what enforces them: “Never use T.must (enforced by Sorbet/ForbidTMust)”. Its commit-style rule explains that a GitHub Actions workflow rejects the wrong format. A rule written like that tells the agent what will happen if it forgets, and the check catches it if the agent forgets anyway.
Two rulebooks in one repository
209 projects keep both an AGENTS.md and a CLAUDE.md at the root. Most handle it well: in 157 of them one file simply points to the other, and five are identical copies. But about 30 keep two genuinely separate files, with different rules for different agents in the same codebase.
That is two maps of the same ground, and nothing keeps them in step. An agent reading one file follows rules the other agent never sees. If you need more than one file, make the second a one-line pointer to the first.
Rules in the folders, not just at the root
187 of the 627 projects (30%) keep instruction files in subfolders, a median of three per project and, in one case, 190. Rules for one part of the code live next to that code, and an agent working elsewhere never loads them. For large codebases it is probably the right shape: a short map at the root, and detail where the detail belongs.
Stale maps were rarer than we expected
We expected many files to point at folders that had moved. They mostly do not. After the AI reviewer checked every flagged path and script against the repository, 10 of 585 files (about 2%) named a path or script that does not exist. The paths that had gone stale were mostly folders that had moved, with the instruction file left behind.
That is good news, and it is also why a check is worth its few milliseconds. When a stale line does appear, the agent does not skip it. It follows it.
What the best files do
The strongest files share four habits.
- They are short and point elsewhere. Kubernetes keeps its AGENTS.md to 38 lines; systemd’s sends the agent to four documents for architecture, workflow, style and contributing.
- They give the commands first. Homebrew opens with the one command to run before asking for input.
- Their rules say what enforces them. “Enforced by
Sorbet/ForbidTMust”; a workflow that rejects the wrong commit format. - They earn each line. systemd’s file asks contributors to add an instruction only after seeing an agent get that particular thing wrong in practice.
Check your own file
You can run the same checks on your own instruction file in ten minutes:
- Count the lines. Over 100? Move detail into docs and leave a pointer.
- Check every path and command it names. Does each still exist?
- Read each rule and ask what would catch it being broken. If a script could, name the script at the end of the rule. If a test already pins it, point to the test. If nothing could, and a reviewer would not notice either, consider deleting it.
- If you keep more than one file, make the others one-line pointers.
In the companion repository (opens in a new tab) of my book, node guards/instructions-lint.ts does the first three on its own AGENTS.md in milliseconds, and you can copy it into your project’s commit gate.
Method and limits
Sample. The GitHub Ranking lists (top 100 by stars overall and in each of 24 languages) as of 15 October 2026: 2,424 projects. We kept the 1,867 with a commit in 2026; one could not be read, leaving 1,866. Popular projects are probably better maintained than most, so these figures likely flatter the average repository.
Files. We counted AGENTS.md, CLAUDE.md and GEMINI.md at the root in any letter case and in subfolders with exactly those names; .github/copilot-instructions.md; .cursorrules and files in .cursor/rules/; and .windsurfrules. For each project we chose one main file at the root (AGENTS.md first, then CLAUDE.md, Copilot’s file, GEMINI.md) and followed short pointer files to the instruction file they name. Three main files are links to files with other names and are left out of the length figures; a few short stubs that point to other documents are counted at their own length.
Rules. A script found lines with a directive word (must, never, always, avoid, should and similar) outside code blocks. About one in seven of those is a fragment or a description, so every rule-level figure comes from random samples classified one rule at a time by a separate AI reviewer (a large language model working from a labelling guide, independent of the script): 200 lines for whether a rule names its check, and 300 lines for topic, whether a script could check it, and whether the rule names that check. Each sample was labelled in a single pass, without a person checking every label, and whether a rule is “partly” checkable is a judgement call. The labels are in the download, so anyone can check them.
Headings. Topics were matched by whole words in headings outside code blocks, so the section shares are approximate.
Dead pointers. Paths count only when the file presents them as part of its map (for example a list item that starts with the path), are not ignored by git and do not exist at the latest commit. Scripts are npm run, pnpm run, make and just targets checked against the root manifest. Every flagged item was checked by the AI reviewer against the repository; most were false alarms, such as git submodules or commands meant for a subfolder, and are excluded.
Data. The scripts, the per-project results and the AI reviewer’s labels are published on the research page for this study.
Questions people ask
How long should an AGENTS.md be?
Short enough to read in full in a review. A budget of about 100 lines, following OpenAI’s advice to treat the file as a map into your docs, is a good start. The exact number matters less than having one and a check that counts.
Should I have both AGENTS.md and CLAUDE.md?
AGENTS.md is the format most projects share: 78% of the projects with an instruction file have one. If an agent needs its own file, make it a one-line pointer to AGENTS.md, as 140 of the projects we studied do, so there is only one set of rules to keep true.
What makes a rule in AGENTS.md checkable?
A rule is checkable when a command fails if the rule is broken: a linter, a test, a CI job or a script. Write that command at the end of the rule. If nothing can check it and a reviewer would not catch it either, the line is probably a wish, and the file is better without it.
