← All guides

claude md management

Claude MD Management: Keep Your CLAUDE.md Lean

November 4, 2026·10 min read

How to manage CLAUDE.md as it grows: which file each rule belongs in, when to split into on-demand context files, and how to audit for stale commands.

TL;DR: Claude MD management is a sorting problem: decide which file each instruction belongs in, then keep the always-loaded one short. The deciding rule is that ~/.claude/CLAUDE.md loads into every session, so only things true for all your projects belong there (github.com). Everything else goes to a project, local, package or on-demand file.

Which CLAUDE.md files exist, and what is each one for?

There are four locations plus one on-demand directory, and the table above is the whole map. The global file at ~/.claude/CLAUDE.md holds user-wide defaults across all projects (getclaudeskills.com). The project root ./CLAUDE.md is checked into git and shared with the team. Personal overrides for one repo go in ./.claude.local.md, which is gitignored and not shared. In monorepos, ./packages/*/CLAUDE.md files give module-level context.

You do not have to wire any of this up. Claude auto-discovers CLAUDE.md files in parent directories, so a monorepo setup works without extra configuration (getclaudeskills.com). A package file and the root file can both apply when you work inside that package.

The practical consequence: scope is a decision you make when you write each line, not something you fix later. A line in the wrong file is either loaded when it is irrelevant or invisible to the people who need it.

Which file should each instruction go in?

Run each instruction through these questions in order. Stop at the first yes.

• Is it true for every project you ever open, and short? Put it in ~/.claude/CLAUDE.md. Examples: how you like answers formatted, your preferred package manager habits, a rule about asking before destructive actions. This file loads into every session, so it has to stay lean (github.com).
• Is it true for every project, but long or only sometimes relevant? Put it in a ~/.claude/context/*.md file and add a one-line pointer to the global index. Topic reference material is loaded on demand (github.com).
• Does the whole team need it for this repo? Put it in ./CLAUDE.md and commit it, since the project root file is checked into git and shared with the team (getclaudeskills.com). Build commands, test commands, architecture rules and naming conventions usually belong here.
• Does it only apply to one package or module? Put it in that package's CLAUDE.md, so it does not clutter the root file. Package-specific files give module-level context in monorepos (getclaudeskills.com).
• Is it your personal preference for this repo and nobody else's? Put it in ./.claude.local.md and add that file to .gitignore (getclaudeskills.com).

Two examples show the rule working. "Never run git push --force without asking" is yours and applies everywhere, so it is one line in the global file. "Run pnpm lint before committing" belongs to one repo and the whole team, so it goes in the project file. "I like terse commit messages in this repo" is personal and repo-specific, so it goes in the local override.

If an instruction fits two scopes, pick the narrower one. Promoting a line to a wider scope later is cheap. Finding out that a personal quirk has been committed into the team file is not.

Why does the always-loaded file need to stay lean?

Because the global file is read into every Claude Code session, whether or not the session needs any of it (github.com). Every line you add is paid for on every run, including runs on projects where the line means nothing.

The case for a small always-on file is that it keeps context small and token-efficient while the deep reference material stays available for when it is actually needed (github.com). The style rule that follows is to write dense rather than verbose, and to prefer copy-paste ready commands over prose descriptions (getclaudeskills.com).

What to cut from the main file:

• Anything about a single project. It belongs in that project's file.
• Long explanations. Keep the rule, move the reasoning to a context file.
• Duplicates of what the project file already says.
• Commands you have not run in weeks. See the audit below.

When this is the wrong advice: a short CLAUDE.md that is missing a rule you keep retyping into prompts is too lean. If you have typed the same correction three times, it deserves a line, in the right scope.

How do you split a long CLAUDE.md into an index plus context files?

The pattern comes from a plugin that manages the user-level ~/.claude/CLAUDE.md together with a chunked context directory at ~/.claude/context/ (github.com). You can do it by hand in a few minutes.

1. Read the global file and mark each section as "always needed" or "sometimes needed". Always-needed means it would change Claude's behavior in nearly any session.
2. Create ~/.claude/context/ and move each sometimes-needed section into its own topic file, such as testing.md or deploy.md. Topic-specific reference material is meant to live there and load on demand (github.com).
3. Reduce ~/.claude/CLAUDE.md to a short index: identity, working-style preferences, and a pointer table (github.com). A pointer is one row: the topic, the file, and when to read it.
4. Check the result. The index should fit on one screen, and every context file should be named in the pointer table.
5. Keep the pointers honest. Whenever you add or edit a context file, update the table in the same sitting. A pointer table that drifts from the directory sends Claude to files that do not exist or hides files that do.

The plugin automates the same steps with three commands. chunk-user-claude prunes the global file and pushes supplementary sections into the right file under ~/.claude/context/ (github.com). edit-user-context <file> <instruction> makes a targeted edit to a context file, or creates one, while keeping the pointer table in sync. The third command, user-claude-health, appears in the audit below.

How do you audit a CLAUDE.md for stale or duplicated content?

Run this checklist monthly, or whenever Claude starts ignoring something you know is written down.

• Size. Is the global file still a short index? If you have to scroll to read it all, it is not. The plugin's health audit checks CLAUDE.md size for the same reason (github.com).
• Pointer-table drift. Does every row point to a file that exists, and does every context file have a row? (github.com)
• Context-file inventory. List ~/.claude/context/ and ask whether each file earned its place.
• Duplication. Search the global, project and package files for the same rule written twice. Keep the narrowest copy.
• MEMORY.md size. It is part of the same family of always-read context, and the plugin's audit checks it too.
• Stale commands. Run every build, test and lint command written in the file. Build commands that no longer work are among the first issues the CLAUDE.md Improver skill flags (getclaudeskills.com).

If a command fails, fix it or delete it. A wrong command is worse than a missing one, because Claude will trust it.

For capturing new rules as you go, pressing # during a session has Claude auto-incorporate learnings into CLAUDE.md (getclaudeskills.com). It is convenient, and it is also how files bloat. Treat each # addition as a draft and re-sort it using the routing rules above at your next audit. Our Claude Code Cheat Sheet lists the other shortcuts worth knowing alongside it.

Should you automate it with a skill or plugin?

Three options, in order of effort.

Manual upkeep. Enough if you have one global file, a few projects, and you run the audit above. It costs minutes per month and installs nothing. If your global file is already a short index, stay here.

The CLAUDE.md Improver skill. Worth it when many project files have accumulated and nobody remembers what is stale. Install it with the skills CLI:

npx skills add anthropics/claude-plugins-official/claude-md-improver --agent claude-code

(getclaudeskills.com) Or install it manually by dropping the skill folder into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo, then restart Claude Code so it picks up the new skill.

The user-level chunking plugin. Worth it when the global file is the problem and you want the index-plus-context layout maintained for you, with chunk-user-claude, user-claude-health and edit-user-context doing the pruning, auditing and syncing (github.com). The user-claude-health command audits CLAUDE.md size, pointer-table drift, context-file inventory, duplication and MEMORY.md size.

We would pick the manual route first for anyone under a handful of projects, because the layout is simple enough that the tooling mostly saves typing. Pick the plugin once you have several context files and keep forgetting to update the pointer table.

One caution on ambition. A feature request on a multi-agent project asked for a way to pull in or delete chunks of CLAUDE.md instructions in a modular, safe way (github.com). That the request exists shows the need is real, but it is a request, not a shipped guarantee. Keep your files in git so any automated edit can be reviewed and reverted.

What does a managed setup look like in one paste?

A managed setup is the layout above with the tuning already done: a dense global file, instructions sorted into the right scope, and no stale commands. The reason to start from a tuned file is that writing the first version is the slow part, and most of that time goes to learning what is worth including. Dense beats verbose, and a clear definition of what "done" looks like for a task helps more than extra prose (getclaudeskills.com) (news.ycombinator.com).

ClockedCode packages exactly that: a curated, continuously updated set of vetted tools, subagents and CLAUDE.md instructions, compiled into a single master prompt you paste once. It is a one-time $39 purchase with lifetime updates, and the tips library at clockedcode.com/free is free. You can uncheck anything you do not want, and unchecked items are removed from the generated prompt. You can then edit the resulting global file and run it through the routing rules above.

If you mainly want guardrails rather than instructions, the Claude Code Permissions Generator and the Claude Code Hooks Preset Generator handle the parts that a CLAUDE.md line can only request, not enforce.

Next action: open ~/.claude/CLAUDE.md now, mark each section "always" or "sometimes", and move the "sometimes" sections into ~/.claude/context/ with a pointer table at the top.