We Analyzed Over 1,500 CLAUDE.md and AGENTS.md Files on GitHub — Here's How Developers Actually Configure AI Agents

AI coding agents read a config file before they touch your code — CLAUDE.md for Claude Code, AGENTS.md as the emerging cross-tool standard. Everyone has opinions about what belongs in them. Nobody had data. So we collected 1,562 real config files from 1,532 public GitHub repositories and measured what developers actually do.

Key Takeaways

• 795 files were CLAUDE.md vs 767 AGENTS.md — a near-even 51% / 49% split. The Claude-specific name still leads, but the tool-agnostic AGENTS.md standard has almost caught up.
• The typical config is small: 66% of files fall in the 1–10 KB range. Sprawling configs are the exception, not the rule.
• 747 of 1,562 files (48%) document build/test commands — the single most common practice we measured.
• 223 files (14%) reference MCP (Model Context Protocol) — early but real adoption of tool/server config.
• The most common section is "Project Overview" (197 files), narrowly ahead of "Architecture" (176) — developers spend more config space orienting the agent than dictating coding rules.

Methodology

We queried GitHub's code-search API for CLAUDE.md and AGENTS.md filenames (four query variants), kept only files whose exact basename is CLAUDE.md or AGENTS.md (GitHub's filename search fuzzy-matches, so we dropped near-misses like subagents.md and AGENTS.md.template), deduplicated by content SHA, and fetched each file's default-branch contents. Limitations worth stating plainly: GitHub code search only indexes default branches and files under roughly 400 KB, caps each query at 1,000 results, and covers public repos only — so this is a large sample, not a census. Collection date: 2026-07-10.

How big is a real agent config?

Lean configs dominate: 1,031 files (66%) sit in the 1–10 KB band, and another 278 are under 1 KB. Only 3 files cross 100 KB. That matters because every token in the config is a token the agent reads on every task — a bloated config quietly eats the context window before any real work begins. The data suggests most developers have converged on "small and focused" without being told to.

What sections do developers write?

Orientation beats instruction. The top sections — Project Overview (197), Architecture (176), Project Structure (109) — describe what the codebase is, while Commands (113) and Testing (99) tell the agent how to operate it. The surprising entry is Testing ranking in the top five: developers clearly learned that agents skip or mangle tests unless the config spells out the runner and the workflow.

How many rules is normal?

The median config is rule-rich but not extreme: 745 files (48%) carry 11–50 bullet-point rules, and 401 more stay under 10. At the tails, 143 files (9%) have no bullet rules at all — pure prose — while 273 files (17%) pack 50+ rules, the zone where instructions start competing with the code for the agent's attention. If your config is in that top tier, it's worth auditing what's actually load-bearing.

Download the dataset

The full per-file metadata (repo, path, size, rule count, section count, MCP/commands flags — no file contents) is free to use under CC-BY 4.0 with a link back to this page:

• agent-config-study-2026.csv
• agent-config-study-2026.json

Frequently Asked Questions

Why publish only metadata and not the file contents?

The files belong to their repository owners under their own licenses — we can't relicense their text. Aggregate statistics and public metadata (repo, path, size) are ours to share, so that's what the dataset contains.

How did you avoid counting the same file twice?

We deduplicated by content SHA, so identical files mirrored across repos count once, and we filtered to exact CLAUDE.md / AGENTS.md basenames to exclude fuzzy filename matches like ai-agents.md or template stubs.

Want a config like the good ones in this study?

Our free CLAUDE.md / AGENTS.md Generator builds one from four quick questions, following the patterns this study found most common.