CLAUDE.md examples (and AGENTS.md) from real repositories

Fred Chang · October 14, 2026

The best CLAUDE.md examples I found are short. They list the exact commands, name the files an agent must not touch, and say what "done" means. Almost none explain the code.

TLDR: copy the shape, not the words. Twelve real files below, then a template.

In CLAUDE.md best practices I counted which rules grew across 5,786 files. From Q4 2025 to Q3 2026, code-idiom rules fell from 18% of a new file to 10%. "Don't touch" rules rose from 13% to 17%. New files shrank from 13.0 rules to 8.9.

What is a CLAUDE.md file?

A Markdown file in your repo that Claude Code reads at the start of a session: build commands, conventions, boundaries. AGENTS.md is the same idea for many tools, among them Codex, Cursor, Gemini CLI and Copilot's coding agent. [2] Claude Code reads AGENTS.md when a repo has no CLAUDE.md. [1] Among new files in repos with 1,000+ stars, 87% were AGENTS.md by Q3 2026.

Twelve real CLAUDE.md and AGENTS.md examples

Stars from GitHub, October 2026. Links go to the commit quoted; root AGENTS.md unless marked.

Repo	Type	Stars	What it does well
TryGhost/Ghost	Web app	56k	A router: links the real docs, nearer file wins
excalidraw/excalidraw (CLAUDE.md)	Web app	134k	Which folder for which change, then three commands
axios/axios	Library	109k	Every rule a boundary with its reason
vercel/next.js	Monorepo	143k	A map: folder tree, entry points, READMEs down to your file
supabase/supabase	Monorepo	112k	One table of apps, ports and nested AGENTS.md files
kubernetes/kubernetes	Monorepo	128k	"Don't touch", each with the command to run instead
vllm-project/vllm	ML	94k	Contribution policy first, then the environment rule
scikit-learn/scikit-learn	ML	68k	No code rules: check labels, disclose AI help, write plainly
facebook/docusaurus	Docs	66k	Which docs are versioned; `examples/` is generated
expo/expo (docs/AGENTS.md)	Docs	53k	A nested file for one folder, copying CI's checks
astral-sh/uv	CLI	91k	ALWAYS / DO NOT / PREFER, nearly all about tests
nektos/act (CLAUDE.md)	CLI	72k	Commands, including one test, then the execution flow

Lines worth copying

Point at docs instead of repeating them (Ghost):

- Read the nearest `AGENTS.md` and README before changing a package
  or subsystem. More specific guidance overrides this file.

Give each boundary its reason (axios):

- Do not edit `dist/` by hand; it is ignored and generated from `lib/` by Rollup.

Name what to run instead (kubernetes):

- **Generated files are read-only.** Never hand-edit `zz_generated.*` or `generated.pb.go`. Run `make update`.

Block the most common mistake (vllm):

- **Never use system `python3` or bare `pip`/`pip install`.** All Python commands must go through `uv` and `.venv/bin/python`.

CLAUDE.md or AGENTS.md: which should you write?

AGENTS.md, if more than one AI tool works in the repo. Then decide how Claude gets it. ollama/ollama's CLAUDE.md is one line: "See AGENTS.md for the shared agent instructions for this repository."

With both files present, Claude Code reads only CLAUDE.md by default. [1] A pointer written in plain words leaves it to Claude to open the other file. A line reading @AGENTS.md imports it at launch.

How long should a CLAUDE.md file be?

Under 200 lines, Anthropic says. Move rules for one part of the codebase into path-scoped rules, which load only for files in that part. [1] Eleven of the twelve fit, and five are under 50. next.js, at 520, is mostly a map of a very large repo.

Dot chart of lines per file. Eleven files fall between 28 (scikit-learn) and 156 (vllm), left of a dashed line at 200 lines; next.js alone sits at 520. — Lines per file at the linked commit. Only next.js passes Anthropic's 200-line guide.

A minimal CLAUDE.md template

# <project> — agent guide
<!-- One line: what this repo is. -->

## Commands
- Install: `pnpm install`
- Check everything: `pnpm check`
- One test: `pnpm test path/to/file.test.ts`

## Don't touch
<!-- Name the file AND what to do instead. -->
- `dist/`, `*.generated.ts`: generated. Run `pnpm gen`.
- Never push to `main`. Never commit `.env`.

## Before you say done
- `pnpm check` passes. New behaviour has a test.

@AGENTS.md  <!-- if you keep both files -->

Keep one CLAUDE.md for every AI and teammate

Your team's style guide and your own preferences have no repo. I keep them in agentleFS, a store of documents your AI tools can read. A CLAUDE.md or AGENTS.md in an agentleFS folder applies to everything under it. When an agent lists or searches there, agentleFS tells it which files apply, and the agent reads them when it needs them. On an agent's page, Load memory and skills from hands it the CLAUDE.md and AGENTS.md of the folders you pick, each time it connects. Claude, ChatGPT, Codex, Cursor and Gemini read the same file. Teammates see only what you share. More in Claude Code memory.

All twelve files are in the public catalog. When a file's licence allows a copy, Mount puts one in your folder. The copy follows GitHub until you pin or edit it.

Try it: sign up free, connect your AI with https://mcp.agentlefs.com/mcp, and mount the example closest to your project.

Related

1. Anthropic, "How Claude remembers your project", Claude Code docs: AGENTS.md is read when there is no CLAUDE.md; with both, CLAUDE.md only by default; @path imports; "target under 200 lines per CLAUDE.md file." Reading AGENTS.md directly needs Claude Code v2.1.277 or later.
2. agents.md: the format, the tools that read it, and "the closest AGENTS.md to the edited file wins."

Excerpts are quoted from the linked commits under each repository's licence (MIT, Apache-2.0 or BSD-3-Clause). Theme shares and the 87% figure come from the best practices data.