CLAUDE.md Best Practices: What Actually Moves the Needle

A CLAUDE.md file is plain markdown that Claude Code reads at the start of every session, and it's the single biggest lever you have over output quality. Get it right and Claude stops guessing your conventions. Get it wrong and you bloat the context window before you've typed a word. The best practice that matters most: keep it short, specific, and universally true for the project.

TL;DR
CLAUDE.md is project memory loaded into every Claude Code session. The best CLAUDE.md files are under ~200 lines, contain only universally-applicable rules (commands, architecture, conventions), point to detailed docs with file references instead of pasting them, and never duplicate what a linter already enforces. Bloated files trigger context rot. Chroma's 2025 study found every one of 18 frontier models degrades as input grows, sometimes from 95% to 60% accuracy (Chroma, 2025). Treat CLAUDE.md like code: commit it, review it, and prune it.

I've been editing CLAUDE.md files daily for over a year, across decade-old Laravel codebases (the Sivon API among them) and the Next.js blog publisher that runs maketocreate.com. This is the deep-dive the rest of my real-world Claude Code workflow that CLAUDE.md plugs into keeps pointing back to. If CLAUDE.md is one of seven moving parts there, here it gets the whole article.

Key Takeaways

• CLAUDE.md loads on every session, so every line spends context budget, and Anthropic's own guidance is to keep it concise (Claude Code docs, 2026).
• Frontier models reliably follow only ~150–200 instructions; Claude Code's system prompt already uses ~50 (HumanLayer, 2025).
• Use file:line references and pointers to agent_docs/, never pasted code blocks. Progressive disclosure keeps the always-loaded file small.
• CLAUDE.md ≠ AGENTS.md ≠ .claude/agents/*.md. They're three distinct surfaces; mixing them up is the most common configuration mistake I see.

What Is CLAUDE.md and Where Does It Live?

CLAUDE.md is a markdown file Claude Code automatically loads into context at the start of every conversation, giving the model persistent, project-specific memory it can't infer from code alone (Claude Code docs, 2026). Think of it as the briefing you'd give a senior contractor on day one, except Claude reads it fresh, every single session, forever.

The claude md file lives in a small hierarchy, and the layering is the part most people miss. There are three locations Claude Code checks, in increasing scope:

• Project memory — ./CLAUDE.md at the repo root. Committed to git, shared with the team. This is the one you'll spend 90% of your time on.
• Local/project-private — ./CLAUDE.local.md (gitignored) for personal overrides you don't want to commit.
• User memory — ~/.claude/CLAUDE.md, applied across every project on your machine. Good for personal preferences ("always explain before refactoring") that aren't repo-specific.

Claude Code also walks up the directory tree, so a CLAUDE.md in a subdirectory layers on top of the root one, which is useful in monorepos. The filename is case-sensitive and exact: it's CLAUDE.md, not claude.md or claude .md. If you've just installed the CLI and don't have one yet, see my guide to installing Claude Code if you haven't yet, then run /init inside any repo and it scaffolds a starter file from your project structure.

CLAUDE.md is loaded into context on every Claude Code session as persistent project memory, layered across three scopes (project ./CLAUDE.md, local ./CLAUDE.local.md, and user ~/.claude/CLAUDE.md), with narrower scopes overriding broader ones, exactly as documented in Anthropic's Claude Code best-practices guide (Anthropic, 2026).

Why CLAUDE.md Is the Most Underrated Claude Code Feature

Most developers install Claude Code, skip CLAUDE.md entirely, and then wonder why it keeps using the wrong test runner. That's a mistake: 84% of developers now use or plan to use AI coding tools, yet only 33% trust their accuracy versus 46% who actively distrust it (Stack Overflow Developer Survey, 2025). A precise CLAUDE.md is the cheapest way to close that trust gap on your own codebase.

Here's the mechanism. Claude Code is the most-loved AI coding tool of 2026, with a 46% "most loved" rating across 15,000 developers surveyed (Pragmatic Engineer via UncoverAlpha, 2026), and it crossed a $2.5B revenue run-rate by February 2026 (UncoverAlpha, 2026). But the model still doesn't know that your project deploys with make ship, that legacy/ is off-limits, or that you use Pest, not PHPUnit. Without CLAUDE.md it relearns (or mis-guesses) those facts every session.

The day it clicked for me was on the Sivon Laravel API. I'd been re-typing "use the repository pattern, not Eloquent in controllers" into every session for a week. I moved one line into CLAUDE.md and the correction stopped being necessary. That's the underrated part: CLAUDE.md doesn't make Claude smarter, it makes it stop forgetting. Every rule you write once is a correction you never type again.

My finding: Across roughly 40 repos I've configured, the single highest-ROI line in any CLAUDE.md is the exact test command. Claude defaults to the ecosystem-common runner (npm test, phpunit) and gets it wrong constantly. One line, Run tests with: npm run test:unit, eliminates an entire class of wasted turns.

How to Write a CLAUDE.md: The Step-by-Step Structure

Knowing how to write a CLAUDE.md comes down to one rule: include only what's true across every session, and structure it around three questions: what, why, and how (HumanLayer, 2025). Frontier models reliably follow only about 150–200 instructions, and Claude Code's system prompt already consumes roughly 50 of those (HumanLayer, 2025). Your budget is smaller than you think.

So what actually goes in the file? Run /init first to scaffold, then rewrite it by hand. A good structure, top to bottom:

1. One-line project description: what this repo is, in a sentence.
2. Tech stack: framework, language, versions, the database. Facts Claude can't reliably guess.
3. Commands: build, test, lint, run, deploy. The exact invocations, not the conventional ones.
4. Architecture: the 3–5 directories that matter and what each does. Point to files, don't describe them in prose.
5. Conventions: patterns the team enforces that a linter can't (repository pattern, error-handling style, naming).
6. Boundaries: what's off-limits (legacy/, generated files, vendored code).
7. Pointers: links to agent_docs/ or deeper specs for anything detailed.

That last one is the technique that keeps the file small: progressive disclosure. Store detailed guidance in separate files and reference them with file paths, so Claude pulls them only when relevant (HumanLayer, 2025). A CLAUDE.md should be a map, not the whole territory.

The strongest CLAUDE.md files answer three questions (what the project is, why its components exist, and how to build, test, and verify it) while pushing detailed guidance into referenced agent_docs/ files. This progressive-disclosure pattern keeps the always-loaded file under the ~150-instruction ceiling frontier models reliably follow (HumanLayer, 2025).

Real CLAUDE.md Examples: Laravel API, Next.js App, Python Pipeline

The fastest way to internalize CLAUDE.md best practices is to read good examples. Below are three condensed, real-shaped files from the stacks I work in. Notice what's absent: no code style rules (the linter owns those), no pasted code, no task-specific instructions.

Laravel API (CLAUDE.md):

# Sivon API

Laravel 11 REST API for booking management. PHP 8.3, MySQL 8, Pest for tests.

## Commands
- Test: `php artisan test` (Pest, NOT PHPUnit directly)
- Lint: `./vendor/bin/pint`
- Migrate fresh: `php artisan migrate:fresh --seed`

## Architecture
- Controllers stay thin — business logic lives in `app/Services/`
- DB access through `app/Repositories/` only. Never use Eloquent in controllers.
- API resources in `app/Http/Resources/` shape every JSON response.

## Conventions
- Form Requests for all validation. No inline `$request->validate()`.
- New endpoints: add a route, a Form Request, a Service method, a Pest feature test.

## Off-limits
- `app/Legacy/` — frozen, do not modify. See agent_docs/legacy-migration.md.

Next.js app (CLAUDE.md):

# maketocreate Blog Publisher

Next.js 16 App Router + React 19 + TypeScript (strict). Tailwind v4. File-based JSON state, no DB.

## Commands
- Dev: `npm run dev` | Build: `npm run build` | Lint: `npm run lint`

## Architecture
- Articles: markdown in `articles/<category>/`. Parser: `lib/parser.ts`.
- Publishing pipeline: `lib/publish-orchestrator.ts`. Adapters in `lib/adapters/`.
- State persisted as JSON via `lib/store.ts`. No database.

## Conventions
- Tailwind v4 configured via `@theme` in `app/globals.css` — there is NO tailwind.config.ts.
- Dark mode is the default-supported path; test both themes.

## Off-limits
- `config.json` is gitignored — never commit API keys.

Python data pipeline (CLAUDE.md):

# Ingest Pipeline

Python 3.13 ETL. uv for deps, Polars (not pandas), Prefect for orchestration.

## Commands
- Install: `uv sync` | Test: `uv run pytest` | Run flow: `uv run python -m flows.daily`

## Architecture
- Extractors: `src/extract/` | Transforms: `src/transform/` (pure functions, Polars)
- Schemas validated with Pydantic v2 in `src/schemas/`.

## Conventions
- All transforms are pure and unit-tested. No I/O inside transform functions.
- Use Polars expressions, not pandas. Reject any pandas import in review.

These claude.md examples share a shape: scannable, command-first, pointer-driven. Each is well under 60 lines. HumanLayer's own production CLAUDE.md is fewer than 60 lines, and that's not an accident (HumanLayer, 2025).

Illustrative estimate based on ~13 tokens/line and a 200K context window; Source: HumanLayer instruction-budget analysis, 2025

CLAUDE.md vs claude/agents.md: When to Use Which

This is where people get tangled, so let's be precise. "Claude agents.md" can mean two different things, and CLAUDE.md is a third. They aren't interchangeable; each loads at a different time for a different reason. The AGENTS.md open standard launched in 2025 backed by OpenAI, Google, Factory, Sourcegraph, and Cursor, and passed 20,000 adopting repositories by August 2025 (Harness, 2026).

Here's the distinction:

• CLAUDE.md: Claude Code's native project memory. Loaded into the main session, always.
• AGENTS.md: the cross-tool open standard, readable by Codex, Cursor, Copilot, and others. Schema-free markdown, same job as CLAUDE.md but vendor-neutral.
• .claude/agents/*.md: subagent definitions. Separate agents you delegate to, each with its own isolated context window and its own instructions.

So which one do you actually write? If your repo only uses Claude Code, write CLAUDE.md and move on. If multiple agents touch the repo, the clean pattern is to keep one canonical file and symlink the other: ln -s CLAUDE.md AGENTS.md (or the reverse). One source of truth, every tool reads it. In December 2025, AGENTS.md was donated to the Linux Foundation's Agentic AI Foundation alongside Anthropic donating MCP, a signal the two ecosystems are converging, not competing (Harness, 2026).

Source: Claude Code documentation and AGENTS.md specification, 2026

The 12 CLAUDE.md Best Practices I Follow Daily

After more than a year of daily use, these are the Claude Code CLAUDE.md best practices I apply to every repo. They exist because each one fixed a real, repeated failure. The throughline: every line earns its context cost, because context rot is real. Chroma's 2025 benchmark showed all 18 frontier models tested, including Claude Opus 4, lose accuracy as input grows, some dropping from 95% to 60% past a threshold (Chroma, 2025).

1. Keep it under ~200 lines. Shorter is better. If it scrolls more than a screen or two, you're paying for it every session.
2. Lead with commands. Test, build, lint, run: the exact invocations. This is the highest-ROI section by a wide margin.
3. Never duplicate the linter. Don't write style rules a formatter enforces deterministically. LLMs are slow and expensive at jobs a linter does instantly (HumanLayer, 2025).
4. Use file:line references, not pasted code. See lib/parser.ts:42 beats a 30-line snippet that goes stale.
5. Only universal truths. No task-specific instructions. "How to design the new billing schema" doesn't belong here; it distracts every unrelated session.
6. Point to agent_docs/. Detailed guidance lives in referenced files, loaded on demand. Progressive disclosure keeps the core lean.
7. State what's off-limits. Frozen directories, generated files, vendored code. Boundaries prevent the most damaging mistakes.
8. Document domain jargon. Map your internal terms to the code so Claude edits the right files.
9. Mention your MCP setup. If the repo relies on specific servers, note them; see my MCP server config that CLAUDE.md should mention for the configs themselves.
10. Prefer hooks for must-happen actions. CLAUDE.md instructions are advisory; hooks are deterministic. If something must run every time, make it a hook, not a sentence.
11. Write imperatively. "Use Pest" beats "We generally prefer Pest when possible." Ambiguity costs adherence.
12. Revise it like code. When Claude does something wrong twice, that's a missing line. Add it. Prune what's gone stale.

The defining trait of a strong CLAUDE.md is ruthless economy: under 200 lines, command-first, linter-free, and built on file references rather than pasted code, because Chroma's 2025 study confirmed every frontier model, Claude Opus 4 included, degrades measurably as context fills, making each unnecessary line a tax on every future session (Chroma, 2025).

Common CLAUDE.md Mistakes (Before and After)

The most common CLAUDE.md mistake is treating it like documentation instead of working memory: dumping everything in, including the things that hurt. The "lost in the middle" effect means models attend poorly to the center of a long context, with accuracy drops exceeding 30% (Morph, 2025). A bloated CLAUDE.md doesn't just waste tokens, it buries the rules that matter.

Three before/after fixes I make constantly:

Mistake 1: Pasting code.

• ❌ Before: a 40-line code block showing "how our service layer works."
• ✅ After: Business logic lives in app/Services/. Pattern example: app/Services/BookingService.php

Mistake 2: Re-stating style rules.

• ❌ Before: "Use 4 spaces, single quotes, trailing commas, max line length 120…"
• ✅ After: delete it. Run ./vendor/bin/pint before committing. The linter is the source of truth.

Mistake 3: Task-specific noise.

• ❌ Before: "When building the new export feature, use streaming and chunk at 1000 rows…"
• ✅ After: delete it. That belongs in the prompt or a plan doc, not in every session's memory.

Here's the counterintuitive part: the worst CLAUDE.md files I've seen aren't the empty ones; they're the thorough ones. A diligent developer documents everything, the file hits 600 lines, and adherence quietly drops because the important rules are now diluted among the trivia. An empty CLAUDE.md costs you nothing. A bloated one actively makes Claude worse. Less really is more here, and it's measurable.

Team CLAUDE.md Workflows: Committing, Code Review, Monorepos

For teams, CLAUDE.md is shared infrastructure: commit it, review changes to it, and treat it as part of the codebase. With 84% of developers now using AI tools, an unmanaged CLAUDE.md means every engineer gets different agent behavior on the same repo (Stack Overflow Developer Survey, 2025). Consistency is the whole point.

The practices that scale to teams:

• Commit CLAUDE.md, gitignore CLAUDE.local.md. The shared file is team policy; the local file is personal preference. Keep them separate.
• Review CLAUDE.md changes in PRs. A new rule changes how Claude behaves for everyone. That deserves the same scrutiny as a code change, and it catches "rules" that are really one person's opinion.
• Monorepos: layer, don't centralize. Put a lean root CLAUDE.md with org-wide conventions, then a focused CLAUDE.md inside each package. Claude Code reads up the tree and merges them, so each team owns its own context without one 1,000-line megafile.
• Pair it with skills. Reusable workflows belong in skills, not CLAUDE.md, so see my guide to using skills, which reference CLAUDE.md project context.

Treated as shared infrastructure, CLAUDE.md should be committed to git, reviewed in pull requests, and layered per-package in monorepos so Claude Code merges a lean root file with focused subdirectory files, giving every engineer identical agent behavior on the same codebase, a real concern given 84% of developers now use AI coding tools (Stack Overflow Developer Survey, 2025).

The Three-File CLAUDE.md System: CLAUDE.md / Subagents / Per-Skill Markdown

The most effective Claude Code setups don't cram everything into CLAUDE.md; they split context across three files that load at three different times, a pattern built directly on progressive disclosure (HumanLayer, 2025). This is the architecture that finally fixed my bloat problem: stop asking "what should I add to CLAUDE.md" and start asking "when should this load."

The three tiers:

1. CLAUDE.md, always loaded. The lean briefing: what, why, how, and boundaries. Stays under ~200 lines because it pays context tax on every single turn.
2. .claude/agents/*.md, loaded on delegation. Subagent definitions. When you delegate a focused job (a code review, a research sweep), that subagent gets its own context window and its own instructions, so the detail never touches your main session.
3. SKILL.md (per skill), loaded on demand. A skill's full instructions load only when the skill is invoked. This is where multi-step workflows and their detailed steps belong.

The mental model that unlocked this for me: CLAUDE.md is RAM, subagents and skills are disk. You don't load your entire hard drive into memory on boot; you page in what you need. Treat your always-loaded CLAUDE.md as the precious, expensive tier it actually is, and push everything situational down into files that load lazily. The result is a smaller core file and deeper capability, not a trade-off between them. More on the token economics of getting this wrong in my breakdown of the cost implications of a bloated CLAUDE.md.

Source: Claude Code documentation; progressive-disclosure pattern per HumanLayer, 2025

Frequently Asked Questions

What is a CLAUDE.md file?

A CLAUDE.md file is plain markdown that Claude Code automatically loads at the start of every session, giving the model persistent project memory: commands, architecture, and conventions it can't infer from code. Anthropic's own guidance is to keep it concise (Claude Code docs, 2026), since every line consumes context budget on each turn.

How long should a CLAUDE.md be?

Aim for under ~200 lines; shorter is better. Frontier models reliably follow only about 150–200 instructions, and Claude Code's system prompt already uses roughly 50 of them (HumanLayer, 2025). Beyond a couple hundred lines you risk context rot, where the rules that matter get diluted and adherence quietly drops.

Is CLAUDE.md the same as AGENTS.md?

No, but they do the same job. CLAUDE.md is Claude Code's native memory file; AGENTS.md is the cross-tool open standard backed by OpenAI, Google, Cursor, and others, which passed 20,000 adopting repos by August 2025 (Harness, 2026). If multiple agents touch your repo, symlink one to the other so there's a single source of truth.

How do I create a CLAUDE.md file?

Run /init inside any repo and Claude Code scaffolds a starter file from your project structure, then rewrite it by hand. Structure it around three questions (what the project is, why its parts exist, and how to build and test it) per HumanLayer's guidance (2025), then point to agent_docs/ for anything detailed instead of pasting it inline.

Does a bloated CLAUDE.md hurt performance?

Yes, measurably. Chroma's 2025 study found all 18 frontier models tested, including Claude Opus 4, degrade as context grows, some dropping from 95% to 60% accuracy past a threshold (Chroma, 2025). A long CLAUDE.md spends context budget every turn and buries critical rules through the "lost in the middle" effect, a 30%+ accuracy drop (Morph, 2025).

Should I commit CLAUDE.md to git?

Yes. Commit CLAUDE.md so the whole team gets consistent agent behavior, and gitignore CLAUDE.local.md for personal overrides. Review changes to it in pull requests, since a new rule changes how Claude behaves for every engineer, which matters when 84% of developers now use AI coding tools (Stack Overflow Developer Survey, 2025).

The Bottom Line

CLAUDE.md is the cheapest, highest-leverage configuration in Claude Code, and almost nobody treats it that way. The whole discipline fits in a sentence: write only what's true every session, keep it under ~200 lines, point to detail instead of pasting it, and let linters and hooks do the deterministic work.

If you do nothing else after reading this:

• Run /init in your main repo tonight, then cut the result in half.
• Move your exact test and build commands to the top. That's the single highest-ROI section.
• Delete every style rule your linter already enforces.
• Push detail down into agent_docs/, subagents, and skills so the always-loaded file stays lean.

The teams getting real value from Claude Code aren't the ones with the longest CLAUDE.md. They're the ones who treat it like working memory: precious, expensive, and ruthlessly pruned. Open yours, and ask of every line: does Claude need this on every session? If not, it doesn't belong there.

{
"@context": "https://schema.org",
"@graph": [
{
"@type": "BlogPosting",
"headline": "CLAUDE.md Best Practices: The Complete 2026 Guide",
"description": "CLAUDE.md best practices that cut wasted tokens and boost Claude Code accuracy: real examples, the 12 rules I follow daily, and how to beat context rot.",
"datePublished": "2026-06-10",
"dateModified": "2026-06-10",
"author": {
"@type": "Person",
"name": "Nishil Bhave"
},
"image": "https://maketocreate.com/images/generated/claude-md-best-practices-complete-guide-hero-v1-scattered.png",
"url": "https://maketocreate.com/claude-md-best-practices-complete-guide/",
"keywords": ["claude.md best practices", "claude md file", "how to write claude.md", "claude.md examples", "claude agents.md", "claude code claude.md best practices"]
},
{
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "What is a CLAUDE.md file?",
"acceptedAnswer": {
"@type": "Answer",
"text": "A CLAUDE.md file is plain markdown that Claude Code automatically loads at the start of every session, giving the model persistent project memory: commands, architecture, and conventions it can't infer from code. Anthropic's own guidance is to keep it concise, since every line consumes context budget on each turn."
}
},
{
"@type": "Question",
"name": "How long should a CLAUDE.md be?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Aim for under roughly 200 lines; shorter is better. Frontier models reliably follow only about 150 to 200 instructions, and Claude Code's system prompt already uses roughly 50 of them. Beyond a couple hundred lines you risk context rot, where the rules that matter get diluted and adherence quietly drops."
}
},
{
"@type": "Question",
"name": "Is CLAUDE.md the same as AGENTS.md?",
"acceptedAnswer": {
"@type": "Answer",
"text": "No, but they do the same job. CLAUDE.md is Claude Code's native memory file; AGENTS.md is the cross-tool open standard backed by OpenAI, Google, Cursor, and others, which passed 20,000 adopting repos by August 2025. If multiple agents touch your repo, symlink one to the other so there's a single source of truth."
}
},
{
"@type": "Question",
"name": "How do I create a CLAUDE.md file?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Run /init inside any repo and Claude Code scaffolds a starter file from your project structure, then rewrite it by hand. Structure it around three questions (what the project is, why its parts exist, and how to build and test it), then point to agent_docs/ for anything detailed instead of pasting it inline."
}
},
{
"@type": "Question",
"name": "Does a bloated CLAUDE.md hurt performance?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Yes, measurably. Chroma's 2025 study found all 18 frontier models tested, including Claude Opus 4, degrade as context grows, some dropping from 95% to 60% accuracy past a threshold. A long CLAUDE.md spends context budget every turn and buries critical rules through the lost-in-the-middle effect, a 30%+ accuracy drop."
}
},
{
"@type": "Question",
"name": "Should I commit CLAUDE.md to git?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Yes. Commit CLAUDE.md so the whole team gets consistent agent behavior, and gitignore CLAUDE.local.md for personal overrides. Review changes to it in pull requests, since a new rule changes how Claude behaves for every engineer, which matters when 84% of developers now use AI coding tools."
}
}
]
}
]
}