Try free

Last updated 13 October 2026

Update CLAUDE.md for a new project layout

The breaking point of a single project file

Your project started as a simple script or a single package, but now it has grown into a monorepo with multiple services, shared libraries, and different build pipelines. The single CLAUDE.md file at the root is becoming a bottleneck because it contains too much information for any one task. When you run a session, the agent reads this entire file to understand the project instructions. If the file is bloated with details about every single sub-package, it consumes a large portion of the context window before you even send your first prompt. This leads to the agent losing track of earlier parts of the conversation or making mistakes because the relevant instructions are buried under irrelevant ones.

A bloated configuration file also makes it harder for the agent to find the specific commands it needs for a task. If the root file contains five different ways to run tests depending on the folder, the agent might pick the wrong one and fail the task. This results in wasted time and higher token costs as the agent tries to recover from errors that could have been avoided with clearer instructions. You need a strategy that provides the agent with the right information at the right time without overwhelming its memory. Refactoring your project layout is not just about moving code; it is about organizing the knowledge the agent needs to work effectively.

Defining the root as a global map

The first step in refactoring is to redefine the purpose of the root CLAUDE.md file. Instead of containing specific implementation details or build commands for every service, it should act as a high-level map of the entire repository. Use this file to describe the general architecture, the relationship between different folders, and the global coding standards that apply to everything. You should include common patterns, naming conventions, and the preferred way to handle errors across the whole project. This ensures that no matter where the agent is working, it adheres to the core principles of your codebase.

The root file should also point the agent toward the subdirectories where more specific information can be found. Use the Read tool to show the agent the folder structure and then use the Write tool to update the root CLAUDE.md with a directory of your services. Mention which folders contain frontend code, which ones hold the backend, and where the shared utilities are located. By doing this, you give the agent a bird's-eye view of the project without forcing it to process the minutiae of every single file. This approach keeps the initial context lean and focused on the big picture.

Implementing subdirectory instructions for specialized context

Subdirectory CLAUDE.md files are the best way to handle specialized context for different parts of your monorepo. When the agent is working inside a specific folder, it looks for a CLAUDE.md file in that directory. This file should contain instructions that are specific to that part of the tree, such as the exact command to run tests for a specific library or the specific linting rules for a frontend package. By keeping these details local, you prevent the root file from becoming a massive document that is hard to maintain.

You can create these files using the Write tool or by running the /init command while you are inside the subdirectory. The agent will then follow the instructions in that local file in addition to the global instructions found at the root. This hierarchical approach allows you to scale your project structure indefinitely. If a sub-package becomes complex enough to warrant its own internal structure, you can even add more CLAUDE.md files in its subdirectories. The agent will always look for the most relevant instructions for the files it is currently editing.

When the agent uses the Glob tool to explore your project, it will see these local files and understand that each part of the monorepo has its own set of rules. This is particularly helpful when you have different teams working on different services within the same repo. Each team can maintain their own CLAUDE.md file without worrying about breaking the instructions for other teams. This isolation makes the agent much more reliable because it is always working with the most relevant and up-to-date information for the specific task at hand.

Managing context limits during the transition

As your project grows, the amount of data the agent has to process increases. Every file the agent uses the Read tool on and every command it runs via the Bash tool adds to the context window. In a monorepo, it is easy to hit the limits of this window if you are not careful. You can use the /cost and /usage commands to monitor how much of the context is being used and what the current spend is for the session. If the context window becomes too full, the agent might start to forget the initial instructions or lose the thread of the current task.

To keep the session efficient, use the /compact command. This command summarizes the conversation so far and frees up space in the context window. It is particularly useful after a long session of refactoring where you have moved many files or changed large blocks of code. If a session becomes too cluttered with old information that is no longer relevant, do not be afraid to use the /clear command. This will start the session over in the same folder, giving you a fresh start with the updated CLAUDE.md files without having to exit and restart the tool.

Auditing the layout with search tools

Once you have split your instructions across multiple files, you need to ensure that they do not contradict each other. The agent uses the Grep and Glob tools to find information across your repository. You can ask the agent to search for specific keywords or patterns to see how it perceives the new structure. For example, use a prompt to check if the build instructions in the root file conflict with the specific build steps in a sub-package. If the agent finds inconsistencies, use the Edit tool to reconcile the differences immediately.

Proactive auditing prevents the agent from getting stuck or providing incorrect commands when you are in the middle of a complex task. You can also use the /status command to get a quick overview of the current session state and which files are currently being tracked. If you find that the agent is consistently missing certain instructions, it might be because they are located in a folder that the agent does not frequently visit. Moving those instructions to a more central CLAUDE.md file or using the /add-dir command can help bring them back into focus.

Automating project standards across the monorepo

Standardizing how the agent interacts with your monorepo can be further improved by using custom settings. You can place a settings.json file in the .claude folder of your project root to define default behaviors for the agent. This file can specify permissions for various tools, such as allowing the Bash tool to run certain commands without asking for permission every time. You can also define custom hooks like PreToolUse or PostToolUse to automate checks or logging whenever the agent performs an action. This level of automation ensures that the agent follows your workflow precisely.

For even more control, you can create custom slash commands by adding markdown files to the .claude/commands directory. These commands can be used to trigger complex workflows that are specific to your monorepo, such as deploying a specific service or running a comprehensive audit of all CLAUDE.md files. By combining these custom commands with the hierarchical file structure, you create a highly tailored environment where the agent can operate with maximum efficiency. This reduces the cognitive load on you as a developer, as you no longer need to explain the same steps to the agent repeatedly.

Organizing multiple sessions for different sub-packages

Managing multiple services in a monorepo often requires you to have several Claude Code sessions open at the same time. You might have one session dedicated to the backend API and another focused on the frontend components. Switching between terminal tabs or windows can lead to mistakes where you run a command in the wrong folder. This is a common problem for developers who need to maintain a high level of focus across multiple workstreams. It becomes difficult to track which session is performing a long-running task and which one is ready for the next prompt.

The adhdTerminal app solves this by running many Claude Code sessions side by side as tiles on a wall. You can give each tile a specific name and color, making it easy to distinguish between the different parts of your monorepo. The app shows whether each session is working, waiting for your input, or idle. This visual overview helps you stay organized without having to manage a dozen separate terminal windows. Because the tiles reopen in the same place after a restart and resume the same session, you can maintain your project layout across multiple days of work.

Testing the new setup with sessions

Testing the new setup requires running sessions across various parts of the project to ensure the agent picks up the correct instructions. You should start a session in the root and another in a deep subdirectory to compare how the agent responds to prompts about build steps. Use the /status command to check if the agent is aware of the local configuration. If you notice the agent is using the wrong test command, it means the subdirectory CLAUDE.md needs more specific instructions or the root file is overriding it in a way you did not intend.

If you find yourself constantly restarting sessions to test these changes, adhdTerminal can help by letting you mirror your entire setup to a free iPhone app. This mirror uses an end to end encrypted link so you can monitor your progress or send a quick prompt even when you are away from your desk. This is particularly useful for long-running tasks where the agent is refactoring multiple files across the monorepo and you want to keep an eye on its status without being tethered to your computer. Once you are satisfied that the agent is following the new layout, you can resume your normal workflow with much better context management.

Questions people ask

Can I have more than two levels of CLAUDE.md files in a deep monorepo?

Yes, the agent can recognize CLAUDE.md files at any depth in your project tree. When working in a subdirectory, it will look for the nearest instruction file in its current folder and then look up the parent directories. This allows you to have a root file, a service-level file, and even a component-level file for very complex parts of your codebase.

How do I prevent the agent from being confused by conflicting instructions?

The best way is to keep root instructions general and subdirectory instructions specific. If you have a global test command in the root but a specialized one in a subdirectory, the agent will generally follow the one most relevant to its current working directory. You can use the /review command to have the agent double check its understanding of the instructions before it begins a task.

Does the agent automatically read all CLAUDE.md files at the start?

The agent typically reads the root CLAUDE.md file when a session starts. As it navigates through your directories using tools like Glob or Read, it will encounter and process the local CLAUDE.md files it finds. You can explicitly point the agent to a specific subdirectory file by asking it to read that file at the beginning of your session.

Read next

More on claude code basics·All posts