TypeScript Type-Check lokal in Vibe Coding integrieren: CLAUDE.md als Regel-Engine

„Der Build schlägt wieder fehl – Typ-Fehler in Zeile 247.“ Kennt ihr das? Nach über 15 Jahren Erfahrung in Softwarequalität und Remote Consulting wissen wir: Typ-Fehler in TypeScript-Projekten kosten Zeit, Nerven und am Ende auch Geld. Doch was, wenn ihr diese Fehler gar nicht erst bis zur CI-Pipeline durchlassen würdet? Genau darum geht es in diesem Artikel: Wie ihr tsc --noEmit als lokalen Type-Check in euren Vibe-Coding-Workflow integriert und die CLAUDE.md-Datei als zentrale Regel-Engine für KI-gestütztes Development nutzt.

Vibe Coding – also das intuitive, KI-unterstützte Programmieren mit Tools wie Claude Code, Cursor oder GitHub Copilot – verändert gerade, wie wir Software entwickeln. Doch die besten KI-Assistenten sind nur so gut wie der Kontext, den sie bekommen. Und genau hier setzt die Kombination aus lokalen Type-Checks und einer sauber konfigurierten CLAUDE.md an.

1. Was bedeutet tsc –noEmit für lokale Entwicklung?

Der TypeScript-Compiler tsc kann mehr als nur Code transpilieren. Mit dem Flag --noEmit führt er eine vollständige Typ-Prüfung durch, ohne JavaScript-Dateien zu erzeugen. Das macht ihn zum perfekten Werkzeug für schnelle Feedback-Loops während der Entwicklung.

# Einmalige Prüfung
npx tsc --noEmit

# Kontinuierliche Überwachung
npx tsc --noEmit --watch

Der Vorteil liegt auf der Hand: Ihr bekommt sofortiges Feedback zu Typ-Fehlern, ohne dass Dateien geschrieben werden. In Vibe-Coding-Szenarien ist das entscheidend, denn die KI generiert oft Code, der syntaktisch korrekt, aber semantisch fehlerhaft ist. Ein lokaler Type-Check fängt diese Fehler ab, bevor sie in eurem Repository landen.

2. Warum reicht der Editor-TypeScript-Server nicht aus?

Viele Entwickler verlassen sich auf die Typ-Prüfung in VS Code oder anderen IDEs. Der TypeScript Language Server markiert Fehler direkt im Code – warum also noch tsc separat ausführen?

Die Antwort liegt in der Architektur: Der Language Server prüft nur geöffnete Dateien und deren direkte Abhängigkeiten. Wenn ihr eine Datei ändert und schließt, ohne ihre Importeure zu öffnen, können Fehler unbemerkt bleiben. tsc --noEmit hingegen prüft das gesamte Projekt gegen die tsconfig.json und findet auch Fehler in Dateien, die ihr gerade nicht bearbeitet.

Aus unserer Consulting-Praxis: Wir haben Projekte gesehen, in denen der Editor „grün“ war, aber der CI-Build regelmäßig fehlschlug. Der Grund waren immer Typ-Fehler in nicht-geöffneten Dateien. Ein lokaler tsc --noEmit vor jedem Commit hätte das verhindert.

3. Wie konfiguriere ich Pre-Commit-Hooks für TypeScript-Projekte?

Die Integration von Type-Checks in Pre-Commit-Hooks ist ein Game-Changer für die Code-Qualität. Mit Husky und lint-staged richtet ihr das in wenigen Minuten ein:

npm install -D husky lint-staged
npx husky init

Fügt dann in eure package.json folgende Konfiguration ein:

{
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"]
  },
  "scripts": {
    "typecheck": "tsc --noEmit",
    "prepare": "husky"
  }
}

Der Clou: tsc lässt sich nicht mit lint-staged kombinieren, da es immer das gesamte Projekt prüft. Fügt daher in euren Pre-Commit-Hook (.husky/pre-commit) einen separaten Type-Check ein:

#!/bin/sh
npx lint-staged
npm run typecheck

So wird bei jedem Commit erst gelinted, dann der Type-Check durchgeführt. Fehler blockieren den Commit, bis sie behoben sind.

4. Was ist die CLAUDE.md-Datei und wie funktioniert sie?

Die CLAUDE.md ist das Herzstück des kontextbewussten Vibe Codings. Sie ist eine Markdown-Datei im Projekt-Root, die Claude Code automatisch einliest und als Regelwerk für alle Interaktionen verwendet. Im Gegensatz zu normalen Prompts behandelt Claude die Inhalte dieser Datei als autoritative System-Regeln.

Eine minimale CLAUDE.md für TypeScript-Projekte sieht so aus:

# Projekt-Konfiguration

## Build-Befehle
- `npm run build`: Kompiliert das Projekt
- `npm run typecheck`: Führt tsc --noEmit aus
- `npm run lint`: ESLint-Prüfung

## Code-Standards
- ES Modules (import/export), kein CommonJS
- Strict TypeScript (noImplicitAny, strictNullChecks)
- Alle Funktionen mit expliziten Return-Types

## Workflow
- Vor jedem Commit: npm run typecheck
- Branch-Naming: feature/TICKET-beschreibung

Der Unterschied zu normalen Prompts: Diese Regeln gelten für jede Interaktion, ohne dass ihr sie wiederholen müsst. Claude behandelt sie als unveränderliche Constraints, nicht als Vorschläge.

5. Wie strukturiere ich CLAUDE.md für optimale KI-Unterstützung?

Die beste CLAUDE.md ist schlank und fokussiert. Anthropic empfiehlt, die Datei menschenlesbar zu halten und auf das Wesentliche zu beschränken. Eine bewährte Struktur aus unseren Projekten:

# Projektname

## Kritische Regeln (WICHTIG)
- TypeScript strict mode ist aktiviert
- Niemals `any` als Typ verwenden
- Alle exports müssen typisiert sein

## Entwicklungs-Befehle
- npm run dev: Startet Entwicklungsserver
- npm run typecheck: tsc --noEmit
- npm run test: Jest mit Coverage

## Architektur-Entscheidungen
- API-Aufrufe nur über services/api.ts
- State-Management mit Zustand
- Styling mit Tailwind CSS

## Bekannte Probleme
- Redis-Client verursacht langsame Type-Checks (Issue #2975)

Fügt Sections nur hinzu, wenn sie tatsächlich relevant sind. Eine überladene CLAUDE.md führt zu schlechteren Ergebnissen, weil Claude Schwierigkeiten hat, das Wesentliche zu priorisieren.

6. Welche Performance-Optimierungen gibt es für tsc –noEmit?

Bei großen Projekten kann tsc --noEmit mehrere Sekunden oder sogar Minuten dauern. Hier sind die effektivsten Optimierungen:

Incremental Compilation aktivieren:

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}

skipLibCheck nutzen:

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

Parallelisierung im Pre-Commit:

#!/bin/sh
npx lint-staged &
npm run typecheck &
wait

Aus unserer Erfahrung: Das Upgrade von TypeScript 4.7 auf 5.2+ brachte in einem Kundenprojekt 20% schnellere Compile-Zeiten – ohne jede andere Änderung.

7. Kann ich verschiedene CLAUDE.md-Dateien für verschiedene Bereiche nutzen?

Ja, und das ist eine der mächtigsten Features für Monorepos. Claude liest CLAUDE.md-Dateien hierarchisch:

/projekt
├── CLAUDE.md           # Globale Regeln
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md   # Frontend-spezifische Regeln
│   └── backend/
│       └── CLAUDE.md   # Backend-spezifische Regeln

Die Regeln werden kaskadiert: Globale Regeln gelten überall, spezifische Regeln ergänzen oder überschreiben sie im jeweiligen Verzeichnis.

Für persönliche Einstellungen, die nicht ins Repository gehören, nutzt ihr CLAUDE.local.md und fügt sie zur .gitignore hinzu. So kann jedes Teammitglied eigene Präferenzen definieren, ohne die Team-Konfiguration zu beeinflussen.

8. Wie integriere ich tsc-Checks in Vibe-Coding-Workflows?

Der effektivste Ansatz kombiniert automatische und manuelle Checks:

Automatisch:

• Pre-Commit-Hook mit tsc --noEmit
• Watch-Mode während der Entwicklung: tsc --noEmit --watch
• CI-Pipeline als finale Absicherung

CLAUDE.md-Integration:

## Workflow-Regeln

WICHTIG: Nach jeder Code-Änderung `npm run typecheck` ausführen.
Bei Typ-Fehlern: Erst Fehler beheben, dann weiterarbeiten.

Diese Regel sorgt dafür, dass Claude selbstständig Type-Checks durchführt und Fehler behebt, bevor neuer Code generiert wird. In der Praxis reduziert das die Iterations-Zyklen erheblich.

9. Welche häufigen Fehler sollte ich vermeiden?

Aus über 15 Jahren Consulting-Erfahrung kennen wir die typischen Stolpersteine:

Fehler 1: Type-Check nur in CI
Wenn ihr Typ-Fehler erst in der CI-Pipeline entdeckt, habt ihr bereits Zeit verloren. Lokale Checks sind schneller und kostengünstiger.

Fehler 2: CLAUDE.md zu detailliert
Eine 500-Zeilen CLAUDE.md ist kontraproduktiv. Haltet euch an 50-100 Zeilen mit den wichtigsten Regeln.

Fehler 3: Keine expliziten Return-Types
TypeScript kann Return-Types inferieren, aber explizite Types machen Code wartbarer und den Type-Check schneller:

// Schlecht
function calculate(a: number, b: number) {
  return a + b;
}

// Besser
function calculate(a: number, b: number): number {
  return a + b;
}

Fehler 4: Watch-Mode vergessen
Einmalige Checks sind gut, kontinuierliches Feedback ist besser. Nutzt tsc --noEmit --watch während der aktiven Entwicklung.

10. Wie starte ich am besten mit dieser Konfiguration?

Der schnellste Weg zur produktiven Einrichtung:

Schritt 1: Type-Check-Script anlegen

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "typecheck:watch": "tsc --noEmit --watch"
  }
}

Schritt 2: Husky einrichten

npm install -D husky
npx husky init
echo "npm run typecheck" >> .husky/pre-commit

Schritt 3: CLAUDE.md erstellen

# Projektname

## Build-Befehle
- npm run typecheck: Type-Check ohne Emit
- npm run build: Production Build

## TypeScript-Regeln
- Strict Mode aktiviert
- Explizite Return-Types für alle Funktionen
- Keine any-Types

## Workflow
- Vor Commits: npm run typecheck

Schritt 4: Testen

# Absichtlichen Fehler einbauen
echo "const x: string = 42;" >> src/test.ts
git add . && git commit -m "Test"
# Commit sollte fehlschlagen

Euer nächster Schritt

Die Kombination aus lokalem TypeScript-Type-Check und CLAUDE.md-Konfiguration ist ein Productivity-Boost für jedes Vibe-Coding-Projekt. Ihr bekommt schnelleres Feedback, weniger Fehler in der CI-Pipeline und eine KI, die eure Projekt-Konventionen versteht.

Ihr wollt diese Konfiguration in eurem Team einführen oder habt Fragen zur optimalen TypeScript-Einrichtung? Mit über 15 Jahren Erfahrung in Softwarequalität, Open Source und Remote Consulting helfen wir euch gerne – von der ersten Analyse bis zur fertigen Implementierung.

Kontakt: roland@nevercodealone.de

Wir freuen uns darauf, eure TypeScript-Projekte gemeinsam auf das nächste Level zu heben!

---

Never Code Alone – Gemeinsam für bessere Software-Qualität!