Try free

Last updated 13 October 2026

Sharing CLAUDE.md across a team

The inconsistent agent problem

Developers often struggle when a coding agent behaves differently for each person on the team. One developer might find that the agent writes perfect Python code while another finds it ignores the project linting rules entirely. This variation usually stems from the agent lacking a consistent set of instructions across different local machines. Without a shared configuration, the agent relies on its general knowledge, which might not align with your specific architectural decisions or library versions. This leads to wasted time during code reviews as humans have to fix the basic style errors the agent introduced because it was not briefed correctly on the project standards.

When multiple people work on the same repository, they expect their tools to behave predictably. If you use a specific linter or a custom test runner, every person's agent should know that. If the instructions stay on only one person's computer, the rest of the team misses out on the automation benefits. You end up with a fragmented workflow where the agent is only as good as the individual developer's setup. To solve this, you must treat the agent's context as a first-class citizen of the codebase, just like your build scripts or configuration files. This ensures that every developer who invokes the claude command gets the same high-quality assistance regardless of their local environment.

Commit CLAUDE.md to your repository

The CLAUDE.md file is the primary way to guide the behavior of Claude Code. You should place this file in the root of your project and commit it to your version control system. When the agent starts a session, it automatically reads this file to understand the project rules. By committing it, you ensure that every developer who clones the repository has the exact same instructions for the agent. This file should contain a clear summary of the project, the primary programming languages used, and any specific patterns the agent must follow to remain consistent with the existing code.

A shared CLAUDE.md file acts as a persistent briefing for the agent. It tells the agent how to use tools like Read and Edit within the context of your specific codebase. For example, if your project requires that every new file has a specific license header, you can specify that in the instructions. The agent will then apply that header every time it uses the Write tool to create a file. This level of automation ensures that the agent acts as a consistent member of the team rather than a guest who does not know the house rules. It also prevents the agent from making assumptions that might be true for other projects but are incorrect for yours.

Organize instructions with subdirectory files

As projects grow, a single instruction file in the root can become cluttered and difficult to manage. Claude Code supports a hierarchical approach where you can place additional CLAUDE.md files in subdirectories. If you have a monorepo with separate folders for frontend and backend code, you should put a specific instruction file in each of those directories. The agent will respect the instructions in the subdirectory it is currently working in, while still following the global rules set in the root file. This allows for fine-grained control without making the main configuration file too large or confusing for the agent to parse.

This hierarchical system is particularly useful for teams with mixed technology stacks. Your backend developers might need the agent to follow strict typing rules in a specific language, while the frontend team might want the agent to focus on specific component patterns. By using subdirectory files, you can provide these specific instructions exactly where they are needed. This prevents the agent from getting confused by trying to apply frontend rules to backend logic. It also makes it easier for team members to update instructions for their specific area of the codebase without affecting the rest of the organization. The agent simply reads the most relevant file for its current task.

Standardize the contents for the team

Your shared CLAUDE.md should explicitly define the commands the agent is allowed to run. You should include the exact strings for building the project, running tests, and linting the code. When the agent knows these commands, it can use the Bash tool to verify its own work before presenting it to you. This reduces the number of broken builds and ensures that the agent's output is always functional. For instance, if you use a specific flag for your test runner to ignore certain slow tests, include that flag in the instructions so the agent does not waste time during its execution cycle.

Beyond just commands, the file should describe the desired outcome for common tasks. If your team prefers the Grep tool over the Glob tool for searching specific strings, you can state that preference clearly. If there are specific files that the agent should always check before making a change, list them in the instructions. This creates a standardized operating procedure for the agent. When every team member uses the same definitions, the agent provides a stable and reliable experience regardless of who is running the session. This predictability is the key to scaling agentic workflows across a large engineering team where consistency is a priority.

Manage personal overrides with local settings

While sharing instructions is vital, individual developers still need some flexibility for their unique setups. Claude Code allows for local overrides through the .claude/settings.local.json file. This file should not be committed to the repository. It is the perfect place for settings that are unique to a developer's machine, such as a custom path to a binary or a specific terminal setup preference. By separating these personal settings from the shared CLAUDE.md, you prevent the repository from being cluttered with environment-specific details that might not work for everyone on the team.

You should update your global or project-level ignore file to ensure that .claude/settings.local.json is never tracked by your version control system. This allows each developer to customize their experience without the risk of breaking the shared configuration for others. For example, one developer might prefer to use the /vim command for editing while another prefers a different internal tool. These preferences can live in the local settings file safely. This balance between shared project instructions and personal configuration ensures that the team stays aligned on the work while individuals stay comfortable in their personal development environment.

Use subagents for expertise

For specialized tasks that require a specific mindset or toolset, you can use subagents. These are defined in markdown files located in the .claude/agents folder. You should treat these agent definitions as shared assets and commit them to your repository just like your main code. A subagent can be configured to handle specific roles, such as a security reviewer or a documentation specialist. When a team member uses the /agents command, they can invoke these specialized personas to perform complex tasks that go beyond standard coding or refactoring.

Sharing subagents allows the most experienced developers on a team to codify their expertise for others to use. If a senior engineer knows the exact steps to perform a safe database migration, they can write a subagent definition that guides Claude Code through those steps precisely. Every other developer on the team can then use that subagent to perform migrations with the same level of care. This helps in distributing knowledge across the team and reduces the bottleneck of waiting for a specialist to be available. It turns the agent into a repository of team knowledge and best practices that everyone can access.

Manage multi-project sessions effectively

When you are part of a team, you often have several different sessions or projects running at the same time. Managing these separate terminal windows can become overwhelming, especially when you need to keep track of multiple Claude Code instances across different repositories. This is where adhdTerminal becomes a useful addition to your workflow. adhdTerminal is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, and it is not affiliated with Anthropic. It runs many Claude Code sessions side by side, where each one is a tile on a wall. A tile has a colour, a number and a name, and it shows whether it is working, waiting for you, done or idle.

The app displays the last exchanges of its conversation and can even show numbers and headlines the project publishes. Tiles reopen in the same place after a restart and resume the same session, which helps you maintain focus. A free iPhone app mirrors the wall over an end to end encrypted link and can answer a prompt or send the next task. This is helpful when you need to step away from your desk but want to monitor a long-running task. It costs 99 dollars once, and one key runs one computer at a time and can be moved, with a 7 day free trial and no account required. Using a dedicated interface for your agent sessions makes it much easier to manage the complexity of a shared team environment.

Synchronize custom slash commands and hooks

You can further enhance team productivity by sharing custom slash commands and hook events. Custom slash commands are markdown files placed in the .claude/commands directory. These files define new shortcuts that any team member can use within a session. For example, you could create a command that triggers a specific set of checks on a pull request. By committing these to the repository, you ensure that everyone has the same set of powerful shortcuts. This standardization makes the agent feel like a bespoke tool designed specifically for your team's needs and internal workflows.

Hook events allow you to trigger actions at specific points in the agent's workflow, such as SessionStart or PreToolUse. You can configure these hooks to run scripts that prepare the local environment or log data for the team. If your team needs to track how often the agent uses certain tools, you can use a PostToolUse hook to record that information. These hooks are configured in the settings files, and by sharing the core configuration, you ensure that the agent's behavior remains consistent across the whole team. This level of integration allows the agent to fit into your existing development pipelines without requiring manual setup from every new developer.

Maintain the environment and instructions

A shared CLAUDE.md is not a static document. It should evolve as your project and team grow over time. You should encourage team members to update the instructions whenever they find a new pattern that works well or a common mistake the agent makes. Since the file is in version control, these changes go through the same code review process as any other code change. This ensures that the instructions remain high-quality and relevant. If the agent starts making errors after a library update, the first place to look is the instruction file to see if the rules need to be adjusted.

Regularly running the claude doctor command helps ensure that the underlying tool is functioning correctly for everyone on the team. If a developer runs into issues, they can use the claude update command to ensure they have the latest features and bug fixes. Keeping the tool and its instructions in sync is a continuous process that requires a small amount of maintenance. By treating the agent's configuration as part of the codebase, you create a culture of continuous improvement for your automated workflows. This investment in the agent's instructions pays off in higher productivity and more consistent code quality for the entire engineering organization.

Questions people ask

Can I use different instructions for my personal experimental branch?

Yes, you can modify the CLAUDE.md file on your local branch without affecting the rest of the team. Since the file is versioned, your changes will only apply to your specific branch until you decide to merge them into the main repository. This allows you to test new instructions or experimental workflows in isolation before sharing them.

What happens if I have a global instruction file and a project specific one?

Claude Code reads the project instructions first to understand the specific environment of the repository. A file located at ~/.claude/CLAUDE.md applies to every session you run on your machine, but project-level files take precedence for tasks within that folder. For team consistency, you should always prefer putting rules in the project repository so every developer has access to them.

How do I stop the agent from looking at private files in the repository?

The agent respects your .gitignore file by default, so it will not read or modify files that you have already excluded from version control. You can also provide specific instructions in the CLAUDE.md file to tell the agent to stay out of certain directories or to never read sensitive files. This ensures that your private data and secrets remain protected even during active agent sessions.

Read next

More on claude code basics·All posts