claude code

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

Anthropic recommends keeping each CLAUDE.md under 200 lines, because longer files cost context and lower adherence. Keep facts Claude needs on every task. Move procedures into skills, folder-specific rules into path-scoped rules, hard rules into hooks and permissions, and team processes into a workflow engine. In ConvOps, the team process lives in a workflow, so CLAUDE.md can stay short.

the route

7 sections · 10 min

  1. How long it should be
  2. Why Claude ignores it
  3. Keep or move
  4. Shorten it step by step
  5. A short example
  6. Where processes go
  7. Keep-it-short checklist
01How long it should be

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.

How Claude Code loads instruction files, per the official memory docs.
FileWhen it loadsCounts against context
CLAUDE.md in the project root and parent foldersAt launchAlways
@path imports inside CLAUDE.mdAt launch, up to four hops deepAlways
CLAUDE.md in a subfolderWhen Claude reads files in that folderOnly then
.claude/rules/*.md without pathsAt launchAlways
.claude/rules/*.md with pathsWhen Claude reads, writes or edits a matching fileOnly then
Skills (.claude/skills/<name>/SKILL.md)Name and description at launch, body when invokedMostly only when used
Auto memory (MEMORY.md)First 200 lines or 25KB at launchAlways, capped

sourcesClaude Code docs: memory

CLAUDE.md + importsevery session
Path ruleson matching files
Skillswhen invoked
fig 1 Loaded at launch versus loaded when needed.
02Why Claude ignores it

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

in the prompt read by the AI

"wait for approval"

Shipped. Nobody said yes.

as a gate checked by the engine

Waiting for approval.

fig 2 A line in a long file is weighed. A rule enforced outside the model is checked.
03Keep or move

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.

Where each kind of line belongs.
Kind of lineExampleWhere it goes
Fact used on most tasksTest command, folder layout, languageStays in CLAUDE.md
Rule for one folderHow API handlers validate input.claude/rules/api.md with paths
Multi-step procedureHow to cut a releaseA skill, run with /release
Something that must never happenNever read .env, never force pushPermission deny rules or a hook
Something that must always happen firstTests pass before a pushA PreToolUse hook
A role with its own focusSecurity reviewerA subagent in .claude/agents
A team process with sign-offsFix, review, approve, shipA workflow engine, such as ConvOps
Long background readingArchitecture notesA doc Claude reads when needed, not an import

sourcesClaude Code docs: memoryClaude Code docs: skills

Procedurea skill
Never do Xdeny rule or hook
Team processa workflow
fig 3 Each kind of line has one home.
04Shorten it step by step

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

measurewc -l, /context
sort lines
move outrules, skills, hooks
under 200
fig 4 Measure, sort, move, check.
05A short example

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.

CLAUDE.md · example
# 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).
06Where processes go

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 shared memory, so they do not have to be appended to CLAUDE.md to survive the session.

Was in CLAUDE.mdIn ConvOps
"Always do A, then B, then ask me before C"A workflow: the engine holds the order and a gate on C
"For content work, cite every claim"A policy, delivered inside the active step
"Remember we chose Postgres over Mongo because..."A memory, recalled when it is relevant
The same rules copied into AGENTS.md and .cursorrulesOne definition, used by any MCP client
Workflowone step in context
Policyinside the active step
Memoryrecalled when relevant
fig 5 In ConvOps the process, the rules and the decisions each have a home.
07Keep-it-short checklist

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

What is CLAUDE.md?

CLAUDE.md is the instruction file Claude Code loads at the start of every session, with the project facts, commands and conventions it needs on every task. ConvOps keeps multi-step team processes in workflows instead, so CLAUDE.md can stay short and carry only those facts. The file is context the model weighs, not configuration it must obey.

Is there a hard size limit for CLAUDE.md?

No, Anthropic documents no hard cap, and it recommends under 200 lines per file because longer files consume more context and reduce adherence. ConvOps helps a team stay under that by moving the process into workflows served one step at a time. Auto memory is different: only its first 200 lines or 25KB load at launch.

Do @imports make a long CLAUDE.md cheaper?

No. Imported files also load at launch, so they cost the same context as text written inline, while ConvOps loads a process step by step, so only the active step is in context. To load other material only when it is needed, use a path-scoped rule in .claude/rules or a skill. Imports help organise the text, not shorten what loads.

Does Claude Code read AGENTS.md?

Yes, recent versions read AGENTS.md when the folder has no CLAUDE.md. ConvOps works with either file, because its workflows reach Claude Code, Codex and other MCP clients over MCP rather than through an instruction file. If you have both files, import AGENTS.md from CLAUDE.md with @AGENTS.md or symlink it, so there is one source.

Why does Claude forget a rule after /compact?

Because rules given only in chat are lost, while the project-root CLAUDE.md is re-read from disk after /compact. ConvOps keeps the current step outside the session, so after a compaction Claude can ask the engine for the step again and get the same instructions. Nested CLAUDE.md files and path rules load again when Claude next reads a matching file.

Should I put "never do X" in CLAUDE.md?

No. ConvOps and Claude Code's own docs draw the same line: a sentence is guidance, and a block needs something outside the model. In Claude Code, put the rule in a permission deny rule or a PreToolUse hook. In ConvOps, policies are guidance delivered with the step, and what stops a step is a gate, a required metric or a required report.

How do I see what Claude Code actually loaded?

Run /context to see the context window, including the memory files, and /memory to open and edit them. ConvOps shows the other half: a guidance preview lists the policies, metrics and reports a run will get before it starts. In recent versions of Claude Code, /doctor prompt-audit also reviews your instruction files.

Who needs to shorten their CLAUDE.md?

Anyone whose CLAUDE.md has grown past the point where Claude Code follows it reliably, usually a team that keeps adding rules after each mistake. ConvOps helps that team move procedures into workflows, step-specific rules into policies and lessons into memory, so the file returns to a few lines that apply to every session.