ESLint Flat Config mit Claude Code in echten Projekten

Claude Code soll die ESLint-Konfiguration nicht erraten

ESLint ist ein Werkzeug für statische Analyse von JavaScript und TypeScript. Statische Analyse bedeutet: Der Code wird vor der Ausführung geprüft, damit vergessene Promises, React-Hooks-Fehler, Barrierefreiheitsprobleme, ungeordnete Imports und riskante Muster früh auffallen.

Seit ESLint v9 ist Flat Config der Standardweg. Auch im Juni 2026 beschreibt die offizielle Dokumentation die Konfiguration weiterhin über Dateien wie eslint.config.js und eslint.config.mjs. Eine vage Anfrage wie “richte ESLint ein” reicht für Claude Code trotzdem nicht. Dann entstehen leicht Mischungen aus alten .eslintrc-Mustern, fehlendem typbasiertem Linting oder Regeln, die CI verlangsamen, aber wenig Nutzen bringen.

Besser ist ein klarer Arbeitsauftrag: verwendeter Stack, generierte Ordner, Befehle, die bestehen müssen, und Regeln, die nur in Tests gelockert werden dürfen. Dieser Artikel fasst den Ablauf zusammen, den Masa für ein React-Admin-Panel, eine Astro-Content-Site und eine kleine TypeScript-Bibliothek nutzt.

Als Referenz dienen ESLint Configuration Files, typescript-eslint typed linting, der eslint-plugin-astro User Guide und die Claude Code CLI reference.

Abhängigkeiten und Scripts zuerst festlegen

Bevor Claude Code Dateien ändert, installiere die passenden Pakete. Das Basisset deckt ESLint, TypeScript, React, Hooks, Barrierefreiheit und Import-Sortierung ab. Die Astro-Pakete brauchst du nur, wenn das Projekt .astro-Dateien enthält.

npm i -D eslint @eslint/js typescript typescript-eslint globals
npm i -D eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y
npm i -D eslint-plugin-simple-import-sort

# Nur für Astro-Projekte
npm i -D eslint-plugin-astro astro-eslint-parser

In package.json sollten lokale Korrektur und CI-Prüfung getrennt sein. lint:fix ist für lokale Aufräumarbeiten. lint und typecheck sind die CI-Befehle. --max-warnings=0 lässt auch Warnungen fehlschlagen; bei älteren Codebasen sollte man das nach der ersten Bereinigung aktivieren.

{
  "scripts": {
    "lint": "eslint . --max-warnings=0",
    "lint:fix": "eslint . --fix",
    "lint:debug": "eslint --print-config src/App.tsx > .eslint-debug.json",
    "typecheck": "tsc --noEmit",
    "ci:verify": "npm run lint && npm run typecheck"
  }
}

Claude Code sollte nach dem Schreiben der Konfiguration nicht stoppen. Es soll dieselben Befehle ausführen, die später auch das Team nutzt.

package.json scripts
  -> eslint.config.mjs
  -> npm run lint:fix
  -> npm run lint
  -> npm run typecheck
  -> CI gate
  -> Rest-Diff mit Claude Code prüfen

Flat Config für TypeScript und React

Für eine React- und TypeScript-App ist diese eslint.config.mjs ein guter Startpunkt. projectService: true aktiviert typbasiertes Linting. Das ist wertvoll, kostet aber Zeit. Deshalb müssen Build-Ausgaben und generierte Ordner früh ignoriert werden.

import js from "@eslint/js";
import globals from "globals";
import react from "eslint-plugin-react";
import reactHooks from "eslint-plugin-react-hooks";
import jsxA11y from "eslint-plugin-jsx-a11y";
import simpleImportSort from "eslint-plugin-simple-import-sort";
import tseslint from "typescript-eslint";

export default tseslint.config(
  {
    ignores: [
      "node_modules/",
      "dist/",
      "build/",
      "coverage/",
      ".next/",
      ".astro/",
      "public/",
      "*.min.js"
    ]
  },
  js.configs.recommended,
  ...tseslint.configs.strictTypeChecked,
  ...tseslint.configs.stylisticTypeChecked,
  {
    files: ["**/*.{js,mjs,cjs,ts,tsx}"],
    languageOptions: {
      ecmaVersion: "latest",
      sourceType: "module",
      globals: {
        ...globals.browser,
        ...globals.node,
        ...globals.es2024
      },
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname
      }
    }
  },
  {
    files: ["**/*.{jsx,tsx}"],
    ...react.configs.flat.recommended,
    settings: {
      react: { version: "detect" }
    },
    rules: {
      ...react.configs.flat.recommended.rules,
      "react/react-in-jsx-scope": "off",
      "react/prop-types": "off"
    }
  },
  {
    files: ["**/*.{jsx,tsx}"],
    plugins: {
      "react-hooks": reactHooks,
      "jsx-a11y": jsxA11y
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
      ...jsxA11y.configs.recommended.rules
    }
  },
  {
    plugins: {
      "simple-import-sort": simpleImportSort
    },
    rules: {
      "simple-import-sort/imports": "error",
      "simple-import-sort/exports": "error",
      "@typescript-eslint/consistent-type-imports": [
        "error",
        { prefer: "type-imports", fixStyle: "separate-type-imports" }
      ],
      "@typescript-eslint/no-floating-promises": "error",
      "@typescript-eslint/no-misused-promises": [
        "error",
        { checksVoidReturn: { attributes: false } }
      ],
      "@typescript-eslint/no-unused-vars": [
        "error",
        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }
      ],
      "no-console": ["warn", { allow: ["warn", "error"] }]
    }
  },
  {
    files: ["**/*.{js,mjs,cjs}"],
    extends: [tseslint.configs.disableTypeChecked]
  },
  {
    files: ["**/*.{test,spec}.{ts,tsx}", "**/__tests__/**/*.{ts,tsx}"],
    rules: {
      "@typescript-eslint/no-explicit-any": "off",
      "@typescript-eslint/no-unsafe-assignment": "off",
      "@typescript-eslint/no-unsafe-member-access": "off"
    }
  }
);

Diese Konfiguration priorisiert echte Risiken statt Geschmacksfragen. no-floating-promises findet vergessene awaits. no-misused-promises reduziert riskante async Handler in JSX. consistent-type-imports hält reine Typ-Imports sauber. Tests dürfen lokal lockerer sein, aber Produktionscode sollte dadurch nicht schwächer werden.

Astro braucht eine eigene Behandlung

Astro-Dateien mischen Template, TypeScript frontmatter, Komponentenaufrufe und Client-Scripts. Wenn eine reine React-Konfiguration auf .astro angewendet wird, scheitert ESLint oft schon beim Parsen.

Für eine Astro-Content-Site nimm zuerst die empfohlenen Flat-Konfigurationen des Plugins und ergänze eine kleine .astro-Sonderregel. astro/no-set-html-directive ist besonders bei Blogs und Dokumentationsseiten nützlich, weil HTML-Injection in redaktionellen Reviews leicht übersehen wird.

import js from "@eslint/js";
import astro from "eslint-plugin-astro";
import globals from "globals";
import tseslint from "typescript-eslint";

export default tseslint.config(
  {
    ignores: ["dist/", ".astro/", "node_modules/", "public/"]
  },
  js.configs.recommended,
  ...astro.configs["flat/recommended"],
  ...astro.configs["jsx-a11y-recommended"],
  ...tseslint.configs.recommendedTypeChecked,
  {
    files: ["**/*.{ts,tsx}"],
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node
      },
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname
      }
    }
  },
  {
    files: ["**/*.astro"],
    languageOptions: {
      parserOptions: {
        parser: tseslint.parser,
        extraFileExtensions: [".astro"],
        projectService: true,
        tsconfigRootDir: import.meta.dirname
      }
    },
    rules: {
      "astro/no-set-html-directive": "error",
      "astro/no-unused-define-vars-in-style": "error"
    }
  }
);

ESLint sollte nicht alle Formatierungsaufgaben übernehmen. Formatierung gehört zu Prettier; ESLint konzentriert sich auf unsicheren Code, Barrierefreiheit, Typfehler und Projektregeln. Dazu passt der Artikel Prettier-Konfiguration mit Claude Code.

Drei reale Anwendungsfälle

Der erste Fall ist ein SaaS-Admin-Panel. Einladungen, Abrechnung und Rollenänderungen enthalten viel asynchronen Code. Hier sollte @typescript-eslint/no-floating-promises ein error sein, weil ein fehlendes await zu einem echten Produktionsproblem werden kann.

Der zweite Fall ist ein technischer Astro-Blog. Die wichtigsten Prüfungen sind .astro-Parsing, Barrierefreiheit, ungenutzte Styles und gefährliches HTML. Weil viele Seiten generiert werden, müssen dist/, .astro/ und Build-Ausgaben ignoriert werden.

Der dritte Fall ist eine TypeScript-Bibliothek. Öffentliche APIs brauchen strengere Regeln als Tests. Typ-Imports, ungenutzte Variablen und Exports sollten im Produktivcode streng bleiben; any kann in Test-Fixtures gezielt erlaubt werden.

Projekt	Strengere Regeln	Lockerere Bereiche
React Admin	Promises, Hooks, a11y	Storybook-Mocks
Astro Blog	.astro, HTML-Injection, ungenutztes CSS	Generierter Inhalt
TypeScript-Bibliothek	Typ-Imports, Variablen, Exports	Test-Fixtures

Wenn auch vor dem Commit geprüft werden soll, kombiniere das mit Husky + lint-staged. In großen Repositories sollte pre-commit schnell bleiben; schweres typbasiertes Linting passt besser in CI.

CI als Qualitätsgrenze einrichten

Lokaler Erfolg reicht nicht. CI muss dieselben Befehle mit denselben Regeln ausführen. Für GitHub Actions ist dieser minimale Workflow oft genug.

name: code-quality

on:
  pull_request:
  push:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck

Wenn ein bestehendes Projekt Hunderte Fehler hat, führe nicht sofort eslint --fix über alles aus. Sammle zuerst die Fehler nach Regel und lasse Claude Code kleine, risikoarme Gruppen reparieren.

npm run lint
npm run lint:fix
npm run lint
npm run typecheck
npm run lint:debug

lint:debug zeigt die aufgelöste Konfiguration für eine Datei. Damit lässt sich prüfen, ob eine React-Regel versehentlich .astro trifft oder ob eine Test-Ausnahme in Produktionscode durchrutscht.

Prompts für Claude Code

Vorlage 1: Neue Einführung.

Führe ESLint Flat Config in diesem Repository ein.
Der Stack ist TypeScript + React. Lies zuerst package.json, tsconfig und vorhandene lint-Konfiguration.
Erstelle eslint.config.mjs und arbeite weiter, bis npm run lint und npm run typecheck bestehen.
Vermeide Autofixes, die Verhalten ändern könnten. Falls einer nötig ist, erkläre vorher den Grund.

Vorlage 2: Lint-Fehler beheben.

Ich füge die Ausgabe von npm run lint ein.
Gruppiere die Fehler nach Regel, behebe zuerst die risikoarmen Kategorien und halte den Diff klein.
Nutze eslint-disable nur als letzten Ausweg. Wenn du es nutzt, ergänze eine einzeilige Begründung.
Führe danach npm run lint und npm run typecheck aus.

Vorlage 3: Astro-Unterstützung.

Prüfe die ESLint-Konfiguration dieser Astro-Site.
Trenne die Regeln für .astro, .ts und .tsx. Nutze die empfohlene Flat-Konfiguration von eslint-plugin-astro.
Setze astro/no-set-html-directive auf error und bestätige, dass React-Regeln nicht versehentlich auf die ganze .astro-Datei angewendet werden.

Vorlage 4: CI-Fehler untersuchen.

Der lint job in GitHub Actions schlägt fehl.
Vergleiche lokale und CI-Versionen von Node, npm, ESLint und Plugins.
Erstelle einen Reproduktionsbefehl und trenne die Lösung in Konfigurationsänderung, Dependency-Update oder Quellcodeänderung.
Wende den kleinsten sicheren Diff an.

Claude Code braucht Dateien, Befehle und Grenzen. “Lint reparieren” ist zu ungenau. “Produktionsregeln nicht lockern und mit diesen Befehlen beweisen” ist deutlich belastbarer.

Typische Stolperfallen

Die erste Falle ist eine alte .eslintrc-extends-Kette in Flat Config zu kopieren. Die Struktur ist anders. Wenn alte Shareable Configs nötig sind, prüfe Kompatibilität, bevorzuge aber Flat-Beispiele aus den Plugin-Dokumenten.

Die zweite Falle ist typbasiertes Linting auf alle Dateien anzuwenden. projectService: true ist stark, aber Bundles, generierte Dateien und Build-Ausgaben machen CI langsam. ignores gehören an den Anfang.

Die dritte Falle ist ein riesiger Autofix-Diff. Import-Sortierung, Typ-Imports, ungenutzte Variablen und Formatierung können echte Verhaltensänderungen verdecken. Masa trennt die erste Einführung meist nach Promises, Imports und Framework-Regeln.

Die vierte Falle sind dauerhafte Warnungen. Eine Warnung, die nie blockiert, wird Rauschen. Teamregeln gehören auf error, temporäre Lernhinweise auf warn, schwache Signale gar nicht in die Konfiguration.

Die fünfte Falle ist fehlender Kontext für Claude Code. Sag explizit, ob Barrierefreiheit kritisch ist, ob Fixtures any nutzen dürfen und ob öffentliche APIs streng sein müssen. Diese Vorgaben liefern bessere Ergebnisse als generische Empfehlungen.

Fazit

ESLint Flat Config macht sichtbar, welche Regeln wo gelten, weil die Projektkonfiguration an einem Ort liegt. Claude Code ist nicht nur zum einmaligen Generieren der Datei nützlich, sondern zum Lesen der Codebase, Ausführen der Prüfungen und Anpassen ohne Standards zu senken.

Wähle zuerst die richtige Basis für React/TypeScript oder Astro. Nimm npm run lint und npm run typecheck in CI auf. Danach helfen klare Prompts, kleine Reparaturen zu bekommen; eslint-disable und große --fix-Diffs müssen weiterhin manuell geprüft werden.

Für den restlichen Workflow passen Prettier und Husky + lint-staged. Wiederverwendbare Review-Prompts und Rollout-Checklisten findest du auf der ClaudeCodeLab-Produktseite.

In der Praxis getestet

Masa hat diese Konfiguration in einem kleinen React-Admin-Panel und einem Astro-Blog-Starter ausprobiert. Der erste Lauf fand vor allem Import-Reihenfolge und mehrere unbehandelte Promises. Ein einzelner eslint --fix-Diff war schwer zu prüfen, deshalb funktionierte die Aufteilung nach Promises, Imports und Astro-Sicherheitsregeln besser. Am reproduzierbarsten war es, npm run lint und npm run typecheck in CI festzulegen, Fehllogs an Claude Code zu geben und kleine Korrekturen mit Nachweisbefehlen zu verlangen.