Introduire un agent IA dans une équipe sans bousculer Git est l’un des chantiers les plus sensibles de 2026. Mal cadré, le Claude Code git workflow transforme chaque pull request en chasse aux régressions, dilue la responsabilité du code et finit par dégrader la qualité au lieu de l’améliorer. Bien cadré, il rend deux à trois jours par sprint sans bruit.

Cet article propose un mode opératoire concret, copiable dans le wiki d’équipe : conventions de branche, traçabilité dans les commits, hooks pre-commit utiles, code review IA-aware, gestion du CLAUDE.md. Tout est testé en équipe distribuée, multi-fuseau.

Le risque de mélanger Claude Code et un repo d’équipe sans règles

Sans cadre, l’arrivée d’un agent IA dans un dépôt provoque trois maux récurrents. D’abord la confusion : on ne sait plus qui a écrit quoi, ni si une régression vient de l’agent ou d’un développeur. Ensuite l’inflation du diff : un refactor mal cadré touche des dizaines de fichiers que personne n’avait demandés. Enfin la dette invisible : du code généré rapidement entre dans la base sans relecture sérieuse, et la facture tombe en maintenance, six mois plus tard.

Trois conventions, une discipline de hooks et une checklist de review suffisent pour éviter ces écueils. Aucun de ces éléments n’est lourd à mettre en place. Le coût est presque entièrement à l’introduction.

Les conventions à poser

Branches dédiées vs branches normales

La règle simple qui fonctionne : préfixer la branche par ai/ dès que la part IA dépasse cinquante pour cent du diff. En dessous, restez sur les conventions habituelles (feat/, fix/, chore/). Le préfixe ne sert pas à stigmatiser, il sert à signaler au reviewer la nature du contenu et à orienter la lecture.

• ai/refactor-auth-module : refactor majeur piloté par Claude Code.
• ai/migrate-vue3-components : migration semi-automatique sur plusieurs fichiers.
• feat/login-rate-limit : feature classique, IA utilisée à la marge.
• fix/cart-rounding : fix court, conventions habituelles, pas de préfixe IA.

Convention de commit pour traçabilité IA

Conventional Commits reste la base : feat:, fix:, chore:, refactor:. On ajoute deux choses : une mention systématique dans le corps du message quand l’IA a contribué, et un trailer Git standardisé pour la traçabilité automatique. Le format s’inspire des bonnes pratiques de Conventional Commits.

refactor(auth): extraire la logique JWT dans un module dédié

Sépare la signature et la vérification des tokens dans
src/auth/jwt.ts, mis à jour les imports dans 4 fichiers.

Couverture de tests maintenue : 92% sur src/auth/.

Assisted-by: Claude Code (session du 2026-04-12, ~40 min)
Reviewed-by: Sophie L.

Le trailer Assisted-by: permet de remonter facilement les contributions IA dans un rapport mensuel, et offre une honnêteté éditoriale qui rassure les clients soumis à audit. Le trailer Reviewed-by: rappelle que la responsabilité humaine n’est jamais déléguée.

Le CLAUDE.md versionné

Le fichier CLAUDE.md à la racine du dépôt est lu à chaque session. Le versionner, c’est lui donner le statut de contrat partagé : tout changement passe par une PR, comme du code. Cette discipline évite la dérive où chaque développeur ajuste sa copie locale et où l’agent reçoit des instructions contradictoires d’une session à l’autre.

# CLAUDE.md (équipe Front)

## Stack obligatoire
- React 19 + TypeScript strict
- TanStack Query pour toutes les requêtes HTTP
- Vitest pour les tests, jamais Jest

## Conventions
- Composants fonctionnels uniquement, jamais de classes
- Hooks personnalisés dans src/hooks/, un fichier par hook
- Pas de any, pas de @ts-ignore sans commentaire justificatif

## Commandes utiles
- npm run check : lint + typecheck + tests rapides
- npm run test:full : suite complète (CI)

## Hors limites pour Claude Code
- Ne pas modifier package.json sans demander
- Ne pas toucher aux migrations dans db/migrations/
- Ne pas générer de hooks Husky : ils sont gérés en .githooks/

## Contact si doute
- Tech lead : Sophie L.
- Sécurité : Karim B.

Les hooks pre-commit qui sauvent

Trois hooks suffisent pour rattraper la majorité des erreurs typiques d’un commit IA-assisté. Ils s’installent avec pre-commit ou avec une configuration .githooks/ classique. Le coût d’exécution est minime, le gain mesurable.

Lint et formatage

Premier rempart, évident mais souvent négligé en mode urgence. Faire passer Biome ou ESLint plus Prettier sur tout fichier modifié garantit que l’agent ne mélange pas les conventions du dépôt. Si le hook échoue, le commit est refusé : pas de discussion.

Détection de secret leak

L’agent peut générer du code de test avec une fausse clé API qui ressemble à une vraie. Un outil comme gitleaks ou trufflehog attrape ces fuites avant qu’elles n’atteignent le dépôt distant. C’est la ligne de défense la plus importante pour les équipes qui manipulent des intégrations tierces.

Attribution automatique

Un petit script vérifie que le message de commit respecte la convention et ajoute si besoin le trailer Assisted-by: selon une règle simple (présence d’une variable d’environnement CLAUDE_SESSION par exemple). Voici un exemple minimal :

#!/usr/bin/env bash
# .githooks/prepare-commit-msg

COMMIT_MSG_FILE="$1"
if [ -n "$CLAUDE_SESSION" ]; then
  if ! grep -q "Assisted-by:" "$COMMIT_MSG_FILE"; then
    printf "\nAssisted-by: Claude Code\n" >> "$COMMIT_MSG_FILE"
  fi
fi

L’idée n’est pas de surveiller, c’est de standardiser. Quand toute l’équipe rédige les commits de la même façon, les rapports sont fiables et les revues plus rapides.

La code review IA-aware

Ce qu’on demande au reviewer

Une PR rédigée avec un agent demande une attention différente d’une PR humaine. Pas plus de temps, mais d’autres réflexes. Voici la checklist que nous diffusons dans les équipes que nous accompagnons.

• Le diff fait-il bien ce que la description annonce, sans modifications opportunistes ?
• Les tests ajoutés couvrent-ils les cas limites ou seulement le cas heureux ?
• Le code respecte-t-il les conventions du CLAUDE.md et du repo ?
• Y a-t-il une dépendance ajoutée qui n’était pas justifiée par la tâche ?
• Le modèle de données est-il cohérent avec le reste du dépôt ?
• Les commentaires de code apportent-ils du contexte ou paraphrasent-ils le code ?

Les patterns qui sentent l’IA mal cadrée

Quelques signaux récurrents trahissent une session non maîtrisée. Quand vous les croisez, demandez la reprise plutôt qu’un patch.

Signal	Diagnostic probable
Try/catch englobants partout sans logique	L’agent a paniqué sur les erreurs sans en discuter
Commentaires qui paraphrasent le code	Pas de contexte fourni, l’agent a meublé
Refactor étendu hors du périmètre annoncé	Tâche mal cadrée, périmètre non posé
Tests qui couvrent le cas heureux uniquement	Pas de demande explicite des cas limites
Nouvelle dépendance npm injustifiée	L’agent a pris la voie la plus courte

La complémentarité avec une stratégie tests générés par IA bien cadrée est immédiate : un test généré sans demande explicite des cas limites se rate de la même manière qu’un code généré sans plan.

Cas d’équipes en télétravail / multi-fuseau

Dans une équipe distribuée, l’agent IA agit comme un coéquipier asynchrone supplémentaire. Plusieurs équipes que nous accompagnons exploitent cela : un développeur lance une session le soir, l’autre reprend la PR le lendemain matin. Pour que le relais fonctionne, deux règles supplémentaires.

• Le commit qui interrompt une session contient un WIP: explicite et un résumé de l’état dans le corps du message.
• La PR contient une note dédiée « contexte de la session IA » qui résume ce qui a été tenté, ce qui marche, ce qui reste.

Ces deux gestes prennent deux minutes et économisent une heure de remise dans le bain pour le relayeur.

Mode opératoire à copier-coller dans le wiki

Voici la version condensée à publier sur Confluence, Notion ou tout wiki interne. Elle tient en une page et suffit à cadrer 95 pour cent des situations.

• Branches préfixées ai/ dès que la part IA dépasse 50 pour cent du diff.
• Commits Conventional Commits + trailer Assisted-by: Claude Code quand applicable.
• Hooks pre-commit obligatoires : lint/format, gitleaks, attribution automatique.
• CLAUDE.md versionné, modifications en PR comme du code.
• Code review : checklist IA-aware en plus de la review classique.
• WIP explicite si la session est interrompue, contexte résumé dans le message.
• Documentation des sessions notables (durée, gain estimé) dans un fichier docs/ai-sessions.md.

Cette base s’inscrit dans le guide complet Claude Code (pilier) et complète bien le comparatif des assistants IA côté outillage. Adaptez-la à votre culture d’équipe sans la dénaturer.

Questions fréquentes

Comment intégrer Claude Code dans un workflow Git existant ?

Trois étapes : poser des conventions de branche et de commit (préfixe ai/, trailer Assisted-by:), installer trois hooks pre-commit (lint, gitleaks, attribution), versionner un CLAUDE.md partagé. Cette mise en place tient en deux heures pour une équipe et ne demande aucun outil propriétaire.

Faut-il des branches dédiées pour le code généré par Claude Code ?

Pas systématiquement. La règle utile : préfixer ai/ dès que la part IA dépasse cinquante pour cent du diff. En dessous, gardez vos préfixes habituels. Le but n’est pas de stigmatiser mais d’orienter la lecture du reviewer pour qu’il applique les bons réflexes.

Comment tracer dans les commits qu’une IA a participé ?

Ajoutez un trailer Assisted-by: Claude Code dans le corps du message, sur le modèle des trailers Co-authored-by:. Un petit hook prepare-commit-msg peut l’ajouter automatiquement quand une variable d’environnement signale une session active. La traçabilité devient native et automatique.

Quels hooks pre-commit installer pour Claude Code ?

Trois hooks couvrent l’essentiel : lint plus formatage (Biome ou ESLint et Prettier), détection de secrets (gitleaks ou trufflehog), et un script d’attribution qui standardise le message de commit. Ces trois hooks tournent en moins d’une seconde sur un projet de taille moyenne.

Comment mener une code review d’une PR rédigée avec IA ?

Appliquez une checklist spécifique : périmètre du diff conforme à la description, tests qui couvrent les cas limites, conformité au CLAUDE.md, dépendances justifiées, cohérence du modèle de données, commentaires utiles. Repérez les patterns d’IA mal cadrée (try/catch partout, refactor opportuniste) et demandez la reprise plutôt qu’un patch.

À retenir : conventions de branche claires, traçabilité automatisée dans les commits, trois hooks pre-commit, CLAUDE.md versionné, et une checklist de review IA-aware. Ces cinq pièces s’installent en une matinée et tiennent durablement la qualité d’un dépôt d’équipe. Mettre Claude Code dans votre équipe sans dégrader la qualité, on l’a fait, on peut vous l’expliquer.