Hooks Claude Code : un tutoriel pour valider vos fichiers JSON

Vous demandez à votre assistant de vérifier les fichiers qu'il modifie. Mais une consigne n'est pas un contrôle automatique. Un hook Claude Code permet de lancer une commande à un moment précis : avant un outil, après son exécution ou lorsqu'une notification est émise.

Ce tutoriel construit un cas volontairement limité : contrôler la syntaxe d'un fichier JSON après une modification par les outils Edit ou Write, puis signaler une erreur à Claude. Vous obtenez une configuration, un script sans dépendance Python externe et une procédure de test. Le script ne modifie aucun fichier.

Les exemples visent macOS ou Linux avec Python 3 et un shell Bash. Les comportements de Claude Code sont vérifiés dans sa documentation officielle au 22 septembre 2026. Les tests du script utilisent des événements simulés : ils ne constituent pas un test de bout en bout dans une session Claude Code.

Quand utiliser un hook plutôt qu'une instruction ?

Une instruction dans CLAUDE.md exprime une règle de travail. Un hook de type command exécute un programme quand l'événement configuré correspond. Il convient donc aux vérifications déterministes : parser un fichier, lancer un formateur déjà installé, vérifier une convention précise.

Ne mettez pas toute votre chaîne de tests dans chaque hook. Pour commencer, choisissez une vérification courte, locale et facile à comprendre. Les tests complets et les contrôles avant livraison gardent leur rôle.

Comprendre événement, matcher et commande

La référence officielle des hooks décrit les trois éléments que nous allons utiliser :

• PostToolUse se déclenche après la réussite d'un appel d'outil.
• Le matcher filtre le nom de l'outil. Ici, Edit|Write cible les deux outils d'édition.
• La commande reçoit un objet JSON sur son entrée standard. Pour ces outils, tool_input.file_path contient le chemin du fichier.

Après ne signifie pas avant. Si le contrôle découvre un JSON invalide, le fichier a déjà été écrit. Un hook PostToolUse ne constitue pas une annulation de cette écriture.

1. Préparer le script de validation

À la racine d'un projet de test, créez le dossier .claude/hooks, puis le fichier .claude/hooks/check-json.py ci-dessous. Vérifiez d'abord que python3 --version fonctionne dans votre terminal.

import json
import sys
from pathlib import Path


def report(message):
    print(message, file=sys.stderr)
    return 2


def main():
    try:
        event = json.load(sys.stdin)
        if not isinstance(event, dict):
            raise ValueError("objet attendu")
        tool_input = event.get("tool_input", {})
        if not isinstance(tool_input, dict):
            raise ValueError("tool_input doit etre un objet")
    except (ValueError, UnicodeError) as exc:
        return report(f"Evenement de hook invalide : {exc}")

    if event.get("tool_name") not in {"Edit", "Write"}:
        return 0

    raw_path = tool_input.get("file_path")
    if not isinstance(raw_path, str) or not raw_path:
        return report("Chemin du fichier absent de l'evenement.")

    path = Path(raw_path)
    if path.suffix.lower() != ".json":
        return 0
    if not path.is_absolute():
        return report("Un chemin absolu est attendu.")

    try:
        text = path.read_text(encoding="utf-8")
        json.loads(text)
    except json.JSONDecodeError as exc:
        return report(
            f"JSON invalide : ligne {exc.lineno}, "
            f"colonne {exc.colno}. Corrigez le fichier modifie."
        )
    except (OSError, UnicodeError):
        return report("Fichier JSON illisible ou encodage UTF-8 invalide.")
    return 0


if __name__ == "__main__":
    sys.exit(main())

Le contrôle ignore les fichiers qui ne se terminent pas par .json. Il ne lance aucune commande construite à partir du chemin reçu : les espaces dans les noms de fichiers restent de simples caractères. Il ne recopie pas le contenu du document dans le message d'erreur.

Ce script vérifie uniquement ce que le parseur json de Python accepte. Il ne valide ni schéma métier, ni champs obligatoires, ni unicité des clés. Il n'est pas adapté aux fichiers JSON avec commentaires. Pour ces besoins, choisissez un validateur spécifique et testez-le séparément.

2. Déclarer le hook dans settings.json

Pour un réglage partagé avec le projet, utilisez .claude/settings.json. Pour un essai personnel limité à ce projet, utilisez .claude/settings.local.json. Notre guide de configuration Claude Code détaille la portée de ces fichiers.

Voici la configuration complète pour un fichier de réglages vide :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/check-json.py\"",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

La variable CLAUDE_PROJECT_DIR permet de référencer le script depuis la racine du projet. Les guillemets protègent le chemin si le dossier du projet contient des espaces. Le script est passé à Python, il n'a donc pas besoin d'être rendu exécutable.

Si votre fichier contient déjà des réglages, fusionnez ce bloc sans les écraser. S'il existe déjà une clé hooks, ajoutez l'événement à cet objet. Si PostToolUse existe déjà, ajoutez votre configuration à son tableau. Ne créez pas plusieurs clés JSON identiques.

Vérifiez la syntaxe de votre fichier de réglages avec python3 -m json.tool .claude/settings.json. Cette commande affiche le document : ne partagez pas sa sortie si vos réglages contiennent des informations privées. Elle vérifie la syntaxe JSON, pas la validité du schéma de configuration Claude Code.

3. Tester le script sans appeler un modèle

Avant de relier un script à votre assistant, vérifiez son comportement indépendamment. Placez ce test dans test-hook.py à la racine du projet. Il crée ses fichiers dans un répertoire temporaire et envoie un événement simulé au script.

import json
import subprocess
import sys
import tempfile
from pathlib import Path

script = Path(".claude/hooks/check-json.py").resolve()
with tempfile.TemporaryDirectory(prefix="test hook ") as folder:
    root = Path(folder)
    for name, content, expected in [
        ("valide.json", '{"active": true}', 0),
        ("invalide.json", '{"active": }', 2),
        ("nom avec espaces.json", '{"count": 3}', 0),
        ("notes.txt", "pas du JSON", 0),
    ]:
        path = root / name
        path.write_text(content, encoding="utf-8")
        event = {"tool_name": "Write", "tool_input": {"file_path": str(path)}}
        result = subprocess.run(
            [sys.executable, str(script)],
            input=json.dumps(event), text=True, capture_output=True
        )
        assert result.returncode == expected, (name, result.stderr)
        print(name, result.returncode)

Lancez python3 test-hook.py. Vous devez obtenir, dans l'ordre, les codes 0, 2, 0, 0. Ces quatre cas ont été exécutés pour ce tutoriel. Ils vérifient notamment qu'un chemin avec espaces est accepté et qu'un fichier texte est ignoré.

Dans un hook PostToolUse, le code 2 transmet le message d'erreur standard à Claude. Il ne bloque pas rétroactivement l'outil qui vient de réussir. Le comportement d'un même code de sortie dépend de l'événement : consultez le tableau officiel des codes de sortie avant de réutiliser ce script ailleurs.

4. Vérifier le déclenchement dans Claude Code

Ouvrez une session dans le projet de test. Utilisez /hooks pour vérifier la présence de votre hook, son événement, sa commande et le fichier de réglages dont il provient. Le menu est un navigateur de configuration en lecture seule ; les modifications se font dans le fichier JSON.

Demandez ensuite une petite modification d'un fichier JSON de démonstration avec l'outil Write ou Edit. Observez l'outil réellement utilisé. Si Claude écrit le fichier avec une commande Bash, votre matcher ne correspond pas et ce contrôle ne s'exécute pas.

Pour un essai d'erreur, utilisez uniquement un fichier jetable, jamais la configuration de votre application. Vérifiez qu'une écriture invalide produit un retour, puis qu'une correction fait disparaître l'erreur. Cette vérification d'intégration reste à effectuer dans votre environnement : les tests autonomes précédents ne la remplacent pas.

Pourquoi mon hook ne fonctionne-t-il pas ?

Pour inspecter l'exécution, la documentation prévoit claude --debug et les journaux sous ~/.claude/debug/. Ce mode écrit des logs ; il ne les affiche pas directement dans le terminal. Relisez et nettoyez les journaux avant de les partager.

Passer d'un essai individuel à une règle d'équipe

Avant de partager ce hook, fixez son périmètre : outils concernés, extensions, taille des fichiers et temps d'exécution acceptable. Notre exemple lit le document entier en mémoire ; réservez-le à de petits fichiers de configuration. Ne l'appliquez pas sans adaptation à des exports volumineux.

Versionnez le script et, si la règle est commune, sa configuration projet. Faites relire les commandes comme du code : un hook s'exécute sur le poste qui utilise le projet. Conservez une procédure simple de retour arrière, en retirant uniquement l'entrée ajoutée à PostToolUse.

Enfin, gardez un contrôle indépendant avant livraison. Une modification par Bash, un autre outil ou un éditeur externe n'est pas couverte par notre matcher. Pour surveiller les modifications d'un fichier quelle qu'en soit l'origine, la documentation actuelle décrit aussi l'événement FileChanged ; c'est un autre périmètre à étudier, pas une propriété de l'exemple présenté ici.

Le bon résultat n'est pas « nous avons installé des hooks ». C'est une erreur précise détectée au bon moment, avec un message exploitable, sans ralentir chaque action. Pour adapter cette méthode aux conventions de votre dépôt et former les personnes qui la maintiendront, découvrez notre formation Claude Code pour équipes.

Sources et périmètre de vérification

• Guide officiel : automatiser avec les hooks, consulté le 22 septembre 2026.
• Référence : événements, entrées, sorties et débogage, consultée le 22 septembre 2026.
• Tests locaux du script Python avec entrées simulées : JSON valide, invalide, nom avec espaces et fichier non JSON. Aucun résultat client ni gain de productivité mesuré n'est revendiqué.