Last updated 13 October 2026
Add test commands to a CLAUDE.md file
The challenge of guiding an agent through your test suite
You open your terminal and run the command claude to start a session. You ask the agent to fix a bug in a specific module. The agent identifies the issue, applies a fix using the Edit tool, and then tries to run tests to verify the change. Without clear instructions, the agent might guess the wrong test runner or attempt to run the entire suite. This wastes your time and consumes unnecessary context because the agent has to process failures that are unrelated to the current task.
A common problem occurs when the agent tries to run a command like npm test in a large project. This command might trigger hundreds of unrelated tests or require environment variables that the agent does not know about. You end up watching the agent fail repeatedly while it tries to figure out how your project is structured. To avoid this, you need to provide the agent with project memory. The primary way to do this is through a CLAUDE.md file.
Setting up the root project instructions
Your first step is to create a CLAUDE.md file in the root of your repository. This file serves as the main guide for the agent. When you start a session, the agent reads this file to understand the project rules. You should include a section specifically for test commands. For example, if you use vitest, explicitly state the command needed to run a single test file. Use a plain heading like Test Commands and list the exact strings the agent should execute via the Bash tool.
Be very specific about the arguments. If your tests require a specific reporter to keep the output readable, include that in the command. By providing these instructions, you stop the agent from guessing. It will look at the CLAUDE.md file, see the command you provided, and use it whenever you ask it to verify its work. This makes the interaction much faster and prevents the agent from getting lost in a sea of terminal output.
Managing environment variables and flags
Many development environments rely on specific flags or environment variables to function. If your tests fail without a certain database URL or a local configuration flag, document this in the CLAUDE.md file. Tell the agent exactly which variables need to be present before it runs a test command. You can instruct it to check for a .env file or to prepend variables directly to the shell command.
Flags are equally important for controlling the amount of data the agent receives. If a test runner produces thousands of lines of output, it will fill the context window and trigger a need for the /compact command sooner than necessary. Instruct the agent to use flags that limit output to failures only. This keeps the conversation focused on the code changes and saves you money by reducing the number of tokens processed in each turn.
Using subdirectory files for specific modules
In a monorepo or a large project with multiple services, a single root CLAUDE.md file might not be enough. You can place additional CLAUDE.md files in subdirectories. The agent combines the instructions from the root file with the instructions in the directory where it is currently working. This allows you to define different test runners for different parts of your tree without creating a massive, confusing configuration file at the top level.
For example, a project might have a frontend folder using playwright and a backend folder using pytest. By placing a CLAUDE.md in each folder, you ensure the agent always uses the correct tool for the task at hand. If you are working in the backend, the agent will ignore the frontend test instructions. This scoping prevents the agent from accidentally running the wrong suite and helps it stay within the relevant context for that specific module.
Controlling execution with permission modes
Claude Code operates in different permission modes that change how it runs commands and edits files. The default mode asks for your approval before every tool use. If you are confident in your test setup, you can use Shift+Tab to cycle to the acceptEdits mode. This allows the agent to modify files and run tests without stopping to ask you for permission every time. This is much faster for iterative bug fixing where you want the agent to try a fix and verify it immediately.
If you want to see what the agent plans to do without it actually touching your terminal, you can switch to the plan mode. In this mode, the agent will describe the test commands it would have run based on your CLAUDE.md file. This is a great way to verify that your instructions are working as expected before you allow the agent to execute code. For tasks where speed is the only priority, the bypassPermissions mode removes all prompts, but you should use this with caution.
Organizing multiple sessions with adhdTerminal
When you are working on several complex features, managing multiple terminal windows for different Claude Code sessions can become difficult. The adhdTerminal app provides a native solution for macOS and Windows that helps you organize these sessions. It displays each session as a tile on a wall, where you can see the last few exchanges and the current status of the agent. This is especially useful when running long test suites in parallel across different branches or projects.
Each tile in adhdTerminal has a name, a color, and a number, making it easy to distinguish between a backend refactor and a frontend bug fix. If you need to step away from your desk, the free iPhone app mirrors your wall over an encrypted link, allowing you to check if a test suite finished or send a quick prompt for the next task. The app ensures your sessions are persistent, so your carefully arranged test environment stays in place even after a system restart.
Verifying project memory with slash commands
Once you have defined your test commands in CLAUDE.md, you should verify that the agent is using them correctly. You can use the /config command to see the current settings and instructions the agent is following. If you suspect the agent is working with outdated information, use the /clear command to reset the session. This forces the agent to re-read the configuration files from the disk and start with a fresh context.
You can also use the /status command to check the health of your current session. If the agent is struggling to run tests, it might be because of a permission issue or a missing dependency. The /doctor command is useful for checking the overall health of your installation. By using these built-in tools, you can maintain a clean and efficient development environment where the agent knows exactly what you expect from it.
Fine tuning tool permissions for testing
Sometimes you want to give the agent more freedom with the Bash tool but keep a tight rein on the Write tool. You can configure these permissions in your .claude/settings.json file. This file allows you to set default behaviors for each tool in your project. You can specify that the agent is always allowed to run certain test commands while requiring a prompt for any file modifications. This granular control helps you balance speed and safety.
If you have local path configurations or specific testing flags that should not be shared with the rest of your team, put them in .claude/settings.local.json. This file is not tracked by your version control system and overrides the project-wide settings. It is the perfect place for your personal developer secrets or machine-specific optimizations. These local settings work alongside your CLAUDE.md instructions to create a personalized experience for the agent on your computer.
Handling failures and context limits
When a test fails, the agent will attempt to read the error message and suggest a fix. If the error message is too long, use the /compact command to summarize the history and free up context space. If you find the agent is stuck in a loop of failing tests, you can press the Escape key to interrupt its current action. Pressing Escape twice will show you a list of previous messages, allowing you to go back to a point before the agent made a mistake.
If you need to quit a session entirely, use Ctrl+C. Before you restart, you might want to update your CLAUDE.md file with more specific instructions to prevent the same failure from happening again. Continuous improvement of your project memory is the best way to get the most out of Claude Code. As your project grows, your test instructions should grow with it, ensuring the agent remains a helpful and efficient partner in your development process.
Questions people ask
Can I use multiple test runners in one CLAUDE.md file?
Yes, you can list multiple commands under a Test Commands heading. Be sure to describe when the agent should use each one, such as using one for unit tests and another for integration tests. The agent will read these descriptions and choose the appropriate command based on your request.
What happens if my test command is not in the root directory?
The agent uses the Bash tool and starts from the root of the project. If your test command needs to be run from a specific folder, you should include the directory change in the command string, such as cd frontend && npm test. Alternatively, place a CLAUDE.md file in that subdirectory with the local command.
Does Claude Code automatically detect my .gitignore file?
The agent respects your .gitignore file by default. It will not read or modify files that are ignored unless you specifically tell it to do so. This is helpful for keeping build artifacts and large dependency folders out of the agent's context window.
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 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.
- 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.