
How to share Claude Code rules across a team
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.
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 into every engineer's session at launch. I checked every path, setting and version number below against Anthropic's memory and 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.
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.
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:
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 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 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:
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 on a Bash command, and a worktree reads the main checkout's copy, which matters once you run several Claude Code agents side by side.
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.
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 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:
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 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.
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 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, 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 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.
spin up your first project.
one project per client, product, or piece of work, staffed with intake, requirements, build and code review agents.