Claude Code for Teams: Setup Guide

Why team setup matters

Claude Code works differently from IDE-based AI tools when you bring a team onto it. There's no centralized dashboard or admin panel managing everyone's experience. Instead, Claude Code reads configuration files from your repository, and whoever controls those files controls how Claude behaves for every developer on the team.

This is actually a strength. Configuration-as-code means your AI behavior is version-controlled, reviewable, and consistent. But it also means a team that skips the setup phase ends up with five developers getting five different Claude Code experiences from the same codebase.

This guide covers the practical steps to go from individual Claude Code usage to a team-wide setup that produces consistent results. If you haven't used Claude Code before, start with our introduction to Claude Code.

The configuration layer system

Claude Code loads settings from multiple layers, and understanding this hierarchy is essential for teams. Settings merge from broadest to most specific:

1. Personal global: ~/.claude/settings.json and ~/.claude/CLAUDE.md. These are per-developer preferences that follow them across all projects. Never commit these.
2. Project shared: .claude/settings.json and CLAUDE.md at the project root. Committed to git. Every team member gets these automatically when they clone or pull.
3. Personal project overrides: .claude/settings.local.json and CLAUDE.local.md. Per-developer overrides for a specific project. Git-ignored.

The key insight: layer 2 is where team consistency lives. Everything you want standardized goes into the committed project files. Everything personal stays in layers 1 or 3.

# What gets committed (team-wide)
.claude/settings.json      # Hooks, permissions, tool config
CLAUDE.md                  # Project instructions, conventions, architecture
.claude/skills/            # Shared skill definitions

# What stays local (per-developer)
~/.claude/settings.json    # Personal global preferences
.claude/settings.local.json # Personal project overrides
CLAUDE.local.md            # Individual notes, experiments

Writing a team CLAUDE.md

The CLAUDE.md file is the single most important artifact for team consistency. When every developer shares the same CLAUDE.md, Claude behaves the same way regardless of who's running it.

A good team CLAUDE.md covers four areas:

Project architecture. What the codebase is, how it's structured, where things live. Claude uses this to navigate the repository without wasting time exploring.

## Architecture
- Frontend: Next.js 15 app router in `src/app/`
- API: tRPC routes in `src/server/api/`
- Database: Drizzle ORM, schema in `src/server/db/schema.ts`
- Tests: Vitest, co-located with source files as `*.test.ts`

Coding conventions. The rules your team follows. Be specific: vague instructions produce vague results.

## Conventions
- Use named exports, never default exports
- Error handling: return Result types, never throw
- All API endpoints need input validation with Zod
- Database queries go through repository functions, never raw SQL in routes

Verification commands. Tell Claude how to check its own work. This is the most commonly missed section and the one that matters most for quality.

## Verification
- Run `pnpm typecheck` after any TypeScript changes
- Run `pnpm test:unit` after modifying business logic
- Run `pnpm lint` before considering any task complete

Boundaries. What Claude should not touch. Explicit boundaries prevent the most common team frustrations.

## Boundaries
- Never modify migration files directly: use `pnpm db:generate`
- Don't change CI/CD config without explicit permission
- The `lib/legacy/` directory uses old patterns intentionally, don't refactor it

Write the CLAUDE.md collaboratively. The developers who know the codebase best should contribute the architecture and conventions sections. Review it like you would any other code change. For a deeper dive into CLAUDE.md authoring, see our CLAUDE.md explained guide.

Shared hooks for team guardrails

Hooks are where you enforce rules that can't be left to interpretation. Unlike CLAUDE.md instructions (which Claude follows voluntarily), hooks are deterministic shell scripts that block or allow actions.

For teams, the most valuable hooks are:

Block writes to protected files. Every team has files that shouldn't be casually modified: environment configs, migration files, CI pipelines. A PreToolUse hook blocks these regardless of which developer is running Claude.

Enforce formatting. A PostToolUse hook that runs your formatter after every file edit eliminates style inconsistencies. Claude writes the code, Prettier formats it, and the result matches your team standards.

Guard destructive operations. Block git push --force, git reset --hard, and other commands that can affect shared branches.

Commit these hooks in .claude/hooks/ and reference them from .claude/settings.json. When a new developer clones the repo, they get the hooks automatically.

Shared skills for repeatable workflows

If your team has standard procedures, like deploying to staging, running database migrations, or creating new API endpoints, encode them as skills. Skills live in .claude/skills/ and get committed to the repository.

A shared deployment skill means any developer can ask Claude to deploy, and it follows the exact same procedure every time. No one needs to remember the sequence of commands or the correct flags.

# .claude/skills/deploy-staging/SKILL.md
---
name: deploy-staging
description: Deploy the current branch to the staging environment. Use when asked to deploy, ship to staging, or push to staging.
---

## Steps
1. Run `pnpm typecheck`: abort if it fails
2. Run `pnpm test:unit`: abort if it fails
3. Run `pnpm build`: abort if it fails
4. Run `./scripts/deploy.sh staging`
5. Verify deployment at https://staging.example.com/health
6. Report the deployment status and URL

The difference between a team with shared skills and a team without is the difference between consistent processes and tribal knowledge. Skills make implicit procedures explicit.

Agent teams: multiple Claude instances working together

Claude Code supports an experimental feature called agent teams: multiple Claude Code instances coordinating on a shared task. One session acts as the team lead, assigning work and synthesizing results. Teammates work independently in their own context windows.

This is different from subagents. Subagents are focused workers that report back to a single parent. Agent team members can communicate with each other, challenge findings, and coordinate independently.

Enable agent teams by adding the experimental flag:

{
  "experimental": {
    "agent_teams": true
  }
}

Agent teams work best for:

• Research tasks: multiple teammates investigate different aspects simultaneously, then share findings
• Cross-layer changes: frontend, backend, and test modifications each owned by a different teammate
• Debugging: teammates test competing hypotheses in parallel and converge on the answer
• New feature development: teammates each own a separate module without stepping on each other

Every teammate loads the same CLAUDE.md, hooks, and skills as a regular session. Your team configuration investment pays off doubly here: each agent instance behaves consistently because the shared config is already in place.

Team plan vs individual plans

Anthropic offers a Team plan alongside individual Pro and Max plans. The Team plan ($30/seat/month, billed annually) adds:

• Admin controls: manage who has access, set usage policies
• Higher usage limits: more generous than individual Pro
• Centralized billing: one invoice for the organization
• Early access: some features reach Team plans before individual plans

For small teams (under 5 developers), individual Pro or Max plans often work fine. The Team plan becomes valuable at scale, when you need admin controls and consolidated billing.

The Team plan does not change how Claude Code's configuration system works. The configuration layers, shared CLAUDE.md, hooks, and skills work identically regardless of billing plan. The Team plan handles the business side, access management and billing, while the repository configuration handles the technical side.

Permission management across a team

Claude Code's permission system controls what tools Claude can use without asking. On a team, you want a baseline permission set committed to the repository so everyone starts from the same point.

In .claude/settings.json, set allowed and denied tool patterns:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(pnpm:*)",
      "Bash(git:status)",
      "Bash(git:diff*)",
      "Bash(git:log*)"
    ],
    "deny": [
      "Bash(rm:*)",
      "Bash(curl:*)",
      "Bash(wget:*)"
    ]
  }
}

Individual developers can loosen permissions in their .claude/settings.local.json if they need broader access for specific workflows. But the baseline keeps everyone safe by default.

Onboarding a new team member

With proper team configuration, onboarding a new developer onto Claude Code takes minutes:

1. They install Claude Code (npm install -g @anthropic-ai/claude-code)
2. They authenticate with their Anthropic account (Pro, Max, or Team plan)
3. They clone the repository, which includes CLAUDE.md, .claude/settings.json, hooks, and skills
4. They run claude in the project directory

That's it. The shared configuration means they get the same Claude behavior as everyone else from their first session. No setup guides, no "ask Sarah how she configured her Claude": the configuration is the documentation.

Common pitfalls to avoid

Overly long CLAUDE.md files. If your CLAUDE.md exceeds a few hundred lines, Claude spends too much context window reading instructions instead of doing work. Keep it focused on what matters for day-to-day development. Move detailed procedures into skills.

Conflicting personal overrides. If developers override shared settings aggressively, you lose the consistency benefit. Establish a team norm: personal overrides are for preferences (like notification style), not for disabling safety hooks.

No version control on settings changes. Treat .claude/settings.json and CLAUDE.md changes like code changes: they go through pull requests with review. A bad settings change can break hooks for the entire team.

Skipping the verification section. Without verification commands in CLAUDE.md, Claude produces code that passes its own judgment but may not pass your CI pipeline. Always tell Claude how to check its work.

Start with the basics

If your team is adopting Claude Code, start here:

1. Write a shared CLAUDE.md with architecture, conventions, and verification commands
2. Add two hooks: block sensitive file writes, guard destructive git commands
3. Commit everything to the repository
4. Have each developer set up their personal authentication

Everything else, including skills, agent teams, and MCP servers, is optimization. The shared CLAUDE.md and basic hooks give you 80% of the team consistency benefit with 20% of the effort.

Want a production-ready team configuration out of the box? Claudify includes pre-built CLAUDE.md templates, 21 hook configurations, shared skills, and a complete team setup guide: everything your team needs to run Claude Code consistently from day one.

Frequently asked questions

Can different team members use different Claude plans?

Yes. Claude Code's configuration system is plan-agnostic. A developer on Pro and a developer on Max both load the same CLAUDE.md, hooks, and skills. The only difference is usage limits: Max users can do more before hitting rate limits. The Team plan adds admin controls but doesn't change configuration behavior.

Do agent teams require the Team billing plan?

No. Agent teams are a Claude Code feature, not a billing feature. Any developer with Claude Code access (Pro, Max, or Team plan) can use agent teams. The Team billing plan manages seats and billing. Agent teams manage multiple Claude instances within a single developer's session.

How do we handle CLAUDE.md conflicts during merges?

Treat CLAUDE.md like any other code file: resolve conflicts manually during merge. In practice, conflicts are rare if you structure the file with clear sections. Each section (architecture, conventions, verification, boundaries) maps to a different concern, so parallel changes rarely touch the same lines. If your team modifies CLAUDE.md frequently, consider splitting instructions into separate files that CLAUDE.md references.