Skip to main content
Back to Blog
· Futurist Systems

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.

Claude Code team setup CLAUDE.md developer tooling

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.

FileWhat it holds
CLAUDE.mdProject rules: how to build, test, branch, commit, what never to touch
<subdir>/CLAUDE.mdRules that only matter inside that directory; loaded when Claude works there
.claude/settings.jsonShared permissions (allow, deny, ask) and hooks
.claude/skills/<name>/SKILL.mdReusable procedures a developer or an agent can invoke by name
.claude/agents/<name>.mdSubagent definitions with their own tools and model
.claude/hooks/*.shOur 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.md and ~/.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 .gitignore yourself.
  • 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:

  1. One paragraph on what the repo is and which sibling repos exist.
  2. A table of rules that must never be broken (no push to main, build must pass before commit, commit message format).
  3. The branch, review and merge sequence as commands, not prose.
  4. 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

  1. Run /init once in the repo if there is no CLAUDE.md yet, then trim the output to the rules you actually enforce.
  2. Move any rule that appears in two people’s personal files into the repo CLAUDE.md.
  3. Create .claude/settings.json with the shared permissions.allow list and the hooks you rely on. Review it in a pull request like any other code.
  4. Confirm .claude/settings.local.json is ignored by git so personal grants do not leak into the shared file, and tell teammates to trust the folder once so the shared allow rules apply.
  5. Turn repeated chat instructions into .claude/skills/<name>/SKILL.md.
  6. Add the subdirectory CLAUDE.md files for the areas that have their own rules.
  7. 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.