CLAUDE.md Best Practices: The Complete 2026 Guide

A developer's guide to CLAUDE.md files recommends keeping them under 200 lines with only universally applicable rules, as bloated files degrade model accuracy from 95% to 60% based on a 2025 Chroma study. The file loads into 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. The guide advises using file:line references to detailed documentation rather than pasted code blocks, and warns against confusing CLAUDE.md with AGENTS.md or `.claude/agents/*.md` files.

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 areunder ~200 lines, contain onlyuniversally-applicablerules 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 https://maketocreate.com/the-complete-claude-code-workflow-how-i-ship-10x-faster/ 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 everysession, 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 referencesand pointers to agent docs/ , never pasted code blocks. Progressive disclosure keeps the always-loaded file small.CLAUDE.md ≠ AGENTS.md ≠They're three distinct surfaces; mixing them up is the most common configuration mistake I see. .claude/agents/ .md . 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 https://code.claude.com/docs/en/best-practices , 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: ./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. ./CLAUDE.local.md gitignored for personal overrides you don't want to commit. ~/.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 https://code.claude.com/docs/en/best-practices , 2026 . 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 https://survey.stackoverflow.co/2025/ai/ , 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 https://www.uncoveralpha.com/p/anthropics-claude-code-is-having , 2026 , and it crossed a $2.5B revenue run-rate by February 2026 UncoverAlpha https://www.uncoveralpha.com/p/anthropics-claude-code-is-having , 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. 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 https://www.humanlayer.dev/blog/writing-a-good-claude-md , 2025 . Frontier models reliably follow only about 150–200 instructions, and Claude Code's system prompt already consumes roughly 50 of those HumanLayer https://www.humanlayer.dev/blog/writing-a-good-claude-md , 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: legacy/ , generated files, vendored code . 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 https://www.humanlayer.dev/blog/writing-a-good-claude-md , 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 https://www.humanlayer.dev/blog/writing-a-good-claude-md , 2025 . 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 https://www.humanlayer.dev/blog/writing-a-good-claude-md , 2025 . Illustrative estimate based on ~13 tokens/line and a 200K context window; Source: HumanLayer instruction-budget analysis, 2025 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 https://www.harness.io/blog/the-agent-native-repo-why-agents-md-is-the-new-standard , 2026 . Here's the distinction: .claude/agents/ .md :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 https://www.harness.io/blog/the-agent-native-repo-why-agents-md-is-the-new-standard , 2026 . Source: Claude Code documentation and AGENTS.md specification, 2026 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 https://www.trychroma.com/research/context-rot , 2025 . See lib/parser.ts:42 beats a 30-line snippet that goes stale. agent docs/ .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 https://www.trychroma.com/research/context-rot , 2025 . 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 https://www.morphllm.com/context-rot , 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. Business logic lives in app/Services/. Pattern example: app/Services/BookingService.php Mistake 2: Re-stating style rules. Run ./vendor/bin/pint before committing. The linter is the source of truth. Mistake 3: Task-specific noise. 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. 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 https://survey.stackoverflow.co/2025/ai/ , 2025 . Consistency is the whole point. The practices that scale to teams: CLAUDE.md , gitignore CLAUDE.local.md . 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.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 https://survey.stackoverflow.co/2025/ai/ , 2025 . 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 https://www.humanlayer.dev/blog/writing-a-good-claude-md , 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: CLAUDE.md , always loaded. .claude/agents/ .md , loaded on delegation. SKILL.md per skill , loaded on demand.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 https://maketocreate.com/claude-code-cost-in-2026-honest-pro-vs-max-vs-api-guide/ . Source: Claude Code documentation; progressive-disclosure pattern per HumanLayer, 2025 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 https://code.claude.com/docs/en/best-practices , 2026 , since every line consumes context budget on each turn. 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 https://www.humanlayer.dev/blog/writing-a-good-claude-md , 2025 . Beyond a couple hundred lines you risk context rot, where the rules that matter get diluted and adherence quietly drops. 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 https://www.harness.io/blog/the-agent-native-repo-why-agents-md-is-the-new-standard , 2026 . If multiple agents touch your repo, symlink one to the other so there's a single source of truth. 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 https://www.humanlayer.dev/blog/writing-a-good-claude-md 's guidance 2025 , then point to agent docs/ for anything detailed instead of pasting it inline. 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 https://www.trychroma.com/research/context-rot , 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 https://www.morphllm.com/context-rot , 2025 . 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 https://survey.stackoverflow.co/2025/ai/ , 2025 . 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: /init in your main repo tonight, then cut the result in half. 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://dev.to/context ": " https://schema.org https://schema.org ", " @graph https://dev.to/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 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/ 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." } } } }