12 Best CLAUDE.md Examples From Real Repos (2026)

CLAUDE.md changed in 2025. By 2026, the question is no longer "should we have a CLAUDE.md file" but "is ours good enough to make Claude Code behave like a senior engineer on day one." The file is the system prompt for every session in your repo. Get it right and Claude Code stops asking obvious questions and starts writing code that fits your conventions.

The hard part is separating CLAUDE.md files that actually steer the model from files that read like a generic README copy. A good CLAUDE.md is short, opinionated, and full of "do this, not that." It names commands, file paths, and gotchas. It does not restate what Claude already knows.

This guide compares the 12 best CLAUDE.md examples from real GitHub repos in 2026. Real patterns, honest takes, and a framework to write your own. If you want help without the trial and error, AY Automate has shipped CLAUDE.md files for production codebases across Next.js, Python, Go, and monorepo stacks.

Best CLAUDE.md examples: a brief overview

• anthropics/claude-code: Best for canonical patterns — the reference implementation from the team that built the tool.
• anthropics/anthropic-quickstarts: Best for minimal starter shape — short, focused, copy-pasteable.
• sst/opencode: Best for monorepo coordination — multi-package TypeScript with clear workspace rules.
• BMAD-METHOD/bmad-method: Best for agent-swarm patterns — multi-agent CLAUDE.md done right.
• awesome-claude-code: Best for community-curated patterns — a living index of what works.
• claude-task-master: Best for task-driven workflows — turns CLAUDE.md into a runtime contract.
• getzep/graphiti: Best for Python + knowledge-graph projects — typed, tested, and tightly scoped.
• langchain-ai/langgraph: Best for graph-based agent codebases — clear boundary between framework and user code.
• run-llama/llama_index: Best for large Python frameworks — handles a huge surface area without bloat.
• microsoft/autogen: Best for multi-language repos — Python and .NET coexisting cleanly.
• vercel/next.js: Best for massive open-source projects — proves CLAUDE.md scales beyond small repos.
• supabase/supabase: Best for full-stack platform codebases — TS, Go, Rust, and SQL in one file.

1. anthropics/claude-code, best for canonical patterns

The official Claude Code repo is the reference for what a CLAUDE.md should look like, because the team that built the tool eats their own dog food. The file is short, opinionated, and structured around the developer loop: how to run the dev server, how to run tests, how to lint, and the exact commit conventions. It does not waste tokens explaining what TypeScript is or what npm does. It treats Claude as a competent collaborator who needs project-specific context, not general programming knowledge.

Key features

• Sectioned by developer task: build, test, lint, commit
• Explicit shell commands with expected output
• "Do not do X" rules listed before "do Y" rules
• Short — under 200 lines — which keeps it readable in every session

Best for

• Teams writing their first CLAUDE.md and looking for shape
• Developer-tooling projects
• CLIs and small focused libraries

Pricing

• Free / open source on GitHub
• No hidden costs

Pros

• Authoritative — written by the team building Claude Code
• Easy to copy the skeleton into your own repo
• Reflects current best practices as the tool evolves

Cons

• Tight scope means it doesn't cover monorepo or multi-language patterns
• You'll outgrow it once your repo has more than a few packages

2. anthropics/anthropic-quickstarts, best for minimal starter shape

The quickstarts repo includes CLAUDE.md files inside each starter project — customer support agent, computer use demo, financial data analyst. These files show what "minimum viable CLAUDE.md" looks like when you want Claude Code productive on a brand new project in under five minutes. Each file is tightly scoped to one app, names the entry points, and lists the environment variables that must be set before code runs.

Key features

• One CLAUDE.md per starter, scoped per app
• Environment variable checklist at the top
• Run commands repeated verbatim from the README
• Pointers to the SDK docs rather than restating them

Best for

• Greenfield projects copying a template
• Teaching juniors how to write a CLAUDE.md
• AI SDK and Claude Agent SDK starters

Pricing

• Free / open source

Pros

• Bite-sized — easy to absorb
• Updated by Anthropic engineers as patterns shift
• Clean separation of repo-level and app-level guidance

Cons

• Too thin for any project past the prototype stage
• Doesn't cover testing strategy or release workflow

3. sst/opencode, best for monorepo coordination

OpenCode from SST is a terminal-based AI coding agent and the CLAUDE.md handles a TypeScript monorepo with multiple packages — CLI, server, web UI, and shared types. The file teaches Claude where each piece lives, which package owns which responsibility, and the "don't touch the generated dist" kind of rules that save you from review pain. It also documents the exact bun and pnpm commands used in CI so Claude can self-verify before claiming work is done.

Key features

• Package map with ownership boundaries
• Build and test commands per workspace
• Explicit rules about cross-package imports
• Notes on generated artifacts to avoid editing

Best for

• TypeScript monorepos with 3+ packages
• Teams using Bun or pnpm workspaces
• CLI + server hybrid projects

Pricing

• Free / open source (MIT)

Pros

• Real-world monorepo patterns
• Active maintenance — patterns evolve with the project
• Pairs well with Claude Code agent setups

Cons

• Heavy reading if you're not on a TS stack
• Some rules are specific to OpenCode's CLI architecture

4. BMAD-METHOD, best for agent-swarm patterns

BMAD is a popular framework for multi-agent development with Claude Code, and the CLAUDE.md is where most projects get the agent-swarm pattern right or wrong. BMAD's file defines agent roles, hand-off contracts, and the file conventions each agent must respect. It treats CLAUDE.md as the constitution that every sub-agent reads on boot, and that pattern has been copied across dozens of forks.

Key features

• Agent roster with scope per agent
• Hand-off file format (markdown contracts)
• Lock-file protocol to prevent concurrent edits
• Mode definitions: plan, build, review, ship

Best for

• Multi-agent orchestration projects
• Teams building their own internal agent framework
• Anyone designing parallel autonomous workflows

Pricing

• Free / open source

Pros

• One of the few public examples of working agent-swarm CLAUDE.md
• Highly structured — easy to adapt to your domain
• Battle-tested across many forks

Cons

• Overkill for solo developers or simple projects
• Steep learning curve before the structure clicks

5. awesome-claude-code, best for community-curated patterns

The awesome-claude-code repo is a curated index of Claude Code resources, including a section dedicated to CLAUDE.md examples and patterns. The repo's own CLAUDE.md is short — it tells Claude how to add new entries, how to format the index, and which categories are valid. But the real value is the linked examples from other repos, which act as a living gallery of what the community considers canonical.

Key features

• Categorized index of CLAUDE.md examples in the wild
• Formatting rules for new entries
• Frequent updates from community PRs
• Links to skills, agents, and hooks alongside CLAUDE.md

Best for

• Anyone researching CLAUDE.md patterns
• Teams choosing between multiple structural approaches
• Open-source maintainers tracking ecosystem trends

Pricing

• Free / open source

Pros

• Comprehensive — updated weekly
• Saves hours of searching across random repos
• Pairs naturally with our roundup of the best Claude Code GitHub repos

Cons

• Quality of linked examples varies
• No editorial filter — popularity does not equal quality

6. claude-task-master, best for task-driven workflows

Task Master turns a CLAUDE.md into a runtime contract: tasks live as files, the agent reads them on session start, and progress updates are written back to disk. The CLAUDE.md teaches Claude how to interact with the task graph — claim a task, lock it, work it, write a hand-off, unlock it. It's one of the cleanest public examples of using CLAUDE.md as an operating manual rather than a static doc.

Key features

• Task file format and lifecycle
• Lock and hand-off protocols
• Status update commands
• Integration with the Task Master CLI

Best for

• Teams wanting a structured agent workflow
• Solo developers running many parallel tasks
• Replacing Jira-style tooling with file-based tracking

Pricing

• Free / open source

Pros

• Demonstrates CLAUDE.md as runtime contract
• Composable with other agent setups
• Encourages discipline in task scoping

Cons

• Requires buying into the Task Master pattern
• File-based tracking has friction at large team scale

7. getzep/graphiti, best for Python + knowledge-graph projects

Graphiti is a Python framework for building temporal knowledge graphs, and the CLAUDE.md is a great example of how to handle a typed Python codebase with heavy testing. It names the package layout, the exact uv and pytest commands, and the linting setup. It also flags the parts of the code that touch external services (Neo4j, OpenAI) so Claude doesn't run them in casual exploration.

Key features

• Python project layout (src + tests)
• uv for dependency management
• Type-checking and lint commands
• External service flags

Best for

• Python framework maintainers
• Teams using uv or modern Python tooling
• Knowledge-graph and memory-layer projects

Pricing

• Free / open source

Pros

• Excellent test-driven workflow guidance
• Clear separation of unit vs integration tests
• Reflects modern Python best practices

Cons

• Some rules are Graphiti-specific (graph types, schemas)
• Less useful if you're not on a typed Python stack

8. langchain-ai/langgraph, best for graph-based agent codebases

LangGraph powers a lot of production agent systems and the CLAUDE.md handles the tricky case of a framework where users extend the code in unpredictable ways. The file distinguishes "framework code" (don't refactor casually) from "examples" (free to modify) and gives Claude clear rules about which APIs are stable and which are experimental. That single distinction prevents a lot of accidental breakage in PRs.

Key features

• Stable vs experimental API markers
• Framework code vs example code separation
• Release process notes
• Pointers to the docs site

Best for

• Framework and library maintainers
• Teams where Claude works on both core code and examples
• Agent infrastructure projects

Pricing

• Free / open source

Pros

• Strong "what not to touch" guidance
• Real-world example of library-vs-app distinction
• Frequently updated as the framework evolves

Cons

• Niche to LangGraph users
• Some context is implicit in the LangChain ecosystem

9. run-llama/llama_index, best for large Python frameworks

LlamaIndex has hundreds of integrations and a massive surface area. The CLAUDE.md does the hard work of routing Claude to the right package without overwhelming it with the full repo map. It uses a "find the right package, then read its local README" pattern that scales — instead of one giant file, it's a small CLAUDE.md plus per-package READMEs that Claude pulls in on demand.

Key features

• Tiered context: repo-level + per-package
• Package discovery rules
• Common gotchas (LLM provider drift, integration breakage)
• Release and changelog conventions

Best for

• Large Python frameworks with many integrations
• Plugin-heavy architectures
• Projects that want to avoid CLAUDE.md bloat

Pricing

• Free / open source

Pros

• Scales without becoming unreadable
• Encourages on-demand context loading
• Good model for RAG framework repos

Cons

• Requires discipline to keep per-package docs current
• Onboarding still requires reading multiple files

10. microsoft/autogen, best for multi-language repos

AutoGen ships Python and .NET in the same repo, which is a challenge for any single CLAUDE.md. Microsoft's solution is to keep a top-level file that handles repo-wide concerns (CI, release, code of conduct) and then point Claude to language-specific subdirectories with their own context. It's one of the clearest public examples of how to write CLAUDE.md for a polyglot codebase.

Key features

• Top-level repo-wide rules
• Language-specific subdirectory pointers
• CI and release commands
• Notes on cross-language type sharing

Best for

• Multi-language enterprise repos
• Teams blending Python and .NET
• Projects with separate language SIGs

Pricing

• Free / open source

Pros

• Handles polyglot complexity gracefully
• Active maintenance from Microsoft Research
• Good template for cross-functional teams

Cons

• Some sections are specific to .NET conventions
• Heavy file — long read on first contact

11. vercel/next.js, best for massive open-source projects

Next.js proves CLAUDE.md can scale to one of the largest TypeScript repos on GitHub. The file focuses on the developer loop — how to reproduce bugs, how to run integration tests, how to pick the right package to modify — rather than trying to explain the entire framework. It also names the parts of the codebase that are deliberately legacy and should not be "improved" without an RFC.

Key features

• Bug-repro workflow
• Integration test commands
• Package map (next, next-swc, create-next-app, etc.)
• "Legacy zones — do not refactor" warnings

Best for

• Large open-source maintainers
• Framework projects with millions of users
• Teams that need to prevent well-meaning refactors

Pricing

• Free / open source (MIT)

Pros

• Proven at extreme scale
• Strong "stay in your lane" guardrails
• Pairs well with Vercel's broader agent stack

Cons

• Heavy file — not a quick read
• Some context relies on Next.js insider knowledge

12. supabase/supabase, best for full-stack platform codebases

Supabase blends TypeScript (dashboard), Go (auth, realtime), Rust (extensions), and SQL (migrations) in one monorepo. The CLAUDE.md handles this by routing Claude to language-specific subdirectories and naming the test commands per stack. It also includes a strong "before opening a PR" checklist — lint, type-check, test, migration check — that catches the most common failure modes in a platform codebase.

Key features

• Per-language subdirectory pointers
• Pre-PR checklist
• Migration safety rules
• Notes on which services run locally vs in CI

Best for

• Full-stack platform teams
• BaaS and PaaS codebases
• Polyglot infrastructure projects

Pricing

• Free / open source

Pros

• Handles four+ languages cleanly
• Strong pre-PR guardrails
• Real-world platform engineering patterns

Cons

• Long file — onboarding takes time
• Some sections assume Supabase architecture knowledge

How to choose the best CLAUDE.md pattern for your repo

1) Is this a single app, a framework, or a monorepo?

The shape of your CLAUDE.md depends entirely on this question. For a single app, copy the anthropic-quickstarts shape — one file, one app, scoped to entry points and env vars. For a framework, copy LangGraph's stable-vs-experimental distinction. For a monorepo, look at sst/opencode or supabase/supabase. If you're building an agent swarm, BMAD-METHOD is the cleanest starting point and pairs naturally with patterns from our best Claude Code skills roundup.

2) How big is the codebase?

Small repos (under 50 files) need a single short CLAUDE.md. Medium repos (50-500 files) benefit from a top-level file plus per-package READMEs, the llama_index pattern. Large repos (500+) need everything Next.js has — package maps, legacy zones, repro workflows — plus discipline about not letting the file rot. The cost of a stale CLAUDE.md grows non-linearly with repo size.

3) Are you running one developer or an agent swarm?

A solo developer can keep CLAUDE.md informal — a few sections, a few rules, evolve as you go. A team running parallel agents (multiple Claude Code sessions, sub-agents, automated tasks) needs the BMAD or claude-task-master treatment: explicit roles, lock protocols, hand-off contracts, and a tracking layer. Skipping this discipline is the most common reason multi-agent setups produce chaotic git history.

4) Are you on Python, TypeScript, or polyglot?

Python projects benefit most from getzep/graphiti — typed, tested, uv-based. TypeScript monorepos should look at sst/opencode. Polyglot codebases — Python + .NET, or TS + Go + Rust — should follow microsoft/autogen or supabase/supabase. Trying to force a single-language CLAUDE.md shape onto a polyglot repo always ends in either bloat or missing context.

Working with AY Automate on your CLAUDE.md

If you're shipping production agents and don't want to spend two weeks iterating, AY Automate writes CLAUDE.md files, agents, and skill libraries for real production codebases. For more, see our roundups of the best Claude Code GitHub repos and the best Claude Code skills. Want a walkthrough? Book a consultation and we'll review your setup in 30 minutes.

FAQ

What is a CLAUDE.md file?

CLAUDE.md is a markdown file at the root of your repo (or in subdirectories) that Claude Code reads on session start. It functions as a project-specific system prompt: it teaches Claude about your stack, your conventions, your commands, and your gotchas, so it stops asking obvious questions and starts writing code that fits.

How is CLAUDE.md different from a README?

A README explains the project to humans. A CLAUDE.md explains it to Claude Code. They overlap on stack and run commands, but a good CLAUDE.md goes further — explicit "do this, not that" rules, file paths, lint and test commands with expected output, and warnings about parts of the codebase that need extra care. A README does not need any of that.

How do I verify a CLAUDE.md is actually working?

Start a fresh Claude Code session and ask it to summarize the project. If the summary names your stack, your test command, and at least one gotcha specific to your repo, the file is working. If it gives a generic summary, you need more specificity. Better yet, ask Claude to perform a small task — if it picks the right file on the first try, your CLAUDE.md is steering the model.

How long should a CLAUDE.md be?

Most good files in 2026 are between 100 and 400 lines. Under 100 and you're missing context. Over 400 and you're either bloating the context window or you should be splitting into per-package files plus a top-level summary, the llama_index pattern.

Should CLAUDE.md be committed to the repo?

Yes. The whole point is that every developer (and every Claude Code session) gets the same context. Treat it like a config file — version it, review changes in PRs, and update it whenever conventions shift. Some teams keep a private CLAUDE.local.md for personal preferences that override the shared file.

Can I use CLAUDE.md with sub-agents and skills?

Yes — and you should. CLAUDE.md is the top-level context. Skills add reusable workflow knowledge. Sub-agents own specific directories. The cleanest setups have all three working together: CLAUDE.md sets the rules, skills handle recurring tasks, and sub-agents enforce ownership boundaries. See our Claude Code skills roundup for examples.

Should I write CLAUDE.md by hand or generate it?

Hand-written is better for the first version because you encode your team's tacit knowledge. Auto-generated CLAUDE.md files (from README, from package.json, from Claude itself) tend to be generic and miss the gotchas. A good middle ground is to draft by hand, then ask Claude to suggest improvements, then keep editing as you find new patterns.

What's the most common CLAUDE.md mistake?

Restating things Claude already knows. "TypeScript is a typed superset of JavaScript" is a wasted token. "We use strict mode, no any allowed, run pnpm typecheck before commit" is useful. Every line should answer "what does Claude need to know about THIS repo?"