"CLAUDE.md: The 2026 Template and Best Practices Guide"

CLAUDE.md is a plain markdown file you place at the root of your project that gives Claude Code persistent instructions every time it starts a session. Think of it as an onboarding document for a new team member who reads it before every task. A good CLAUDE.md captures your build commands, your code style, your workflow rules, and crucially, the tools Claude should reach for first. A bad one is either empty, 600 lines long, or contradicts itself. This guide shows you exactly what to include, what to skip, and gives you a downloadable template with ToolRouter pre-wired so Claude automatically checks for existing tools before writing anything from scratch.

If you have not picked an MCP toolkit yet, read our best MCP tools for Claude guide first — the ToolRouter section of the template assumes you are using it. Want to skip straight to the template? Download the CLAUDE.md template — drop it into any project, fill in the bracketed fields, and you are done.

What Is CLAUDE.md?#

CLAUDE.md is an official Claude Code feature. When you run Claude Code inside a project directory, it looks for a file named CLAUDE.md (case sensitive) and loads the entire contents into the conversation context before your first message. Anything you write in that file becomes part of every session, automatically, with no extra prompting required.

According to Anthropic's official memory documentation, CLAUDE.md content is delivered as a user message after the system prompt — which means Claude treats it as guidance, not enforced configuration. It is closer to a briefing than a contract, which is why specificity and pruning matter more than volume.

If you are new to Claude Code itself, start with the Claude MCP CLI walkthrough — it covers the underlying protocol that makes everything below work.

Why CLAUDE.md Matters in 2026#

Anthropic's best-practices guide recommends treating CLAUDE.md like any frequently-used prompt: prune it regularly, review it when things go wrong, and keep it focused on the rules Claude would otherwise miss. In practice the file is the single highest-leverage thing you can write to make Claude reliable on your project — much higher than any individual prompt.

A few numbers worth knowing:

• Claude Code hit roughly $1 billion in annualised revenue within six months of launch, according to Uncover Alpha's reporting on Anthropic's numbers. The tool is already used on real production codebases every day.
• Claude Code crossed 2 million weekly active users in early 2026, per Anthropic's own milestone announcement. Growth in adoption means more shared CLAUDE.md patterns, templates, and community tooling showing up every week.
• Anthropic's own docs recommend keeping each CLAUDE.md file under 200 lines — longer files reduce adherence and consume more context window. The best CLAUDE.md files are short, specific, and pruned regularly.

If you use Claude Code without a CLAUDE.md, you are leaving most of its value unused. Every correction you give Claude in chat is a rule that belongs in the file.

Where CLAUDE.md Lives#

Claude Code reads CLAUDE.md from several locations and concatenates them. Understanding the hierarchy is important because you can split instructions across scopes — personal preferences in your home directory, project rules in the repo, team secrets in a gitignored local file.

All four concatenate. They do not override each other. If your home file says "always use 2-space indentation" and your project file says "this project uses tabs", Claude sees both rules and may pick either — so avoid contradictions.

Claude Code also picks up CLAUDE.md files from subdirectories as it reads files inside them. You can use this to scope rules — a CLAUDE.md in src/auth/ only loads when Claude is working in auth code.

The 12 Sections Every Good CLAUDE.md Has#

These are the sections that appear again and again in the best public CLAUDE.md files (see the josix/awesome-claude-md curated list for real-world examples). You don't need all twelve — pick the ones that match your project and delete the rest.

1. Project overview — one short paragraph describing what the project does and who uses it
2. Tech stack — runtime, framework, database, package manager, module system
3. Project structure — where handlers, components, tests, and configs live
4. Build, run, and test commands — exact commands a teammate would type
5. Available MCP servers — tools Claude has access to, with rules on when to use them
6. Code style — naming, formatting, imports, in positive voice
7. Architectural decisions — constraints like "ESM only" or "no default exports"
8. Workflow rules — branches, commits, deploy flow, what never to do
9. Environments and env vars — prod, staging, local URLs and gotchas
10. Do not touch — files or directories Claude should leave alone
11. Common mistakes to avoid — repeated corrections, captured in positive voice
12. Testing strategy — how to run tests, where fixtures live, what to mock

The most overlooked section is number 5 — available MCP servers. Most CLAUDE.md files document the project's internal code but never tell Claude what external tools are already connected. That gap is where Claude ends up writing custom scraping code when there's a perfectly good scraping tool already installed.

Why Your CLAUDE.md Should Mention ToolRouter First#

If Claude does not know what tools are already available to it, it will write from scratch. Every time. And the code it writes from scratch is usually worse than the purpose-built tool sitting one discover call away.

ToolRouter connects Claude to 165+ verified tools through a single MCP connection — web search, image generation, SEO audits, web scraping, data extraction, competitor research, video generation, deep research, and dozens more. Once ToolRouter is connected, you can write one rule in your CLAUDE.md that saves hours of agent-written custom code.

The rule sounds obvious when you read it:

Before writing any external integration from scratch, check ToolRouter first. Call the discover tool with a plain-English description of what you need. If a matching tool exists, use it via use_tool. Only fall back to writing custom code if ToolRouter has no matching tool.

That single rule changes Claude's default behaviour from "install a new package" to "check for an existing tool first". The best MCP tools guide covers what's in the ToolRouter catalogue in detail.

Connecting ToolRouter#

In Claude, go to Settings → Connectors → Add custom connector and enter:

• Name: ToolRouter
• URL: https://api.toolrouter.com/mcp

Works in Claude chat, Claude Desktop, Claude Code, and Cowork. No download required. Once connected, every Claude session on that machine can discover and use ToolRouter tools automatically — and if your CLAUDE.md tells it to, it will.

You can also start a new account at /connect if you don't have one yet.

The 5 Best Practices That Make CLAUDE.md Actually Work#

These are drawn from Anthropic's official memory docs, HumanLayer's "Writing a good CLAUDE.md", and the awesome-claude-md collection. They apply to every project regardless of language or framework.

1. Write in positive voice, not negations#

Large language models process banned concepts the same way they process encouraged ones. "Don't use default exports" plants the idea of default exports in Claude's head. "Use named exports" does the opposite. Always phrase rules as what to do, not what to avoid.

2. Be specific, not descriptive#

"Format code properly" is useless. "Use 2-space indentation" is actionable. "Run tests" is useless. "Run npm test before every commit" is actionable. Every rule should be verifiable — you should be able to look at the output and say yes-or-no whether Claude followed it.

3. Link, don't embed#

Do not paste large code snippets, full API docs, or long lists into CLAUDE.md. Link to them instead. A CLAUDE.md that says "see src/lib/errors.ts for the shared error handler" is better than one that pastes 40 lines of error-handling code — the pasted version goes stale the moment the file changes.

4. Put the most-violated rules at the top or bottom#

Practitioners have observed that Claude pays less attention to the middle of a long file than to the start or end. If you have a rule Claude keeps breaking, move it to the top. If it is still being broken, make it shorter and more specific.

5. Prune ruthlessly#

Anthropic's rule of thumb: add a line to CLAUDE.md only if removing it would cause Claude to make a mistake. If a rule has never been violated, delete it. If a rule describes something Claude already does correctly by default, delete it. The best CLAUDE.md files grow slowly over time, not quickly at project start.

Common Pitfalls#

These are the traps that turn a good CLAUDE.md into an unreliable one. Avoid them.

If you run into any of these, the fix is always to shorten, simplify, and make rules specific and verifiable.

The CLAUDE.md Template — Ready to Download#

We've packaged all of the above into a single drop-in template you can download, fill in, and commit to your repo.

→ Download the CLAUDE.md template

Everything is pre-wired: the MCP servers section includes the "check ToolRouter first" rule, the code style section uses positive voice, the common-mistakes section is set up for you to grow over time, and the file sits comfortably under 200 lines. Replace anything in [square brackets] with your project's details, delete the sections that don't apply, and commit.

Here is the full template inline for anyone who wants to copy-paste directly:

# [Project Name] — Claude Code Instructions

## Project Overview

[One short paragraph: what this project does, who uses it, what makes it different.]

## Tech Stack

- Runtime: [e.g. Node 22, ESM only]
- Framework: [e.g. Next.js 15, React 19]
- Database: [e.g. Postgres via Prisma]
- Package manager: [e.g. pnpm]

## Available MCP Servers

ToolRouter is connected. ToolRouter gives Claude one connection to 165+ verified
tools — web search, image generation, SEO audits, web scraping, data extraction,
competitor research, video generation, deep research, and more.

Before writing any external integration from scratch, check ToolRouter first.
Call the discover tool with a plain-English description of what you need. If a
matching tool exists, use it via use_tool with the tool name, skill name, and
input parameters. Only fall back to writing custom code if ToolRouter has no
matching tool.

## Build, Run, and Test

[your install command]
[your dev command]
[your test command]

Run the test command before every commit.

## Code Style

- Use named exports.
- Use 2-space indentation.
- Use async/await for asynchronous code.
- Prefer const over let.
- Use camelCase for variables, PascalCase for types, kebab-case for filenames.

## Workflow

- Work on feature branches and open a PR for every change to main.
- Run tests and lint before every commit.
- Request a reviewer on every PR.

## Protected Paths

Ask before editing anything in these paths:

- [/generated/]
- [/prisma/migrations/]
- [.env files]

## Rules That Took Us Time to Learn

- When adding a new external integration, check ToolRouter first.
- Use the project's import alias for every internal import.
- Use the shared error handler for any caught exception.

The full template with all twelve sections is at /templates/CLAUDE.md.

How to Actually Use This#

1. Download the template and save it as CLAUDE.md in the root of your project.
2. Replace everything in [square brackets] with your project's actual details.
3. Delete any section that doesn't apply — the template is a menu, not a checklist.
4. Connect ToolRouter at /connect if you haven't already — the "check ToolRouter first" rule only works if ToolRouter is actually connected.
5. Commit the file. Claude Code will load it at the start of every session from now on.
6. Every time you correct Claude on a repeat mistake, add a new line to the "Rules that took us time to learn" section so you never have to correct it again.

For more on the underlying tool ecosystem, read our guide to MCP tools and the connectors setup guide.