What you will be able to do
- Measure the words that load together in your project against a budget.
- Run the one-line test on every line and record each verdict in a cut ledger.
- Move each cut line to the right destination and leave a one-line pointer.
- Set up one instructions file that Claude Code, OpenCode and Kimi Code all read.
- Confirm it loaded with /context and re-check the word count whenever it changes.
Key takeaways
- A CLAUDE.md is too long when it carries lines the agent would not get wrong without them; Anthropic targets under 200 lines per file, and we budget words, not lines.
- Ask one question of every line: would the agent make a mistake without it? Keep only the yes answers.
- Every cut line gets a home: a docs page, a folder rule, a skill, a workflow step, a hook, or the bin.
- Keep CLAUDE.md as the one source and make AGENTS.md a symlink to it: it is the simplest setup where Claude Code, OpenCode and Kimi Code all read the same instructions.
- Re-measure with a word count on every edit, because a trimmed file grows back.
A CLAUDE.md is too long when it carries lines the agent would not get wrong without them. Anthropic's docs target under 200 lines per CLAUDE.md file; we budget words, because lines hide density. By the end of this guide you will have audited your file line by line, given every cut line a home, and set up one file that Claude Code, OpenCode and Kimi Code all read.
A long instructions file is not a writing problem. It is a filing problem: almost every line in it is true, it is just in the wrong place. A misplaced line costs context in every session and buries the rules that matter. Anthropic says it plainly: bloated CLAUDE.md files cause Claude to ignore your actual instructions (Anthropic, Best practices(opens in new tab)).
Every example uses Mossbank, a made-up scheduling app for plumbing and heating firms. Its file and numbers are invented; the budgets and rules are the ones we run at Neomanex.
What you need before you start
Audit the files that load together, not the one you happen to have open. The agent never sees one file alone: Claude Code loads every CLAUDE.md from the top of the project down to the folder you work in, plus everything they import.
| You need | Why |
|---|---|
| Every instructions file that loads in your working folder | The agent pays for the sum |
A word count (wc -w on macOS or Linux) | The budget is in words |
/context in Claude Code | It shows which files actually loaded |
Measure what actually loads
We stopped counting lines. A table row can hold a paragraph, so we budget words and treat a dense file as a long one.
Run wc -lw on each file, add up the words, then divide words by lines. Above about 15 words per line, table cells have become paragraphs: split the cell or move the content out.
| File | Target | Hard max | Why |
|---|---|---|---|
| Child file (one subfolder) | 500 words | 750 words | It adds only what the parent lacks |
| Project root | 1,200 words | 1,800 words | Identity, folder map, tests, deploy, gotchas; children carry the rest |
| Workspace root (many projects) | 2,000 words | 2,800 words | It loads in every session, for every kind of work |
| Everything that loads together | 5,000 words | 7,000 words | The agent pays for the sum, not for one file |
Anthropic's line target exists because "longer files consume more context and reduce adherence" (Anthropic, Memory(opens in new tab)). Imports count in full: imported files also load at launch.
Mossbank's root file is 420 lines and about 9,600 words: 23 words per line, far past the 1,800-word project-root hard max.
Run the one-line test on every line
Anthropic's pruning question is the whole audit: would removing this line cause Claude to make a mistake? The discipline is asking it of every line, including the ones you wrote last week.
What is a cut ledger? A cut ledger is a table with one row per line or block of the file: the line, whether the agent gets something wrong without it, why, and where the line goes.
| # | Line in Mossbank's file | Wrong without it? | Why | Goes to |
|---|---|---|---|---|
| 1 | "Run tests with make test, never bare pytest" | Yes | Bare pytest skips the database fixtures | Keep |
| 2 | "price is stored in cents (see models/job.py)" | Yes | A wrong guess corrupts data | Keep, with its source |
| 3 | A 60-line module map | Sometimes | Reference, needed when navigating | Docs page |
| 4 | How to add a payment provider, 14 steps | For that task only | A procedure | Skill |
| 5 | "In migrations/, never edit a migration that has run" | In that folder only | One subtree | Folder rule |
| 6 | "NEVER run db reset against staging" | It must never happen | Prose is advisory | Hook |
| 7 | Release: version, changelog, tag, deploy, health page, ask Dana before tagging | At release only | An order and a sign-off | Workflow step |
| 8 | "Use 4-space indentation" | No | The formatter enforces it | Delete |
| 9 | "The API has 37 endpoints" | No | Wrong by the next commit | Delete |
| 10 | The parameter list of the team's MCP tools | No | The tool sends its own schema | Delete |
Two rows stay. Row 2 stays only because it names the file that proves it.
Give every cut line a destination
Deleting is the last resort, not the first. Most cut lines are knowledge that belongs somewhere the agent reads only when it needs it.
Ask the questions in this order. The first yes picks the home.
| Home | Takes | Loads when |
|---|---|---|
| Hook | Something that must always or never happen | Every tool call, and it blocks |
| Workflow step | A process with an order or a sign-off | At that step |
| Folder rule | Something true in one folder only | When the agent reads, writes or edits a file in that folder |
| Skill | A procedure some tasks need | When the task matches; until then only its short description loads |
| Docs page | Reference: maps, explanations | When the agent follows the pointer |
| Delete | Counts, history, copies, anything the agent already does right | Never |
The hook comes first because the file is advisory: Anthropic's docs say to block an action regardless of what Claude decides, use a PreToolUse hook. Our guide to stopping Claude Code deleting your files builds one step by step. A folder rule in Claude Code is a .claude/rules/ file with paths: frontmatter, here matching migrations/**, or a child CLAUDE.md in that folder. We path-scope ours.
Mossbank's release checklist is the classic misfiled line: an order and Dana's sign-off, read in full every session, with the stop left to memory. We keep processes like this as ConvOps workflows(opens in new tab), so the agent reads one step at a time and the sign-off is a step of its own (how we run our company on workflows). Move every process out and the file shrinks to an identity file: that is the radical route, graph engineering.
Move each line and leave a one-line pointer
A cut that loses knowledge is not a cut. It is a future bug, so every moved line leaves a pointer behind.
Mossbank's module map becomes docs/module-map.md, and the file keeps one line naming the page. Of the 420 lines, 90 stay, 150 go to three docs pages, 60 to two skills, 30 to one folder rule, 25 to the release workflow, 10 to two hooks, and 55 are deleted. The file ends at about 100 lines, the 90 kept plus 10 pointer lines, and 1,100 words, under the 1,200-word target.
An @ import is not a cut. @docs/module-map.md loads the page at launch anyway. A plain pointer loads nothing until the agent follows it.
Make one file serve CLAUDE.md and AGENTS.md
Two instruction files for three tools means each tool reads a different file. We keep one source and link the other name to it.
We tested each setup on 9 October 2026, with a different codeword in each file:
| Setup in the project folder | Claude Code 2.1.295 | OpenCode 1.18.31 | Kimi Code 0.31.1 |
|---|---|---|---|
| AGENTS.md only | Loads AGENTS.md | Loads AGENTS.md | Loads AGENTS.md |
| CLAUDE.md and AGENTS.md, two files | Loads CLAUDE.md only | Loads AGENTS.md only | Loads AGENTS.md only |
| AGENTS.md as a symlink to CLAUDE.md | Loads it once | Loads it once | Loads it once |
| CLAUDE.md only | Loads CLAUDE.md | Loads CLAUDE.md | Does not load it |
Two separate files drift, so each tool follows different instructions. CLAUDE.md alone leaves Kimi Code with nothing. Keep CLAUDE.md as the source and run ln -s CLAUDE.md AGENTS.md: of the four setups we tested, it is the only one in which all three tools read the same text once. Ours is generated: a script creates AGENTS.md beside every CLAUDE.md, so each folder has one source.
Per Anthropic's docs, Claude Code's Edit and Write tools refuse to write through a symlink, so edit CLAUDE.md; on Windows, make CLAUDE.md a one-line @AGENTS.md import instead. Delete or move the pair together: a deleted CLAUDE.md leaves its AGENTS.md link pointing at nothing.
Check it loaded, then re-check every time it grows
A trimmed file grows back by default, because every lesson wants to live in the file everyone reads. The re-check is part of the edit, not a cleanup day.
| Check | How | What you see |
|---|---|---|
| Did it load? | /context in Claude Code | The Memory files list names each loaded file; with the symlink, only CLAUDE.md |
| Inside the budget? | wc -w summed over the files that load together | A number to hold against the budget, on every edit |
| Does anything contradict? (optional) | /doctor prompt-audit, Claude Code 2.1.283 or later | Stale or conflicting instructions with proposed edits; nothing changes until you ask |
Mossbank's file gains two lines in its first week, both real lessons, and the word count catches them. The rule: a new lesson goes to its destination first, and to the file last.
Start with your longest process. Create a free ConvOps account(opens in new tab), have your AI write that process as a workflow, then delete it from the file. Want a second pair of eyes on your team's instruction files? Book a free Discovery Session.
Common mistakes and the rules they left
Every rule in our budget exists because a file got something wrong, not because a style guide said so. Each mistake below happened to us, retold on Mossbank.
| Mistake | On Mossbank | Rule it produced |
|---|---|---|
| Counting lines | A 180-line file at 33 words per line is about 6,000 words | Budget words; flag above about 15 words per line |
| A contract with no source | The file says price is in euros; it is cents, so the agent writes a discount in euros | A line that states a field, type or shape cites the file that proves it |
| Deploy steps in a child file | worker/CLAUDE.md still describes the old deploy and contradicts the root | The parent owns each fact; a child carries one pointer at most |
| Counts | "The API has 37 endpoints" is wrong by the next commit | Describe, never count |
| Restating a rule that already loads | The file copies the shared test rules, with an old flag | Point to the rule; never restate it |
Steps
Measure what actually loads
Run wc -lw on every instructions file that loads in your working folder, imports included, and add up the words. Compare each file and the total with the word budget, and flag any file above about 15 words per line.
Run the one-line test on every line
For each line or block, ask whether the agent would make a mistake without it. Record the line, the answer and the reason in a cut ledger, and keep only the yes answers.
Give every cut line a destination
Ask in order: must it always or never happen (hook), does it have an order or a sign-off (workflow step), is it true in one folder only (folder rule), is it a procedure for some tasks (skill), is it reference (docs page). If every answer is no, delete it.
Move each line and leave a one-line pointer
Move each line to its destination and leave a one-line pointer in the file wherever the agent needs to find it. Never count an @ import as a cut, because imported files load at launch.
Make one file serve CLAUDE.md and AGENTS.md
Keep CLAUDE.md as the source and run ln -s CLAUDE.md AGENTS.md in the same folder, so Claude Code, OpenCode and Kimi Code read the same text once. Delete or move the two files together.
Check it loaded, then re-check every time it grows
Run /context in Claude Code and confirm the file is listed under Memory files. On every edit, run wc -w again against the budget, and send each new lesson to its destination before the file.
Frequently asked questions
How long is too long for a CLAUDE.md?
Anthropic's docs target under 200 lines per CLAUDE.md file. At Neomanex we budget words instead, because a short file of dense table rows still costs a lot: about 1,200 words for a project root, 2,000 for the root of a large workspace, and 5,000 for everything that loads together. Past those, or above about 15 words per line, the file is too long. The real test is per line: keep only what prevents a mistake.
Who should trim their CLAUDE.md or AGENTS.md?
Developers and team leads whose coding agent ignores rules it was given, or whose instructions file grows with every lesson, should trim it. At Neomanex the rule is to audit a file once it passes its word budget. The result is a file the agent follows and that costs less context in every session, with the cut knowledge kept in docs pages, skills, folder rules, workflows and hooks.
What should I remove from my CLAUDE.md first?
Delete what the agent never needs: counts that go stale, project history, copies of other files, tool parameter lists the tool already sends, and style rules a formatter enforces. The Neomanex standard lists these as straight deletes, because they cost context and buy nothing. Then move reference material to docs pages, and move processes with an order or a sign-off into workflows, which is where Neomanex keeps them, in ConvOps.
Does importing files with @ make my CLAUDE.md shorter?
No. At Neomanex we count every @ import in the word budget, because Anthropic's docs say imported files also load at launch, so an import moves text without cutting its cost. A real cut is a docs page with a one-line pointer, a skill, or a path-scoped rule, because each of those loads only when the agent needs it.
Why doesn't Claude use my AGENTS.md?
Claude Code reads AGENTS.md only when no CLAUDE.md exists in the folder or above it. Neomanex tested this on Claude Code 2.1.295 in October 2026: with both files present, it loaded CLAUDE.md only. The fix is one source per folder: keep CLAUDE.md and make AGENTS.md a symlink to it, or on Windows make CLAUDE.md a one-line @AGENTS.md import.
Is AGENTS.md too long the same problem as CLAUDE.md too long?
Yes, and it takes the same audit. Neomanex tested OpenCode 1.18.31 and Kimi Code 0.31.1 in October 2026: both read AGENTS.md, OpenCode ignores CLAUDE.md when an AGENTS.md exists, and Kimi Code does not load a project CLAUDE.md. One trimmed CLAUDE.md with AGENTS.md as a symlink to it serves Claude Code, OpenCode and Kimi Code with the same text.
How do I fix "prompt is too long" in Claude?
Run /context in Claude Code to see what fills the context window, then run /compact or start a fresh session. At Neomanex we treat this error as a full conversation, which is a different problem from a long instructions file. A lean CLAUDE.md still helps, because it loads before your first message and every session starts smaller.