Skip to content
Lesson 13 of 14

Team Setup and Best Practices

8 min read

From Individual to Team

Using Claude Code as a solo developer is straightforward. You configure it to your preferences, learn the features, and develop your own workflows. Scaling that to a team introduces new challenges: consistency, governance, cost management, and knowledge sharing. This lesson covers how to set up Claude Code for team adoption so that every developer benefits from shared best practices without sacrificing individual flexibility.

Team Onboarding With Shared CLAUDE.md

The foundation of team-wide Claude Code usage is a shared CLAUDE.md file committed to your repository root. This file establishes the conventions that every developer's Claude Code session will follow:

# Project: Acme API

## Architecture
- Monorepo with packages/ directory (api, web, shared)
- API: Express.js with TypeScript, PostgreSQL via Prisma
- Web: Next.js 14 with App Router
- Shared: common types and utilities

## Coding Standards
- TypeScript strict mode, no `any` types
- Use barrel exports (index.ts) for public APIs
- Error handling: custom AppError class, never throw raw strings
- Naming: camelCase for variables, PascalCase for types, kebab-case for files

## Git Conventions
- Branch naming: feat/, fix/, refactor/, docs/ prefixes
- Commit messages: conventional commits (feat:, fix:, refactor:, etc.)
- Always squash-merge PRs to main
- Never force-push to main or develop

## Testing
- Unit tests with Vitest, integration tests with Supertest
- Minimum 80% coverage for new code
- Test file naming: *.test.ts co-located with source

## Forbidden Actions
- NEVER delete migration files
- NEVER modify the auth middleware without security review
- NEVER commit .env files or API keys
- NEVER drop database tables in migration scripts

Every team member who uses Claude Code in this repository will have these instructions loaded automatically. This eliminates the "it works on my machine" problem for AI-assisted development -- everyone's Claude follows the same rules.

Try this: review your team's coding standards and translate the top ten rules into CLAUDE.md format. Commit it and ask a teammate to verify that Claude follows the rules in their session.

Shared Plugins for Team Workflows

Package your team's common workflows into a plugin that every developer installs:

{
  "name": "acme-dev-toolkit",
  "description": "Standard development workflows for Acme engineering",
  "version": "2.1.0",
  "components": {
    "commands": [
      "commands/pr-review.md",
      "commands/deploy-staging.md",
      "commands/onboard-service.md"
    ],
    "skills": [
      "skills/code-style.md",
      "skills/error-handling.md",
      "skills/api-conventions.md"
    ],
    "hooks": [
      "hooks/pre-commit-lint.sh",
      "hooks/block-env-commits.sh"
    ],
    "agents": [
      "agents/security-reviewer.md"
    ]
  }
}

Distribute through your team's private Git repository:

# Every developer runs this once
/plugin install https://github.com/acme-corp/claude-dev-toolkit

When you release a new version, developers update with:

/plugin update acme-dev-toolkit

Monorepo Strategies

In monorepos, different services often have different conventions. Use directory-scoped CLAUDE.md files to handle this:

monorepo/
  CLAUDE.md                    # repo-wide rules
  packages/
    api/
      CLAUDE.md                # API-specific rules
    web/
      CLAUDE.md                # frontend-specific rules
    mobile/
      CLAUDE.md                # mobile-specific rules

Claude Code merges these files hierarchically. When working in packages/api/, Claude sees both the root CLAUDE.md and the api-specific CLAUDE.md. The more specific file can override or extend the root rules.

Example packages/api/CLAUDE.md:

# API Service

## Additional Rules (extends root CLAUDE.md)
- Use Zod for all request validation schemas
- Every endpoint must have rate limiting middleware
- Database queries go through the repository pattern, never raw SQL in controllers
- API responses follow the envelope format: { data, error, meta }

Example packages/web/CLAUDE.md:

# Web Application

## Additional Rules (extends root CLAUDE.md)
- Use Server Components by default, Client Components only when needed
- CSS: Tailwind utility classes only, no custom CSS files
- Images: always use next/image with explicit width and height
- State management: React Server Components + URL state, no client-side stores

Security Governance

Teams need guardrails that prevent accidental damage. Implement these through hooks and permission mode policies.

Hook-based guardrails in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "command": "bash -c 'echo \"$CLAUDE_TOOL_INPUT\" | grep -qiE \"(rm -rf|drop table|force push|--force)\" && echo \"BLOCKED: Dangerous command detected\" && exit 1 || exit 0'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "write|edit",
        "command": "bash -c 'echo \"$CLAUDE_TOOL_INPUT\" | grep -qiE \"(API_KEY|SECRET|PASSWORD|PRIVATE_KEY)\" && echo \"BLOCKED: Potential secret in code\" && exit 1 || exit 0'"
      }
    ]
  }
}

Permission mode policy: Document which modes are appropriate for which contexts:

| Context | Recommended Mode | Rationale | |---------|-----------------|-----------| | New team members | default | Full visibility while learning | | Daily development | acceptEdits | Trust file edits, review commands | | Code review | plan | Read-only analysis | | CI/CD pipelines | auto + max-turns | Autonomous but bounded | | Production debugging | plan | Read-only to avoid accidental changes |

Cost Management

AI-assisted development has real costs. Teams need visibility and controls:

# Check current session cost
/cost

# View accumulated usage statistics
/stats

Team-level controls:

  • Set --max-turns limits in CI configurations to prevent runaway sessions
  • Establish per-developer monthly budgets through your API key management
  • Use /effort auto as the default so Claude calibrates token usage to task complexity
  • Reserve extended thinking for genuinely complex problems, not routine tasks

Cost-saving practices:

  • Use /compact regularly to reduce context size and token consumption
  • Use specific prompts instead of open-ended ones -- focused prompts use fewer tokens
  • Use claude-sonnet for routine tasks, reserve claude-opus for complex reasoning
  • Review /stats weekly to identify unusually expensive sessions

Code Quality Gates

Enforce quality standards automatically through a combination of hooks and skills:

# skills/quality-gate.md
---
triggers:
  - pre_commit
---

Before committing any code changes, verify:

1. The linter passes with zero errors: `npm run lint`
2. All tests pass: `npm test`
3. No TypeScript errors: `npx tsc --noEmit`
4. No TODO or FIXME comments in the committed files
5. New functions have JSDoc documentation
6. New API endpoints have test coverage

If any check fails, report the failure and do NOT proceed with the commit.

This skill fires before every commit, ensuring that code quality is enforced consistently regardless of which developer is working.

Knowledge Sharing

The most underappreciated aspect of team Claude Code adoption is knowledge sharing. When one developer discovers an effective prompt pattern or workflow, the entire team should benefit.

Document patterns in CLAUDE.md:

## Proven Patterns

### Debugging Flaky Tests
When investigating flaky tests, use this approach:
1. Run the test 10 times to measure failure rate
2. Check for shared state between tests
3. Look for timing dependencies or race conditions
4. Verify test isolation (database cleanup, mock restoration)

### Performance Investigation
When investigating performance issues:
1. Run the relevant benchmark first to establish baseline
2. Use profiling tools: `npx clinic doctor -- node src/server.ts`
3. Focus on the hot path identified by the profiler
4. After fix, re-run benchmark to confirm improvement

Create team skills for common tasks that every developer performs:

# These become available to every developer via the shared plugin
/pr-review      # standardized code review
/deploy-staging # safe staging deployment
/onboard        # generate onboarding docs for a new service

Compliance and Audit

For regulated industries, Claude Code provides several compliance-relevant features:

  • Session logs capture every prompt and response, providing an audit trail of AI-assisted changes
  • Permission controls enforce separation of duties (read-only for auditors, write for developers)
  • Hook-based restrictions can block specific operations in production environments
  • Sandbox mode isolates Claude's execution environment to prevent unauthorized system access

Configure these in your team's .claude/settings.json and commit the settings to version control so that compliance rules are enforced consistently.

Migration Path: Individual to Team

Follow this progression when rolling out Claude Code across a team:

Phase 1 -- Individual Pilot (1-2 weeks). One or two developers use Claude Code with personal configurations. They identify which features are most valuable and document initial patterns.

Phase 2 -- Shared Configuration (1 week). Create the team CLAUDE.md, establish coding conventions, and configure basic hooks. All pilot users switch to the shared configuration.

Phase 3 -- Plugin Development (1-2 weeks). Package the most useful workflows into a team plugin. Create skills for common tasks and hooks for guardrails.

Phase 4 -- Team Rollout (ongoing). All developers install the plugin and use the shared configuration. Hold a team session to demonstrate workflows and answer questions.

Phase 5 -- CI/CD Integration (1-2 weeks). Add Claude Code to the CI pipeline for automated reviews, test analysis, and documentation generation.

Common Pitfalls

Divergent configurations. When developers maintain separate personal configurations that conflict with team standards. Solution: commit CLAUDE.md and settings to the repo.

Missing guardrails. Not setting up hooks to prevent dangerous operations. One accidental rm -rf or force-push can be expensive. Solution: implement PreToolUse hooks from day one.

Context bloat. Developers running very long sessions without compacting. Solution: establish a team norm of running /compact after each major subtask.

Inconsistent permission modes. Some developers using auto mode on production databases while others use plan. Solution: document recommended modes per context and enforce through onboarding.

Ignoring costs. Not monitoring usage until the monthly bill arrives. Solution: weekly /stats reviews and per-project budget alerts.

A well-configured team setup turns Claude Code from a personal productivity tool into a team-wide force multiplier. The investment in shared configuration, governance, and workflows pays dividends as every developer benefits from the collective best practices.