What 7,370 popular GitHub repositories put in AGENTS.md and CLAUDE.md

Coding agents start every session knowing nothing about the repository in front of them. An instruction file is how a project tells them what the code cannot: the commands that build and test it, the conventions reviewers enforce, the mistakes to avoid. Two names now dominate. AGENTS.md is an open format that OpenAI Codex, Cursor, GitHub Copilot's cloud agent and many other agents read. CLAUDE.md is the file Claude Code reads.

This study measures what projects actually write in them. On 27 September 2026 we read the instruction files of every public GitHub repository with 5,000 or more stars that is not a fork, is not archived, and was pushed to in the previous 90 days: 7,370 repositories. It is a census of that population, not a sample. The per-repository dataset (CC BY 4.0) and the scripts that produced it are free to download.

Who has an instruction file

33.4% of the 7,370 repositories have at least one instruction file for a coding agent, and AGENTS.md is the most common: 1,864 repositories (25.3%) have one at the root, against 1,415 (19.2%) with a CLAUDE.md. GitHub Copilot's instructions file follows at 6.0% and Cursor's rules at 2.4%.

The more popular the repository, the likelier the file. 21.9% of repositories with 5,000–9,999 stars have an AGENTS.md, rising to 41.8% of the 409 repositories with 50,000+. At that top band, 50.1% have an instruction file of some kind.

By primary language, among the 11 languages with at least 150 repositories in the census, TypeScript projects are the most likely to have an AGENTS.md (40.3%) and Shell projects the least (12.8%).

When a repository has both files

1,013 repositories have both an AGENTS.md and a CLAUDE.md: 54.3% of the repositories with an AGENTS.md, and 71.6% of those with a CLAUDE.md.

How the two files relate decides what Claude Code sees. Its documentation says that by default it reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it. When both exist, it reads CLAUDE.md, and gets the contents of AGENTS.md only if CLAUDE.md carries them.

In 74.1% of these repositories it does. 360 import AGENTS.md with an @AGENTS.md line, 367 join the two files with a symlink, and 24 keep a copy of AGENTS.md in CLAUDE.md.

In the other 262 (25.9%), CLAUDE.md is a separate file, and Claude Code by default does not load AGENTS.md at all. 72 of these are short files that tell Claude to read AGENTS.md, and 64 longer ones mention it; Claude Code's documentation notes that when a CLAUDE.md only tells Claude in words to read AGENTS.md, Claude sees it only if it decides to open the file. The remaining 126 never mention AGENTS.md.

Symlinks carry a cost the import does not. Claude Code's documentation warns that on Windows, Git checks a committed symlink out as a plain text file unless core.symlinks is enabled, which leaves that clone with a one-line file in place of the instructions. 36.2% of the repositories with both files depend on a symlink, against 35.5% that use the import.

How long the files are

The median AGENTS.md is 819 words and 105 lines long, and one in ten runs past 2,696 words. Codex's /init command, which writes an AGENTS.md for a repository, asks for 200 to 400 words. 13.4% of files fall in that range, and 41.0% run past 1,000.

Length has a hard edge in Codex. By default it reads 32 KiB of project instructions and truncates a file past that point. 67 AGENTS.md files (3.6%) are larger than that on their own, so Codex at its default settings never reads their end.

CLAUDE.md files are shorter: a median of 483 words and 71 lines, partly because 32.7% are under 100 words (an @AGENTS.md import on its own is one word). Claude Code's documentation suggests keeping each CLAUDE.md under 200 lines, because longer files take more context and are followed less reliably; 265 (18.7%) are 200 lines or longer.

What the files say

We sorted every heading below the title into topics, using rules published on the methodology page. The five most common topics in AGENTS.md files are testing, code style and conventions, project structure, Git and pull requests, and commands. They are the five sections Codex's /init template recommends: project structure, build and test commands, coding style, testing guidelines, and commit and pull request guidelines.

Commands are the part an agent can act on without interpretation. 73.5% of AGENTS.md files name a test, build or lint command in code formatting: 60.1% a test command, 50.3% a build command, and 52.3% a lint, format or type-check command.

Secrets are the gap. 39.3% of AGENTS.md files mention security, credentials or secrets somewhere, but only 10.6% state a rule against leaking them, such as never committing an API key or logging a token. In CLAUDE.md files the share is 4.5%. We checked the rule by hand on a random sample of 40 files it flagged, and 38 were genuine rules about secrets. It finds explicit prohibitions only, so more files touch on secrets than it counts.

Files written from a template

Some files show where they came from. Codex's /init prompt tells the model to title the document "Repository Guidelines", and 4.9% of AGENTS.md files carry exactly that title. 18.6% of CLAUDE.md files contain the sentence "This file provides guidance to Claude Code", a common opening we could not trace to a published template, so we report it only as text.

How the files change

The files are maintained, not written once. The median AGENTS.md has been changed in 5 commits, and 79.6% have more than one; for CLAUDE.md the figures are 3 commits and 68.6%. Symlinks are left out of these figures, because a link's history is the commit that created it.

Counting the quarter in which each file was first added, more repositories have added an AGENTS.md than a CLAUDE.md in every quarter since 2025 Q4.

The most-starred repositories with an AGENTS.md

For examples to read, these are the 12 most-starred repositories in the census with an AGENTS.md, with the size of each file and what the repository's CLAUDE.md does.

What this means for your repository

1. If you keep both files, join them. Put the shared instructions in AGENTS.md and add an @AGENTS.md line to CLAUDE.md, with anything that applies only to Claude Code below it. If CLAUDE.md would hold nothing else, you can delete it: from version 2.1.277, Claude Code reads AGENTS.md directly when there is no CLAUDE.md.
2. Prefer the import to a symlink if anyone clones on Windows. A symlink checked out without core.symlinks becomes a one-line text file.
3. A sentence is not an import. A CLAUDE.md that says "read AGENTS.md" leaves it to the model to open the file. The @AGENTS.md line loads it every session.
4. Check the length against the agents you use. Codex stops at 32 KiB by default, and Claude Code suggests under 200 lines per CLAUDE.md. Move detail that applies to one part of the code into an AGENTS.md in that directory.
5. Put commands in code formatting, exactly as they run. Agents act on them without interpretation.
6. Say what to do with secrets. Only 10.6% of files do. One line closes the gap: never commit, log or print credentials, and where they come from instead.
7. Name the file exactly AGENTS.md. 14 repositories use another case, such as agents.md. Codex looks for the exact name, so on a case-sensitive file system it would not find them.

For how to write the file itself, see our guide to AGENTS.md and CLAUDE.md for coding agents.

Methodology in brief

• Population. Every public GitHub repository with 5,000 or more stars that is not a fork, is not archived, and was pushed to between 29 June 2026 and 27 September 2026: 7,370 repositories, listed through GitHub's search API. All 7,370 could be read.
• Files. The root of each repository's default branch, read through GitHub's GraphQL API. AGENTS.md and CLAUDE.md are matched in any letter case, CLAUDE.md also in .claude/, and symlinks are followed to the file they point at.
• Classification. Pattern rules for topics, commands, security and secrets rules, and a comparison of links, imports and text for how CLAUDE.md relates to AGENTS.md. Every rule is published in full.
• History. Commits that touched each file on the default branch, up to 100 per file.

Limitations

• Popular, active, public repositories only. The census says nothing direct about private code or smaller projects, where habits may differ.
• Root files only. Nested AGENTS.md files in subdirectories, common in monorepos, are not counted.
• A file is not use. A repository can have an instruction file that no one's agent reads, and contributors can use agents without one.
• Rules are patterns. Topic, command and secrets classifications are pattern matches. They are published in full and were checked by hand on samples, but they will misread some files.
• Word counts split on spaces, which undercounts Chinese, Japanese and Korean. 69 AGENTS.md files are mostly such text; without them the median is 840 words rather than 819.
• Tool behaviour is as documented on 27 September 2026. Claude Code reads AGENTS.md directly from version 2.1.277, and a user can change its default so that it reads both files. Our classification describes the default.
• A snapshot. Repositories change daily; the figures describe 27 September 2026.

Cite this study

Cite the report by its title, Stride Research, 2026 and this URL. The dataset is licensed CC BY 4.0: credit "Stride Research, AGENTS.md and CLAUDE.md census 2026" with a link to this page.

Stride Research. (2026). What 7,370 popular GitHub repositories put in AGENTS.md and CLAUDE.md. Newlight Solutions. https://www.stride.page/research/agents-md-claude-md-study-2026