git-guardrails-claude-code

Présentation de la skill git-guardrails-claude-code

La skill git-guardrails-claude-code aide Claude Code à refuser une courte liste de commandes Git destructrices avant leur exécution. Son rôle réel est simple : ajouter une couche de sécurité pour qu’une session de développement assistée par IA ne puisse pas lancer à la légère git push, git reset --hard, git clean -f, supprimer des branches avec git branch -D, ni effacer les changements du working tree avec git checkout . ou git restore ..

À qui s’adresse git-guardrails-claude-code

Cette skill convient particulièrement aux personnes qui :

• utilisent Claude Code directement sur de vrais dépôts
• veulent bénéficier d’une aide par IA sans lui permettre d’exécuter des actions Git irréversibles
• travaillent sur des repos partagés, des repos de production ou des codebases clients
• préfèrent une application locale de la règle plutôt qu’un simple “fais attention” dans le prompt

Si votre principale inquiétude concerne la destruction accidentelle de code ou des push non autorisés pendant une session d’agent, git-guardrails-claude-code est un très bon choix.

Ce qui la distingue d’un prompt classique

Un prompt classique peut demander à Claude de ne pas exécuter de commandes risquées, mais un prompt reste une consigne souple. git-guardrails-claude-code s’appuie sur un hook PreToolUse, donc la restriction vit dans le chemin d’exécution de Claude Code, et pas seulement dans la conversation. C’est le principal différenciateur, et la raison la plus solide de l’installer.

Ce que la skill bloque réellement

Le script shell fourni vérifie les commandes Bash entrantes et bloque notamment les motifs suivants :

• git push
• git reset --hard
• git clean -f
• git clean -fd
• git branch -D
• git checkout .
• git restore .
• les variantes liées au force-push, comme push --force

Le message de blocage indique à Claude qu’il n’a pas l’autorité nécessaire pour utiliser cette commande.

Ce que cette skill ne fait pas

git-guardrails-claude-code n’est pas un moteur complet de politique Git. Elle ne :

• vérifie pas la qualité des commits
• n’exige pas d’approbations
• ne distingue pas les destinations de push sûres des destinations risquées
• ne comprend pas les règles de branchement propres à votre dépôt
• ne protège pas contre les commandes en dehors des motifs listés, sauf si vous modifiez le script

C’est important pour décider de l’adoption : il s’agit d’un garde-fou ciblé, pas d’une gouvernance complète.

Comment utiliser la skill git-guardrails-claude-code

Commencez d’abord par décider du périmètre

Le premier choix pratique dans la skill source est de savoir si vous installez le garde-fou :

• pour ce projet uniquement dans .claude/settings.json, ou
• pour tous les projets dans ~/.claude/settings.json

Ce choix détermine où copier le script et jusqu’où le blocage s’applique. Pour la plupart des équipes, une installation au niveau du projet est plus sûre pour tester. Une installation globale a du sens une fois que vous savez que vous voulez les mêmes restrictions Git partout.

Lisez d’abord ces fichiers

Vous pouvez comprendre l’essentiel en lisant :

1. SKILL.md
2. scripts/block-dangerous-git.sh

Cet ordre de lecture est utile, car SKILL.md explique le branchement du hook, tandis que scripts/block-dangerous-git.sh montre les motifs de commande bloqués exactement. Si vous vous souciez des faux positifs ou des angles morts, le script compte plus que le texte descriptif.

Contexte d’installation de git-guardrails-claude-code

Le processus git-guardrails-claude-code install consiste surtout en une configuration manuelle dans le système de hooks de Claude Code :

1. copier le script shell dans un répertoire de hooks
2. le rendre exécutable
3. l’enregistrer sous PreToolUse pour le matcher Bash

Le chemin du dépôt pour le script source est :

scripts/block-dangerous-git.sh

Les emplacements cibles sont :

• portée projet : .claude/hooks/block-dangerous-git.sh
• portée globale : ~/.claude/hooks/block-dangerous-git.sh

Ensuite, rendez-le exécutable :

chmod +x .claude/hooks/block-dangerous-git.sh

ou pour une portée globale :

chmod +x ~/.claude/hooks/block-dangerous-git.sh

Ajouter correctement le hook Claude Code

Pour une portée projet, la skill montre un hook PreToolUse dans .claude/settings.json qui exécute le script copié via "$CLAUDE_PROJECT_DIR".

Les points de câblage essentiels sont :

• événement de hook : PreToolUse
• matcher : Bash
• type de hook : command
• commande : chemin vers block-dangerous-git.sh

Si ce hook n’est pas enregistré sous PreToolUse, le script existera bien, mais il n’interceptera jamais les commandes.

Comment le script fonctionne en pratique

Le script shell lit l’entrée de l’outil depuis l’entrée standard, extrait .tool_input.command avec jq, puis compare la commande à un petit tableau de motifs dangereux via grep -qE.

Autrement dit, les points de blocage à l’adoption sont simples :

• jq doit être disponible dans l’environnement
• le chemin de commande dans les settings doit être valide
• le script doit être exécutable
• Claude Code doit effectivement faire passer les appels à l’outil Bash par le système de hooks

Si l’un de ces éléments échoue, la protection devient discrètement plus faible que vous ne le pensez.

Quelles informations la skill attend de votre part

La skill source elle-même demande très peu de contexte, mais un bon flux git-guardrails-claude-code usage commence par ces décisions :

• projet uniquement ou global
• si la liste de blocage par défaut suffit
• si votre équipe veut aussi bloquer des commandes supplémentaires comme git tag -d, git rebase --abort ou des push spécifiques à certains remotes
• si les utilisateurs ont malgré tout besoin d’un chemin d’escalade manuel documenté pour les push légitimes

Sans ces réponses, l’installation est simple, mais l’adéquation avec votre politique peut être mauvaise.

Transformer un objectif vague en prompt solide

Prompt faible :

• “Set up git guardrails.”

Prompt plus solide :

• “Install git-guardrails-claude-code for this project only. Copy the hook script into .claude/hooks/, make it executable, update .claude/settings.json with a PreToolUse hook for Bash, and then show me the exact blocked Git patterns from the script.”

Pourquoi c’est mieux :

• le périmètre est défini
• la destination est précisée
• la demande couvre à la fois la configuration et la vérification
• cela réduit le risque que Claude improvise une autre structure de hook

Un bon workflow pour le premier déploiement

Un guide git-guardrails-claude-code guide pragmatique ressemble à ceci :

1. choisir la portée projet ou globale
2. examiner scripts/block-dangerous-git.sh
3. copier le script dans le répertoire de hooks cible
4. exécuter chmod +x sur le fichier copié
5. brancher le hook PreToolUse dans le bon fichier de settings
6. tester avec une simulation inoffensive ou une commande manifestement bloquée dans un dépôt sûr
7. décider s’il faut personnaliser les motifs

Cet ordre compte, car il vous permet de vérifier la vraie liste d’application avant un déploiement plus large.

Comment valider l’installation

Ne vous arrêtez pas à “le fichier existe”. Validez le comportement :

• confirmez que le chemin du fichier de settings est bien celui utilisé par Claude Code
• confirmez que la commande du hook pointe vers le script copié, et non vers le chemin source du dépôt
• déclenchez un motif bloqué dans un dépôt jetable
• vérifiez que Claude reçoit un refus au lieu d’exécuter la commande

Pour cette skill, la vérification comportementale est plus importante que la vérification visuelle.

Cas d’usage idéal pour les workflows Git

git-guardrails-claude-code for Git Workflows est particulièrement utile si votre workflow IA préféré consiste à :

• laisser Claude modifier librement les fichiers
• laisser Claude inspecter les diffs et le statut
• garder la suppression de branches, les force-push, les hard reset et les commandes de nettoyage sous contrôle humain explicite

Cette répartition fonctionne bien, car elle conserve la productivité de l’IA sur les tâches de code tout en gardant les actions irréversibles sur le dépôt entre des mains humaines.

Quand personnaliser le script

La liste par défaut est volontairement limitée. Personnalisez scripts/block-dangerous-git.sh si :

• votre équipe considère git push comme acceptable mais veut bloquer uniquement --force
• vous voulez aussi bloquer git commit --amend
• votre workflow inclut des cas sensibles de suppression de branches
• vous souhaitez des règles différentes selon les dépôts

Le principal arbitrage se situe entre simplicité et précision. Le script d’origine est facile à auditer ; une version fortement personnalisée demande davantage de tests.

FAQ sur la skill git-guardrails-claude-code

git-guardrails-claude-code convient-elle aux débutants

Oui, si le débutant utilise déjà Claude Code et veut un comportement par défaut plus sûr autour de Git. La mise en place est courte, et le principe est facile à comprendre : intercepter les appels à l’outil Bash avant exécution. Les seules parties un peu techniques sont la configuration JSON du hook et les permissions du script shell.

Est-ce mieux que dire à Claude “never push”

Oui, pour les commandes précises qu’elle couvre. git-guardrails-claude-code transforme une règle conversationnelle en contrôle au moment de l’exécution. C’est donc beaucoup plus fiable que de compter uniquement sur la mémoire du prompt.

Est-ce que git-guardrails-claude-code bloque toutes les commandes Git dangereuses

Non. Elle bloque les motifs explicitement présents dans le script. Si votre modèle de risque inclut d’autres commandes, vous devez les ajouter vous-même. C’est une limite importante de la skill.

Puis-je utiliser git-guardrails-claude-code de façon globale

Oui. La skill prend explicitement en charge une installation globale via ~/.claude/settings.json et ~/.claude/hooks/block-dangerous-git.sh. L’installation globale est pratique, mais une installation projet par projet est plus simple à tester et plus sûre si différents dépôts ont besoin de politiques différentes.

Est-ce que cela gênera le travail de développement normal

En général, très peu, si votre workflow habituel ne prévoit pas que Claude fasse des push ou exécute des nettoyages Git destructeurs. La compatibilité est meilleure avec un mode de travail où Claude modifie le code, lance les tests et prépare les changements, tandis qu’un humain garde la main sur l’autorité Git finale.

Quand ne faut-il pas utiliser cette skill

Évitez git-guardrails-claude-code si :

• vous voulez réellement que Claude gère Git de bout en bout
• votre équipe a besoin de listes d’autorisation fines plutôt que de simples blocages par motifs
• vous ne pouvez pas vous appuyer sur des hooks shell ou sur jq
• vous avez besoin d’une application à l’échelle de l’organisation au-delà de la configuration locale de Claude Code

Dans ces cas-là, cette skill peut sembler trop limitée ou trop locale.

Comment améliorer la skill git-guardrails-claude-code

Auditer les motifs bloqués par rapport à vos vrais risques

Le moyen le plus rapide d’améliorer git-guardrails-claude-code consiste à comparer la liste de motifs par défaut aux erreurs Git qui vous préoccupent réellement. Beaucoup d’équipes se soucient moins de tous les push que de :

• force pushes
• suppression de branches protégées
• nettoyages destructeurs dans des monorepos
• réinitialisations du working tree pendant une phase de debug

Si votre politique diffère, modifiez le tableau de motifs au lieu d’accepter la valeur par défaut les yeux fermés.

Donner à Claude des instructions d’installation plus solides

Si vous demandez à Claude d’appliquer cette skill, donnez des détails concrets :

• le périmètre
• le chemin de destination exact
• s’il faut conserver ou fusionner les hooks existants
• s’il faut afficher le fichier JSON final pour relecture
• s’il faut tester le hook après configuration

Une demande plus solide serait :

• “Install git-guardrails-claude-code only in this repo, merge with any existing .claude/settings.json hooks instead of overwriting them, and show the final settings diff.”

Cela évite l’un des modes d’échec les plus fréquents : remplacer une configuration de hook existante.

Surveiller les erreurs de fusion des hooks

En pratique, le vrai problème n’est pas forcément le script shell mais la mise à jour du fichier de settings. Si un dépôt a déjà des hooks configurés, une installation faite sans précaution peut les écraser. Demandez :

• un diff, pas une réécriture aveugle
• la préservation des entrées PreToolUse existantes
• une explication de l’ordre des hooks si plusieurs commandes s’exécutent

Pour beaucoup d’utilisateurs, c’est plus important que la liste des commandes bloquées.

Tester les faux positifs et les contournements

Comme le script repose sur du pattern matching, vous devriez tester :

• les commandes légitimes qui doivent passer
• les commandes bloquées qui doivent échouer
• les variantes que vous supposez bloquées mais qui ne le sont peut-être pas
• les chaînes de commande qui contiennent un texte similaire de manière inattendue

C’est le bon levier pour renforcer la confiance dans git-guardrails-claude-code usage, surtout avant un déploiement global.

Renforcer le script seulement après avoir observé de vrais manques

Il est tentant d’ajouter immédiatement beaucoup de motifs. Résistez à cette envie sauf si vous avez des preuves. Une blocklist courte et lisible est plus facile à maintenir et à faire confiance. Élargissez-la après avoir observé :

• les commandes que Claude tente souvent
• les commandes que les utilisateurs jugent risquées
• les motifs qui sont passés entre les mailles
• les commandes qui ont été bloquées alors qu’elles n’auraient pas dû l’être

Vous garderez ainsi un garde-fou compréhensible.

Ajouter un chemin d’escalade humain

Une bonne amélioration opérationnelle consiste à associer le garde-fou à une règle claire, par exemple :

• Claude peut préparer les commits et expliquer les étapes de push
• un humain effectue manuellement le push final ou le nettoyage destructeur

La skill s’en trouve améliorée, car les utilisateurs cessent de se battre contre le garde-fou et commencent à organiser leur workflow autour de lui.

Revoir si la portée globale ou projet est toujours la bonne

Après les premiers usages, réévaluez le périmètre :

• si la règle fonctionne sur tous les dépôts, passez-la en global
• si certains dépôts ont besoin d’un comportement Git plus souple, gardez-la au niveau projet
• si les équipes diffèrent, maintenez des versions distinctes du script au niveau projet

C’est l’un des moyens les plus simples d’améliorer l’adéquation sans modifier le code.

Garder le script lisible

Si vous personnalisez git-guardrails-claude-code, veillez à ce que le script shell reste facile à auditer. Préférez une liste de motifs claire et un seul chemin d’erreur à une logique trop astucieuse. Pour un contrôle de sécurité, la lisibilité fait partie de la fiabilité.