How to share Claude Code configuration across your engineering team

Your team adopted Claude Code. Developers love it. Productivity is up. But three months in, you notice something: every engineer has a completely different configuration. One developer has a meticulous CLAUDE.md with architecture context, testing norms, and security rules. Another has an empty one. A third never created one at all.

Their .claude/settings.json files are equally inconsistent. Some developers have granted broad tool permissions. Others have restricted their agent to the point where it cannot run tests. Nobody is sharing their custom slash commands, and the specialized agents that your senior engineer built in .claude/agents/ only exist on their laptop.

This is the configuration drift problem. It affects every team using AI coding agents at scale, and it gets worse as the team grows. You start to see:

• New engineers spend their first hour copying someone else's CLAUDE.md from a Slack message
• Someone updates a shared prompt pattern and has to manually notify the rest of the team
• Your CISO asks "what are your AI agents allowed to do?" and nobody has a single answer
• A contractor leaves and you realize they had critical custom commands and MCP server configurations that nobody else has
• Developers on the same repo get different behavior from Claude Code because their settings diverge

The good news: this is a solved problem. There are three practical approaches to share Claude Code configuration across your engineering team, ranging from simple to enterprise-grade.

Before choosing a sharing approach, it helps to understand the full set of Claude Code configuration files that your team needs to keep in sync. There are six key pieces:

CLAUDE.md — project memory and custom instructions

This is the primary file that shapes how Claude Code behaves. It lives at the root of your project and contains architecture context, coding standards, testing norms, and behavioral instructions. A good team CLAUDE.md might look like:

# Project Instructions

## Architecture
This is a Next.js 14 app with a separate Express API.
Auth is handled in packages/auth using Firebase Auth.
All database access goes through packages/core (Clean Architecture).

## Code Standards
- TypeScript strict mode. No `any` types.
- Prefer functional components with hooks.
- All new code must have unit tests (Vitest).

## Testing
Run `pnpm test` before committing. Run `pnpm test:e2e` for Playwright E2E tests.
Never skip failing tests — fix them or explain why.

## Agent Behavior
- Be concise. Show code, not descriptions of code.
- Never hardcode secrets. Use environment variables only.
- Always run `pnpm check` (lint + type-check) before considering work done.

.claude/settings.json — permissions and tool configuration

This file controls which tools Claude Code can use and what commands it is allowed to run. Sharing a consistent settings.json means every developer's agent has the same guardrails:

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(pnpm *)",
      "Bash(make *)",
      "Bash(npx vitest *)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(curl * | bash)",
      "Bash(sudo *)"
    ]
  }
}

.claude/commands/*.md — custom slash commands

These are team-specific workflows encoded as slash commands. When shared, every developer gets the same /review, /deploy, or /test commands:

# .claude/commands/review.md
Review the current diff against our coding standards.
Check for:
1. TypeScript strict compliance (no any, no ts-ignore)
2. Test coverage for new functions
3. No hardcoded secrets or API keys
4. Proper error handling (no silent catches)
Output a summary with pass/fail for each check.

.claude/agents/*.md — specialized agent definitions

Agent files define specialized personas that developers can invoke for specific tasks. A shared set ensures the whole team has access to the same expert agents:

# .claude/agents/qa-engineer.md
You are a QA engineer specializing in E2E testing with Playwright.
When given a feature, write comprehensive test scenarios covering:
- Happy path
- Edge cases and error states
- Mobile and desktop viewports
- Accessibility (keyboard navigation, screen readers)
Always use the Page Object pattern and data-testid selectors.

.mcp.json — MCP server configuration

MCP (Model Context Protocol) servers extend Claude Code with external tools. A shared .mcp.json ensures every developer has access to the same integrations:

{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["-y", "@sentry/mcp-server"],
      "env": {
        "SENTRY_AUTH_TOKEN": "env:SENTRY_AUTH_TOKEN"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

.claude/rules/*.md — context-specific rules

Rules files auto-load based on file paths. For example, a rule for API development only loads when editing files in apps/api/. These are powerful for large codebases where a single CLAUDE.md would become unwieldy.

Now that you know what needs to be shared, here are three approaches, from simplest to most robust.

The most straightforward way to share Claude Code settings across your team is to commit the configuration files directly to your project repository. Every developer who clones the repo gets the same CLAUDE.md, the same .claude/settings.json, and the same custom commands.

# Typical repo structure with shared Claude Code config
my-project/
├── CLAUDE.md                    # Shared project instructions
├── .claude/
│   ├── settings.json            # Shared tool permissions
│   ├── commands/
│   │   ├── review.md            # Team code review command
│   │   ├── test.md              # Team testing command
│   │   └── deploy-checklist.md  # Deployment checklist command
│   ├── agents/
│   │   ├── qa-engineer.md       # QA specialist agent
│   │   └── security-reviewer.md # Security review agent
│   └── rules/
│       ├── api-development.md   # Rules for API files
│       └── e2e-testing.md       # Rules for test files
├── .mcp.json                    # Shared MCP server config
└── src/
    └── ...

Updates go through your normal pull request workflow. When someone improves the CLAUDE.md or adds a new custom command, they open a PR, the team reviews it, and everyone gets the update on their next git pull.

For organizations with multiple repositories, you can create a dedicated engineering-standards repo and symlink from each project:

# Symlink org CLAUDE.md into each project
ln -s ~/org/engineering-standards/CLAUDE.md ~/projects/api/CLAUDE.md
ln -s ~/org/engineering-standards/CLAUDE.md ~/projects/frontend/CLAUDE.md

Pros: Simple, version-controlled, works with your existing PR workflow, zero new tooling.

Cons: Does not scale across many repos. Symlinks are fragile and require manual setup. No way to push updates to developers — they must pull. Merge conflicts in CLAUDE.md when multiple people edit it. No visibility into who is actually using the config.

Many engineering teams already use dotfiles repositories to share shell configs, editor settings, and development tooling. The same pattern works for sharing Claude Code configuration at the user level.

Claude Code reads configuration from two locations: the project directory and the user's home directory at ~/.claude/. A dotfiles setup can populate the home directory with organization defaults while leaving project-level configs for per-repo customization.

# Team dotfiles repo structure
team-dotfiles/
├── claude/
│   ├── CLAUDE.md              # Org-wide agent instructions
│   ├── settings.json          # Default tool permissions
│   ├── commands/
│   │   ├── review.md          # Standard code review
│   │   ├── commit.md          # Commit message generator
│   │   └── onboard.md         # Onboarding helper
│   └── agents/
│       ├── architect.md       # Architecture review agent
│       └── docs-writer.md     # Documentation agent
├── install.sh                 # Symlinks everything to ~/.claude/
└── README.md

# install.sh
#!/bin/bash
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
mkdir -p ~/.claude/commands ~/.claude/agents

# Symlink settings
ln -sf "$SCRIPT_DIR/claude/settings.json" ~/.claude/settings.json

# Symlink commands
for cmd in "$SCRIPT_DIR"/claude/commands/*.md; do
  ln -sf "$cmd" ~/.claude/commands/
done

# Symlink agents
for agent in "$SCRIPT_DIR"/claude/agents/*.md; do
  ln -sf "$agent" ~/.claude/agents/
done

echo "Claude Code team config installed."

Developers clone the dotfiles repo once, run the install script, and get the organization's baseline. They can layer personal customizations on top by adding their own files to ~/.claude/ — the team defaults serve as a starting point, not a straitjacket.

To update the team config, a developer pushes changes to the dotfiles repo and notifies the team to git pull && ./install.sh.

Pros: Familiar pattern for teams already using dotfiles. Supports personal customization on top of team defaults. Works across multiple projects without per-repo setup.

Cons: No centralized management — updates require each developer to manually pull and reinstall. No enforcement; developers can ignore or override everything. No audit trail of who has which version. Does not handle per-platform configs (Cursor, Copilot, Gemini) without significant extra scripting.

GAL (Governance Agentic Layer) was built specifically to solve the problem of sharing and syncing Claude Code configuration across organizations. Instead of relying on git pulls, symlinks, or install scripts, GAL provides a centralized dashboard where an admin sets the approved configuration and a CLI that distributes it to every developer with a single command.

The setup takes about two minutes:

# Install the GAL CLI
npm install -g @scheduler-systems/gal

# Authenticate with your GitHub account
gal auth login

# Pull the organization's approved Claude Code configuration
gal sync --pull

# That's it. Your local environment now has:
# - CLAUDE.md with org-approved instructions
# - .claude/settings.json with approved permissions
# - .claude/commands/*.md with team slash commands
# - .claude/agents/*.md with shared agent definitions
# - .mcp.json with approved MCP server configs

When an admin updates the approved configuration in the GAL dashboard — adding a new custom command, tightening a permission, updating the project instructions — every developer gets it on their next gal sync --pull. No Slack messages, no manual copying, no merge conflicts.

GAL also handles multi-platform configuration. The same approved config can be synced to Claude Code, Cursor, GitHub Copilot, Windsurf, Gemini Code Assist, and Codex from a single source of truth. If your organization uses multiple AI coding agents, you set the policy once and GAL translates it to each platform's configuration format.

For enterprise teams, GAL adds an audit trail: you can see which developers have synced, when they last pulled the config, and which version they are running. This is the answer to your CISO's question about what your AI agents are configured to do.

Pros: Centralized management from a dashboard. One-command sync for developers. Multi-platform support. Audit trail and version history. Scales to organizations of any size.

Cons: Requires a GAL account (free tier available). Adds a tool to the workflow. Newer product compared to git-based approaches.

Here is how the three approaches compare across the factors that matter most when sharing Claude Code configuration across a team:

The right approach depends on your team size, how many repositories you manage, and whether you have compliance requirements around AI agent governance.

Solo developer or team of 1-5: Commit your CLAUDE.md and .claude/ directory directly to your repo. This is the simplest path and it works because you can coordinate updates over a quick standup or Slack message. Use your normal PR workflow to review changes to the config.

Team of 5-15, single repo or small multi-repo: Use a combination of git repo configs and a dotfiles repository. Put project-specific context in each repo's CLAUDE.md. Put org-wide settings, commands, and agents in a shared dotfiles repo that every developer installs to ~/.claude/. This gives you a baseline with room for per-project customization.

Team of 10-20+ or enterprise with compliance needs: Use GAL. At this scale, the manual overhead of keeping dotfiles in sync breaks down. New hires forget to run the install script. Updates require chasing people on Slack. Your security team asks for proof that everyone is on the approved config. GAL solves all of this with centralized management and one-command sync. This is the Claude Code enterprise setup that scales with your organization.

Hybrid approach: Many teams start with git and graduate to GAL as they grow. GAL can ingest your existing CLAUDE.md and .claude/ configs, so the migration is straightforward — you are not starting over.

Regardless of which approach you use to sync CLAUDE.md and settings across your organization, here are the patterns that work well for teams:

Keep CLAUDE.md focused on the "why" and "how"

The best CLAUDE.md files are not exhaustive documentation. They tell Claude Code how the team works: what the architecture looks like, what testing framework to use, what code patterns to prefer, what commands to run before committing. Think of it as the instructions you would give a senior contractor on their first day.

Use settings.json for security boundaries

The permissions in .claude/settings.json are your first line of defense. At minimum, deny destructive commands like rm -rf, piped curl execution, and sudo. Allow the specific tools your team uses: git, your package manager, your build system.

Encode team workflows as custom commands

If your team has a standard code review checklist, a PR creation workflow, or a deployment process, encode it as a .claude/commands/ file. This turns tribal knowledge into repeatable, consistent workflows that every developer can invoke with a slash command.

Build specialized agents for common tasks

Agent definitions in .claude/agents/ let you create expert personas for specific work: a QA engineer for test writing, a security reviewer for code audits, an architect for design reviews. Sharing these across the team means everyone has access to the same specialized capabilities.

Use rules for large codebases

If your CLAUDE.md is getting long, split context-specific instructions into .claude/rules/ files. These auto-load based on file paths, so Claude Code only sees the API development rules when editing API files, and only sees E2E testing rules when working on tests. This keeps context focused and reduces token usage.

Syncing Claude Code configuration across your team and enforcing it are different things. It is worth understanding the distinction before choosing your approach.

Sync distributes the approved config. Developers get the right settings, commands, and instructions. But they can still override them locally — add their own permissions, modify the CLAUDE.md, skip the sync.

Enforcement ensures the config cannot be overridden. The agent's permissions are locked to what the admin approved. Attempts to run denied commands are blocked at runtime, not just absent from the settings file.

For most engineering teams, sync is enough. The friction of deviating from the team config is high enough that developers follow it naturally. The 80/20 rule applies: config sync solves 80% of the consistency problem with minimal developer friction.

Enforcement becomes necessary for teams with strict compliance requirements — SOC 2, ISO 27001, financial services, healthcare. If your auditors need proof that AI agents cannot exceed their approved scope, sync alone is not sufficient.

The practical path: start with sync. Build the habit across your team. Layer enforcement on top when compliance demands it. GAL supports both — sync today, enforcement when you are ready.

Here is the fastest path to sharing Claude Code configuration across your engineering team, based on where you are today:

If you have not started sharing configs at all: Commit your best developer's CLAUDE.md and .claude/ directory to your main repository today. Even this minimal step ensures every developer who clones the repo gets a working baseline. You can iterate from there.

If you are already using a git repo or dotfiles: Evaluate whether the manual overhead is sustainable. If developers are consistently out of date, or if your security team is asking for audit trails, it is time to look at a centralized solution.

If you want centralized management now: Start at gal.run. The setup is fast:

1. Install the CLI: npm install -g @scheduler-systems/gal
2. Authenticate: gal auth login
3. Connect your GitHub organization
4. Upload your approved configuration via the dashboard
5. Tell your team to run: gal sync --pull

From that point on, any update to the approved config is one gal sync --pull away for every developer on the team. No Slack messages, no install scripts, no wondering whether everyone is on the same page.

The organizations that get AI agent governance right early will move faster with more confidence as agents become more capable. Whether you start with a git repo, dotfiles, or GAL, the important thing is to start. Pick the approach that matches your team today, and upgrade when you outgrow it.