Configurer Husky + lint-staged avec Claude Code: guide pre-commit pratique

Claude Code peut modifier beaucoup de fichiers en une seule session. C’est pratique pour refactorer, ajouter des tests ou nettoyer une configuration, mais cela augmente aussi le bruit en revue. Le temps humain doit servir à juger le comportement, l’architecture et les risques, pas à repérer des imports inutilisés ou des différences de formatage.

Husky + lint-staged apporte une réponse simple. Un Git hook est un petit script exécuté par Git à un moment précis, par exemple avant un commit. Husky permet de versionner ces hooks dans le dépôt. lint-staged exécute des commandes uniquement sur les fichiers déjà ajoutés avec git add, ce qui évite de relancer tout le projet à chaque commit. Les hooks Claude Code sont différents: ils appartiennent au cycle de vie de Claude Code. Ils peuvent aider, mais ils ne remplacent pas un Git hook partagé par toute l’équipe.

L’objectif n’est pas de créer un CI local lourd. Le bon compromis consiste à garder pre-commit rapide, à déplacer les vérifications plus coûteuses vers pre-push, puis à laisser CI faire l’arbitrage complet.

Vue d’ensemble

Le découpage que je recommande est stable: pre-commit pour les contrôles rapides et proches des fichiers, pre-push pour les contrôles projet, CI pour la validation complète. Ce découpage réduit le risque que les développeurs prennent l’habitude de contourner le hook avec --no-verify.

flowchart LR
  A["Claude Code modifie des fichiers"] --> B["Le développeur fait git add"]
  B --> C["Husky pre-commit"]
  C --> D["lint-staged"]
  D --> E["ESLint / Prettier"]
  E --> F["commit"]
  C --> G["typecheck, tests et build vont en pre-push ou CI"]

J’ai vérifié les références actuelles: Husky Get started, lint-staged README, documentation Git hooks et Claude Code hooks reference. En pratique, Husky recommande npx husky init, et lint-staged a besoin d’un hook pre-commit plus une configuration qui associe des glob de fichiers à des commandes.

Configuration minimale

Si ESLint ou Prettier ne sont pas encore propres dans le projet, commencez par le guide ESLint avec Claude Code et le guide Prettier. Husky ne fait que déclencher les commandes; il ne corrige pas une configuration fragile.

Avec Claude Code, donnez une consigne précise:

Ajoute Husky et lint-staged à ce dépôt Node.js/TypeScript.
Le pre-commit doit traiter seulement les fichiers JS, TS, JSON, Markdown et CSS staged.
Exécute ESLint en auto-fix et Prettier dans pre-commit.
Ne mets pas typecheck, tests ni build dans pre-commit; place-les en pre-push ou CI.
À la fin, liste les commandes de vérification manuelle.

La mise en place manuelle tient en deux commandes:

npm install --save-dev husky lint-staged eslint prettier
npx husky init

npx husky init crée .husky/pre-commit et met à jour le script prepare dans package.json. Remplacez le contenu du hook par:

#!/usr/bin/env sh
npx lint-staged

Ajoutez ensuite une configuration courte. Si le projet possède déjà des scripts, fusionnez les clés au lieu d’écraser le fichier.

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint --fix .",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix --max-warnings=0",
      "prettier --write"
    ],
    "*.{json,md,mdx,yml,yaml,css,scss}": [
      "prettier --write"
    ]
  }
}

Testez avec un fichier volontairement mal formaté:

git add src/example.ts
npx lint-staged --debug
git commit -m "chore: verify pre-commit checks"

Le mode --debug indique quelle configuration a été chargée, quels fichiers ont correspondu aux motifs et quelles commandes ont été lancées. Pour demander un diagnostic à Claude Code, fournissez cette sortie.

Configuration plus maintenable

Dans un dépôt qui grandit, je préfère déplacer la configuration vers lint-staged.config.mjs. Le package.json reste lisible et l’on peut ajouter de petits helpers. Cet exemple cite les noms de fichiers pour éviter les erreurs avec des chemins contenant des espaces.

// lint-staged.config.mjs
const shellQuote = (file) => `"${file.replaceAll('"', '\\"')}"`;
const joinFiles = (files) => files.map(shellQuote).join(" ");

export default {
  "*.{js,jsx,ts,tsx}": (files) => [
    `eslint --fix --max-warnings=0 ${joinFiles(files)}`,
    `prettier --write ${joinFiles(files)}`,
  ],
  "*.{json,md,mdx,yml,yaml,css,scss}": (files) =>
    `prettier --write ${joinFiles(files)}`,
};

Après ce déplacement, supprimez la clé lint-staged de package.json. Deux sources de vérité créent de la confusion pour les humains et pour Claude Code.

Trois cas d’usage

Premier cas: une application TypeScript. Claude Code modifie souvent composants, tests et utilitaires dans le même changement. ESLint en auto-fix et Prettier retirent beaucoup de bruit avant la revue. Le typecheck complet demande le contexte du projet et doit plutôt rester en pre-push ou CI.

Deuxième cas: un site Astro ou Next.js riche en contenu. Les fichiers MDX, JSON, CSS et TypeScript changent ensemble. lint-staged garde le diff centré sur le contenu réel au lieu de mélanger texte et formatage.

Troisième cas: un monorepo. Lancer tous les tests de tous les packages en pre-commit devient vite trop lent. Mieux vaut formater et linter les fichiers staged, puis laisser CI ou le task runner choisir les tests de packages selon les chemins modifiés.

commit-msg et pre-push

La règle de message de commit mérite son propre hook. Pour Conventional Commits, commitlint est le choix habituel.

npm install --save-dev @commitlint/cli @commitlint/config-conventional

// commitlint.config.mjs
export default {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "subject-max-length": [2, "always", 72],
  },
};

#!/usr/bin/env sh
npx --no -- commitlint --edit "$1"

Placez ce shell dans .husky/commit-msg. Pour les contrôles plus lourds, utilisez .husky/pre-push:

#!/usr/bin/env sh
npm run validate

Le script validate peut refléter CI:

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "test:ci": "vitest run --coverage",
    "build": "vite build",
    "validate": "npm run typecheck && npm run lint && npm run format:check && npm run test:ci && npm run build"
  }
}

Pièges fréquents

Le premier piège est de rendre pre-commit trop ambitieux. Si chaque commit prend deux minutes, le hook sera contourné. S’il dure quelques secondes, il devient une habitude.

Le deuxième piège est le partial staging. lint-staged travaille sur ce qui est staged, mais le même fichier peut aussi contenir des modifications non staged. Pour comprendre un résultat étrange, regardez git status --short, git diff --staged et npx lint-staged --debug ensemble.

Dans une équipe mixte Windows, macOS et Linux, les fins de ligne comptent. Les hooks Husky sont des scripts shell; les garder en LF est le choix le plus sûr.

* text=auto eol=lf
*.cmd text eol=crlf
*.bat text eol=crlf

Évitez aussi les corrections comme || true. Elles cachent l’échec au lieu de le résoudre. Demandez plutôt à Claude Code de raccourcir le message d’erreur, de déplacer une tâche lente vers pre-push ou de documenter la commande de correction.

Résultat vérifié

J’ai testé cette structure sur un petit projet TypeScript/Vite avec un formatage volontairement cassé, un import inutilisé et un problème d’espacement MDX. pre-commit est resté rapide, car seuls les fichiers staged étaient traités. npx lint-staged --debug a montré clairement les fichiers et les commandes. Les erreurs de types ont été arrêtées plus tard par npm run validate en pre-push, ce qui garde un rythme de commit plus fluide.

Conclusion

Husky + lint-staged est une barrière de qualité pragmatique pour le développement assisté par Claude Code. Gardez pre-commit léger, déplacez les contrôles coûteux vers pre-push ou CI, et indiquez cette séparation dans vos prompts Claude Code. Le hook devient alors une habitude d’équipe plutôt qu’un obstacle local.

Pour aller plus loin, consolidez les règles avec le guide ESLint et standardisez le formatage avec le guide Prettier.