The Ultimate Guide to CLAUDE.md in 2026

What Is CLAUDE.md?

CLAUDE.md is a markdown file that Claude Code automatically reads at the start of every conversation. It holds project-specific instructions, conventions, and context that you'd otherwise repeat in every prompt — your tech stack, build commands, coding standards, and architectural decisions.

Think of it as an onboarding document. Every time Claude Code starts a session, it knows nothing about your codebase. CLAUDE.md is how you bring it up to speed instantly.

Why CLAUDE.md Matters So Much

CLAUDE.md sits at the top of the leverage hierarchy in your AI-assisted development workflow:

CLAUDE.md           →  affects every session, every task, every output
  ↓
Research & Planning →  shapes implementation approach
  ↓
Implementation      →  produces the actual code

A bad line in your code is a bad line of code. A bad line in your CLAUDE.md creates bad lines across every single task Claude works on. Conversely, a well-crafted CLAUDE.md compounds quality improvements across your entire workflow.

This is why you should never auto-generate your CLAUDE.md using /init or similar tools. Hand-craft every line.

The File Hierarchy: Where CLAUDE.md Files Live

Claude Code reads CLAUDE.md files from multiple locations in a specific hierarchy. Understanding this is critical for organizing instructions effectively.

Memory File Locations

Hierarchy Rules

• Files higher in the directory tree are loaded first; more specific files take precedence.
• CLAUDE.local.md is automatically added to .gitignore — perfect for personal preferences that shouldn't be committed.
• All .md files in .claude/rules/ are loaded as project memory with the same priority as .claude/CLAUDE.md.
• Child directory CLAUDE.md files load on demand, not at startup.

Scoped Rules with YAML Frontmatter

Rules in .claude/rules/ can be conditionally scoped to specific file patterns:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

Rules without a paths field load unconditionally.

The Golden Rule: Less Is More

Research indicates that frontier LLMs can reliably follow approximately 150–200 instructions. Claude Code's own system prompt already consumes roughly 50 of those. That leaves you with around 100–150 instructions before quality starts degrading.

Here's what happens as instruction count increases:

• Performance degrades uniformly — Claude doesn't just ignore later instructions, it starts ignoring all of them more frequently.
• Smaller models exhibit exponential decay in instruction-following; larger thinking models show linear decay.
• LLMs bias toward instructions at the peripheries of the prompt (beginning and end).

Practical Implications

• Keep your root CLAUDE.md under 300 lines. Shorter is better — some high-performing teams keep theirs under 60 lines.
• Every line must be universally applicable. If an instruction only matters for a specific task, it doesn't belong in the root file.
• Claude Code wraps your file with a system reminder telling Claude it can ignore content it deems irrelevant. The more noise in your file, the more likely Claude ignores even the important parts.

What to Include: The WHAT, WHY, and HOW Framework

Structure your CLAUDE.md around three pillars:

1. WHAT — The Project Map

Tell Claude about your tech stack, project structure, and key dependencies. This is especially important in monorepos.

## Project Overview

This is a React Native mobile app built with Expo (SDK 52), using Supabase
for auth and database, and RevenueCat for subscriptions.

## Project Structure

- `app/` — Expo Router file-based routing
- `components/` — Shared UI components
- `lib/` — Utilities, Supabase client, API helpers
- `supabase/` — Database migrations and edge functions

2. WHY — Purpose and Context

Explain what the project does and why architectural decisions were made. This helps Claude make better judgment calls.

## Purpose

Supascript is a teleprompter app for content creators. The core value prop
is simplicity — users should be recording within 10 seconds of opening the app.

## Key Decisions

- We use Expo Router (not React Navigation) for deep linking support
- Auth uses Supabase with both Google and Apple Sign-In
- Subscriptions go through RevenueCat, not direct StoreKit

3. HOW — Working on the Project

Give Claude the exact commands it needs to build, test, and verify its work.

## Development Commands

- `bun install` — Install dependencies (NOT npm)
- `bun run dev` — Start Expo dev server
- `bun run typecheck` — Run TypeScript compiler checks
- `bun test` — Run test suite

## Verification

After making changes, always run:
1. `bun run typecheck`
2. `bun test`

What to Exclude: Common Mistakes

Don't Include Exhaustive Code Style Guidelines

LLMs are in-context learners. If your codebase consistently follows a style, Claude will pick it up by reading your code. Embedding detailed style rules wastes instruction budget and degrades performance.

Instead: use a linter and formatter (like Biome, ESLint, or Prettier) and set up a Claude Code hook that runs them automatically.

// .claude/hooks.json — example stop hook
{
  "stop": [
    {
      "command": "bun run lint:fix && bun run format",
      "description": "Auto-fix lint and format issues"
    }
  ]
}

Don't Include Task-Specific Instructions

Instructions about how to structure a database schema, write a specific API endpoint, or handle a one-off migration don't belong in your root CLAUDE.md. They dilute universally applicable instructions.

Don't Include Obvious Programming Wisdom

Claude already knows how to write clean code, handle errors, and follow common patterns. Instructions like "write clean, readable code" or "handle edge cases" waste instruction budget.

Don't Stuff "Hotfixes" for Bad Behavior

If Claude did something wrong once, resist the urge to add a rule about it. Instead, ask yourself whether the fix is genuinely universally applicable. If not, find a better solution (hooks, slash commands, scoped rules).

Progressive Disclosure: The Scalability Pattern

For larger projects, use progressive disclosure — give Claude a map of where to find detailed information, rather than dumping everything into one file.

Create a Docs Directory

agent_docs/
  ├── building_the_project.md
  ├── running_tests.md
  ├── code_conventions.md
  ├── service_architecture.md
  ├── database_schema.md
  └── deployment_process.md

Reference Them in CLAUDE.md

## Deep Reference Docs

Before starting work, read whichever of these are relevant to your task:

- `agent_docs/building_the_project.md` — Build system, dependencies, compilation
- `agent_docs/running_tests.md` — Test framework, fixtures, mocking patterns
- `agent_docs/service_architecture.md` — How services communicate
- `agent_docs/database_schema.md` — Schema design, migrations, naming conventions
- `agent_docs/deployment_process.md` — CI/CD, staging, production deploys

Use @include for Auto-Loading

Claude Code supports importing external files directly into your CLAUDE.md:

@agent_docs/building_the_project.md

Imported files can recursively import additional files, up to 5 levels deep.

Prefer Pointers Over Copies

Don't copy code snippets into your docs — they go stale fast. Instead, use file:line references:

See the auth middleware pattern in `src/middleware/auth.ts:15-42`

Scoped Rules: Right Context at the Right Time

Use .claude/rules/ for instructions that only apply to specific parts of your codebase:

.claude/rules/
├── frontend/
│   ├── react.md      # React component patterns
│   └── styles.md     # Styling conventions
├── backend/
│   ├── api.md        # API endpoint patterns
│   └── database.md   # Query and migration patterns
└── general.md        # Always loaded (no paths frontmatter)

Each file can use YAML frontmatter to scope when it loads:

---
paths:
  - "src/components/**/*.tsx"
  - "src/screens/**/*.tsx"
---

# React Component Rules

- Use functional components with hooks
- Props interfaces go in the same file, exported separately
- Co-locate styles with components

This keeps your root CLAUDE.md lean while still giving Claude detailed guidance exactly when it needs it.

CLAUDE.local.md: Personal Preferences

Use CLAUDE.local.md for preferences that shouldn't be shared with your team:

# Personal Preferences

- I use the VS Code terminal; don't suggest iTerm commands
- When explaining things, be concise — I'm a senior engineer
- I prefer seeing the full diff before you commit anything
- My local Supabase runs on port 54321

This file is auto-gitignored, so teammates won't inherit your personal setup.

Real-World Example: A Well-Structured CLAUDE.md

Here's a complete example that follows all the best practices:

# Supascript — Teleprompter App

## Overview

React Native app (Expo SDK 52) for content creators. Supabase backend,
RevenueCat subscriptions, Expo Router navigation.

## Stack

- Runtime: Expo (SDK 52) with Expo Router v4
- Language: TypeScript (strict mode)
- Backend: Supabase (auth, database, edge functions)
- Payments: RevenueCat
- Package manager: bun (NOT npm or yarn)

## Project Structure

- `app/` — File-based routing (Expo Router)
- `components/` — Reusable UI components
- `lib/` — Supabase client, helpers, constants
- `hooks/` — Custom React hooks
- `supabase/functions/` — Edge functions
- `supabase/migrations/` — Database migrations

## Commands

- `bun install` — Install dependencies
- `bun run dev` — Start dev server
- `bun run typecheck` — Type check
- `bun test` — Run tests
- `bun run eas:build` — Build with EAS

## Verification

Always run after changes: `bun run typecheck && bun test<kbd>## Key Patterns

- Auth: Supabase Auth with Google</kbd>+<kbd>Apple Sign-In (see</kbd>lib/auth.ts`)
- Navigation: Expo Router with `(auth)` and `(app)<kbd>groups
- Data fetching: React Query</kbd>+<kbd>Supabase client (see</kbd>hooks/useQuery.ts`)

## Reference Docs

Read relevant docs before starting a task:
- `docs/architecture.md` — System design and data flow
- `docs/auth-flow.md` — Authentication implementation details
- `docs/deployment.md` — App Store and EAS submission process

This is ~40 lines. It covers WHAT, WHY, and HOW without bloat.

Advanced Patterns

Use Hooks Instead of Instructions

Rather than telling Claude "always run the linter," set up a hook that does it automatically:

{
  "stop": [
    {
      "command": "bun run typecheck",
      "on_fail": "ask_claude_to_fix"
    }
  ]
}

Use Slash Commands for Recurring Workflows

Create .claude/commands/ for task-specific workflows instead of cramming them into CLAUDE.md:

<!-- .claude/commands/pr.md -->
Review the current git diff. Check for:
1. Type safety issues
2. Missing error handling
3. Consistent naming with existing patterns

Then create a PR with a descriptive title and summary.

Invoke with /pr in Claude Code.

Use Auto Memory

Claude Code can write its own notes in ~/.claude/projects/<project>/memory/. The MEMORY.md entrypoint is loaded into every session (first 200 lines). Let Claude learn organically about your project over time rather than trying to front-load everything.

Quick Reference Checklist

Use this checklist when writing or reviewing your CLAUDE.md:

• Under 300 lines (ideally under 100)
• Every instruction is universally applicable to all tasks
• Includes project overview (stack, structure, purpose)
• Includes exact build/test/verify commands
• Uses progressive disclosure for detailed docs
• No code style rules (use linters and formatters instead)
• No task-specific instructions (use scoped rules or slash commands)
• No auto-generated content (hand-crafted, every line intentional)
• Pointers, not copies (reference files instead of duplicating content)
• Personal preferences in CLAUDE.local.md, not the shared file
• Scoped rules use .claude/rules/ with YAML frontmatter paths

Key Takeaways

1. CLAUDE.md is the highest-leverage file in your workflow. Treat every line as precious.
2. Less is more. Fewer, better instructions outperform a wall of text every time.
3. Universally applicable only. Task-specific context belongs in scoped rules, slash commands, or reference docs.
4. Use progressive disclosure. Point Claude to detailed docs; don't inline everything.
5. Don't use it as a linter. Deterministic tools (linters, formatters, hooks) are faster, cheaper, and more reliable.
6. Hand-craft it. Auto-generation produces mediocre results for the highest-leverage file in your setup.
7. Use the full hierarchy. Root CLAUDE.md, CLAUDE.local.md, .claude/rules/, slash commands, and hooks each serve a specific purpose.

*Last updated: February 2026.