---
title: "How to share Claude Code rules across a team"
description: "To share Claude Code rules across a team, commit CLAUDE.md, .claude/rules/ and .claude/settings.json, then reach other repositories with imports, symlinks or a managed CLAUDE.md."
url: "https://aldena.ai/blog/share-claude-code-rules-across-a-team"
---

# How to share Claude Code rules across a team

Published 2026-11-17.

## Commit CLAUDE.md and keep personal rules out of git

The simplest way to share Claude Code rules across a team is a committed `CLAUDE.md`, because [Claude Code loads it](https://code.claude.com/docs/en/memory) into every engineer's session at launch. I checked every path, setting and version number below against Anthropic's memory and [settings](https://code.claude.com/docs/en/settings) docs on November 17, 2026.

A shared rule goes wrong when its file sits in the wrong scope, like a team convention kept in one engineer's `~/.claude/CLAUDE.md` or a personal test URL committed for everyone.

| File                                         | Who it reaches                                                       | In git                                          |
| -------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------- |
| Managed `CLAUDE.md`                          | Every user on a machine IT deploys it to                             | No, deployed with MDM, Group Policy or Ansible  |
| `./CLAUDE.md` or `./.claude/CLAUDE.md`       | Everyone who clones the repository                                   | Yes                                             |
| `.claude/rules/*.md`                         | Everyone who clones it, and a rule with `paths` only for its files   | Yes                                             |
| `.claude/settings.json`                      | Everyone who clones it, for permissions, hooks, plugins and env vars | Yes                                             |
| `CLAUDE.local.md`                            | You, in this project                                                 | No, add it to `.gitignore`                      |
| `.claude/settings.local.json`                | You, in this project                                                 | No, Claude Code adds it to your global excludes |
| `~/.claude/CLAUDE.md` and `~/.claude/rules/` | You, in every project on your machine                                | No                                              |

IT puts the managed file at `/Library/Application Support/ClaudeCode/CLAUDE.md` on macOS, `/etc/claude-code/CLAUDE.md` on Linux and WSL, and `C:\Program Files\ClaudeCode\CLAUDE.md` on Windows. Claude Code loads `CLAUDE.md` and `CLAUDE.local.md` from the working directory and every directory above it, and it concatenates them instead of letting one override another. A `CLAUDE.md` in a subdirectory waits until Claude reads or edits a file there.

![A repository holding CLAUDE.md, .claude/rules and .claude/settings.json, plus an IT-managed CLAUDE.md, wired to three engineers who all load the shared set, while CLAUDE.local.md, settings.local.json and \~/.claude/CLAUDE.md stay on one machine, and a team rule kept in one engineer's \~/.claude/CLAUDE.md reaches only that engineer](https://cdn.aldena.ai/images/blog/share-claude-code-rules-across-a-team-1-20261117.png)

I keep anything a reviewer would block a pull request over in a committed file, and my own preferences, such as a local test URL, in `CLAUDE.local.md` or under `~/.claude/`. When one engineer's sessions behave differently from everyone else's, `/context all` lists the memory files that actually loaded, and it's the first command I'd run on [a team rolling out Claude Code](https://aldena.ai/blog/claude-code-for-teams).

## Move rules into .claude/rules/ before CLAUDE.md passes 200 lines

Anthropic's memory docs target under 200 lines per `CLAUDE.md` file, and the `.claude/rules/` folder holds the rest as one Markdown file per topic, found recursively.

A long `CLAUDE.md` costs context in every session, and per the same docs Claude follows it less closely. Splitting it with `@path` imports changes nothing, since an imported file loads together with the `CLAUDE.md` that imports it. A rule file with a `paths` field does change it:

```markdown
---
paths:
  - "src/db/**/*.ts"
  - "migrations/**/*.sql"
---

# Database rules

- Every schema change ships as a new migration file. Never edit an applied one.
- Run the migration tests before calling a database change done.
```

Claude Code loads a rule with `paths` only when Claude reads, writes or edits a matching file, so the database rules above cost nothing in a session that never touches the database. A rule without `paths` loads at launch, with the same priority as `.claude/CLAUDE.md`.

![A project's .claude folder with CLAUDE.md and rules/testing.md loading at launch, and rules/database.md and rules/frontend/components.md loading only on a matching file, so editing src/db/user.ts pulls in the database rules while the component rules never load in a session that opens no .tsx file](https://cdn.aldena.ai/images/blog/share-claude-code-rules-across-a-team-2-20261117.png)

A comment I leave on two pull requests becomes a rule file, named for its topic, like `database.md` or `testing.md`. Conflicts need watching too, because the docs warn that Claude may pick either of two contradicting instructions, and Claude Code v2.1.283 and later checks for them with `/doctor prompt-audit`.

## Rules guide Claude, and settings and hooks enforce

Claude Code treats `CLAUDE.md` and rules as context rather than enforced configuration, so [Anthropic's docs](https://code.claude.com/docs/en/memory) send a hard block to a `PreToolUse` hook or a `permissions.deny` rule.

So a guideline like "prefer small pull requests" fits a rule file, and a boundary like "never read `.env`" goes in the committed `.claude/settings.json`:

```json
{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)", "Bash(git push --force *)"]
  }
}
```

Everyone who clones the repository then gets the same permissions, hooks and plugin settings, and each engineer keeps personal exceptions in `.claude/settings.local.json`. I hadn't expected `deny` and `ask` rules to apply the moment the file lands, while `allow` rules and most `env` values wait until each engineer trusts the folder. The local file also collects each ["Yes, and don't ask again" answer](https://aldena.ai/blog/claude-code-permission-prompts) on a Bash command, and a worktree reads the main checkout's copy, which matters once you [run several Claude Code agents](https://aldena.ai/blog/run-multiple-claude-code-agents) side by side.

![Two columns: CLAUDE.md, .claude/rules and AGENTS.md are context Claude weighs and can still skip, fit for a rule like prefer small pull requests, while permissions.deny, a PreToolUse hook and managed settings are checked before a tool runs, so a rule like never read .env fails the tool call](https://cdn.aldena.ai/images/blog/share-claude-code-rules-across-a-team-3-20261117.png)

When I can't place a rule, I picture Claude ignoring it once. A leaked `.env` or a force-pushed branch calls for a setting or a hook, and anything milder can live in a rule file. An organization that needs a boundary on every machine puts it in managed settings, which no project or user file overrides.

## Sharing rules across many repositories takes imports, symlinks or IT

Claude Code reaches a second repository through `@path` imports, symlinks in `.claude/rules/` or a managed `CLAUDE.md`.

An `@path` line in `CLAUDE.md` pulls in another file, resolved relative to the importing file and at most four hops deep. A path outside the working directory counts as external, so each engineer approves it in a dialog the first time, and declining keeps those imports off for good.

A symlink such as `ln -s ~/shared-claude-rules .claude/rules/shared` puts a shared folder inside a project. A target outside the working directory needs the same one-time approval, per project, and after that only its rules without `paths` load, so path-scoped shared rules quietly do nothing.

A managed `CLAUDE.md` needs IT, which pushes the file to every machine with MDM, Group Policy or Ansible, or puts the text in the `claudeMd` key of `managed-settings.json`. `claudeMdExcludes` can skip any other `CLAUDE.md` in a monorepo, but never this one.

![Four cards: an @path import that asks each engineer for approval once, symlinked rules that need approval per project and then load only rules without paths, a managed CLAUDE.md that IT pushes to every machine, and a red card for copying the rules into each repository, where ten copies drift apart](https://cdn.aldena.ai/images/blog/share-claude-code-rules-across-a-team-4-20261117.png)

I'd avoid the fourth route, a copy of the file in every repository. A copy never changes when the original does, so ten repositories end up with ten slightly different rule sets and nobody can say which is current.

With many repositories, I'd put the few rules that must hold everywhere in the managed file and keep the rest in a shared rules repository that each engineer symlinks into their projects. Approving the link once per project is a small annoyance, and I'll take it over ten drifting copies.

## Teams on Claude Code and Codex can keep one AGENTS.md

Claude Code v2.1.277 and later reads `AGENTS.md` when no `CLAUDE.md` sits in the working directory or above it, and [Codex reads AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md) before doing any work.

`CLAUDE.local.md` counts as a `CLAUDE.md` here. An engineer who adds a personal local file to a repository that relies on `AGENTS.md` silently stops Claude Code from reading `AGENTS.md`, while everyone else still gets it. A short `CLAUDE.md` that imports it closes that gap:

```markdown
@AGENTS.md

## Claude Code only

- Use plan mode before any change that touches more than one package.
```

Claude reads the imported file first and the lines under it second, and the import never makes it read `AGENTS.md` twice. I'd keep the import even on a current version, because the docs list sessions where Claude Code can't read `AGENTS.md` directly (any version before v2.1.277, and in some cases the first session after an upgrade), and the import covers those. A `CLAUDE.md` symlinked to `AGENTS.md` works too, until someone clones the repository on Windows, where Git checks a committed symlink out as a plain text file unless `core.symlinks` is on.

My [writer and reviewer setup for Claude Code and Codex](https://aldena.ai/blog/claude-code-and-codex-together) keeps its rules in this same `AGENTS.md`, with `CLAUDE.md` cut down to the import.

## How shared rules work in Aldena

Aldena shares a convention across projects as a team skill, a versioned document with one team-wide active version that every project on the team serves.

![Aldena's project Skills settings, with a custom release-runbook skill that has a Promote button and a commit-conventions skill marked as shared from the team catalog at version 1](https://cdn.aldena.ai/images/features/skill-marketplace/project-and-shared-skills.png)

This part is about my own product, so weigh it accordingly. A skill isn't an always-on rule, since it loads only for the agents it's assigned to. I write a convention as a [custom skill](https://aldena.ai/features/skill-marketplace) of up to 32,000 characters, assign it to the agents that need it, and promote it. Promoting moves the skill into the team catalog with its version history and agent assignments, and it appears in every project on the team. Switching its active version once makes every project serve the new one, and rolling back means making an earlier version active again.

Skills attach to any agent, and an agent's runtime can be [Claude Code or Codex](https://aldena.ai/features/agents), so the same skill reaches both. Claude Code runs on each member's own Claude plan, or on the team's Anthropic key for anyone who hasn't signed in, and Codex runs on the team's OpenAI key.

Nobody has to retype the conventions a team already keeps in a repository. With [GitHub](https://aldena.ai/integrations/github) or Bitbucket connected to a project, Aldena reads one branch of one repository, in the `.agents`, `.claude` and `.cursor` folders at its root. Skills arrive as custom skills, commands become skills too, and agents arrive as custom agents. Each connection gets one import, and an import is a copy, so later commits in the repository don't change what it created.

For one repository, I still commit `CLAUDE.md` and `.claude/rules/` and stop there. A team skill earns its place once the same convention has to hold in many projects and on both runtimes.
