Husky + lint-staged mit Claude Code einrichten: praktischer pre-commit Guide

Claude Code kann in einer Sitzung viele Dateien ändern: Komponenten, Tests, Konfigurationen und Dokumentation. Das spart Zeit, vergrößert aber auch die Diff-Fläche. Ein Review sollte sich auf Verhalten, Schnittstellen und Risiken konzentrieren, nicht auf ungenutzte Imports, uneinheitliche Formatierung oder Markdown-Zeilenumbrüche.

Husky + lint-staged setzt genau an dieser Stelle an. Ein Git hook ist ein kleines Skript, das Git zu einem bestimmten Zeitpunkt ausführt, zum Beispiel direkt vor einem Commit. Husky macht solche Hooks im Repository versionierbar. lint-staged führt Befehle nur für Dateien aus, die bereits mit git add vorgemerkt wurden. Claude Code hooks sind etwas anderes: Sie laufen innerhalb des Claude-Code-Lebenszyklus. Sie können helfen, ersetzen aber keinen Git hook, der jeden Commit schützt.

Das Ziel ist kein schweres lokales CI. Der sinnvolle Schnitt lautet: schnelle Prüfungen in pre-commit, mittlere Projektprüfungen in pre-push und vollständige Absicherung in CI.

Empfohlener Ablauf

Die stabilste Struktur ist eine klare Aufteilung. pre-commit prüft dateinahe Dinge wie Formatierung und Linting. pre-push kann TypeScript, Tests und Build ausführen. CI bleibt die letzte Instanz. So bleibt der Commit schnell genug, damit niemand routinemäßig --no-verify nutzt.

flowchart LR
  A["Claude Code ändert Dateien"] --> B["Entwickler wählt Dateien mit git add"]
  B --> C["Husky pre-commit"]
  C --> D["lint-staged"]
  D --> E["ESLint / Prettier"]
  E --> F["commit"]
  C --> G["Typecheck, Tests und Build laufen in pre-push oder CI"]

Für die aktuellen Details habe ich die offiziellen Quellen geprüft: Husky Get started, das lint-staged README, das Git hooks Manual und die Claude Code hooks reference. Praktisch wichtig: Husky empfiehlt npx husky init, und lint-staged braucht zusätzlich eine Konfiguration, die Dateimuster auf Befehle abbildet.

Minimale funktionierende Einrichtung

Wenn ESLint oder Prettier im Projekt noch nicht sauber konfiguriert sind, beginne mit dem Claude Code ESLint Guide und dem Prettier Guide. Husky startet nur Befehle; stabile Regeln müssen darunter existieren.

Ein guter Prompt an Claude Code beschreibt Umfang und Grenzen:

Füge Husky und lint-staged zu diesem Node.js/TypeScript-Repository hinzu.
pre-commit soll nur staged JS-, TS-, JSON-, Markdown- und CSS-Dateien prüfen.
Führe ESLint mit Auto-Fix und Prettier in pre-commit aus.
Typecheck, Tests und Build gehören nicht in pre-commit, sondern in pre-push oder CI.
Liste danach die manuellen Verifikationsbefehle auf.

Manuell reichen diese Befehle als Start:

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

npx husky init erzeugt .husky/pre-commit und aktualisiert das prepare-Skript in package.json. Ersetze den Hook-Inhalt durch:

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

Danach kommt eine kleine Konfiguration in package.json. Bestehende scripts sollten zusammengeführt, nicht überschrieben werden.

{
  "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"
    ]
  }
}

Teste mit einer absichtlich schlecht formatierten Datei:

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

--debug zeigt, welche Konfiguration geladen wurde, welche Dateien zu welchem Glob passten und welche Befehle ausgeführt wurden. Diese Ausgabe ist die beste Grundlage, wenn Claude Code einen fehlgeschlagenen Hook analysieren soll.

Wartbare lint-staged Konfiguration

In größeren Repositories verschiebe ich die Konfiguration lieber nach lint-staged.config.mjs. Dadurch bleibt package.json lesbar, und Hilfsfunktionen sind möglich. Das folgende Beispiel zitiert Dateinamen, damit Pfade mit Leerzeichen nicht sofort brechen.

// 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)}`,
};

Wenn diese Datei existiert, entferne den lint-staged-Block aus package.json. Zwei Quellen für dieselbe Regel führen zu Drift und verwirren auch AI-gestützte Änderungen.

Drei typische Einsatzfälle

Der erste Einsatzfall ist eine TypeScript-Produktanwendung. Claude Code ändert oft Komponenten, Tests und Hilfsfunktionen gemeinsam. ESLint Auto-Fix und Prettier entfernen viel Review-Rauschen. Der vollständige Typecheck ist projektweit und gehört besser in pre-push oder CI.

Der zweite Einsatzfall ist eine Astro- oder Next.js-Website mit viel Inhalt. MDX, JSON-Metadaten, CSS und TypeScript ändern sich häufig zusammen. lint-staged sorgt dafür, dass Artikel-Diffs nicht von Formatierungsdetails überdeckt werden.

Der dritte Einsatzfall ist ein Monorepo. Alle Tests aller Packages in pre-commit auszuführen ist meist zu langsam. Formatiere und lintere staged Dateien lokal, und überlasse Pakettests dem Task-Runner oder CI auf Basis der geänderten Pfade.

commit-msg und pre-push trennen

Regeln für Commit-Nachrichten gehören in einen eigenen commit-msg Hook. Für Conventional Commits ist commitlint üblich.

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"

Diese Shell-Zeilen kommen in .husky/commit-msg. Teurere Checks laufen in .husky/pre-push:

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

Das passende validate-Skript kann CI spiegeln:

{
  "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"
  }
}

Häufige Stolperfallen

Der häufigste Fehler ist ein zu schwerer pre-commit Hook. Wenn jeder Commit zwei Minuten dauert, wird der Hook umgangen. Ein Hook, der wenige Sekunden braucht, wird akzeptiert.

Partial staging ist die zweite Falle. lint-staged arbeitet mit staged Dateien, aber dieselbe Datei kann zusätzlich unstaged Änderungen enthalten. Prüfe bei seltsamen Ergebnissen gemeinsam git status --short, git diff --staged und npx lint-staged --debug.

In Teams mit Windows, macOS und Linux sind Zeilenenden wichtig. Husky Hooks sind Shell-Skripte, daher ist LF die sicherste Wahl.

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

Vermeide außerdem Lösungen wie || true. Sie verstecken Fehler und machen die Qualitätsprüfung wirkungslos. Besser ist es, Fehlermeldungen zu verkürzen, langsame Befehle nach pre-push zu verschieben oder den Reparaturbefehl zu dokumentieren.

Ergebnis aus dem Praxistest

Ich habe diese Struktur in einem kleinen TypeScript/Vite-Projekt mit kaputter Formatierung, ungenutztem Import und MDX-Abstandsfehler getestet. pre-commit blieb schnell, weil nur staged Dateien verarbeitet wurden. npx lint-staged --debug machte die Zuordnung von Dateien zu Befehlen transparent. TypeScript-Fehler wurden bewusst erst in npm run validate bei pre-push gestoppt, was den Commit-Fluss deutlich angenehmer machte.

Fazit

Husky + lint-staged ist eine pragmatische Sicherheitslinie für Claude-Code-Workflows. Halte pre-commit leicht, verschiebe teure Prüfungen nach pre-push oder CI, und schreibe diese Aufteilung in deine Claude-Code-Prompts. Dann ist der Hook kein lokales Hindernis, sondern ein gemeinsamer Qualitätsstandard.

Als nächstes lohnt sich der Blick in den ESLint Guide und den Prettier Guide.