Team Conventions at Scale

The N×M×P problem

In a team of 5 developers using 3 AI tools on 2 operating systems, you potentially have 30 different configurations. In practice, after 3 months, no two developers have the same CLAUDE.md: Alice has added TypeScript rules that Bob never received, Carol configured macOS paths that break on Linux.

This is not a discipline problem. It is a configuration architecture problem.

Solution: Profile-Based Module Assembly

Instead of a shared monolithic file, the recommended structure breaks instructions into reusable modules assembled by profile.

profiles/          ← 1 YAML file per developer
  alice.yaml
  bob.yaml
modules/           ← Atomic instructions per topic
  core-standards.md
  typescript-rules.md
  git-workflow.md
  macos-paths.md
skeleton/          ← Template with placeholders
  claude.md
sync-script.ts     ← Automatic assembler

An updated module propagates automatically to all developers on the next sync.

Developer profile (YAML)

name: "Alice"
os: "macos"
tools: [claude-code, cursor]
modules:
  core: [core-standards, git-workflow, typescript-rules]
  conditional: [macos-paths, cursor-rules]

Alice receives only the modules she needs. Bob on Linux without Cursor receives a different CLAUDE.md, generated from the same sources.

Measured results

Tested on a team of 5 developers, TypeScript/Node.js stack:

The 59% reduction comes from each developer loading only the modules relevant to their environment, instead of the full file.

Versioned settings.json = team rules

Shared rules (hooks, allowed permissions) go into the versioned .claude/settings.json. Personal overrides go into the gitignored .claude/settings.local.json.

// .claude/settings.json (team, in the repository)
{
  "hooks": {
    "PreToolUse": [{ "matcher": "Bash", "hooks": [...] }]
  }
}

This separation ensures that team guardrails apply to everyone, while letting each developer customize their local environment without risk.

Break-even point

The setup is worth it for teams of 5+ developers. Below that, a simple shared CLAUDE.md is sufficient. The maintenance cost of the assembler (a few dozen lines of TypeScript or Python) is recouped in the first month on a team of 5+.

For smaller teams, the simple strategy remains effective: one shared versioned CLAUDE.md, one settings.local.json per developer for overrides.