Try free

Last updated 13 October 2026

Setting up a CLAUDE.md file for a project

AI agents require consistent context

Your AI agent starts every new session with a blank slate unless you provide specific instructions. You might find yourself repeating the same instructions about your preferred testing framework or directory structure every time you run the claude command. This repetition wastes time. It also fills your context window with redundant information that pushes out the actual code you are trying to write. When the agent uses tools like Write or Edit without knowing your style, it produces code that you must fix manually. This defeats the purpose of using an automated coding agent in your terminal.

A central configuration file prevents this drift by providing a permanent source of truth for the project. The agent reads this file at the start of a session to understand how you work. Without it, the agent might guess your build commands or use an older library version that does not match your environment. You need a way to lock in these details so that every prompt you send benefits from the same high level of project awareness. This ensures that the Bash tool runs the correct commands and the Edit tool respects your formatting preferences every single time.

Project memory files provide a source of truth

The file you need is named CLAUDE.md and it should sit in the root directory of your git repository. This file is not for your human teammates, although they might find it useful; it is specifically for the agent. The agent looks for this file immediately when you start a session using the claude command. It treats the contents of this file as high priority instructions that override its general training. If you have specific ways you like to handle error states or if you prefer a specific functional programming style, this is the place to document those choices.

The agent uses the Read tool to access this file and keep it in context. You do not need to manually feed this file to the agent in every prompt. Because it sits in your repo, you can version control it just like your source code. This ensures that when your project architecture evolves, your AI instructions evolve with it. If you find the agent making the same mistake twice, you should update this file immediately rather than just correcting the code in the terminal. This creates a feedback loop that makes the agent more effective over the life of the project.

Documentation for build and test commands

Your instructions should begin with the basic commands required to build, test, and lint your project. The agent needs to know exactly how to run your test suite so it can verify its own work using the Bash tool. For example, if you use a specific package manager or a custom test runner, explicitly state the command. This allows the agent to run tests automatically after it performs an Edit or Write operation. It reduces the back and forth where you have to tell the agent that its change broke the build.

Include the specific paths to your logs or build artifacts if they are non-standard. If your project requires certain environment variables to be set before running tests, document those requirements here. You can also define how the agent should interpret test failures. If certain tests are known to be flaky, telling the agent to ignore those specific failures will prevent it from getting stuck in an infinite loop of trying to fix a problem that is not related to its current task. This technical foundation allows the agent to use the Task tool more effectively.

Definition of architectural patterns and style

Beyond simple commands, you must define the architectural patterns of your codebase. If you use a specific design pattern like Dependency Injection or a strict Model-View-Controller setup, describe it clearly. Mention which directories hold which types of files. If you want the agent to use the Glob tool to find files, it helps if the agent knows the naming convention for your components or modules. This prevents the agent from creating new files in the wrong places or using outdated patterns it found in other parts of the web.

Coding style is equally important for a clean git history. Specify your preferences for indentation, trailing commas, or the use of semicolons. If you prefer async-await over promises, or if you have a specific way of naming private variables, put it in the file. The agent will attempt to match the existing style of a file it reads, but having explicit rules in the project memory file ensures consistency across the entire project. This is especially useful when the agent is creating a file from scratch using the Write tool.

Hierarchical instructions for complex projects

You can have multiple levels of instructions for different parts of your project. While the root CLAUDE.md handles the whole repo, you can place another CLAUDE.md file in a subdirectory to provide more specific rules for that folder. For example, your frontend folder might have different linting rules and build commands than your backend folder. The agent is smart enough to use the subdirectory file when it is working on files in that part of the tree. This prevents the main configuration file from becoming too bloated and confusing.

For settings that you want to apply to every project on your machine, you can use the file at ~/.claude/CLAUDE.md instead. This is useful for global preferences like your name, your preferred language, or common shell aliases. If you are working on many different projects simultaneously, keeping track of all these sessions can become difficult. This is where adhdTerminal helps by letting you run many different sessions side by side on a single wall of tiles. Each tile shows a different project with its own specific configuration, making it easy to switch context without losing track of which rules apply to which repository.

Verification of agent understanding

After you create or update your instructions, you should verify that the agent is actually following them. You can use the /status command to see the current state of the session and ensure the agent has recognized your project structure. If you feel the context is getting messy or the agent is ignoring your rules, you can use the /compact command. This summarizes the conversation and clears out old noise while keeping the essential project instructions from your markdown file in the window.

You can also use the /memory command to see what the agent currently understands about your project. If the agent is still making mistakes, try rephrasing your instructions to be more direct. Use active voice and avoid ambiguous terms. The agent responds best to clear, imperative sentences. If you find yourself frequently overriding the agent's decisions, it is a sign that your instructions need more detail or a better structure. A well-tuned CLAUDE.md file should result in fewer manual corrections.

Specialized workflows with subagents and hooks

For complex projects, you can go beyond simple instructions by using subagents and custom hooks. Subagents are defined as markdown files in the .claude/agents directory. You can create specialized agents for tasks like documentation, security auditing, or database migrations. Each subagent can have its own set of instructions that are even more focused than your main project file. This allows you to delegate specific parts of a task to an agent that is optimized for that specific type of work.

You can also use hook events to trigger certain behaviors at specific points in the session. For example, you can use the PostToolUse hook to automatically run a linter after the agent uses the Edit tool. This ensures that every change the agent makes is immediately checked for style violations. If you are managing a complex workflow with many moving parts, you might find it helpful to use adhdTerminal to mirror your session wall to your iPhone. This allows you to monitor the progress of long-running tasks or send the next task to the agent even when you are away from your desk.

Configuration of tool permissions and security

When the agent needs to run commands or edit files, it operates within a specific permission mode. The default mode usually asks for your consent before performing sensitive operations. You can change this behavior in the .claude/settings.json file in your project or the global ~/.claude/settings.json file. You can configure specific permissions for different tools like Bash or Write. If you trust the agent to run your test suite but not to delete files, you can set those boundaries in the settings.

You can cycle through permission modes like acceptEdits or plan by pressing Shift+Tab inside the session. If you are in a hurry and trust your project instructions to keep the agent on the right track, you might use bypassPermissions, but this should be done with caution. The agent respects your .gitignore file by default. This prevents the agent from accidentally leaking secrets or modifying build artifacts that should remain untouched. Proper permission management ensures that the agent remains a safe and controlled tool in your environment.

Maintenance of the project instruction set

Your project instructions are not a set-it-and-forget-it tool. As your project grows and the tools you use change, you must update your markdown files. Use the /review command to have the agent look over your current files and suggest improvements based on the recent history of the session. If you notice the agent struggling with a new library you just added, take a moment to add a few lines about that library to your instructions. This keeps the agent's knowledge current and relevant.

It is also a good idea to run the claude update command regularly to ensure you have the latest features and bug fixes for the agent itself. If you encounter issues with the installation, the claude doctor command can help diagnose problems with your environment. By maintaining a clean and accurate set of instructions, you ensure that your AI agent remains a productive partner. The time you spend refining your project memory file will pay for itself in the quality of the code the agent produces and the speed at which it completes tasks.

Questions people ask

Can I use multiple CLAUDE.md files in one project?

Yes, you can place a file in the root and additional files in subdirectories. The agent will prioritize the instructions in the subdirectory when working on files within that specific folder. This is useful for projects with separate frontend and backend stacks.

How do I make the agent remember my specific coding style across all projects?

You should place your global instructions in the ~/.claude/CLAUDE.md file. The agent reads this file in every session regardless of which folder you are in. It is the best place for personal preferences like your preferred shell or general code formatting rules.

What is the difference between settings.json and CLAUDE.md?

The settings.json file controls the behavior of the agent itself, such as tool permissions and model choices. The CLAUDE.md file is for project-specific information like build commands, architecture, and style guides. Use settings for technical constraints and the markdown file for coding context.

Read next

More on claude code basics·All posts