Claude Code for Teams: Setup, Shared Config, and Best Practices

Q: Q: Can developers override the repo-level settings.json with their personal settings?

A: User-level ~/.claude/settings.json and project-level .claude/settings.json are merged, with project-level taking precedence for conflicting keys. A developer cannot override a project-level deny entry with a user-level allow. This is by design — project policy wins.

Q: Q: How do we handle API keys securely across the team?

A: Issue each developer a unique API key from the Anthropic Console. Never commit an API key to the repo. If a key is exposed, rotate it immediately in the Console. The shared .claude/settings.json should not contain any credentials — only permissions configuration.

Q: Q: What's the right spend limit to set for a developer?

A: Start at $75/month for active developers and review after 30 days. Most developers running Claude Code 4–6 hours per day on a real codebase with Sonnet as the default model will spend $40–$80/month. Opus-heavy workflows can reach $200+/month.

Q: Q: Should CLAUDE.md be committed or gitignored?

A: Commit it. The repo-level CLAUDE.md is part of your codebase's infrastructure. It should go through code review like any other configuration file. Treat significant changes to CLAUDE.md the same as changes to .eslintrc or tsconfig.json — they affect every developer.

Q: Q: How do we enforce that developers actually use the shared CLAUDE.md and don't ignore it?

A: Claude Code reads CLAUDE.md automatically on every session start. Developers can't bypass it without explicitly using --no-context flags. For extra enforcement, add a CI check that verifies key sections of CLAUDE.md haven't been removed (grep -q "Banned Operations" CLAUDE.md || exit 1).

Teams using Claude Code need more than a solo developer setup. A shared repo-level CLAUDE.md, committed .claude/settings.json with an explicit permissions allowlist, per-developer spend tracking, and a one-day onboarding checklist are the four pillars. Without them, costs balloon, behavior drifts between developers, and security reviews fail. This guide gives you every piece. For the full solo-developer reference, see the Claude Code Complete Guide.

Why Team Setup Differs from Solo Use

A solo developer can rely on memory for context and tolerate inconsistent behavior. A team cannot. Three problems compound quickly without structure:

Consistency drift. Developer A has a global ~/.claude/CLAUDE.md that instructs Claude to always use TypeScript strict mode. Developer B has nothing. The same codebase produces different AI outputs depending on who is driving.

Cost sprawl. Claude Code charges per token at the API level. A single developer running exploratory sessions can consume $50–$200 in a day without realizing it. Multiply by 10 developers and a month of work and you have a surprise invoice that ends the program.

Security gaps. Claude Code can run shell commands, edit files, and call external APIs. Without an explicit allow/deny list committed to the repo, any developer's session can—accidentally or not—run destructive operations.

The fix is a small amount of upfront configuration stored in version control so every developer gets the same behavior on git clone.

The Two-Layer Config System

Claude Code reads configuration from two places, applied in order:

User-level: ~/.claude/CLAUDE.md and ~/.claude/settings.json — personal preferences, global API key, personal tool permissions.
Project-level: <repo-root>/.claude/settings.json and <repo-root>/CLAUDE.md — team standards, committed to git, applies to everyone.

Project-level config overrides user-level where they conflict. This is the right default for teams: shared rules win.

Shared CLAUDE.md: What Goes Where

Repo-level CLAUDE.md (commit this)

The repo-level CLAUDE.md is the source of truth for how Claude should behave in this specific codebase. It should answer every question Claude might ask itself when working in your repo.

Sections to include:

1. Project overview (2–3 sentences). What the repo does, primary language, framework.

2. Architecture summary. Key directories, what lives where, module boundaries. Claude reads this to understand the blast radius of any change.

3. Coding standards. Linter config (ESLint, Ruff, etc.), naming conventions, import order, preferred patterns for async/error handling.

4. Test policy. Which test framework, where tests live, required coverage thresholds, how to run the test suite.

5. Build and run commands. Exact commands to install dependencies, run dev server, build for production. Claude runs these when verifying its own changes.

6. Banned operations. Explicit list: "Never run db:drop. Never push to main directly. Never delete the .env.example file." Putting these in CLAUDE.md means they're visible to every session.

7. External services. Which APIs the project calls, which environment variables are required, where secrets are managed (e.g., AWS Secrets Manager, not .env files).

8. PR conventions. Branch naming, commit message format, PR size guidelines. Claude will follow these when creating branches and commit messages.

9. Dependency policy. Approved package registries, how to add a new dependency (e.g., "open a PR with justification"), any banned packages.

10. Known issues / active work. A short list of files or modules under active refactoring that Claude should treat as unstable. This prevents Claude from generating code that interacts with half-finished migrations.

User-level ~/.claude/CLAUDE.md (personal, not committed)

Each developer's personal CLAUDE.md should cover preferences that are theirs alone:

Preferred editor key bindings for diff review
Personal shortcuts ("when I say 'ship it' I mean create a PR, not push to main")
Output verbosity preferences
Personal API key and model preferences

Keep the split clean: repo CLAUDE.md = team standards; personal CLAUDE.md = individual workflow.

Team .claude/settings.json: Shared Permissions

The most security-relevant file to commit is .claude/settings.json. This controls what Claude Code is allowed to do without prompting the developer for confirmation.

A well-structured team settings file:

{
  "permissions": {
    "allow": [
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(git log:*)",
      "Bash(git add:*)",
      "Bash(git commit:*)",
      "Bash(git checkout:*)",
      "Bash(git branch:*)",
      "Bash(cat:*)",
      "Bash(ls:*)",
      "Bash(grep:*)",
      "Bash(find:*)",
      "Bash(curl https://api.yourservice.com/*)",
      "Read(*)",
      "Edit(*)",
      "Write(src/**)",
      "Write(tests/**)"
    ],
    "deny": [
      "Bash(git push --force:*)",
      "Bash(git push origin main:*)",
      "Bash(rm -rf:*)",
      "Bash(DROP TABLE:*)",
      "Bash(kubectl delete:*)",
      "Bash(aws s3 rm:*)",
      "Write(.env)",
      "Write(*.pem)",
      "Write(secrets/**)"
    ]
  }
}

Key design decisions:

Allowlist read/diff/test commands so Claude can verify its own work without interruption.
Allowlist git commit but deny git push --force and direct main pushes. Claude creates commits; humans (or CI) do the pushing.
Deny writes to secrets files explicitly. Even if Claude's instructions say to update .env, the permissions layer stops it.
Scope writes to src/ and tests/ for maximum safety. Extend as needed for your repo structure.

Commit this file. Every developer who clones the repo inherits these boundaries automatically.

Cost Management for Teams

How Claude Code billing works

Claude Code uses your Anthropic API key. Every message — input and output tokens — is billed at the standard API rate for the model in use. A developer running Claude Code for 8 hours might consume $30–$150 depending on session intensity and model choice.

Tracking spend per developer

The cleanest approach: issue each developer a separate API key (Anthropic supports multiple keys per account). Set spending limits per key in the Anthropic Console under Settings → API Keys → Spend Limits.

Recommended limits by role:

Senior engineers / active feature work: $100/month soft limit, $200 hard limit
Junior engineers / learning: $50/month soft limit, $75 hard limit
QA / light use: $25/month hard limit

Soft limits send an email alert. Hard limits stop API calls until the next billing cycle or until you raise them manually.

Model selection as a cost lever

The biggest cost variable is model selection. Teams should default to Claude Sonnet 4 for most work, and explicitly gate Opus usage to tasks that need it (complex architectural reasoning, ambiguous refactors).

Add to your repo CLAUDE.md:

Default model: claude-sonnet-4-5 for all tasks.
Use claude-opus-4 only for: architecture planning, cross-cutting refactors, security review.
Never use claude-opus-4 for: generating boilerplate, running tests, formatting.

Claude Code respects model instructions in CLAUDE.md when using the /model command or when invoked from scripts.

Prompt caching to reduce repeat costs

If your team runs Claude Code against the same large codebase repeatedly, enable prompt caching in any API-level tooling. Prompt caching gives up to 90% cost reduction on repeated context. As of April 2026, Claude Sonnet cached input tokens cost $0.30/MTok vs $3.00/MTok uncached — a 10x reduction. See the Claude Prompt Caching Guide for a step-by-step implementation.

Onboarding New Developers

A new developer should be productive with Claude Code within 4 hours. Here is the checklist:

Day 1 checklist

Environment setup (30 minutes)

Install Claude Code: npm install -g @anthropic-ai/claude-code
Set personal API key: claude config set apiKey sk-ant-...
Verify installation: claude --version
Clone repo — .claude/settings.json and CLAUDE.md are already present

Configuration (20 minutes)

Create personal ~/.claude/CLAUDE.md with name, preferred output style
Run claude /permissions to review what the repo allows and denies
Set a personal spend limit in the Anthropic Console

First tasks with Claude Code (2 hours)

Run claude "explain the architecture of this repo" — verifies Claude reads CLAUDE.md correctly
Run claude "find all TODO comments and categorize them by module" — safe read-only exploration
Run claude "write a test for [simple function]" — first write operation
Review the diff, approve, run the test suite

Team practices review (1 hour)

Read the repo CLAUDE.md fully
Review .claude/settings.json allow/deny list
Understand the git workflow (no direct pushes to main, PR required)
Confirm personal API key has a spend limit set

First commands every developer should run

# Check what Claude knows about the repo
claude "summarize this codebase for a new developer"

# Explore safely before making changes
claude "what are the riskiest files to modify and why"

# Test the permissions setup
claude "try to write to .env and tell me what happened"

Security Policies for Shared Codebases

What to put in permissions.deny

Beyond the obvious destructive commands, deny these for shared enterprise codebases:

"deny": [
  "Bash(curl * | bash:*)",
  "Bash(wget * | sh:*)",
  "Bash(pip install:*)",
  "Bash(npm install -g:*)",
  "Bash(brew install:*)",
  "Bash(git remote add:*)",
  "Bash(git remote set-url:*)",
  "Write(Dockerfile)",
  "Write(.github/**)",
  "Write(*.tfvars)",
  "Write(terraform/**)"
]

Rationale:

Pipe-to-shell patterns (curl | bash) are the canonical supply chain attack vector.
Global package installs should go through your dependency policy process, not ad-hoc Claude sessions.
Git remote changes prevent Claude from accidentally adding or redirecting remotes.
Infrastructure files (Dockerfile, Terraform) change the security perimeter — require human review.

Auditing Claude Code sessions

Claude Code logs session activity to ~/.claude/logs/ by default. For compliance-sensitive teams, redirect these logs to a central location. Add to your CI pipeline a weekly scan of .claude/settings.json to ensure the deny list hasn't been modified:

git diff origin/main -- .claude/settings.json | grep -E '"deny"' && echo "Deny list changed — requires security review"

Git Hooks + Claude Code: Team-Level Policy Enforcement

Git hooks run before commits and pushes, making them ideal for policy enforcement that doesn't rely on developers remembering the rules.

Pre-commit hook: prevent secrets

#!/bin/bash
# .git/hooks/pre-commit
# Block commits that contain obvious secret patterns

if git diff --cached | grep -E '(sk-ant-[a-zA-Z0-9]+|AKIA[A-Z0-9]{16}|ghp_[a-zA-Z0-9]+)'; then
  echo "ERROR: Possible API key or secret detected in staged changes."
  echo "Remove the secret before committing."
  exit 1
fi

Commit-msg hook: enforce format

#!/bin/bash
# .git/hooks/commit-msg
# Enforce conventional commits format

commit_msg=$(cat "$1")
pattern='^(feat|fix|chore|docs|refactor|test|ci|perf|style|revert)(\([a-z0-9-]+\))?: .{1,72}$'

if ! echo "$commit_msg" | grep -qE "$pattern"; then
  echo "ERROR: Commit message must follow conventional commits format."
  echo "Example: feat(auth): add OAuth2 login flow"
  exit 1
fi

To share hooks with the team (hooks aren't committed with .git), store them in .githooks/ and add to your repo CLAUDE.md:

Run once after cloning: git config core.hooksPath .githooks && chmod +x .githooks/*

Claude Code will follow the commit message format because it's in CLAUDE.md and enforced by the commit-msg hook.

Complete Team CLAUDE.md Template

Copy and adapt this template for your repo:

# [Project Name] — Claude Code Configuration

## 1. Project Overview
[2–3 sentences: what the project does, primary stack, production URL]

## 2. Architecture
- `src/` — application source
- `src/api/` — API route handlers
- `src/services/` — business logic
- `src/models/` — database models
- `tests/` — test suite (mirrors src/ structure)
- `infra/` — Terraform and deployment config (human review required)

## 3. Coding Standards
- Language: TypeScript 5.x, strict mode enabled
- Formatter: Prettier (run `npm run format`)
- Linter: ESLint (run `npm run lint`)
- Imports: absolute paths from `src/`, no relative `../../` beyond 1 level
- Error handling: always use typed errors, never throw plain strings

## 4. Test Policy
- Framework: Vitest
- Location: `tests/` mirroring source structure
- Coverage threshold: 80% lines
- Run: `npm run test`
- New code requires tests before PR approval

## 5. Build and Run
```bash
npm install          # install dependencies
npm run dev          # development server (port 3000)
npm run build        # production build
npm run test         # full test suite
npm run lint         # lint check
npm run format       # auto-format

6. Banned Operations

Never run DROP TABLE or equivalent destructive DB commands
Never push to main directly — all changes via PR
Never delete or modify .env.example
Never commit credentials, API keys, or tokens
Never modify files in infra/ without a linked Jira ticket

7. External Services

PostgreSQL: connection via DATABASE_URL env var
Redis: connection via REDIS_URL env var
Auth: Auth0 tenant (credentials in AWS Secrets Manager, not .env)
Email: Sendgrid via SENDGRID_API_KEY

8. PR Conventions

Branch: <type>/<ticket-id>-<short-description> (e.g., feat/ENG-123-add-oauth)
Commits: conventional commits format (enforced by hook)
PR size: under 400 lines changed preferred; split larger work
Required reviewers: 1 senior engineer + automated CI pass

9. Dependency Policy

New dependencies require a PR description explaining necessity
No packages with known CVEs (checked by Dependabot)
Prefer packages with >1000 weekly downloads and active maintenance
Pin exact versions in production dependencies

10. Active Work / Unstable Files

src/services/billing.ts — under refactor as of 2026-Q2, treat as unstable
src/models/user.ts — schema migration in progress, do not modify
tests/integration/ — being migrated to Playwright, existing tests may fail

11. Model Guidance

Default: claude-sonnet-4-5
Use Opus only for: architecture decisions, security review, complex refactors
Always run npm run test and npm run lint after making changes


---

## FAQ

**Q: Can developers override the repo-level settings.json with their personal settings?**

A: User-level `~/.claude/settings.json` and project-level `.claude/settings.json` are merged, with project-level taking precedence for conflicting keys. A developer cannot override a project-level `deny` entry with a user-level `allow`. This is by design — project policy wins.

**Q: How do we handle API keys securely across the team?**

A: Issue each developer a unique API key from the Anthropic Console. Never commit an API key to the repo. If a key is exposed, rotate it immediately in the Console. The shared `.claude/settings.json` should not contain any credentials — only permissions configuration.

**Q: What's the right spend limit to set for a developer?**

A: Start at $75/month for active developers and review after 30 days. Most developers running Claude Code 4–6 hours per day on a real codebase with Sonnet as the default model will spend $40–$80/month. Opus-heavy workflows can reach $200+/month.

**Q: Should CLAUDE.md be committed or gitignored?**

A: Commit it. The repo-level `CLAUDE.md` is part of your codebase's infrastructure. It should go through code review like any other configuration file. Treat significant changes to CLAUDE.md the same as changes to `.eslintrc` or `tsconfig.json` — they affect every developer.

**Q: How do we enforce that developers actually use the shared CLAUDE.md and don't ignore it?**

A: Claude Code reads CLAUDE.md automatically on every session start. Developers can't bypass it without explicitly using `--no-context` flags. For extra enforcement, add a CI check that verifies key sections of CLAUDE.md haven't been removed (`grep -q "Banned Operations" CLAUDE.md || exit 1`).

---

## Sources

- [Claude Code documentation — CLAUDE.md files](https://docs.anthropic.com/en/docs/claude-code/memory)
- [Claude Code settings.json reference](https://docs.anthropic.com/en/docs/claude-code/settings)
- [Claude Code permissions system](https://docs.anthropic.com/en/docs/claude-code/security)
- [Anthropic Console — API key management](https://console.anthropic.com/)
- [Claude API pricing](https://www.anthropic.com/pricing)
- [Conventional Commits specification](https://www.conventionalcommits.org/)

---

## Take It Further

**[Claude Code Power Prompts 300](https://shoutfirst.gumroad.com/l/agfda?utm_source=claudeguide&utm_medium=article&utm_campaign=claude-code-for-teams)** — 300 battle-tested prompts for Claude Code, organized by use case. Copy, paste, ship.

40 slash command templates. Token-optimized variants. JSONL file for direct import. Tested in production sessions.

[→ Get Claude Code Power Prompts 300 — $29](https://shoutfirst.gumroad.com/l/agfda?utm_source=claudeguide&utm_medium=article&utm_campaign=claude-code-for-teams)

*30-day money-back guarantee. Instant download.*