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

CLAUDE.md too long? Cut 460 lines to 195 without losing a rule: docs size target, always-on test, AGENTS.md vs CLAUDE.md, and a practical check.

Topic: Claude & MCP
Published: 2026-10-23
URL: https://productivitytech.io/claude-md-too-long/

In [the audit of my Claude Code knowledge base](/claude-code-memory-lessons/) 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](https://code.claude.com/docs/en/memory): **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](/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:

| Kind of content | Where it goes |
| --- | --- |
| Durable facts (stack, contacts, decisions) | Knowledge-base topic or client file, linked from `MEMORY.md` |
| Repeatable procedures | A versioned skill (`SKILL.md`), pointed to by name from the client file |
| Path-specific coding rules | Path-scoped rules under `.claude/rules/`, so they load only when matching files are in play |

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](https://github.com/Sinfjell/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`](https://github.com/Sinfjell/personal-memory-template/blob/main/AGENTS.md) holds the rules; [`CLAUDE.md`](https://github.com/Sinfjell/personal-memory-template/blob/main/CLAUDE.md) is only:

```md
@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](/claude-code-memory-lessons/). 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:

```md
# 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`](https://github.com/Sinfjell/personal-memory-template/blob/main/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**](https://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/](/products/personal-memory-template/).

The March setup post is still the architecture. The [seven failures post](/claude-code-memory-lessons/) is what broke after daily use. This post is the `CLAUDE.md` row from that table.

[Subscribe below](#foot-sub) if you want the later pieces in the series by email.

## FAQ: CLAUDE.md size

<!-- faq -->