CLAUDE.md examples: what 270 top GitHub repos put in them

Updated 9 min read

A good CLAUDE.md example is short and specific: the commands to build and test, the rules that differ from the defaults, and the mistakes Claude should not make, in about 120 lines. We read the CLAUDE.md files in the 1,000 most-starred GitHub repositories with recent pushes. 270 have one. In the 124 that hold their own instructions, the median file is 118 lines, 73% list build or test commands and 80% have “do not” rules.

Below are the numbers, excerpts from React, Bun, Playwright, PyTorch and others, the patterns they share, and a template built from them. For what CLAUDE.md is and where Claude Code loads it from, start with our CLAUDE.md guide.

What do real CLAUDE.md files contain?

Measure (124 files with their own instructions) Result
Median length 118 lines, 792 words (middle half: 50 to 229 lines)
Under 200 lines 88 (71%)
Over 300 lines 22 (18%); the longest is 1,550
A build, install or test command 90 (73%)
A test command 70 (56%)
A lint, format or typecheck command 65 (52%)
A style or conventions section 85 (69%)
Architecture or structure notes 93 (75%)
Git, commit or pull request rules 89 (72%)
“Do not” rules (never, do not, avoid) 99 (80%); median 4 such lines
All-caps emphasis (IMPORTANT, CRITICAL, MUST) 36 (29%)
@ imports of other files 7 (6%)
Commands, style, architecture and do-nots, all four 61 (49%)

Anthropic’s memory docs say files over 200 lines “consume more context and may reduce adherence”. Most of these repositories stay under that. The most common section headings mention tests (65 files), commands (62), architecture (50), development (45) and build (44).

How we picked the repositories

On October 1, 2026, we asked GitHub’s search API for public repositories with more than 1,000 stars, not archived, pushed since July 1, 2026, sorted by stars. The API returns at most 1,000 results per search, so the sample is the 1,000 most-starred of those, from 29,547 to 550,982 stars. For each one we read the top level of the default branch and fetched CLAUDE.md, or .claude/CLAUDE.md when there was none at the root; we did not look in subdirectories, so some repositories have more instructions than we counted. A script did the counting: “build or test command” means a code span or block with a build, install or test command for a common tool (npm, cargo, pytest, make and so on); “style” and “architecture” mean a heading with words like style, conventions, structure or overview (architecture also counts the word anywhere); “do not” means a line with never, do not, don’t, must not or avoid. Pattern matching misses some cases and overcounts others, so read the percentages as close, not exact.

Do most repos just point CLAUDE.md at AGENTS.md?

More than half do. Of the 270 CLAUDE.md files, 146 (54%) hold no instructions of their own:

  • 60 are symlinks, 57 of them to an AGENTS.md file (home-assistant/core, apache/airflow and PostHog/posthog among them).
  • 86 are short pointer files. 53 are a single @AGENTS.md import line, as in n8n, rust-lang/rust and supabase/supabase.

AGENTS.md is the shared instruction file other coding agents read, and 365 of the 1,000 repositories have one at the root. Our AGENTS.md guide covers which tools read it.

How the pointer is written matters. By default, Claude Code reads AGENTS.md on its own only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it, so a pointer file switches that off. An @AGENTS.md import loads the file in full. A sentence does not: 13 pointer files say it in words, such as “Before doing anything else, read AGENTS.md and follow it.” The docs say Claude then sees AGENTS.md “only if it decides to open the file”, and suggest deleting the CLAUDE.md or replacing the sentence with the import.

Symlinks work too, with two limits from the same docs: Claude’s Edit and Write tools refuse to write through a symlink, and on Windows Git checks a committed symlink out as a one-line text file unless core.symlinks is enabled. Use the import if anyone clones on Windows.

CLAUDE.md examples worth copying

React: a 13-line map

react/react (251k stars) does one job: tells Claude which part of the monorepo is which, and that the compiler has its own file.

## Monorepo Overview

- **React**: All files outside `/compiler/`
- **React Compiler**: `/compiler/` directory (has its own instructions)

The other section, “Current Active Work”, names a plan folder and a branch. That is the one part that has to be kept current by hand.

Excalidraw: commands with a comment each

excalidraw/excalidraw (133k stars, 34 lines) covers structure, workflow, commands and architecture in a screen. The commands say what each is for:

yarn test:typecheck  # TypeScript type checking
yarn test:update     # Run all tests (with snapshot updates)
yarn fix             # Auto-fix formatting and linting issues

Bun: rules that come with a reason

oven-sh/bun (96k stars, 240 lines) has 17 “do not” lines, and many say why:

- **CRITICAL**: Never use `bun test` directly - it won't include your changes
12. **Branch names must start with `claude/`** - This is a requirement for the CI to work.

A rule with a reason lets Claude handle the case the rule did not foresee.

Playwright: architecture as a rule, not a tour

microsoft/playwright (97k stars, 164 lines) states the boundary Claude must not cross instead of listing every folder:

**Key rule**: Client code NEVER imports server code. Server code NEVER imports client code. Communication is only through the protocol.

It also names one command to run before committing: “Always run flint before committing.”

PyTorch: rules for the agent itself

pytorch/pytorch (104k stars, 348 lines) opens with an AI policy section. Its first rule for GitHub is “You may never act autonomously on GitHub.” It also gives Claude a place for its own mess:

Use `agent_space/` (git-ignored, at repo root) for temporary scripts, scratch files, and throwaway experiments. Do not commit files from this directory.

Electron: one safety rule up front

electron/electron (123k stars, 342 lines) puts this near the top: “Never use npx. It is considered dangerous because it can silently fetch and execute arbitrary packages from the registry.” It then lists the safer ways to run binaries.

Twenty: 50 lines of house rules

twentyhq/twenty (58k stars) has three sections under its title: House rules, Commands and Gotchas. Rules that CI enforces are written down so Claude does not learn them from a failed build:

- **Commit messages must not carry AI attribution.** CI rejects commits containing `@anthropic.com` co-author trailers or "Generated with Claude Code" lines.

Claude Code: about one thing

Anthropic’s own anthropics/claude-code (149k stars, 40 lines) has no build commands. It covers one risk, the GitHub Actions workflows that call Claude: “Workflow jobs in this repository that call Claude run with three protections. Keep them when you add or edit a workflow.” A CLAUDE.md does not need every section, only the ones the repository needs.

LocalSend, Kotlin and Ansible: pointers that add something

localsend/localsend (8 lines) keeps one Claude-specific rule (“Always use fvm flutter / fvm dart, never the bare flutter / dart binaries”) above @AGENTS.md. JetBrains/kotlin (18 lines) imports shared guidelines and a personal file, “Local Preferences: @./.claude/local.md”. ansible/ansible is three imports:

- @AGENTS.md
- @~/.claude/ansible.md
- @CLAUDE.local.md

What patterns do good CLAUDE.md files share?

  • Commands in a code block. 70% of the files have one. Exact commands beat “run the tests”.
  • “Never X, because Y.” 80% have do-not rules; the useful ones name the reason or the failure.
  • Boundaries over layouts. 75% describe architecture. The docs’ /doctor checkup (Claude Code v2.1.206 or later) proposes cutting directory layouts, dependency lists and architecture overviews Claude can read from the code, and keeping pitfalls, rationale and conventions. Playwright’s one-line rule survives that trim; a folder tour does not.
  • Rules for git and pull requests. 72% cover commits, branches or PRs: when to push, what goes in a PR description, attribution.
  • Emphasis kept rare. 29% use all-caps words. Bun uses 7 in 240 lines; one file in the sample uses 28.
  • Few imports. Only 7 of 124 use @ imports. The docs note imports help organization but do not save context, since imported files load at launch.
  • The rest moves to .claude/. 173 of the 1,000 repositories have a .claude/ folder: skills in 124, settings.json in 64, commands in 37, agents in 32, rules and hooks in 20 each.

One pattern to skip: 29 files (23%) still open with the stock sentence “This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.” It tells Claude nothing it does not know.

A CLAUDE.md template built from these files

Copy this into CLAUDE.md at your repository root and delete the sections you do not need. Aim for under 200 lines.

# <Project name>

<One line: what it is, the main language and framework.>

## Commands
```bash
<install command>
<build command>
<test one file>        # the fast loop
<lint and typecheck>   # run before every commit
```

## Architecture
- <A boundary Claude must not cross, and why>
- <Where generated code lives, and the command that writes it>

## Rules
- Never <thing>, because <what breaks>.
- Always <thing> before <step>.

## Git and pull requests
- Branches: <pattern>
- <When to commit or push, what goes in a PR description>

## Gotchas
- <Env vars, pinned tool versions, tests that need a service running>

If your team also uses Codex, Cursor or other agents, put the shared instructions in AGENTS.md and keep CLAUDE.md to the import plus anything only Claude needs:

@AGENTS.md

## Claude Code
- <Claude-specific rules, if any>

Where CLAUDE.md stops

Every file in the sample is about one repository: how to build it, test it and not break it. That is the job. It is a poor home for knowledge that spans repositories or agents: why the team picked a vendor, what an investigation found, how three services fit together. A file that loads in full every session, and works best under 200 lines, cannot grow into that.

A shared wiki can. Dexio is a hosted wiki for AI agents: Claude Code, Codex, Cursor and your other agents list, read, search, write, edit and link the same markdown pages over MCP, and you see what they know as a page graph at https://app.dexio.wiki. It is free for one person. Keep CLAUDE.md short and add a pointer:

## Team wiki
- Before you work on a topic, search the Dexio wiki with `search_pages` and read what is there.
- When you work out something that will be needed again, write it to the wiki.
  Update the page that exists instead of adding a duplicate.

The Claude Code memory guide covers setup, and context engineering covers what to load into an agent and when.

FAQ

What should a CLAUDE.md file include?

Commands Claude cannot guess, rules that differ from the language’s defaults, architecture boundaries, git and PR conventions, and gotchas. In our sample, the most common headings were tests, commands and architecture, and 49% of files had all four of commands, style, architecture and do-not rules.

How long should a CLAUDE.md be?

Under 200 lines, per Anthropic’s docs; Claude Code shows a warning at startup and in /status when a file is over the recommended length. In the 124 files we measured, the median is 118 lines and 71% are under 200.

Should I use CLAUDE.md or AGENTS.md?

If only Claude Code works in the repository, CLAUDE.md alone is fine. If other agents do too, keep one AGENTS.md and a CLAUDE.md that imports it with @AGENTS.md; 53 repositories in our sample use exactly that one line. See the AGENTS.md guide.

Does Claude Code read CLAUDE.md files in subfolders?

Yes, when it works with files in that folder; the root file loads at the start. React’s root file notes that its compiler folder has its own instructions. Where each file goes and how they combine is in the CLAUDE.md guide.

Sources

Keep reading

Ask a question

Ask anything about Dexio.

About
We reply by email.