CLAUDE.md Best Practices: 9 Rules That Stop Claude From Ignoring You (2026)

CLAUDE.md Best Practices: 9 Rules That Stop Claude From Ignoring You (2026)

Most CLAUDE.md best practices posts give you a template and call it done, but the file you wrote last week is probably already being ignored, and you don't know why. The fix is rarely "add more rules." It's usually the opposite. We've shipped Claude Code on every recent client project, and these 9 rules are what actually move the needle: hierarchy that matches how Claude loads files, an instruction budget you can't break, the AGENTS.md decision, and the six reasons Claude silently drops your file mid-session.

Key Takeaways

• CLAUDE.md is project memory loaded into Claude Code's context, keep it under 200 lines or rules start dropping.
• Files load top-down: global, project root, subdirectory (lazy), and CLAUDE.local.md (personal, gitignored).
• Use AGENTS.md if you run Cursor or Copilot too; symlink CLAUDE.md to AGENTS.md to dual-target.
• If Claude ignores your file, 90% of the time it's length, vagueness, or a missing "why."

What CLAUDE.md Actually Does (And Why It Matters)

In short: CLAUDE.md is a markdown file Claude Code reads as project memory at the start of every session. It's not a system prompt, a hook, or a skill, it's advisory context that nudges Claude toward your team's conventions. Think of it less as documentation and more as a config file your AI pair programmer actually reads.

A lot of teams write CLAUDE.md like a README. That's the first mistake. A README explains the project to humans who can skim and skip. CLAUDE.md is consumed wholesale by Claude Code at session start, every line costing tokens and adherence. It's much closer to a config file or a set of test fixtures than to docs.

It's also not the only way to steer Claude. Hooks run deterministic actions (formatting, blocking commits). Skills bundle reusable workflows. CLAUDE.md sits in between as advisory context, Claude evaluates it, sometimes overrides it, and definitely forgets parts of it if you write too much. That distinction is the foundation for everything below, and it's why CLAUDE.md is one tool in the broader practice of context engineering, not a silver bullet.

Rule #1: Treat it like code, not docs. Version it. Review it in PRs. Trim it the way you'd refactor a bloated module. According to Anthropic's CLAUDE.md guide, the file is loaded with the same priority as any system instruction, which means a stale rule from six months ago is still actively shaping every response today.

How CLAUDE.md Loads: The 4-Tier Hierarchy

In short: Claude Code loads CLAUDE.md from four tiers: global (~/.claude/CLAUDE.md), project root, CLAUDE.local.md for personal overrides, and subdirectory files that lazy-load only when Claude reads files inside that directory. Sibling subdirectories never see each other's CLAUDE.md, which keeps claude code memory scoped tight.

The hierarchy is the single most misunderstood part of CLAUDE.md, and it's where 0 of the top 5 SERP results go deep. Here's what's actually happening under the hood:

Two terms worth pinning down: lazy loading and sibling isolation.

Lazy loading means a subdirectory CLAUDE.md doesn't enter Claude's context until Claude actually opens a file inside that directory. If you ask "fix the login bug" and Claude only touches backend/, your frontend/CLAUDE.md never loads. This is good, it keeps the context window clean, but it bites teams that put critical rules in subdirectories expecting them to always apply.

Sibling isolation is the corollary: frontend/CLAUDE.md and backend/CLAUDE.md never load each other. They share only what's in the project root. So if your frontend rules contradict your backend rules, that's fine. If they need to share a convention, push it up to the root file.

CLAUDE.local.md is the escape hatch. It's loaded but not committed, perfect for "I prefer pnpm but the team standardized on npm" style overrides. The catch: it's not auto-gitignored. You have to add it yourself. Forget that and you'll commit your personal rules into the team's repo.

Rule #4: Match instructions to where Claude actually reads them. Style rules for React components belong in frontend/CLAUDE.md, not the root. Database migration rules belong in backend/. The Anthropic Memory docs (updated November 2025) confirm this, the lazy-load behavior is intentional and load-bearing.

What to Put Inside CLAUDE.md (And What to Leave Out)

In short: Inside CLAUDE.md goes anything Claude can't infer from your code: build commands, naming conventions, anti-patterns your team has burned on, and the why behind each rule. Out goes anything in the README, anything in package.json, and any rule that changes weekly. claude code instructions should be testable and specific.

Here's a minimal CLAUDE.md that actually pulls weight:

# Project: techsy-app

## Commands
- Build: `pnpm build` (Turbopack — Webpack flags don't apply)
- Test: `pnpm test --run` (we use Vitest, not Jest)
- Lint: `pnpm lint` (will fail CI on warnings, not just errors)

## Conventions
- Server components by default. Add `'use client'` only when truly needed.
  Why: we hit 8s LCP last quarter from over-clienting.
- Database access only via `lib/db/` helpers — never raw SQL in routes.
  Why: row-level security policies live in those helpers.
- Tests colocate as `*.test.ts` next to the file under test.

## Don'ts
- Don't add a new dependency without opening a PR comment first.
- Don't use `any` — use `unknown` and narrow.

## Where to look
- Schema: `db/schema.ts`
- Auth flow: `lib/auth/README.md`

Now compare that to the anti-pattern version most teams ship:

# Project Rules

- Write clean, maintainable code.
- Follow best practices.
- Use TypeScript properly.
- Make sure tests pass.
- Be consistent with existing patterns.
- Document complex logic.

The second file isn't wrong. It's just useless. Claude already wants to write clean code. "Be consistent" doesn't tell Claude which pattern to be consistent with. Anthropic engineer Boris Cherny's public examples lean hard toward the first style, concrete commands, named tools, and the why behind decisions that aren't obvious from the codebase alone.

Rule #2: Be specific, not aspirational. "Write clean code" is aspirational. "Server components by default; add 'use client' only when truly needed" is testable. The same discipline underpins good prompt engineering: specific, testable instructions beat vague aspirations whether they live in a prompt or a CLAUDE.md.

Rule #3: Explain why every rule matters. The "why" isn't fluff, it's how Claude decides edge cases. A rule with a reason ("we hit 8s LCP from over-clienting") generalizes to similar situations. A rule without a reason gets ignored the moment context shifts. The pattern is also documented in Builder.io's CLAUDE.md guide.

Why Is Claude Ignoring Your CLAUDE.md? The Instruction Budget

In short: Claude isn't malicious, it's running out of attention. Past roughly 80 lines you'll notice rules dropping; past 200 lines, large blocks get ignored entirely; past 500 words of dense rules, adherence collapses. The fix is an instruction budget. Treat every line as a cost on claude code memory and per-rule adherence.

Recent research confirms what production users keep finding: instruction-following degrades non-linearly with rule count. The arxiv paper 2507.11538 on instruction-following capacity shows adherence per rule drops as you stack more, and HumanLayer's analysis of CLAUDE.md in production echoes the same finding.

Translation: every rule you add makes every other rule slightly less likely to be followed. So a 400-line CLAUDE.md isn't 4x as effective as a 100-line one. It's often less effective, because the rules you actually care about get diluted by the ones you wrote on a Friday three months ago and never deleted.

In our CLAUDE.md files, anything past line 150 starts visibly losing adherence. By line 250 we've seen Claude skip entire sections. So we cap.

wc -l CLAUDE.md

That's the whole tool. Run it. If you're over 200, you're over budget. The hard rule we ship to clients:

Treat CLAUDE.md like a 200-line budget. Every line costs adherence. Spend it where it matters.

Rule #1 reinforced: Keep it short. Under 200 lines. Under 500 words of dense rules. If you find yourself wanting to add automation rules ("always run prettier after edits"), those probably belong in Claude Code hooks instead, hooks are deterministic and don't cost instruction-budget tokens.

Should You Use CLAUDE.md, AGENTS.md, .cursorrules, or copilot-instructions?

In short: If you only use Claude Code, CLAUDE.md is fine. If you use two or more agent CLIs (Codex, Cursor, Copilot, Sourcegraph), switch to AGENTS.md and symlink CLAUDE.md to AGENTS.md. AGENTS.md emerged in late 2025 as a cross-tool standard, most modern agents fall back to it, so a single file feeds every ecosystem.

This is the question 0 of the top 5 results actually answer. Here's the matrix:

The dual-target trick is one line:

ln -s AGENTS.md CLAUDE.md

That's it. Now Claude Code, Codex, and any AGENTS.md-aware tool read the same file. Update once, every agent picks it up. The AGENTS.md spec is open and intentionally minimal, it's just markdown with conventional sections.

Two real-world wrinkles. First: if your team has a Cursor power user, Cursor's .cursorrules takes a different approach, single file, no hierarchy, more rigid format. Some teams keep both: AGENTS.md for the shared rules, .cursorrules for Cursor-specific quirks. Second: Copilot's .github/copilot-instructions.md doesn't fall back to AGENTS.md, so Copilot-heavy teams need a separate file.

If you're picking an agent stack from scratch, our Claude Code vs Cursor vs Copilot breakdown covers the trade-offs at the use level. The short version: Claude Code's hierarchy is the most powerful for monorepos, Cursor's UX wins for solo work, Copilot's IDE integration is still the smoothest for incremental adoption.

Rule #9: Use AGENTS.md if you run more than one agent CLI. Don't maintain two files saying the same thing. Pick the file most of your stack reads, symlink the rest.

CLAUDE.md vs Hooks vs Skills: The Decision Triangle

In short: CLAUDE.md = advisory context. Hooks = deterministic actions. Skills = bundled capabilities. Pick the wrong one and you'll burn instruction budget on something a hook should handle, or write a CLAUDE.md rule for something only a skill can deliver. The triangle is the cheapest way to keep CLAUDE.md lean.

Three tools, three jobs. The mistake we see most often: putting "always run prettier after editing" in CLAUDE.md. Claude reads it. Claude sometimes runs prettier. You're frustrated. The fix is to move that line out of CLAUDE.md and into a hook, because hooks fire deterministically every time, with no advisory wiggle room.

If a rule must always fire, it belongs in a hook. If it's a style preference Claude can evaluate against context, it belongs in CLAUDE.md. If it's a multi-step workflow with bundled assets (templates, scripts, prompts), it belongs in a skill.

Rule #8: Pick CLAUDE.md vs hooks vs skills correctly, putting a hook in CLAUDE.md is the most common waste of instruction budget. Configure deterministic actions with Claude Code hooks and package reusable workflows as Claude skills. Your CLAUDE.md gets shorter, your guardrails get firmer, and Claude stops "forgetting" the rules that matter.

Monorepo Patterns: Nested CLAUDE.md, @imports, and .claude/rules/

In short: In a monorepo, keep the root CLAUDE.md tiny, pointers and shared conventions only. Push specifics into apps/*/CLAUDE.md so each subtree has scoped rules. Use @imports to share modular rule files via .claude/rules/. This is progressive disclosure, Claude pulls each piece only when relevant.

A typical monorepo CLAUDE.md tree:

.
├── CLAUDE.md                        # 30 lines — points to subdirs and shared rules
├── .claude/
│   └── rules/
│       ├── style.md
│       ├── testing.md
│       └── security.md
├── apps/
│   ├── web/
│   │   └── CLAUDE.md                # Next.js-specific rules
│   └── api/
│       └── CLAUDE.md                # Fastify-specific rules
└── packages/
    └── shared/
        └── CLAUDE.md                # Library author rules

The @import syntax lets the root file pull in shared rule chunks without restating them:

# Root CLAUDE.md

This is a Turborepo. See subdir CLAUDE.md for app-specific rules.

@import .claude/rules/style.md
@import .claude/rules/testing.md
@import .claude/rules/security.md

## Top-level commands
- `pnpm dev` runs all apps in parallel
- `pnpm test` runs every workspace's test script

This is progressive disclosure in practice. The root file is a 30-line pointer. Each subdirectory CLAUDE.md adds 50–80 lines of focused rules. The .claude/rules/ files hold convention chunks that multiple subdirectories can pull in. Nothing is duplicated, nothing is missed, and no single file exceeds the instruction budget.

The lazy-loading rule from earlier matters even more here: when Claude works on apps/web/Button.tsx, it sees the root file plus apps/web/CLAUDE.md plus the @import-ed rule files. It does not see apps/api/CLAUDE.md. That's the whole point, backend conventions don't pollute frontend context, and your context window stays usable.

Rule #6: Use @imports to keep the root file under 200 lines. The Anthropic Best Practices for Claude Code guide treats this as the standard monorepo pattern. Subagents inherit parent CLAUDE.md context too, which is worth knowing if you're nesting workflows, see context engineering for how that interacts with subagent design.

6 Reasons Claude Ignores Your File (And the Fix for Each)

In short: When Claude ignores CLAUDE.md, it's almost always one of six causes: file too long, vague phrasing, missing "why," context compaction, conflicting parent file, or wrong filename. Each has a 60-second fix. Test in a fresh session after every change, that's Rule #7.

1. File too long (>200 lines / >500 words)

Run wc -l CLAUDE.md. If it's over 200, trim aggressively. Move automation rules to hooks. Move workflows to skills. Split shared chunks into .claude/rules/ and pull them with @import. The most common reason Claude "stopped following" your rules is that the file got too long over time and adherence quietly collapsed.

2. Vague phrasing ("write clean code")

Replace every aspirational rule with a specific, testable one. "Be consistent" is invisible to Claude. "Use server components by default; only add 'use client' for forms or interactive UI" is something Claude can actually apply.

3. Missing "why"

Rules without reasons don't generalize. Claude can't infer when to bend the rule because it doesn't know what the rule is protecting against. Every non-obvious rule gets a one-liner: "we use unknown not any because we had three runtime crashes from typed-as-any API responses last quarter."

4. Context compaction discarded it

Long sessions trigger compaction, Claude summarizes earlier context to fit the window, and CLAUDE.md content sometimes gets summarized into oblivion. The fix: /clear after major context burns, or restart the session entirely. This is exactly what GitHub Issue #17530 keeps surfacing.

5. Conflicting parent CLAUDE.md

Global says "use 4 spaces." Project root says "use 2 spaces." Subdirectory says nothing. Claude picks one, sometimes the wrong one. Audit ~/.claude/CLAUDE.md and project root for contradictions. Whichever is more specific should win, but only if you make that explicit.

6. Wrong file location or filename case

Claude.md and CLAUDE.md are different files on Linux and macOS. So are claude.md and CLAUDE.md. Confirm the path is exactly ./CLAUDE.md (all caps), and confirm Claude Code is launched from the directory containing it. GitHub Issue #668 is full of cases where the file existed but Claude couldn't see it because of pathing.

Rule #7: Test in a fresh session. After any CLAUDE.md change, open a new session and ask Claude to "summarize the rules in CLAUDE.md." If the summary misses something, the file isn't doing its job.

Your First CLAUDE.md in 10 Minutes: A 5-Step Starter

In short: Run /init to seed a draft, trim it to 6–10 real rules with reasons, add 3 commands Claude should know, add 2 anti-patterns your team has hit, then test in a fresh session by asking Claude to summarize the file. Total time: about 10 minutes. The 5-step recipe is what we use on day 1 of every new repo.

1. Run /init to seed a draft. Claude Code's /init command scans your repo and writes a starter CLAUDE.md. Don't ship what it writes. /init output is a starting point, not a finished file, and frankly, most of what it generates can go.

2. Trim it to 6–10 lines of actual rules with reasons. Delete anything generic. Delete anything in the README. Keep only rules Claude can't infer from the code itself.

3. Add 3 commands Claude should know. Build, test, lint. Include the exact command and any non-obvious flags. If you use Vitest not Jest, say so.

4. Add 2 anti-patterns this team has hit. Real ones. "Don't use any because we had three runtime crashes" beats "use TypeScript properly" every time.

5. Open a fresh session and verify. Ask Claude to "summarize the rules in CLAUDE.md." If it misses something, the file is too long, too vague, or missing a "why." Fix and repeat.

Rule #5: Don't auto-generate from /init alone. /init is a starting point, not a finished file. The 8 minutes you spend trimming it are where the value is.

FAQ

What is a CLAUDE.md file?

A CLAUDE.md file is a markdown file Claude Code reads as project memory at the start of every session. It tells Claude your conventions, commands, and anti-patterns so it doesn't have to guess. It works at four levels: global, project root, subdirectory (lazy-loaded), and a personal CLAUDE.local.md you keep gitignored.

How long should a CLAUDE.md file be?

Under 200 lines and under 500 words of dense rules. Past those thresholds, Claude's instruction-following degrades, every rule you add makes every other rule slightly less likely to be followed. Treat it as a fixed budget. If you need more, split into subdirectory CLAUDE.md files and use @import for shared chunks.

Where should I put CLAUDE.md?

The main one goes in your project root (./CLAUDE.md) and gets committed. Add subdirectory CLAUDE.md files for app-specific rules in monorepos. Put cross-project preferences in ~/.claude/CLAUDE.md. Use CLAUDE.local.md for personal overrides you don't want committed, but remember to gitignore it manually.

Why is Claude ignoring my CLAUDE.md?

90% of the time it's one of three things: the file is too long (over 200 lines), the rules are vague ("write clean code"), or rules are missing a "why" Claude can use to apply them. Run wc -l CLAUDE.md, then audit for specificity. Test changes in a fresh session by asking Claude to summarize the file.

Should I use CLAUDE.md or AGENTS.md?

If your team only uses Claude Code, stick with CLAUDE.md. If you use two or more agent CLIs (Codex, Cursor, Sourcegraph), switch to AGENTS.md and symlink CLAUDE.md to it: ln -s AGENTS.md CLAUDE.md. Most modern agent CLIs fall back to AGENTS.md, so one file feeds every tool.

Should I run /init to generate CLAUDE.md?

Yes, as a draft. No, as a finished file. /init scans your repo and produces a starter, but it's verbose and generic. Anthropic and HumanLayer both recommend trimming aggressively after running /init. The 8 minutes you spend cutting and adding "why" lines are where the file actually becomes useful.

How do CLAUDE.md files work in a monorepo?

The root CLAUDE.md stays tiny, pointers and shared rules only. Each app gets its own apps/*/CLAUDE.md with scoped conventions. Subdirectory files lazy-load only when Claude reads files inside that subtree, so siblings stay isolated. Use @import .claude/rules/style.md to share modular rule chunks without duplicating them across apps.

What's the difference between CLAUDE.md, hooks, and skills?

CLAUDE.md is advisory context, Claude reads it and usually follows it. Hooks are deterministic actions that always fire (formatting, blocking commits). Skills are bundled capabilities for reusable workflows with assets. Use CLAUDE.md for style guidance, hooks for hard rules, and skills for multi-step jobs you'll repeat across projects.

How Techsy Approaches This

At Techsy, every Claude Code project we ship has a CLAUDE.md under 150 lines and an AGENTS.md symlink. We treat the file like code, version it, review changes in PRs, and re-test in fresh sessions before merge. Need help wiring AI agents into your dev workflow? Get a free consultation.