Last updated 13 October 2026
Formatting instructions inside CLAUDE.md
Standardizing project behavior for terminal agents
You likely waste several minutes every time you start a new coding session because you have to explain your build pipeline to the terminal agent. When you run the claude command, the agent starts with a clean slate regarding your specific project needs. Without clear guidance, it may attempt to run tests using the wrong runner or try to build the project using outdated commands it remembers from its general training data. This leads to wasted tokens and unnecessary back-and-forth as you correct the tool output manually in the terminal.
The most effective way to solve this friction is to provide a source of truth that the agent can read immediately upon initialization. Claude Code is designed to look for a file named CLAUDE.md to understand the local environment. By using a standardized markdown format, you ensure the agent uses the Bash tool correctly for every task. This eliminates the need to repeat yourself every time you start a session or use the /clear command to refresh the conversation context. A well-formatted instruction file acts as a permanent brain for your project that any agent session can tap into immediately.
Placing and organizing instruction files
Your primary CLAUDE.md file belongs in the root directory of your repository. This file serves as the global configuration for the entire project. When you launch a session, the agent uses the Read tool to scan this file and incorporate the instructions into its current context. If your project is a simple single-language repository, one file in the root is sufficient to cover all build commands and testing patterns. The agent will treat these instructions as the highest priority when deciding how to interact with your code.
In more complex environments like monorepos or polyglot systems, you can place additional CLAUDE.md files in specific subdirectories. A file located in a subdirectory applies its rules specifically to that part of the file tree. This is useful when you have a backend written in Go and a frontend written in TypeScript within the same repository. The agent identifies the nearest CLAUDE.md file to the files it is currently editing to ensure it uses the correct linter and test suite for that specific component. You can also place a global instruction file at ~/.claude/CLAUDE.md to apply your personal preferences across every project you work on.
Formatting build commands for clarity
The agent looks for a specific section usually titled Build Commands to find execution strings. You should use a level two markdown heading for this section to make it easily discoverable. Under this heading, provide the exact shell commands needed to compile your project or start a development server. For a Node.js project, you might list npm run build or nested commands for specific environments. Be explicit about any prerequisites like installing dependencies or setting up local databases before the build can succeed.
Use markdown code blocks to wrap the commands so the agent can clearly distinguish between descriptive text and the actual syntax. If your build process requires specific environment variables, list them alongside the commands. The agent uses this information to determine which Bash tool calls are safe and necessary. If the instructions are vague, the agent might spend several turns trying to guess the correct build script by reading your package.json or Makefile, which adds latency to your workflow. Providing these commands directly in CLAUDE.md skips this discovery phase entirely.
Defining test suites and execution patterns
Testing is one of the most common tasks for a coding agent, and providing a Test Commands section is vital for automation. Specify the main test runner and how to target specific files or directories. For example, if you use pytest, tell the agent to run pytest followed by the file path. If your tests require a specific configuration file or a custom flag like --parallel, include those details in your instructions. This prevents the agent from running the entire test suite when you only wanted to check the changes in a single file.
Explain how the agent should interpret test results. If your suite produces specific artifacts or requires a clean-up step after a failure, describe these requirements in plain English within the test section. The agent uses the Read tool to understand these nuances before it attempts to fix a bug or refactor a component. When the agent knows exactly how to verify its work, it can operate with much higher autonomy, running tests in the background while you focus on higher-level architectural decisions.
Establishing code style and linting standards
To maintain consistency across your codebase, create a section for Code Style and Linting. Define your preferences for indentation, whether you use tabs or spaces, and your preferred quote styles. Mention specific tools like Prettier, Black, or ESLint that the agent should use to format code before submitting changes. While the agent generally follows the existing style of a file, explicit instructions in CLAUDE.md provide a tie-breaker when the agent is creating new files from scratch.
List the command used to run the linter and any auto-fix flags available. For instance, specify that the agent should run npm run lint --fix after modifying files. This ensures that the agent cleans up its own work before you even see the diff. By making the linting process part of the standard instructions, you reduce the number of review cycles spent on trivial formatting issues. The agent will learn to treat these commands as a mandatory step in its task completion process.
Managing project visibility with adhdTerminal
When you are working on a large project with many moving parts, you might find yourself running multiple Claude Code sessions simultaneously. Managing these different contexts and ensuring each one follows the correct CLAUDE.md instructions can be mentally taxing. This is where adhdTerminal provides a significant advantage by organizing your sessions into a grid of tiles on your desktop. You can see the status of a build command in one tile while reviewing test results in another, all while the app tracks which project rules apply to each specific session.
The visual feedback in adhdTerminal allows you to monitor whether an agent is currently idle, working, or waiting for your permission to run a tool. This layout is especially helpful when you have different CLAUDE.md files in various subdirectories. You can name and color-code each tile to match the specific service or module you are working on. This high-level overview ensures that you never lose track of which agent is following which set of project instructions, making it easier to manage complex workflows without feeling overwhelmed by terminal tabs.
Using memory and context management effectively
As you work through a session, the agent may discover new patterns or requirements that are not yet in your CLAUDE.md file. You can use the /memory command to view the current session's learned context and identify useful information that should be made permanent. If the agent consistently finds a specific workaround for a build error, move that solution into your root CLAUDE.md file. This turns temporary session knowledge into a permanent asset for your project, ensuring the next time you run claude, the agent is already aware of the fix.
When a conversation becomes too long and the context window fills up, the /compact command helps by summarizing the interaction. However, the /compact command does not change your CLAUDE.md file. It only simplifies the current session history to free up tokens. To keep your instructions effective, you must manually update the markdown files when project requirements change. This discipline prevents the agent from relying on stale information and keeps your token usage efficient by providing clear, up-to-date guidance at the start of every interaction.
Controlling tool permissions and safety
Claude Code operates with different permission levels that dictate how it can interact with your file system and execute commands. By default, the agent asks for permission before using tools like Edit or Bash. You can use the Shift+Tab shortcut inside a session to cycle through modes like plan or acceptEdits. Your CLAUDE.md file can help guide the agent in these modes by clearly stating which files are safe to modify and which directories should be treated as read-only. This adds an extra layer of safety to your automated coding workflow.
You can further refine these permissions in the .claude/settings.json file by defining which tools are allowed for specific paths. While CLAUDE.md provides the instructions on what to do, the settings file provides the technical constraints on how the agent can do it. If the agent encounters a permission error, it will often use the Read tool to check CLAUDE.md for alternative ways to complete the task. Keeping these two files synchronized ensures that the agent always has a path forward that aligns with your security and project management preferences.
Scaling with subagents and advanced setups
For highly specialized tasks, you can go beyond basic instructions by using subagents defined in the .claude/agents directory. These are markdown files that act as specialized personas for the agent, such as a database expert or a documentation writer. These subagents still respect the core instructions in your CLAUDE.md file but bring additional expertise to specific problems. This modular approach allows you to scale your development process by delegating different parts of a project to agents with focused configurations.
Monitoring these complex interactions is easier when you use adhdTerminal to mirror your project wall to your mobile device. The free iPhone app allows you to keep an eye on long-running tasks or subagent sessions while you are away from your desk. You can respond to a prompt or send the next task through an encrypted link, ensuring that your CLAUDE.md instructions are being followed even when you are not actively typing at your computer. This flexibility allows you to maintain progress on complex builds and test suites without being tethered to a single terminal window.
Questions people ask
Does the agent automatically update the CLAUDE.md file when it finds a better way to build the project?
The agent will not modify your CLAUDE.md file unless you explicitly use the Write tool or ask it to save a specific instruction. You should review the session history and use the /memory command to identify useful patterns before manually adding them to the file. This manual step ensures that only verified and stable instructions are kept as permanent project rules.
What should I do if the agent ignores the build commands I have written in the markdown file?
Check the project root and ensure the file is named exactly CLAUDE.md with no hidden extensions. You can use the /doctor command to verify that the agent is correctly identifying your project environment. If the agent still ignores the file, try using the /clear command to restart the session and force the agent to re-read the directory structure from scratch.
How do I handle project-specific secrets or environment variables that shouldn't be in a shared markdown file?
Do not put sensitive information like API keys or passwords directly into CLAUDE.md. Instead, use the file to instruct the agent to read environment variables from a .env file or your local shell. You can also use .claude/settings.local.json to store user-specific configurations that are not tracked by your version control system, keeping your project instructions secure and portable.
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.
- 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.