How to write AGENTS.md and CLAUDE.md: what 100 repos do

What AGENTS.md and CLAUDE.md are for

A coding agent starts every session knowing nothing about your project. The rules file is where you write down, once, what you would otherwise explain every time: build and test commands, code conventions, the directory layout, every “never do this”. This post is about how to write that file: which name to use, what to put in it, how long to keep it.

AGENTS.md does not belong to any one tool. It is an open format run by the Agentic AI Foundation, part of the Linux Foundation, and its own site says more than 60,000 open-source projects use it. It is plain Markdown with no required fields. CLAUDE.md is the file Claude Code reads at the start of every session. It is plain Markdown too, with a few features of its own: it can import other files (@path), and it can have layers for a user or an organisation.

We build a tool that reads these files every day: when diffox reviews a pull request, it reads the repository’s rules file too (how it works is in a separate post). The measurements below are a by-product of that work.

Which tool reads which file

We built the table below from each tool’s own documentation on 13 October 2026. It may change as new versions ship; each tool’s name links to its source.

Source: each tool’s own documentation, 13 October 2026. The Claude Code row holds for version 2.1.277 and later.

Two things stand out. First, all five tools can read AGENTS.md: Gemini CLI with a setting, Claude Code only when there is no CLAUDE.md next to it. Second, each tool handles subfolders differently: Codex combines everything from the root down, Copilot takes the nearest file, and Claude Code loads a subfolder’s file only once you open a file there.

On 18 June 2026, Google stopped serving Gemini CLI to free users and to Google AI Pro and Ultra subscribers and pointed them to Antigravity CLI; with a paid API key or a company licence you can keep using Gemini CLI. We read Antigravity’s rules documentation on 28 October 2026. It reads a file named AGENTS.md or GEMINI.md without any setting. It loads a subfolder’s file once the agent reads or edits a file in that folder. It combines the files it finds; when rules conflict, the subfolder’s rule wins. Each file is capped at 24 KB. CLAUDE.md is not among the files the documentation lists; if your rules are in AGENTS.md, Antigravity reads them too.

AGENTS.md is more common than CLAUDE.md

To see which file is more common, we picked the repositories by one rule: GitHub’s 100 most-starred repositories on 13 October 2026. Much of the list is not software anyone builds (resource lists, books, courses). We picked them without looking at whether they have a rules file, so we left the list as it is.

47 of the 100 repositories have at least one of the two files at the root. 42 have AGENTS.md and 24 have CLAUDE.md; 5 have CLAUDE.md alone. The other tools’ own files are rarer: Copilot’s file is in 11 repositories, Cursor’s rules folder in 4 and GEMINI.md in 3. The old .cursorrules file is still in 1; .windsurfrules and .clinerules are in none.

Count the files in subfolders and the other tools’ files too, and 55 repositories have at least one of them.

When both files are there, Claude Code reads only CLAUDE.md

This is what people most often get wrong. For a long time Claude Code did not read AGENTS.md at all, and many sources still say so. Since version 2.1.277 it does, on one condition: there must be no CLAUDE.md (or CLAUDE.local.md) in the working directory or any directory above it. If both are there, by default it reads only CLAUDE.md.

In practice, if there is a CLAUDE.md next to it, a rule you add to AGENTS.md never reaches Claude Code. Codex, on the other hand, reads only AGENTS.md by default. So you have to keep the two files in sync by hand.

A CLAUDE.local.md for your personal notes has the same effect: as long as it exists, Claude Code does not read AGENTS.md. To have Claude Code read both, set “Project instructions” in /config to claude-md-and-agents-md.

In 19 of the 100 repositories the two files sit side by side at the root. We went through them one by one to see how the two files are linked.

8 repositories link CLAUDE.md straight to AGENTS.md: 5 by writing @AGENTS.md in CLAUDE.md, 3 with a symbolic link. In n8n, AutoGPT, RustDesk and Clash Verge Rev, CLAUDE.md is a single line. In 2 repositories CLAUDE.md just mentions AGENTS.md in a sentence; according to Claude Code’s documentation, the agent sees that file only if it decides to open it. 3 repositories keep a copy of the same text in both files, and in 1 of them the copies no longer have the same number of rules. In the remaining 6, the two files hold different texts, so Claude Code and Codex read different instructions in the same project.

Two ways to point CLAUDE.md at AGENTS.md

The data points the same way: keep the rules in one file and point the other file at it. Put the rules in AGENTS.md, since more tools read it, and add this CLAUDE.md next to it:

@AGENTS.md

## Claude Code
Notes for Claude Code only go here.

The import line loads AGENTS.md as part of CLAUDE.md, and notes for Claude Code alone go below it. If you have no such notes, a symbolic link works too: ln -s AGENTS.md CLAUDE.md.

A symbolic link has two drawbacks. Someone who clones the repository on Windows may get a one-line text file instead of the link. And Claude Code refuses to write through the link and edits the real file instead. If anyone on your team uses Windows, the import line is the safer choice.

Keeping only AGENTS.md is now an option too, because current versions of Claude Code read it directly. Leaving the one-line CLAUDE.md in place for older versions does no harm: Claude Code does not load the same file twice.

What popular repositories put in the file

To see what goes in the file, we looked at the headings of the 47 files we read. If a file gave a topic a heading of its own, we counted it as covering that topic.

The most common topic is commit and pull request rules (29 files). Then come setup and run commands (26), code style (26), directory layout (21), tests (16) and security (7). Leaving headings aside, 36 of the 47 files include a command, in a code block or inline. This count only looks at the words in headings, so it is rough, but the order is clear: an agent first wants to know what to run and how, and how to submit a change.

Two good examples, from Kubernetes and AutoGPT

Both examples come from the files in this count. The Kubernetes AGENTS.md is 38 lines long. Every rule says what not to do and what to do instead; each command comes with a note on what it is for:

## Constraints

- **Generated files are read-only.** Never hand-edit `zz_generated.*` or `generated.pb.go`. Run `make update`.
- **go.mod/go.work are generated.** Use `hack/pin-dependency.sh` + `hack/update-vendor.sh`. Never `go mod tidy`.
…
## Commands

Run `make help` for all available targets. Common workflows:

```
make test WHAT=./pkg/kubelet GOFLAGS=-v     # Unit tests (one package)
make test-integration WHAT=./test/integration/scheduler
make verify                                 # All verification checks
make update                                 # ALL generators and formatters
```

AutoGPT’s AGENTS.md is 92 lines; it sets out the directory layout, each part’s test command and measurable pull request rules. Its CLAUDE.md is just the line @AGENTS.md: the setup we recommended above.

## Testing

- Backend: `poetry run test` (runs pytest with a docker based postgres + prisma).
- Frontend integration tests: `pnpm test:unit` (Vitest + RTL + MSW, primary testing approach).
…
## Pull requests

…
- Keep out-of-scope changes under 20% of the PR.

Both files are written in sentences that an agent and a person can both check: “never hand-edit generated files; run make update”, or “keep out-of-scope changes under 20% of the PR”. The quotes are from the commit the count read; “…” marks lines left out.

An AGENTS.md template to start from

A short AGENTS.md skeleton, built from the headings popular repositories use most and from the two examples above. It is only a sample; replace the commands and paths with your project’s own:

# Project name

## Commands
- Install: `pnpm install`
- Test one package: `pnpm test --filter api`
- Lint and format: `pnpm lint && pnpm format`

## Project structure
- `apps/web` - Next.js front end
- `packages/api` - API service

## Code style
- TypeScript strict mode. Never use `any`; use `unknown`.

## Testing
- Add or update the test that covers your change.

## Commits and pull requests
- Conventional commits: `feat(api): ...`
- Keep unrelated changes out of the pull request.

## Never
- Never hand-edit files under `generated/`. Run `pnpm generate`.
- Never commit secrets; read them from the environment.

If you use Claude Code, put the one-line CLAUDE.md beside it: @AGENTS.md. Every line in the template is a command or a rule that can be checked; saying what the project does is the README’s job.

How to write a good rule

The most useful test for what to put in the file comes from Claude Code’s documentation: an instruction should be concrete enough to verify. “Use 2-space indentation” instead of “format code properly”; “run npm test before committing” instead of “test your changes”. Here are six points that combine that test with what we learned writing our own file:

• Tell the agent what to do. A sentence that says “do this” or “never do that” can be checked; a description of the project cannot. 3 of the 47 files we read contain no such sentence at all; the median file has 10.
• Write the exact command. From “run the tests” the agent cannot tell which command you mean; write pnpm test --filter api and it runs that.
• Say why the rule is there. In our own file, every rule sits next to the failure that made us write it. A rule with no reason written down is deleted by the first person who finds it inconvenient.
• Leave out what your tools already enforce. Adding a rule the formatter or the linter already checks costs lines; the longer the file, the less closely its instructions are followed.
• Write each rule in one place. When the same rule lives in two files, one copy goes stale, and it is the one people read least.
• Add a rule when a mistake repeats, delete it once it no longer applies. Write the rule when the agent makes the same mistake a second time. In Claude Code, /doctor prompt-audit lists outdated and conflicting instructions.

The first of these points matters directly for diffox. When diffox reviews a pull request, it reads the rules file at the repository’s root: AGENTS.md first, CLAUDE.md if there is none. It follows a symbolic link and an @AGENTS.md line. It then passes the file’s “do this” and “never do that” sentences to the specialist agents as review rules. So a rule you can check is also a rule the review can use.

Most rules files are under 200 lines

Three tools give three different length limits in their documentation. Claude Code aims for under 200 lines per file, because a longer file uses more context and makes instructions less likely to be followed. Cursor recommends under 500 lines per rule. Codex stops adding files once the ones it has combined reach 32 KiB in total.

The 47 files we read have a median of 92 lines; the shortest has 4 and the longest 1,017. 14 run past 200 lines and 2 past 500. The number of files that go over Codex’s 32 KiB limit on their own is 1.

In a monorepo, a subfolder gets its own rules file

Large repositories do not keep all their rules in one file. Of the 98 repositories whose whole tree we could read, 27 also have an AGENTS.md or CLAUDE.md in a folder other than the root: 278 files in total.

A subfolder’s file covers the changes made in that folder: frontend rules live in the frontend folder, backend rules in the backend folder. The root file stays short, and the agent loads only the rules for the part of the code it is working on.

One of our own measurements, from September 2026, shows how often this matters: in 17 repositories with a rules file in a subfolder, 202 of the 417 most recently merged pull requests changed at least one file in such a folder.

One thing to watch: tools handle subfolders differently. If you cover the same topic in two different ways at two levels, which one applies depends on the tool. Do not leave sentences that contradict each other.