CLAUDE.md Too Long? How I Cut 460 Lines to 195 Without Losing a Rule

In the audit of my Claude Code knowledge base I published the before/after numbers from 22 October 2026. One row was personal: my global instructions file, CLAUDE.md, had grown to 460 lines and 4,815 words. After the cleanup it was 195 lines.

This post is that trim: what the docs say about size, the one test I use for every line, where the rest of the content belongs, how AGENTS.md fits next to CLAUDE.md, and a practical way to check that you still have the rules you care about. Examples use Acme and Example Client, never real clients.

How long should CLAUDE.md be?

Quick answer from the Claude Code memory docs: target under 200 lines per CLAUDE.md file.

The same page is blunt about oversized files. Under “My CLAUDE.md is too large”:

Files over 200 lines consume more context and may reduce adherence. Claude Code skips a file over 4 MiB. Use path-scoped rules to load instructions only when Claude works with matching files, or trim content that isn't needed in every session. Splitting into @path imports helps organization but doesn't reduce context, since imported files load with the CLAUDE.md importing them.

Two details matter in practice:

1. Under 200 lines is a target, not a soft suggestion you can ignore forever. Longer files still load (until 4 MiB), but they cost context and adherence.
2. @imports do not shrink what Claude sees. They organize the file for humans. The imported content still lands in context with the CLAUDE.md that pulls it in.

My file at 460 lines was more than double the target. The hard ceiling of 4 MiB was never the problem. Context cost was.

What piles up in a long CLAUDE.md

I did not keep a line-by-line inventory of the old file, so I won't give category counts. These are the kinds of content that end up in a global instructions file, and where each kind belongs:

• Identity and hard stops (who you are, what never to do): always-on
• Workflow habits that apply every day: also always-on, if they are short
• Procedures that only matter for one task, like invoicing Example Client or debugging Acme’s webhook: a skill or a topic file
• Client facts that change (contacts, stack quirks): clients/acme.md, not global instructions

The pattern matches Layer 1 in my five-layer Claude Code memory system: the identity file teaches behavior. Topic files hold knowledge. When those two jobs share one file, the file grows without a natural stop.

The one test for every line: always-on or on-demand

The test is one question per block:

Does the agent need this in every session, before it has opened any project file?

• Yes → keep it in the rules file (short, concrete, non-contradictory).
• No → move it somewhere the agent can load on demand: a knowledge-base file, a skill, a path-scoped rule, or a client entry.

Examples of always-on rules:

• Start with the knowledge-base index (MEMORY.md) when I ask about past work
• Never invent secrets; name the password-manager item instead
• Prefer one topic per file; put dated history in a changelog
• Do not edit a generated rules copy by hand

Examples of on-demand content:

• How to invoice Example Client (steps → skill; facts → client file)
• Acme deploy quirks (client file)
• A long debugging narrative that only mattered for one incident (topic file under engineering/debugging/)

A useful secondary filter: include only what the agent cannot find itself. The ETH Zürich study on instruction files (arXiv 2602.11988) does not prove that rule. It did not find a significant effect of context files on coding-task success, and it found no clear relation to length, so I do not use it to claim “shorter always wins.” I use it to resist stuffing the always-on file with facts the agent can read from the repo when needed.

Where the moved lines went: reference files, skills, client files

Content that fails the always-on test has three natural homes next to the rules file:

I don't have counts for how many of my lines went to each place, so I won't give a split. What matters is that the always-on file stops being a wiki.

The free personal-memory template encodes the same split. Its AGENTS.md says to keep that rules file under 150 lines, caps MEMORY.md at 150 lines, caps client entry files at 120 lines, and flags topic files over 40 KB. Those limits are the template’s, verified in the public repo — not measurements from my private knowledge base.

One rules file: AGENTS.md vs CLAUDE.md

AGENTS.md is a simple open format: a predictable markdown file where you put agent instructions that would clutter a human README. Many coding agents already look for it.

Claude Code’s memory docs describe how the two files interact:

• If the project has AGENTS.md and no CLAUDE.md, Claude can load AGENTS.md.
• If both exist in the project tree, Claude loads CLAUDE.md by default (not both), unless you change the project-instructions setting.
• A common pattern is a CLAUDE.md that imports AGENTS.md, so Claude still sees the shared rules.

I use that last pattern, and the template does too: one AGENTS.md holds the rules; CLAUDE.md is only:

@AGENTS.md

Why bother? Because I once kept a hand-edited copy of my rules for Codex. The copies drifted until one said the opposite of the other. Generating or importing from one source file is boring, but it means there is only one place a rule can change.

Remember the import caveat from the docs: @AGENTS.md does not save context versus pasting the same text into CLAUDE.md. It saves drift. Keep AGENTS.md short for the same reason you keep CLAUDE.md short.

How to check that no rule fell out

I do not have a measured “before/after adherence” score for this trim, so I will not claim one. Here is a practical check you can run on your own file:

1. Snapshot the old file (CLAUDE.md.bak or a git commit) before you delete anything.
2. Extract a checklist of imperative rules from the old file — every “always / never / must / do not” line, one row per rule.
3. Mark each row as kept in rules, moved to path X, or deleted on purpose (with a one-line reason).
4. Smoke-test with real prompts you already trust: open a fresh session, ask for work that used to depend on a moved rule (for example “invoice Example Client” or “debug Acme’s webhook”), and confirm the agent reads the skill or client file instead of inventing steps.
5. Optionally run Claude Code’s prompt audit (/doctor prompt-audit on recent versions) to surface contradictions and stale references after the move.

If a checklist row has nowhere to live and you still need the behavior, it was always-on after all — put it back in the rules file and cut something else.

The 195-line skeleton (Acme examples)

My file is now 195 lines. I won't paste the private file. Here is an illustrative skeleton in the same spirit, with Acme and Example Client as stand-ins:

# Rules for every agent

## Reading
- Start with MEMORY.md; follow its pointer instead of scanning the whole repo.
- If I name a client, read clients/<slug>.md before answering.

## Hard stops
- No secrets in files. Name the password-manager item.
- Do not invent Acme or Example Client facts; read the client file.

## Writing
- One topic per file. Current state in the topic file; dated events in the changelog.
- Bump last_updated on meaningful edits.

## Size
- MEMORY.md stays short; long sections become folder INDEX.md files.
- Client entry files stay short; grow into clients/<slug>/ with a reading map.

## Skills
- Facts in files, steps in skills. Point to a skill by name from the client file.

The template’s public AGENTS.md is the cloneable version of that skeleton, with the size table and lint script already attached.

Start from the template

If you want the split without rebuilding it:

👉 github.com/Sinfjell/personal-memory-template — one AGENTS.md, a CLAUDE.md that only imports it, index and client size limits, and /setup. Product page: /products/personal-memory-template/.

The March setup post is still the architecture. The seven failures post is what broke after daily use. This post is the CLAUDE.md row from that table.

Subscribe below if you want the later pieces in the series by email.

FAQ: CLAUDE.md size