Claude ignores your CLAUDE.md — it’s probably too long

CLAUDE.md is loaded into context in full at the start of every session — it is “context,” not “enforced configuration.” The longer the file, the more easily any single rule drowns in the noise. The official docs say it outright: a bloated CLAUDE.md causes Claude to ignore your actual instructions.

One-line answer

Steps

1. First confirm the file actually loads. Run /context in a session and look for your CLAUDE.md in the Memory files list. OfficialIf it isn’t listed, Claude can’t see it — that’s a path problem, not a length problem. Listed but not followed? Keep going.
2. Run a line-by-line “deletion test.” OfficialThe official recommendation is to keep a single file under 200 lines; anything longer consumes more context and lowers adherence — and the docs warn explicitly that “if Claude ignores a rule, the file is most likely too long and the rule is drowning in noise.” Typical keeps and deletes:

   Keep (what Claude can’t guess)	Delete (what Claude figures out itself)
   Build/test commands it couldn’t guess	Anything inferable by reading the code
   Code style that differs from the defaults	Standard conventions of the language
   Repo etiquette (branch naming, PR conventions)	Detailed API docs (a link is enough)
   Project-specific architecture decisions, environment traps	File-by-file codebase descriptions, long tutorials
   Non-obvious gotchas	Filler like “write clean code”

3. Move rules that only apply locally into .claude/rules/. OfficialMarkdown files in the rules directory can scope themselves via a paths field in the YAML frontmatter (e.g. src/api/**/*.ts) so they enter context only when Claude reads a matching file — no match, no space used. A rule without paths still loads every time, so don’t just move the pile to a different directory.
4. Move “occasionally used, multi-step procedures” into skills. OfficialSkills load on demand: they enter context only when you invoke them or Claude judges them relevant — a good fit for domain knowledge and reusable workflows. Rule of thumb: CLAUDE.md holds “facts true in every session,” skills hold “procedures only some tasks need.”
5. Turn “must happen every single time” actions into hooks. OfficialCLAUDE.md is advisory context with no enforcement power; hard constraints like “must lint before commit” or “never touch the migrations directory” are only guaranteed when written as hooks. The official fix guidance, in spirit: instructions Claude gets right without a reminder — delete them or convert them into hooks.
6. Clean out contradictions and lazy splits. OfficialWhen two rules conflict, Claude may pick either one; and @path/to/file imports are purely organizational — imported files are still fully loaded at startup and save no context whatsoever. From v2.1.206 you can run /doctor, which suggests trims for a checked-in CLAUDE.md: cut directory structures and dependency lists derivable from the code; keep the traps, the rationale, and the non-default conventions.
7. Verify the effect. Our takeAfter slimming down, watch a few sessions: are the previously ignored rules now being followed? The official docs also suggest adding “IMPORTANT” / “YOU MUST” emphasis to a few critical rules — but that is the final seasoning, not the cure for a long file.

Copy-paste prompt

Help me slim down @CLAUDE.md to under 200 lines:
1. Review it line by line; for each line answer: "Would you make a mistake without it?" If not, mark it for deletion.
2. Find rules that contradict or duplicate each other, and recommend which to keep.
3. Rewrite rules that only apply to specific directories/file types as rule files under .claude/rules/
   with paths frontmatter; rewrite multi-step procedures as skills under .claude/skills/.
4. List the actions that must be enforced every time (e.g. lint before commit) and suggest the matching hook config.
5. Output: the full slimmed-down CLAUDE.md + a migration list (what moved where, and why).
Show me the plan first; only change files after I confirm.

Sources & last verified

• OfficialHow Claude remembers your project (memory) — the 200-line target, path-scoped rules, imports saving no context, /doctor trims, conflicting rules picked arbitrarily; fetched 2026-08-05.
• OfficialBest practices — Write an effective CLAUDE.md / The over-specified CLAUDE.md — the deletion test, the keep/delete table, “bloat causes ignored instructions”; fetched 2026-08-05.
• Last verified: 2026-08-05 · volatility: high (tied to concrete product mechanics — rules/skills/hooks and /doctor; re-checked periodically).