Claude Code for Teams

Quick Answer

A team setup for Claude Code has 3 parts: shared CLAUDE.md committed to the repo, .claude/settings.json with team hooks and MCP servers, and an onboarding checklist for new hires. TLDR: put team rules in the repo, personal rules in the home config, and agree on a model policy to keep cost predictable. Shared skills live in .claude/skills/ and propagate on every git pull.

Summary of the 9 team setup steps

1. Write a team CLAUDE.md at the repo root
2. Configure shared hooks in .claude/settings.json
3. Agree on a model policy for cost management
4. Share skills in .claude/skills/ committed to git
5. Build a new-hire onboarding checklist
6. Set up code review automation with Claude Code Action
7. Define paired session patterns for hard problems
8. Track cost per team member or seat
9. Document incident response for auto-accept mistakes

Team CLAUDE.md

The single most important file for a team is the project CLAUDE.md, committed to git at the repo root. Every team member gets it on clone, changes propagate on pull, and every Claude Code session across the team loads the same rules at session start. Keep it short (150 to 400 words) and cover language version, folder layout, test and lint commands, commit format, and any hard prohibitions (do not edit this file, do not import from this package, do not commit secrets to the repo). Avoid personal preferences: those belong in the home config file. A team CLAUDE.md that reads like a personal diary slows everyone down because every rule is context-loaded on every turn for every team member, which multiplies the cost of bloat. A team CLAUDE.md that reads like a concise rulebook accelerates the whole team with minimal ongoing cost.

Project settings.json

Team-wide configuration lives in .claude/settings.json. Commit it to git. It carries 4 kinds of settings.

Hooks: the PreToolUse and PostToolUse hooks enforced for every team member. Commonly: block rm -rf, block direct pushes to main, enforce conventional commit format.

MCP servers: the project-specific MCP integrations (GitHub, a custom docs server, a database inspector). Configured here so every team member has the same tools.

Default model: the model tier Claude Code uses by default for the project. Teams optimizing for cost often set Sonnet; teams optimizing for speed might set Haiku.

Permission mode: default, plan, or auto-accept. Most teams set default here and let individual sessions toggle as needed.

Personal vs team settings

2 config files and it pays to keep them separate.

~/.claude/settings.json is your personal config. Model preferences you want across every project, personal hooks, your own MCP servers. Not shared.

/.claude/settings.json is the team config. Shared hooks, project MCP servers, team defaults. Committed to git.

The project file overrides the personal file on a per-setting basis. This means you can have a global preference for Haiku, but the team config forces Sonnet for this project.

Keep secrets out of both files. Use env vars for API keys, tokens, and credentials.

Onboarding checklist

A new team member should hit the ground running in under an hour. Here is a 7-step checklist.

1. Install Claude Code via npm globally
2. Authenticate with API key or OAuth (depending on team policy)
3. Clone the repo
4. Verify CLAUDE.md loads (/status shows it)
5. Verify hooks are active (/status shows them)
6. Walk through the 5 core team workflows as skills
7. Run a first task in default mode for 30 minutes

Document this checklist in the repo, ideally as a docs/claude-onboarding.md file referenced from CLAUDE.md. New hires read it once and are set up.

Shared hooks

Hooks are where teams enforce standards that go beyond CLAUDE.md rules. 5 hooks worth sharing across most teams.

1. Block rm -rf outside the project folder
2. Block git push --force to main or master
3. Block writes to files matching secret patterns (.env, .pem, credentials)
4. Enforce conventional commit format
5. Block dependency additions without a changelog entry

Each hook is a shell script in .claude/hooks/. Exit non-zero to block, zero to allow. The .claude/settings.json registers which hook runs on which tool call.

Hooks catch mistakes before they land. A missed conventional commit is annoying; a force-push to main is a real incident. Hooks prevent both.

Model policy

With a team of 5 or more, model choice starts to matter for cost. A typical policy sets 3 tiers.

Haiku for mechanical tasks: lint fixes, import rewrites, formatting, renaming variables. Roughly one third the cost of Sonnet.

Sonnet for feature work, refactors, debugging, and most daily coding. The default for most tasks.

Opus for architecture, hard debugging, and reviews on sensitive code. Roughly 5x Sonnet but worth it when the task actually needs the capability.

A 2026 cost-efficient team setup typically lands on Sonnet default, Haiku for mechanical work, Opus for architecture. Total spend 30 to 40 percent lower than all-Sonnet without a quality drop.

Code review with Claude Code Action

The official GitHub Action runs Claude Code against every PR. It posts review comments, flags issues, and can auto-apply suggested fixes on approval.

A common setup: run the action on every PR, require it to pass before human review, use its output as a first pass that a human reviewer builds on.

This reduces reviewer load roughly 40 percent without losing quality. Humans still catch the judgment calls; Claude handles the mechanical checks.

Paired sessions for hard problems

2 developers can share a single Claude Code session via screen share or tmux. One developer drives, one navigates. Claude does the mechanical work while humans discuss approach.

This works best on thorny debugging, new feature architecture, and risky refactors. The pair acts as a check on prompts before they are sent, catching vague or wrong instructions that a solo developer might send.

Cost stays the same as a single-developer session. Throughput often improves 1.5x because 2 brains catch more than 1.

Shared skills

Skills at .claude/skills/ are team workflows in file form. /commit, /review, /deploy, /release, /test are common across most teams.

Commit the skills folder to the repo. Every team member gets the same commands on clone. Updates propagate on pull.

This matters most for workflows that have rules (conventional commits, specific deploy sequences, release tagging conventions). Skills enforce the rules by wrapping the workflow.

Cost tracking per team member

2 paths depending on auth mode.

API key billing: generate a key per team member. The Anthropic console shows usage per key. Easy to see who spends what.

OAuth subscription: each team member logs in with their own claude.ai account. The seat-level billing shows usage per seat.

Set a monthly budget per team member. A typical pattern: active developers get 1000 USD/month of API budget or a Max tier OAuth seat. Power users get more, part-time users less.

Security policy

Claude Code reads and writes files. It runs shell commands. It can call APIs. 3 categories of policy matter for teams.

What Claude can touch. Project files yes. System files no. Production credentials no.

What Claude can run. Shell commands yes, but hooked. Deploy scripts only after human approval. Database migrations only in staging unless explicitly authorized.

What Claude can send. Source code stays within the team. PII never leaves the machine without explicit approval.

Document these policies in CLAUDE.md or a referenced docs/security.md. Make them enforceable through hooks where possible.

Incident response

Auto-accept mistakes happen. 4 steps of incident response.

Stop the session immediately. Ctrl-C or close the terminal.

Assess damage. Run git status to see uncommitted changes. Run git log to see committed changes. Check any external systems the session might have touched.

Roll back. Git reset for committed changes. Git stash for uncommitted. Contact external service owners if the session touched production data.

Learn. Add a hook to prevent the recurrence. Update CLAUDE.md if a rule was missing. Write a short postmortem if the incident had real impact.

Most teams hit 1 or 2 minor incidents in their first month with auto-accept and none afterwards. The hooks get tighter, the habits get better, and the risk drops.

A team setup checklist

Before declaring the team setup complete, verify 8 things.

1. Team CLAUDE.md committed and reviewed
2. .claude/settings.json with hooks committed
3. 5 core skills in .claude/skills/
4. Onboarding doc written and tested with a new hire
5. Model policy documented and agreed
6. Cost tracking set up per team member
7. Code review automation configured on PRs
8. Incident response documented

This is roughly a 2-day setup for a 5-person team. The payoff is consistent workflows, predictable cost, and fewer incidents. Well worth the investment.