Claude Code for Teams: Shared Configuration Patterns

By Tyler Cyert

Configuring Claude Code for teams means setting up shared conventions that every developer's Claude Code sessions follow — while leaving room for personal customization. The goal is consistency: whether a junior developer or a senior architect runs Claude Code on your codebase, the agent follows the same rules, permissions, and patterns.

Claude Code's configuration system is designed for teams from the ground up. Committed files define team standards. Gitignored files hold personal preferences. The two layers compose without conflicting.

The Team Configuration Stack

Everything in the "Yes" column is version-controlled and reviewed in pull requests. Everything in the "No" column is personal and never shared.

Setting Up Team Configuration

1. Write a Shared CLAUDE.md

Your CLAUDE.md is the team's agent instruction manual. Include:

• Project overview and current state
• Stack and major dependencies
• Build, test, and lint commands
• Architecture and key directories
• Coding conventions the team agreed on
• Guardrails (things the agent must never do)

Keep it under 200 lines. Review it in PRs like any other code.

2. Define Shared Permissions

Your team's settings.json should include permissions that enforce team policies:

• Allow read operations and safe build commands
• Deny destructive operations (force push, database reset, production deploys)
• Let individual developers override with their local settings

The committed settings.json is the team's security baseline. No one's Claude Code session can bypass deny rules, regardless of their local overrides.

3. Add Shared Hooks

Hooks in settings.json enforce team automation:

• Auto-formatting ensures consistent code style without discussion
• Test running catches regressions before they reach PR review
• Lint checking maintains code quality standards

Because hooks are deterministic, every team member gets the same automated checks regardless of their local preferences.

4. Create Shared Rules

Move file-specific conventions from CLAUDE.md into rules:

• Component conventions for React files
• API handler patterns for route files
• Database rules for schema and migration files
• Test conventions for test files

Rules load only when relevant files are touched, keeping each session's context lean.

5. Define Agent Roles

If your team uses agent teams, define the roles in .claude/agents/. These definitions are committed and shared — every developer's agent team uses the same role definitions.

Personal Customization

CLAUDE.local.md

Each developer creates their own CLAUDE.local.md for personal preferences:

• Verbosity level (terse vs. explanatory responses)
• Local environment paths
• Personal workflow shortcuts
• Temporary debugging context

settings.local.json

Personal tool configuration:

• Additional allows for commands only you run
• MCP server connections with personal API keys
• Model preferences (if your team allows different models)

Onboarding New Developers

With proper team configuration, onboarding a new developer to your Claude Code setup takes minutes:

1. Clone the repo (configuration comes with it)
2. Create CLAUDE.local.md (optional, for personal preferences)
3. Create settings.local.json (for personal API keys)
4. Start coding

The new developer's Claude Code sessions immediately follow team conventions, use the right permissions, and run the same hooks. No separate setup guide needed — the configuration is the guide.

Managing Configuration Changes

Review in PRs

Changes to CLAUDE.md, settings.json, rules, and agent definitions should go through pull request review. These files define your team's coding standards — treat them with the same rigor as code changes.

Avoid Breaking Changes

When updating shared configuration, consider the impact on existing workflows. If you add a new deny rule, make sure no one's active development depends on that command. If you change a convention in CLAUDE.md, update the corresponding code or add a migration plan.

Document the Why

When adding rules or permissions, include a brief comment about why. "Never modify migration files" is clearer with context: "Applied migrations cannot be safely changed without a new migration."

Common Team Patterns

Small Team (2-5 developers)

• One CLAUDE.md with full project context
• One settings.json with shared permissions and hooks
• 3-5 rules for major file types
• No agent team definitions (use subagents for parallel work)

Medium Team (5-15 developers)

• CLAUDE.md focused on high-level context
• Comprehensive rules for each layer of the stack
• Agent definitions for common roles (reviewer, test writer)
• Skills for team-specific procedures (deploy, release, hotfix)

Large Team (15+ developers)

• Minimal CLAUDE.md (architecture and links to docs)
• Extensive rules with clear ownership
• Full agent team definitions with role-based permissions
• Skills library for operational procedures
• Managed settings for organizational policies

Scaffolding Team Configuration with DotBox

Setting up Claude Code for a team means coordinating CLAUDE.md, settings.json, rules, skills, agents, and directory structure across committed and gitignored files. DotBox turns it into one setup prompt — draw your team's agents, their tools and the skills they share, paste the prompt into Claude Code, review what it wrote, and commit it to your repo. Every developer on the team gets the same starting point from the first git pull.