Hooks de configuration Claude Code

La qualité d'une équipe d'ingénierie se mesure à un chiffre : combien de temps il faut à un nouveau pour faire tourner le projet sur sa machine.

Les bonnes équipes ont besoin d'un lien, d'une doc, de quelques commandes. La plupart des équipes perdent une ou deux journées à pairer, à démêler des fils Slack, des pages wiki poussiéreuses, et des allers-retours pour comprendre pourquoi quelque chose a planté.

Les agents rendent ça soluble.

Mettre en route un codebase a toujours été un choix entre trois mauvaises formes :

Les scripts purs sont prévisibles mais fragiles. Ils exécutent les mêmes commandes à chaque fois et bloquent dès que la réalité change. Une dépendance manquante ou une base de données en panne, et le script meurt simplement.

Les agents purs sont malins mais peu fiables. Tu ne peux pas en brancher un dans un pipeline CI/CD et t'attendre à la même sortie exacte à chaque exécution.

Les docs pures sont flexibles mais dépendent des humains. Personne ne les lit, et elles deviennent obsolètes en quelques semaines.

Ce qui fonctionne, c'est de tresser les trois ensemble. Les scripts gèrent l'exécution. Les agents les supervisent. Tu te retrouves avec un document vivant qui s'exécute.

Les hooks de configuration ont atterri dans Claude Code le 25 janvier 2026. Ce sont un type de hook dédié qui se déclenche avant que ta session démarre. Quand tu lances :

claude --init

Le hook de configuration passe en premier, puis Claude démarre. Le hook peut installer des paquets, initialiser la base de données, et préparer ton environnement. Quand Claude démarre, il sait déjà ce qui s'est passé.

C'est là que ça devient intéressant. Tu peux accrocher un prompt au flag init :

claude --init "/install"

Maintenant le hook tourne, et la commande /install se déclenche juste après. L'agent lit les fichiers de log, comprend ce qui s'est passé, et rapporte en langage naturel.

claude --init "/install true"

Trois modes de setup en découlent :

┌─────────────────────────────────────────────────────────┐
│  DETERMINISTIC          AGENTIC           INTERACTIVE   │
│  (hooks only)           (hooks + prompt)  (hooks + Qs)  │
│                                                         │
│  claude --init          /install          /install true │
│                                                         │
│  - Fast                 - Supervised      - Asks Qs     │
│  - Predictable          - Diagnostic      - Adapts      │
│  - CI-friendly          - Reports status  - Context-    │
│                                             aware       │
└─────────────────────────────────────────────────────────┘

Mode déterministe : script seul. Rapide, répétable, parfait pour CI/CD où chaque exécution doit correspondre.

Mode agentique : script d'abord, puis un agent lit les résultats. Il scanne les fichiers de log, parse les erreurs, et te dit en langage naturel ce qui a fonctionné ou échoué.

Mode interactif : script d'abord, puis l'agent t'entraîne dans un court Q&A. "Base de données fraîche ou garder l'ancienne ? Installation complète ou minimale ? Tu veux que je vérifie les prérequis d'abord ?"

Le script est toujours la source de vérité. Hooks et prompts appellent le même script à chaque fois. Ce qui change, c'est si un agent supervise, et s'il te pose des questions au départ.

Just est un petit lanceur de commandes, et il s'associe bien avec les hooks de configuration. Traite-le comme un lanceur pour ton travail d'ingénierie. Au lieu de mémoriser des flags, tu tapes just et tu vois toutes les commandes disponibles :

just          # See all commands
just cldi     # Deterministic setup
just cldii    # Agentic setup (with reporting)
just cldit    # Interactive setup (asks questions)

Le justfile lui-même reste simple :

# Deterministic codebase setup
cldi:
  claude --init
 
# Agentic codebase setup
cldii:
  claude --init "/install"
 
# Interactive setup (asks questions)
cldit:
  claude --init "/install true"
 
# Deterministic maintenance
cldm:
  claude --maintenance
 
# Agentic maintenance (with reporting)
cldmm:
  claude --maintenance "/maintenance"

Les coéquipiers et les agents n'ont plus à mémoriser des flags deux fois. Ils lancent just cldii et ça fonctionne.

--init-only est le flag pour le pipeline. Il exécute le hook, retourne un code de sortie, et s'arrête. Pas de session interactive attachée.

L'onboarding est là où ça brille. Un nouvel ingénieur tape just cldit et l'agent le guide :

Agent: How should I handle the database?

┌─ Database Setup ─────────────────────────────────┐
│  ○ Fresh database (Recommended)                  │
│  ○ Keep existing                                 │
│  ○ Skip database setup                           │
└──────────────────────────────────────────────────┘

L'agent demande le mode d'installation, les variables d'environnement, et s'il faut vérifier les prérequis d'abord. Il s'adapte aux réponses et n'exécute que les étapes qui correspondent.

Les scripts ne peuvent pas faire ça. Ils jouent la même cassette à chaque fois. Les agents peuvent s'arrêter en cours d'exécution, poser une question de clarification, et bifurquer selon la réponse.

Les hooks de configuration sont l'un des 12 événements du cycle de vie du système de hooks. La configuration vit dans .claude/settings.json :

{
  "hooks": {
    "Setup": [
      {
        "matcher": "init",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/setup_init.py",
            "timeout": 120
          }
        ]
      },
      {
        "matcher": "maintenance",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/setup_maintenance.py",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Le script du hook exécute tes commandes et journalise tout :

def main():
    # Install backend dependencies
    run(["uv", "sync"], cwd="apps/backend")
 
    # Install frontend dependencies
    run(["npm", "install"], cwd="apps/frontend")
 
    # Initialize database
    run(["uv", "run", "python", "init_db.py"], cwd="apps/backend")
 
    # Tell Claude what happened
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "Setup",
            "additionalContext": "Setup complete. Run 'just be' and 'just fe' to start."
        }
    }))

La commande slash /install récupère le log et rédige les résultats :

---
description: Run setup and report installation results
---
 
## Workflow
 
1. Run /prime to understand the codebase
2. Read the log file at .claude/hooks/setup.init.log
3. Analyze for successes and failures
4. Write results to app_docs/install_results.md
5. Report to user

Quand quelque chose plante, l'agent a déjà le contexte pour diagnostiquer. Liste les modes d'échec habituels dans le prompt, et l'agent parcourra le playbook de correction tout seul.

Pense au temps d'onboarding par rapport au rythme auquel tu veux faire grandir ton équipe. Un seul prompt pourrait-il gérer le setup et l'installation pour un nouvel arrivant ? Pourrait-il rendre chaque étape claire en demandant avant d'agir ?

Oui, sur les deux points. Les agents sont assez bons pour ça. Ce qui manque, c'est la standardisation.

Déterminisme préservé : le hook déclenche le même script à chaque fois. Zéro variance LLM pendant l'exécution. L'agent ne regarde les résultats qu'après que le travail déterministe est terminé.

Compatible CI : GitHub Actions exécute claude --init-only et obtient un code de sortie propre.

Interactif quand ça compte : les nouveaux ont un guide pour le setup. Tout le monde d'autre exécute la version rapide.

Un document vivant qui s'exécute : ton process d'installation vit maintenant en langage naturel, intégré dans des prompts que les agents suivent. Les mises à jour se font en éditant le prompt.

Commence simple. Écris un script .claude/hooks/setup_init.py qui installe tes dépendances, branche-le dans .claude/settings.json, puis ajoute une commande /install qui lit le log et rapporte. Enveloppe le tout dans un justfile pour que ton équipe lance just install et arrête d'y penser.

Tu veux quelque chose de plus léger ? Si tu veux juste charger un contexte différent selon le type de session, une commande slash suffit généralement. Pas de script d'installation requis.

Les hooks de configuration payent le plus quand tu veux une commande qui installe tout, diagnostique les échecs, et guide les nouveaux ingénieurs à chaque étape. Les scripts fournissent la certitude. Les agents fournissent le jugement. Si ton équipe saute entre Windows, Linux et macOS, lis les patterns de hooks cross-platform pour que le même setup tourne sur tous les OS.