Best AGENTS.md examples in 2026

What each one does that the others do not

• 1. mui/material-ui

  JavaScript99k stars1,084 words24 headings23 commandsscore 100

  The most complete file in the corpus, and the one to copy first. Every command is written for the exact package manager and workspace filter the repo uses — `pnpm -F @mui/material build`, not `build the package` — so an agent never has to guess a workspace flag. It also does the thing most files forget: a pre-PR checklist and a PR title format, at the bottom, where an agent reaches for them last.

  Read AGENTS.md on GitHub Sections, commands and score

• 2. vllm-project/vllm

  Python88k stars754 words25 headings10 commandsscore 100

  Opens with a mandatory contribution policy before a single build command: check for duplicate work with `gh issue view`, no low-value busywork PRs, fail closed when unsure. Most AGENTS.md files tell an agent how to build. This one tells it when not to open the pull request at all, which is the rule a maintainer actually needs enforced.

  Read AGENTS.md on GitHub Sections, commands and score

• 3. caddyserver/caddy

  Go75k stars1,076 words17 headings5 commandsscore 99

  Notice what the test commands carry in their comments: `go test -race -short ./...` is labelled as matching CI, and so is the lint command. An agent that runs the documented command gets the same verdict the pipeline will give it, so it stops guessing at a green build.

  Read AGENTS.md on GitHub Sections, commands and score

• 4. rails/rails

  Ruby59k stars847 words22 headings9 commandsscore 100

  The clearest worked example of a convention with a right and a wrong shape: it shows `Object#with` for temporary config changes next to the manual set/restore pattern it replaces, labelled Correct and Avoid. Prose telling an agent to 'follow existing patterns' does nothing; two code blocks side by side do.

  Read AGENTS.md on GitHub Sections, commands and score

• 5. mozilla/pdf.js

  JavaScript54k stars914 words25 headings12 commandsscore 97

  The best architecture section here — the worker/main-thread split is explained before any instruction depends on it, so a rule about where code may live has a reason attached. Its one gap is measured and shown below: the corpus flags it for having no explicit prohibitions.

  Read AGENTS.md on GitHub Sections, commands and score

• 6. ethereum/go-ethereum

  Go51k stars436 words12 headings8 commandsscore 100

  The shortest file on this list and still a perfect score: a numbered six-step pre-commit checklist, commit message format, PR title format, nothing else. Proof that the quality score is not rewarding length — this is well under half the corpus median and beats almost everything.

  Read AGENTS.md on GitHub Sections, commands and score

• 7. duckdb/duckdb

  C++40k stars1,613 words42 headings7 commandsscore 96

  The one to study for navigation rather than rules. It spends whole sections on how to find a component and how to search the codebase, which is the work an agent does before it can follow any instruction. Long enough that the corpus flags the context cost — read it for the pattern, not the page count.

  Read AGENTS.md on GitHub Sections, commands and score

• 8. strapi/strapi

  TypeScript73k stars1,368 words27 headings40 commandsscore 96

  The monorepo reference. More distinct commands than any other file here, and they are separated by the situation that calls for them — unit tests marked as fastest and to be run first, then admin-panel tests, type checking, API integration, CLI, Playwright E2E. An agent picks the cheapest check that could fail.

  Read AGENTS.md on GitHub Sections, commands and score

• 9. elastic/elasticsearch

  Java78k stars2,046 words28 headings9 commandsscore 96

  Written for a codebase where the obvious command is wrong. It carries a debugging section for a specific Gradle error an agent will otherwise hit and misdiagnose, plus which Javadoc must be read before touching certain methods. Institutional knowledge, not a README rewrite.

  Read AGENTS.md on GitHub Sections, commands and score

• 10. n8n-io/n8n

  TypeScript199k stars2,383 words26 headings23 commandsscore 96

  The longest file on this list, from the highest-starred repository in the corpus, and worth seeing precisely because the length is a real trade. It ships a `pnpm agent:setup` command built for agents specifically, and a security section that survives contact with an agent trying to be helpful. The corpus still flags it for context cost.

  Read AGENTS.md on GitHub Sections, commands and score

Browse the rest at every indexed AGENTS.md, ranked by score, or narrow to your own stack from the stack index.

How long should an AGENTS.md be?

Shorter than most people write it: the median AGENTS.md across 396 repositories in the RuleStack corpus is 954 words, and the 90th percentile is 2,955. The evidence that length is not the point is in the table above. ethereum/go-ethereum scores 100 on 436 words, while n8n-io/n8n takes 2,383 and is flagged by the corpus for context cost. Every word in an AGENTS.md is loaded on every request the agent makes, so length is a recurring bill, not a one-off. Write the commands and the prohibitions; leave out anything the agent can read off the codebase itself.

Does Claude Code read AGENTS.md?

No. Anthropic’s documentation is explicit: Claude Code reads CLAUDE.md, not AGENTS.md. The documented fix is not to duplicate the file — it is to create a CLAUDE.md whose first line is @AGENTS.md, which imports the shared instructions, and then add any Claude-specific rules underneath. A symlink works too if you have nothing Claude-specific to add. This is the single most common wrong assumption about AGENTS.md, and it is why 126 repositories in the corpus carry both files. Read the Claude Code memory documentation for the import rules. Checked 2026-08-02.

Do I need both AGENTS.md and CLAUDE.md?

Only if your team actually uses Claude Code, and then the second file should be one line long. Of the 396 repositories shipping AGENTS.md, 126 also ship CLAUDE.md — 31.8% of them, counted 2026-08-03. That is the number to weigh against the maintenance cost, and no capability table can produce it. The failure mode is not having two files; it is having two files that disagree, which happens the first time someone edits one and forgets the other. Import instead of copying. Full breakdown on AGENTS.md vs CLAUDE.md, where CLAUDE.md’s own adoption sits at 248 repositories.

Does Cursor read AGENTS.md, or do I need .cursor/rules?

Cursor reads both. Its documentation describes AGENTS.md as a simple alternative to .cursor/rules and supports it in the project root and in subdirectories. Reach for .cursor/rules only when you need a rule to load conditionally — that is the one thing AGENTS.md cannot express, and Cursor offers four activation modes for it: Always Apply, Apply Intelligently, Apply to Specific Files, and Apply Manually. One trap worth knowing before you start: Project rules must use the .mdc extension. A plain .md file in .cursor/rules is ignored. A rule that silently never applies looks exactly like a rule the model chose to ignore. See Cursor’s rules documentation and our Cursor rules format page. Checked 2026-08-02.

Where does AGENTS.md go in a monorepo?

One at the repository root, then another inside each package that needs different instructions. The specification states that agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions. In practice that means the root file should carry only what is true everywhere — the package manager, the commit convention, the prohibitions — and per-package files carry the build and test commands for that package. Strapi is the worked example in this list. Checked 2026-08-02 against agents.md .

What does a good AGENTS.md actually contain?

Runnable commands first, prohibitions second, architecture third. Reading across the ten files above, the sections that recur are: exact build and test commands including the package-manager flags, the lint and format command with a note on whether it matches CI, an explicit list of what not to do, a short architecture orientation, and a pre-PR checklist. The sections that recur in low-scoring files and add nothing are a restated project description, a dependency list, and a directory tree — all three of which the agent can read off the repository for free. AGENTS.md has no schema to help you here: AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide. That freedom is why the median file is mediocre and why the ten above are worth reading before you write yours.