Try free

Last updated 13 October 2026

How to prune a large CLAUDE.md file

Large project instruction files slow down your development cycle

Your CLAUDE.md file starts as a helpful guide for Claude Code. It contains your build commands, test patterns, and style preferences. Over weeks of development, it becomes a graveyard of finished features and old architectural decisions. The agent reads this file at the start of every session. If the file is too long, the agent spends more of your context window on instructions than on your actual code. This leads to slower responses and higher costs because the input token count increases with every turn.

A large file also confuses the agent. When you have hundreds of lines of instructions, some rules will eventually contradict each other. The agent might try to follow an old architectural pattern from months ago while you are trying to implement a new one. This results in code that you have to fix manually, which defeats the purpose of using an agent. Pruning is not just about saving money. It is about making sure the agent has the right information to do the job correctly. You must keep the context window focused on the task at hand.

Move specific instructions to subdirectory files

You can move instructions closer to the code they describe. Claude Code looks for a CLAUDE.md file in the root directory first. It also looks for these files in subdirectories. If you have a complex frontend and a separate backend, create a CLAUDE.md inside the frontend folder. Put the React patterns and CSS rules there. Move the database schema and API conventions to a CLAUDE.md in the backend folder. This keeps the root file small and ensures the agent only reads relevant rules when it works in those specific parts of the tree.

This subdirectory strategy prevents the root file from becoming a catch-all for every technical detail in the repo. When the agent uses the Read tool on a file in the frontend directory, it will respect the instructions found in that local CLAUDE.md file. This provides a natural way to partition knowledge. It reduces the amount of text the agent must process for every single prompt. You only load the context that is necessary for the current part of the codebase.

Use the agent to audit its own instructions

You can ask the agent to help you clean the file. Open a session with the command claude and tell the agent to read the CLAUDE.md file using the Read tool. Ask it to identify instructions that contradict the current state of the codebase. The agent can use the Grep tool to see if the files or functions mentioned in the instructions still exist. If a rule describes a library you no longer use, the agent can find that out easily. This is much faster than checking every line yourself.

Request a summary of the current file from the agent. Ask it to suggest a shorter version that only includes the most critical information for your current tasks. You can tell the agent to use the Write tool to create a new, leaner version of the file. By using the agent for this task, you ensure that the instructions it suggests are the ones it actually finds most useful for its operation. This creates a feedback loop that keeps your project configuration efficient and accurate.

Establish a standard structure to prevent future bloat

A standard structure prevents the file from growing into a messy list of notes. Divide your CLAUDE.md into three main sections: Build and Test, Style and Patterns, and Current Focus. The Build and Test section should be a simple list of commands. The Style and Patterns section should hold the core logic of the app that does not change often. The Current Focus section is the only part you should update frequently. When a task in the Current Focus section is done, delete it or move only the permanent parts to the Style section.

Keep the commands section minimal. You do not need to keep five different ways to run a single test in the CLAUDE.md file. Keep one standard command and delete the rest. If a command is complex, move it into a shell script and just list the script path in the markdown file. This keeps the project instructions readable for both you and the agent. Avoid adding long explanations of why a rule exists. The agent needs to know what to do, not the historical background of every decision.

Manage session context with internal commands

The /compact command helps when your session history gets too long. It does not change your CLAUDE.md file directly, but it summarizes the current conversation to free up space in the context window. If you find that the agent is ignoring your CLAUDE.md instructions, the session might be too cluttered. Use /compact to clean up the internal state. This makes the agent more likely to pay attention to the persistent project instructions instead of getting lost in the history of the last ten prompts.

If you have just finished a major refactor and your CLAUDE.md is now updated, use /clear to start the conversation fresh. This ensures the agent picks up the newest version of your instructions without being biased by old logic in the chat history. You can also use /cost to see how much each session is spending. If the cost per turn is rising rapidly, it is a clear sign that your CLAUDE.md file or your session history has grown too large for efficient work.

Monitor multiple projects for efficiency patterns

Running several projects at once reveals which ones have the best instructions. In adhdTerminal, you can see multiple Claude Code sessions as tiles on a wall. If one project always takes longer to think or shows higher costs in the /cost output, its project instructions might be the reason. You can compare the performance of a clean project against one with a bloated CLAUDE.md side by side. This visual feedback makes it easier to spot when a file needs maintenance before it becomes a major problem.

The tile system in adhdTerminal also helps you manage the pruning process across different repos. You can have one tile dedicated to a backend refactor and another to a frontend cleanup. Each tile shows whether it is working or waiting for you. You can see the last few exchanges for each project without clicking into them. If you notice an agent making the same mistake in multiple tiles, it is time to update your global instructions at ~/.claude/CLAUDE.md to fix the issue everywhere at once.

Archive old rules instead of deleting them

Treat your project instructions like code. Do not just delete old rules if you think you might need them later. Move them to a markdown file in a directory called docs or archive. Claude Code will not read those files unless you specifically tell it to or unless it uses the Glob tool to find them. This keeps the active context window clean while preserving the history of your decisions. It prevents the root CLAUDE.md from becoming a historical log while still keeping that knowledge available for future reference.

If you need to bring a rule back, you can use the Read tool on the archive file and then use the Write tool to move the text back into the root CLAUDE.md file. This keeps your main instruction file dynamic and responsive to your current needs. A file that only contains what you are doing this week is much more effective than a file that contains everything you have done this year. Regular archiving keeps the agent fast and accurate.

Centralize common rules in the global config

You have a global instruction file at ~/.claude/CLAUDE.md that applies to every project. If you find yourself repeating the same style rules in every project, move them there. This allows you to delete those lines from the project-specific CLAUDE.md files. By centralizing common preferences like your preferred testing framework or indentation rules, you reduce the noise in every individual repository. This makes it easier to see the unique rules that actually matter for a specific codebase.

Check this global file regularly to ensure it does not become bloated itself. Only put rules there that truly apply to everything you do. If a rule is specific to one language, it is better to keep it in the project root or a subdirectory. The goal is to minimize the total number of tokens the agent must read before it can start helping you. Every line you remove from your project instructions is more space for the agent to understand your actual source code.

Use manual pruning for stable features

Manual pruning is the best way to save tokens on stable code. Remove descriptions of features that are now well understood and stable. The agent can infer how a stable feature works by reading the existing code with the Read tool. Use the CLAUDE.md file for the weird things that are not obvious from the source code itself. If a piece of logic is standard and follows your typical patterns, the agent does not need a written rule to explain it every single time.

Check your .gitignore file to ensure you are not accidentally making the agent read unnecessary files. Claude Code respects .gitignore rules. If the agent is reading large build artifacts or dependency folders, it will fill up the context window instantly. Proper ignore rules are just as important as a clean CLAUDE.md file. By keeping both the instructions and the file tree clean, you ensure the agent remains a sharp and effective tool for your daily development tasks.

Questions people ask

Will Claude Code automatically delete old sections of my CLAUDE.md file?

No, the agent will not delete parts of your project instructions unless you explicitly tell it to. It treats CLAUDE.md as a source of truth and will only modify it if you use a command or a prompt asking for an update. You should periodically review the file to remove outdated information.

How do I know if my CLAUDE.md is too big?

Run the /cost command inside a session to see how many tokens are being used. If the base cost for a single prompt is high even before you start a long conversation, your project instructions are likely the cause. You may also notice the agent taking longer to plan its actions.

Can I use multiple instruction files in the same folder?

Claude Code specifically looks for the file named CLAUDE.md. You can have other markdown files for documentation, but the agent will not read them automatically at the start of a session. It is better to keep one primary CLAUDE.md for active instructions and use other files only for reference when the agent needs to look something up.

Read next

More on claude code basics·All posts