How do we share one Claude Code setup across a small team?
Commit CLAUDE.md, .claude/settings.json, skills and hooks into each repo so every developer and every agent session starts from the same rules. What goes in the repo, what stays personal, and a checklist to roll it out.
Put the setup in the repository, not on laptops. Claude Code reads CLAUDE.md, .claude/settings.json, .claude/skills/ and .claude/agents/ from the project directory, so once those files are committed, every developer and every agent session on that repo starts with the same instructions, permissions and automation. Hooks are configured in settings.json and can call scripts you keep in the repo, so they travel too. Personal preferences stay in ~/.claude/ and in .claude/settings.local.json, which are not meant to be shared.
What travels with the repo
These are the files Claude Code picks up from the project root. Commit all of them.
| File | What it holds |
|---|---|
CLAUDE.md | Project rules: how to build, test, branch, commit, what never to touch |
<subdir>/CLAUDE.md | Rules that only matter inside that directory; loaded when Claude works there |
.claude/settings.json | Shared permissions (allow, deny, ask) and hooks |
.claude/skills/<name>/SKILL.md | Reusable procedures a developer or an agent can invoke by name |
.claude/agents/<name>.md | Subagent definitions with their own tools and model |
.claude/hooks/*.sh | Our convention: the scripts that hooks in settings.json call; Claude Code reads the hook config, not this folder |
What stays out of the repo:
~/.claude/CLAUDE.mdand~/.claude/settings.json: one person’s defaults across all their projects..claude/settings.local.json: personal overrides for this repo. When Claude Code writes it for a per-machine permission grant, it adds the file to the global git excludes; if you create it by hand, add it to.gitignoreyourself.CLAUDE.local.md: personal notes about the project that should not reach teammates.
Keep the root CLAUDE.md short
The root file loads in every session, so every line costs context for every task. We keep ours to a scope statement, a table of critical rules and the git workflow, and push detail into subdirectory files: src/CLAUDE.md for the website code, scripts/CLAUDE.md for automation and the merge gate, docs/CLAUDE.md for content voice. Claude loads the subdirectory file only when it works in that directory, so the backend rules do not sit in the context of a copy edit.
A root CLAUDE.md that works for a team of three to thirty usually has:
- One paragraph on what the repo is and which sibling repos exist.
- A table of rules that must never be broken (no push to
main, build must pass before commit, commit message format). - The branch, review and merge sequence as commands, not prose.
- Pointers to where the detail lives.
If a rule is enforced by a hook or a script, say so in the file. “Direct gh pr merge is blocked by a hook, use safe-merge.sh” tells the agent what will happen and what to do instead, which is cheaper than letting it find out.
Share permissions, not prompts
Permissions in .claude/settings.json are the part most teams forget to commit. Without them, each developer approves the same npm run build and git commit prompts by hand, and each one ends up with a different local allow list. Our shared file allows the build, check and i18n commands, git add, git commit, git push, and gh pr and gh issue, nothing wider. One detail to tell new teammates: the committed allow rules only take effect after each person has trusted the project folder in Claude Code; deny and ask rules apply straight away. The full breakdown is in our post on which permissions to allow or deny.
Skills instead of pasted instructions
When the same multi-step procedure is explained in chat twice, it becomes a skill: a folder under .claude/skills/ with a SKILL.md that has a name, a description of when to use it, and the steps. Our self-review skill, for example, is the only path for opening a pull request; its description says so, and the root CLAUDE.md names it as the canonical path. Everyone on the team, human or agent, opens PRs the same way because the procedure is a file, not tribal knowledge.
Rollout checklist
- Run
/initonce in the repo if there is noCLAUDE.mdyet, then trim the output to the rules you actually enforce. - Move any rule that appears in two people’s personal files into the repo
CLAUDE.md. - Create
.claude/settings.jsonwith the sharedpermissions.allowlist and the hooks you rely on. Review it in a pull request like any other code. - Confirm
.claude/settings.local.jsonis ignored by git so personal grants do not leak into the shared file, and tell teammates to trust the folder once so the sharedallowrules apply. - Turn repeated chat instructions into
.claude/skills/<name>/SKILL.md. - Add the subdirectory
CLAUDE.mdfiles for the areas that have their own rules. - Ask one teammate to clone fresh on a clean machine and run a routine task. If they get a permission prompt the rest of the team does not, the shared file is incomplete.
What a new laptop should look like
The test we use: clone the repo, install dependencies, open Claude Code. If the session already knows the branch rules, the build command, the review path and which commands it may run without asking, the setup is in the repo. If any of that has to be explained again, it is still on someone’s laptop.
We install exactly this layout across a team’s repositories as a fixed-scope engagement; the details are on our Claude Code fleet setup page.
Ready to automate your business?
Get a free workflow analysis to discover your highest-ROI automation opportunities.