CLAUDE.md too long? What to keep and what to move

How long should CLAUDE.md be?

Under 200 lines per file. That is Anthropic's own guidance in the Claude Code memory docs: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence."

Two details matter. First, @path imports do not save anything: the docs note that imported files also load at launch, so splitting a long file into imports keeps the same cost. Second, every CLAUDE.md from the project root up through parent folders loads at launch, so a long file in a parent folder is paid for in every repo below it.

Line count is a proxy for the real problem. A short file of vague advice ("write clean code") helps less than a short file of specific facts: the exact command, the exact path, the exact rule. Specific beats long.

The same applies to AGENTS.md. Recent versions of Claude Code read AGENTS.md when a folder has no CLAUDE.md, and you can import it with @AGENTS.md or symlink it. A long AGENTS.md has the same problem in every agent that reads it.

sourcesClaude Code docs: memory

Why does Claude ignore parts of my CLAUDE.md?

Because CLAUDE.md is context, not configuration. Anthropic's docs say Claude treats these files "as context, not enforced configuration". The longer and vaguer the file, the more each line competes with the code and the task in front of the model.

The usual causes are the same in every long file: rules that only apply to one folder, multi-step procedures that matter once a week, duplicates that drifted apart, and contradictions. On contradictions, the docs say Claude may pick one arbitrarily.

Thoughtworks placed "agent instruction bloat" in the Caution ring of its Technology Radar (Vol. 34, April 2026), recommending teams "be deliberate and selective with instructions" and continuously refine toward a minimal, coherent set.

1. Symptom: Claude follows a rule in one session and not the next. Cause: the rule competes with too much else.
2. Symptom: Claude follows the wrong one of two rules. Cause: a contradiction, often an old line nobody deleted.
3. Symptom: Claude forgets a rule after a long session. Cause: it lived in a nested file or chat, not the root CLAUDE.md, which is re-read after /compact.

sourcesClaude Code docs: memoryThoughtworks Radar: agent instruction bloat

What should stay in CLAUDE.md, and what should move?

Keep what Claude needs on almost every task, in one line each. Move everything else to the place that loads it only when it is needed, or that enforces it instead of asking. Anthropic's guidance: "If an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule."

A quick test for each line: would Claude make a mistake on most tasks without it? If not, it does not belong in the always-loaded file. If the mistake would be costly, it belongs in something enforced, not in a sentence.

sourcesClaude Code docs: memoryClaude Code docs: skills

How do I shorten a long CLAUDE.md step by step?

Measure, sort every line by where it belongs, move it, then check what loads. The commands below are all built into Claude Code.

1. 1

   Measure

   Count the lines in every instruction file Claude loads, then open /context in Claude Code to see the memory files and their share of the window.

   wc -l CLAUDE.md AGENTS.md .claude/rules/*.md 2>/dev/null

2. 2

   Run the prompt audit

   In recent versions of Claude Code, /doctor prompt-audit reviews your instruction files. Use /memory to open and edit them.

   /doctor prompt-audit

3. 3

   Move folder rules to path-scoped rules

   A rule with paths frontmatter loads only when Claude touches a matching file.

   ---
   paths:
     - "src/api/**/*.ts"
   ---
   # API handler rules
   - Validate input with the zod schema next to the handler.
   - Return errors as { code, message }. Never leak stack traces.
   - Every new route gets a test in tests/api.

4. 4

   Move procedures to skills

   Each multi-step procedure becomes .claude/skills/<name>/SKILL.md. Only its name and description load until you run it.

   mkdir -p .claude/skills/release && $EDITOR .claude/skills/release/SKILL.md

5. 5

   Turn "never" lines into deny rules

   A deny rule is enforced; a sentence is not. Put it in .claude/settings.json and delete the sentence.

   {
     "permissions": {
       "deny": ["Read(./.env)", "Read(./secrets/**)", "Bash(git push --force *)"]
     }
   }

6. 6

   Delete duplicates and contradictions

   Search for the same topic in several places and keep one line. If two lines disagree, decide, and delete the loser.

7. 7

   Check the result

   Start a new session, run /context again, and give Claude a small task in each area you moved. Confirm that the path rules and skills load when they should, and only then.

sourcesClaude Code docs: memoryClaude Code docs: skillsClaude Code docs: permissions

What does a short CLAUDE.md look like?

Commands, layout, a few conventions, and pointers to where the rest lives. The example below is 19 lines. Everything that used to follow it now loads only when it applies.

Notice what is missing: no tone advice, no history of past decisions, no procedure. Decisions and their reasons belong in a memory store or the commit history, where they can be found when they are relevant.

# Project: billing-api

## Commands
- Install: pnpm install
- Test: pnpm test (must pass before any commit)
- Lint: pnpm lint --fix

## Layout
- src/api: HTTP handlers. src/domain: pure logic, no I/O.
- Migrations in db/migrations, one file per change.

## Conventions
- TypeScript strict. No default exports.
- Money is integer cents, never floats.

## More
- API rules load from .claude/rules/api.md when you edit src/api.
- Release steps: run /release.
- Architecture notes: docs/architecture.md (read it when needed).

Where should a multi-step team process live instead?

In a workflow engine, not in any instruction file (how to make Claude Code follow a process compares the options). A process with sign-offs, branches and several people is often one of the largest blocks in a long CLAUDE.md, and it is also the part the model is most likely to compress or skip.

ConvOps holds that process as a graph of workflows and serves it to Claude Code over MCP one step at a time, so only the active step is in context. Rules that apply to a kind of work become policies attached to the workflow and arrive inside the step they govern. Decisions made along the way are stored as memories in the brain, so they do not have to be appended to CLAUDE.md to survive the session.

What is the checklist for keeping it short?

Review it like code: on every change, and on a schedule. Use /init for a first draft, then prune it like any other file.

1. Under 200 lines per file, with no imports used as a workaround.
2. Every line is a fact or a rule Claude needs on most tasks.
3. No procedure longer than three lines. It is a skill.
4. No rule that only applies to one folder. It is a path-scoped rule.
5. No "never" or "always" sentence that a deny rule or hook can enforce.
6. No two lines on the same topic.

Frequently asked questions