Partager une config Claude Code en équipe

Deux développeurs, le même repo, le même prompt. Chez l’un, Claude Code lance les tests avant chaque commit et refuse de toucher aux fichiers de migration. Chez l’autre, il commit sans tester et réécrit une migration en production. Même projet, comportements opposés : une demi-journée perdue à comprendre pourquoi.

La raison est toujours la même : la config Claude Code de l’équipe vit sur les machines, pas dans le repo. Voici comment structurer ce qui se partage, ce qui reste personnel, et les pièges qui vous attendent entre les deux.

Les trois couches de configuration

Claude Code lit sa configuration en cascade, de la plus générale à la plus spécifique :

1. Utilisateur : ~/.claude/ (ou CLAUDE_CONFIG_DIR). Vos préférences globales, votre authentification, votre mémoire. Jamais dans git.
2. Projet partagé : .claude/settings.json et CLAUDE.md à la racine du repo. Versionnés, identiques pour toute l’équipe.
3. Projet local : .claude/settings.local.json. Vos surcharges personnelles sur ce projet. Dans le repo physiquement, mais ignoré par git.

La couche la plus spécifique gagne. Un réglage dans settings.local.json écrase le même réglage dans settings.json, qui écrase celui de ~/.claude/settings.json. C’est le point le plus important de cet article : si un collègue a un comportement différent du vôtre, la réponse est presque toujours dans sa couche locale.

Ce qui va dans git

CLAUDE.md : les règles du projet

CLAUDE.md à la racine du repo est lu par Claude Code au démarrage de chaque session. C’est le bon endroit pour tout ce qu’un nouveau développeur devrait savoir :

# Règles projet

## Conventions
- Tests avec Vitest, pas Jest. `npm run test:unit` avant tout commit.
- Les migrations dans db/migrations/ ne se modifient jamais, on en crée une nouvelle.
- Messages de commit en anglais, format conventional commits.

## Architecture
- Le module payments/ ne dépend jamais de notifications/.
- Toute nouvelle route passe par le middleware d'auth, sans exception.

Écrivez-le comme un onboarding : des règles concrètes et vérifiables, pas des généralités. “Fais du code propre” ne sert à rien ; “les migrations ne se modifient jamais” évite un incident.

.claude/settings.json : permissions et hooks partagés

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(npm run lint)",
      "Read(**)"
    ],
    "deny": [
      "Bash(git push --force*)",
      "Read(.env*)",
      "Read(secrets/**)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --silent"
          }
        ]
      }
    ]
  }
}

Deux choses à retenir de cet exemple :

• Les deny partagés sont votre filet de sécurité d’équipe. Interdire la lecture de .env et le push force à tout le monde, c’est une ligne de JSON. La même règle communiquée sur Slack, c’est un incident par trimestre.
• Le hook de lint avant commit s’exécute chez tout le monde, pareil. C’est la version exécutable de “n’oubliez pas de linter”.

.mcp.json : les serveurs MCP du projet

Les serveurs MCP déclarés dans .mcp.json à la racine du repo sont proposés à toute l’équipe :

{
  "mcpServers": {
    "postgres-dev": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DEV_DATABASE_URL}"
      }
    }
  }
}

Le point crucial : la variable ${DEV_DATABASE_URL} est une référence d’environnement, pas une valeur. Chaque développeur la définit dans son shell ou son .env local. Le fichier versionné décrit le serveur, jamais le secret.

Au premier lancement, chaque membre de l’équipe voit une demande d’approbation pour les serveurs du .mcp.json. C’est normal et c’est souhaitable : personne ne doit exécuter un serveur MCP qu’il n’a pas approuvé. Quant à savoir lesquels méritent leur place dans ce fichier, j’ai fait le tri dans les serveurs MCP qui servent vraiment.

Le reste du répertoire .claude/

Depuis 2026, le répertoire projet peut aussi contenir des sous-dossiers versionnables : rules/ pour découper un gros CLAUDE.md, agents/ pour les définitions de sous-agents, skills/ pour les skills projet. Même logique pour tous : si toute l’équipe doit avoir le même comportement, ça va dans git.

Ce qui reste local

.claude/settings.local.json

Vos surcharges personnelles sur le projet : un modèle par défaut différent, des permissions plus larges parce que vous êtes lead, un hook de notification qui n’intéresse que vous. Claude Code ajoute ce fichier au .gitignore automatiquement lors de sa création, mais vérifiez :

.claude/settings.local.json

Les secrets, toujours

Clés API, tokens, URLs avec credentials : jamais dans settings.json, jamais dans .mcp.json, jamais dans CLAUDE.md. Les références d’environnement existent pour ça. Un secret commité dans une config Claude Code est un secret commité, avec tout ce que ça implique de rotation et de nettoyage d’historique.

L’authentification et la mémoire

Chaque développeur a son compte, son abonnement, sa mémoire. Rien de tout ça ne se partage via le repo. Si vous gérez plusieurs comptes sur une machine (perso et client, par exemple), j’ai détaillé le setup dans plusieurs comptes Claude Code sur une seule machine.

Les pièges

Le piège du local qui écrase le partagé

Le classique : l’équipe ajoute une règle deny dans settings.json, un développeur a un allow plus large dans son settings.local.json d’avant, et la règle d’équipe ne s’applique pas chez lui. Personne ne le voit, parce que le fichier local n’est pas dans git.

Le réflexe de debug : quand un comportement diverge entre deux machines, comparez d’abord les couches locales.

# ce que git connaît
cat .claude/settings.json

# ce que git ne connaît pas
cat .claude/settings.local.json 2>/dev/null

Le piège du CLAUDE.md qui dérive

Trois repos, trois CLAUDE.md copiés-collés puis modifiés indépendamment. Six mois plus tard, les conventions divergent et plus personne ne sait laquelle est la bonne. Il n’y a pas encore d’héritage de config entre repos dans Claude Code : si vous avez un socle commun, gérez-le comme un template synchronisé (un script qui propage les sections communes), pas comme des copies libres.

Le piège de la demande d’approbation ignorée

Un nouveau serveur MCP arrive dans .mcp.json via une pull request. Vos collègues voient une demande d’approbation au prochain lancement et cliquent oui sans lire. Le mécanisme d’approbation ne protège que si l’équipe a le réflexe de lire ce qu’elle approuve : mentionnez tout nouveau serveur MCP dans la description de la PR qui l’introduit.

Par où commencer

Si votre équipe n’a rien de tout ça aujourd’hui, l’ordre qui rapporte le plus vite :

1. Un CLAUDE.md avec vos cinq règles les plus violées. Une demi-heure, gain immédiat.
2. Les deny de sécurité dans .claude/settings.json : secrets illisibles, push force interdit.
3. Le .mcp.json avec vos serveurs communs et des références d’environnement.
4. Les hooks partagés, en dernier : c’est le plus puissant mais aussi le plus intrusif, donc à introduire quand l’équipe fait déjà confiance au reste.

La config d’équipe Claude Code, c’est comme le CI : le jour où c’est en place, on se demande comment on faisait avant. Et le fichier local de chacun reste là pour l’expérimentation, exactement comme il doit l’être.