Last updated 13 October 2026
Add build instructions to your CLAUDE.md file
The frustration of the broken build loop
You open a session in a complex project and ask the agent to fix a bug. It writes the code and then tries to verify its work by running a build. If your project uses a standard setup like a basic React app or a simple Python script, the agent might guess the right command. However, many professional projects involve custom scripts, specific environment variables, or multi-step processes that the agent cannot know by default. It tries a common command, fails, and then starts a loop of guessing different tool chains. This cycle wastes your tokens and your time while the agent struggles to find the correct entry point for your compiler or test runner.
When the agent hits a build error because it used the wrong command, it often tries to fix the error by changing the code rather than changing the command. It assumes the command it chose is correct and that your project is broken. You end up watching the agent refactor perfectly good logic just to satisfy a build script that does not exist. You can stop this behavior by providing a clear map of your project requirements in a specific file that the agent reads at the start of every session. This file provides the necessary context to prevent the agent from guessing and ensures it uses the tools you actually use in your daily workflow.
Establish a project memory with the root markdown file
The most effective way to guide the agent is to create or edit a file named CLAUDE.md in the root directory of your repository. This file serves as the primary project instructions and project memory for the agent. When you run the claude command to start a session, the agent looks for this file to understand the rules of the road. If you do not have one, the agent relies on its general knowledge, which is often too broad for a specific codebase. By placing specific build instructions here, you tell the agent exactly which tools to use and which flags are necessary for a successful compilation.
Structure your CLAUDE.md file with clear headings such as Build Commands or Development Scripts. Use standard markdown formatting to list the commands. The agent is trained to recognize these patterns and will prioritize the instructions found in this file over its own guesses. You should include the exact command for building the project, running the local development server, and executing tests. If your project requires a specific sequence, such as installing dependencies before running a build, write that sequence down clearly. This ensures that the agent follows your established pipeline instead of trying to find a shortcut that might lead to a failure.
Specify exact commands for the bash tool
The agent interacts with your system through a tool called Bash. When it needs to build your project, it generates a shell command and executes it through this tool. By defining the build instructions in CLAUDE.md, you are essentially providing the input for the Bash tool. For example, if your project uses a makefile with a specific target, state that the build command is make build-all. If you use a package manager with custom scripts, specify the exact script name like npm run build:dev. The more specific you are, the less likely the agent is to use the wrong tool or a default setting that does not apply to your environment.
You should also include information about how to handle build output. If your build process generates a large amount of logs or puts artifacts in a specific folder, mention this in the file. The agent can use the Glob or Read tools to inspect the results of the build, but it needs to know where to look. If the build command requires certain environment variables to be set, list them in the instructions. You do not need to include sensitive secrets, but naming the required variables helps the agent understand why a build might be failing and allows it to ask you for the missing information or check your local configuration files.
Manage environment requirements and dependencies
Builds often fail because the environment is not set up correctly. Your CLAUDE.md should outline the prerequisites for a successful build. This includes the required version of a language runtime or the presence of specific system libraries. While the agent can use the bash tool to check the environment, it is more efficient to tell it what to expect. If your project uses a local settings file for environment overrides, mention that the agent should look at .claude/settings.json or .claude/settings.local.json. This helps the agent understand the hierarchy of configurations in your project and how they affect the build process.
When you work on multiple projects, the environment for each one might be different. If you use adhdTerminal on macOS or Windows, you can manage these different environments by running multiple sessions side by side. Each tile on your wall can represent a different project or a different branch of the same project. Since each tile maintains its own session and context, the build instructions in each CLAUDE.md file remain isolated. You can see at a glance if a build is working or waiting for your input in one project while you continue working in another. This visual feedback is helpful when you are juggling several complex build pipelines at the same time.
Use subdirectory instructions for complex repositories
In a large repository with multiple components, a single root file might become too cluttered. You can place a CLAUDE.md file in a subdirectory to provide specific instructions for that part of the tree. For instance, if your repository has a frontend folder and a backend folder, each can have its own instruction file. The agent will respect the instructions in the subdirectory when it is working within that folder. This is useful when the frontend uses a completely different build system than the backend. It prevents the agent from trying to run npm commands in a directory that only contains Go code.
When the agent navigates into a subdirectory, it combines the instructions from the root and the local file. You should keep the root file for general project rules and use the subdirectory files for specific build and test commands. This modular approach makes the instructions easier to maintain and ensures the agent always has the most relevant context for the task at hand. If you find that the agent is getting confused between different parts of the project, check if the subdirectory instructions are clear and do not conflict with the root instructions. You can use the Read tool to verify what the agent sees in these files.
Optimize the session context for long builds
Long build processes can fill up the context window of a session with log messages and file reads. A full context window can make the agent less responsive or cause it to forget the original build instructions. You can use the /compact command to summarize the session and free up space. This command keeps the essential information while removing the detailed logs of previous build attempts. It ensures that the agent still remembers the build commands from CLAUDE.md even after a long debugging session. If the session becomes too messy, the /clear command allows you to start over in the same folder with a fresh context while retaining the permanent instructions in your markdown files.
If you are using adhdTerminal, you can monitor the status of these long builds across different projects without having to keep every terminal window visible. The app shows whether a tile is working or idle, which is useful when a build takes several minutes to complete. You can switch to another task on your wall and return when the tile indicates that the build is done or requires your attention. The free iPhone app can also notify you of the build status, allowing you to stay informed even if you step away from your desk. This setup helps you maintain momentum across multiple build-heavy projects without losing track of your progress.
Control permissions for automated build tools
By default, the agent might ask for permission before running certain build commands or editing files. You can change this behavior using permission modes. If you trust the agent to run your build scripts without intervention, you can switch to the acceptEdits mode by pressing Shift+Tab inside the session. This allows the agent to execute tools and save changes more quickly. However, for sensitive build steps or commands that might have side effects, you might prefer the plan mode, where the agent describes what it will do before it does it. This gives you a chance to review the build command before the bash tool executes it.
You can also configure permanent permissions in your settings.json file. Under the permissions key, you can allow or deny specific tools for different commands. If you want the agent to always be able to run your build script but always ask before searching the web, you can set those rules there. This level of control ensures that the agent remains a helpful assistant without becoming a risk to your system. Remember to check your current configuration with the /config command to see which permissions are active and how they might affect the agent's ability to follow your build instructions.
Verify the build instructions with testing and hooks
After you add build instructions to your CLAUDE.md file, you should verify that the agent can follow them. Ask the agent to run a full build and observe its behavior. If it still makes mistakes, refine the instructions to be more explicit. You can also use hook events to trigger specific actions during the build process. For example, a PostToolUse hook can be used to check the status of a build after the bash tool finishes. This allows you to automate the verification of the build results and ensures that the agent does not move on to the next task if the build failed.
If you encounter issues with the installation or the agent's ability to run commands, use the /doctor command or run claude doctor from your terminal. This check ensures that your environment is healthy and that the agent has the necessary permissions to access the tools it needs. Keeping your build instructions up to date is an iterative process. As your project evolves and you add new scripts or dependencies, update the CLAUDE.md file to reflect these changes. This small investment in maintenance pays off by providing a reliable and efficient automated development experience.
Questions people ask
What should I do if the agent ignores my build commands in CLAUDE.md?
Check if the file is in the root directory and uses clear markdown headings. If the session has a very long history, the agent might be hitting context limits, so use the /compact command to refresh its memory. You can also explicitly tell the agent to read the CLAUDE.md file at the start of the conversation.
Can I use global build instructions for all my projects?
Yes, you can place general instructions in ~/.claude/CLAUDE.md to apply them to every session you start. This is useful for global preferences like preferred shell flags or standard cleanup commands. However, specific build scripts should stay in the project-level file to avoid conflicts.
How do I handle builds that require interactive input?
The agent works best with non-interactive build scripts. If your build requires user input, try to use flags that bypass prompts, such as -y or --silent. If that is not possible, you will need to provide the input manually when the agent runs the command in the interactive interface.
Read next
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.
- Assign names to Claude Code session tilesLearn how to name your sessions so you can easily identify them on the adhdTerminal wall and switch between different feature branches.