Last updated 13 October 2026
Add common error fixes to CLAUDE.md
Recurring errors drain developer productivity
You fix a build error in the morning and by the afternoon the AI agent makes the same mistake in a new session. This happens because Claude Code starts every conversation with a fresh context. While the agent can use the Read tool to look at your source files, it does not naturally remember the struggle you went through to resolve a specific dependency conflict or a broken environment variable. You end up paying for the same tokens and waiting for the same Bash commands to fail twice. This cycle is frustrating when you know exactly what the fix is but the agent keeps guessing wrong.
The problem is a lack of persistent project memory. Every time you run the claude command, the agent tries to be helpful based on what it sees in the current file tree. If your project has a unique setup or a known bug in a third party library, the agent will treat it like a standard problem. It might try to run a generic install command that breaks your local environment. You need a way to tell the agent to check for these traps before it takes its first action. This is where your configuration files become the most valuable part of your repository.
Without a central place for troubleshooting notes, you spend more time correcting the agent than writing code. You might find yourself typing the same instructions into the prompt every time you use claude --continue or start a new session with /clear. This manual overhead defeats the purpose of using a coding agent. To fix this, you must treat your project instructions as a living document that grows every time you hit a wall. You want the agent to learn from its mistakes so you do not have to teach the same lesson twice.
Centralize fixes in the CLAUDE.md file
The primary tool for project memory is the CLAUDE.md file located in your repository root. Claude Code reads this file at the start of sessions to understand how to build, test, and interact with your code. Most developers use it for build commands or linting rules, but it is also the best place for a troubleshooting section. By adding a specific heading for common errors, you ensure the agent sees the solutions before it tries to use the Bash tool to run a failing command.
When you encounter a recurring error, document the exact error string. The agent often uses the Grep tool to find information in your project. If you include the specific text of a compiler error in CLAUDE.md, the agent is much more likely to recognize the pattern when it sees that same text in the terminal output. You should provide the root cause and the specific command needed to resolve it. This turns a generic coding assistant into a specialist for your specific codebase.
You can also use ~/.claude/CLAUDE.md for errors that are specific to your machine rather than the project. If your local path configuration always causes issues with a certain tool, put the fix in your home directory config. Claude Code merges these instructions. This prevents you from polluting the project repo with fixes that only apply to your laptop. It keeps the agent informed about your specific environment without breaking things for your teammates.
Format error entries for agent recognition
Structure your troubleshooting section so the agent can scan it quickly. Use clear headings for each error type, such as Database Connection Failures or Type Mismatch in Legacy Modules. Inside these sections, describe the symptoms first. If a specific log file always holds the answer, tell the agent to use the Read tool on that file immediately when it sees a failure. This saves time because the agent stops guessing and goes straight to the source of the truth.
Provide the exact Bash commands for the fix. If an error requires clearing a cache or deleting a lock file, write that down. Do not just say clear the cache but provide the actual command like rm -f tmp/cache.lock. This reduces the chance of the agent making a typo or using a flag that is not supported on your operating system. The more concrete your instructions are, the less likely the agent is to loop through failed attempts.
Include a section on what not to do. If a common fix for a library actually breaks your specific implementation, explicitly tell the agent to avoid that path. For example, you might write that the agent should never run a global update on a specific package because it breaks the build. These negative constraints are often more powerful than positive ones because they prevent the agent from entering a destructive state that requires a manual reset.
Update instructions during a live session
You do not need to exit your terminal to improve the agent memory. When the agent successfully fixes a difficult bug, you should immediately tell it to record the fix. You can say something like use the Edit tool to add this solution to the troubleshooting section in CLAUDE.md. This ensures the knowledge is captured while the context is fresh. If you wait until the end of the day, you might forget the specific details that made the fix work.
Using the /memory command helps you see what the agent currently thinks the project state is. If you notice that its internal summary is missing a key piece of information about a recent error, that is your signal to update CLAUDE.md. You can also use the /review command to have the agent look over its own work and suggest improvements to its instructions. This creates a feedback loop where the agent helps maintain its own documentation.
If a session becomes cluttered with many failed attempts before you found the fix, use the /compact command. This summarizes the long conversation and keeps the context window lean. Once you have saved the correct fix to CLAUDE.md, you can even use /clear to wipe the session history. When the agent starts over in that folder, it will re-read the updated file and have the correct solution ready for the next time that error appears.
Manage multiple projects with adhdTerminal
If you are working across many different repositories, keeping track of which CLAUDE.md has which fix is difficult. You might have several terminals open, each running a different Claude Code session. This is where adhdTerminal becomes useful. It displays your active sessions as a wall of tiles on your screen. Each tile shows the name and status of a project, so you can see at a glance which session is currently dealing with a build error and which one has finished its task.
With adhdTerminal, you can monitor the headlines and numbers your projects publish. If a specific tile turns red or shows an error status, you can jump in and check if that error is already documented in your CLAUDE.md. Because the tiles resume in the same place after a restart, you do not lose the visual layout of your work. This makes it much easier to maintain a library of troubleshooting steps across a complex microservice architecture without getting overwhelmed by floating terminal windows.
Automate error detection with hooks
You can take your troubleshooting to the next level by using hook events. For example, you can configure a PostToolUse hook that triggers whenever a Bash command fails. While you cannot write complex scripts for this directly in the settings, you can instruct the agent in CLAUDE.md to always check the troubleshooting section whenever a tool returns a non-zero exit code. This makes the agent proactive about its own failures.
Use the UserPromptSubmit hook to remind the agent to check for environmental issues before it starts a large task. You can define these behaviors in your .claude/settings.json file. By combining these hooks with a well-maintained CLAUDE.md, you create a system where the agent is constantly checking its work against your known list of errors. This drastically reduces the number of times you have to intervene manually.
If you have a very specific set of errors for a sub-part of your project, place a second CLAUDE.md in that subdirectory. Claude Code will apply the instructions from the root file and the subdirectory file together when it works in that folder. This is perfect for monorepos where the frontend and backend have completely different error patterns and fix procedures. It keeps your documentation relevant to the task at hand.
Verify your fixes with targeted prompts
After you add a new fix to your documentation, you must verify that the agent can actually follow it. You can use the claude -p command to run a single prompt that triggers the known error condition. For example, tell the agent to try and build the project in an environment you know is broken. If the agent reads CLAUDE.md and applies the fix you wrote instead of failing, you know your documentation is effective.
If the agent still fails, look at how it is using the tools. It might be that your instructions are too vague or that the agent is prioritizing a different rule. You can use the /config command to check your current settings and see if any permission modes are blocking the agent from running the necessary fix commands. If the agent is in plan mode, it will only describe what it would do, which is a great way to test if it understands your new troubleshooting steps without actually changing any files.
Use the /status command to ensure the agent is aware of the files you just edited. Sometimes if you edit CLAUDE.md in an external IDE, the agent might need a moment to recognize the changes in its next turn. By confirming that the agent sees your updates, you ensure that the next time a real error occurs, the solution is already in the context window. This habit of verification turns your troubleshooting section into a reliable asset.
Maintain a lean and relevant configuration
A CLAUDE.md file that is too large can become a burden. If you include every single minor warning, the agent might get confused about which instructions are the most important. Periodically review your error list and remove fixes for bugs that have been permanently patched in your source code. Keeping the file focused on current, active problems ensures the agent has enough space in its context window for your actual code.
If you find that a certain error is very complex, consider moving the fix into a custom command. You can create a markdown file in .claude/commands that describes a complex multi-step fix. Then, in your CLAUDE.md, you simply tell the agent to use that custom slash command when it encounters the specific error. This keeps your main configuration file clean while still providing the agent with deep knowledge when it is needed.
Finally, remember that your settings.json and CLAUDE.md work together. If a fix requires specific permissions for a tool like WebFetch to check an internal status page, make sure those permissions are granted. You can set these in .claude/settings.json under the permissions key. By aligning your security settings with your troubleshooting needs, you empower the agent to solve problems autonomously and correctly every time.
Questions people ask
Should I check CLAUDE.md into version control?
Yes, you should commit CLAUDE.md to your repository so your entire team benefits from the collected knowledge. If you have personal fixes that only apply to your local machine, put those in ~/.claude/CLAUDE.md or .claude/settings.local.json instead. This allows the agent to follow project-wide standards while respecting your individual setup.
What is the best way to stop the agent from repeating a specific Bash error?
Add the exact error message to a troubleshooting section in CLAUDE.md and provide the mandatory fix command. You can also use the /permissions slash command to restrict the agent from using certain problematic flags or tools in that project. If the error persists, use the /memory command to see if the agent is correctly identifying the problem.
Can I use multiple CLAUDE.md files in one project?
Yes, Claude Code supports a hierarchical structure for instructions. You can have a root CLAUDE.md for the whole project and additional ones in subdirectories for specific modules. The agent will read the global file, the root file, and the file in its current working directory, combining them into one set of instructions.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- 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.