JavaScript mit KI zu TypeScript migrieren: sicherer Plan

Um JavaScript mit KI zu TypeScript zu migrieren, bittest du einen Agenten nicht, „das Projekt zu konvertieren“. Du richtest eine TypeScript-Konfiguration ein, die das vorhandene JavaScript akzeptiert, und lässt Agenten dann Dateien in einer festen Reihenfolge konvertieren, wobei Typchecker und Tests entscheiden, wann ein Schritt fertig ist. Der Compiler ist der beste Reviewer, den du einem Agenten je geben wirst: Er ist schnell, wird nie müde und lässt sich nicht zu einem „sieht gut aus“ überreden.

Dieser Leitfaden ist die praktische Umsetzung dieser Idee: die genaue tsconfig.json für den Start, wie du die Reihenfolge der Dateien festlegst, wie du die Strictness verschärfst, ohne eine Woche lang rote Builds zu haben, wie du any im Griff behältst, wie die Typprüfung zum eigenen Prüfschritt des Agenten wird und wie du die Arbeit ohne Merge-Konflikte auf parallele Agenten verteilst. Das allgemeine Sicherheitsnetz eines Legacy-Refactorings (Charakterisierungstests, Rollback, Review) behandelt Legacy-Code mit KI refactoren; lies das zuerst, dieser Beitrag wiederholt es nicht.

Versionsabhängige Details folgen hier der offiziellen TypeScript-Dokumentation mit Stand Oktober 2026.

Warum Agenten für diese Aufgabe gut sind

Eine Migration von JS zu TS ist größtenteils mechanische Arbeit mit einem klaren Signal am Ende jedes Schritts. Genau darin sind Coding-Agenten gut:

• Das Feedback kommt sofort. tsc gibt Datei, Zeile und Fehlercode aus. Ein Agent kann das lesen und den Fehler beheben, ohne zu raten.
• Die Arbeit lässt sich natürlich aufteilen. Dateien und Ordner lassen sich einzeln konvertieren, sodass die Aufgabe in viele kleine, reviewbare Schritte zerfällt.
• Der langweilige Teil ist riesig. Parametertypen ergänzen, Interfaces für bereits existierende Objekte schreiben und @types-Pakete installieren ist genau die Art Arbeit, die Leute jahrelang vor sich herschieben.

Das Risiko ist genauso klar. Ein Agent, der den Compiler unbedingt grün bekommen soll, greift zu any, as-Casts und @ts-ignore, weil damit Fehler verschwinden. Der Großteil dieses Leitfadens dreht sich darum, diese Ausgänge zu schließen.

Schritt 1: eine tsconfig, die dein JavaScript akzeptiert

Der erste Commit sollte keinen Anwendungscode ändern. Er fügt TypeScript und eine Konfiguration hinzu, die das Projekt typprüft, während jede Datei noch .js ist.

npm install --save-dev typescript @types/node

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "strict": false,
    "noEmit": true,
    "incremental": true,
    "target": "es2022",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "types": ["node"],
    "skipLibCheck": true
  },
  "include": ["src"]
}

Was jede Einstellung bewirkt:

• allowJs lässt .js- und .ts-Dateien im selben Programm leben, sodass eine .ts-Datei eine .js-Datei importieren kann und umgekehrt.
• checkJs: false verhindert, dass TypeScript Fehler in Dateien meldet, die du noch nicht angefasst hast. Du nimmst Dateien einzeln dazu.
• strict: false ist Absicht. Seit TypeScript 6.0 ist strict standardmäßig true; ließest du es weg, wäre am ersten Tag jede strict-Prüfung aktiv.
• types: ["node"] ist aus demselben Grund wichtig: In TypeScript 6.0 ist der Standardwert von types ein leeres Array, sodass Node-Globals nur erkannt werden, wenn du sie aufführst. Ergänze "jest" oder "vitest/globals", wenn deine Tests auf Globals setzen.
• noEmit passt zu Projekten, in denen ein Bundler, tsx oder ein Framework den Code bereits in JavaScript umwandelt und TypeScript ihn nur prüft. Baut tsc deine App, lass es weg und setz stattdessen outDir.
• module und moduleResolution: Nimm nodenext für Node-Apps; für Code, den ein Bundler baut, ist "module": "esnext" mit "moduleResolution": "bundler" meist das richtige Paar.

Füge ein Skript hinzu und lass die CI es ausführen:

{
  "scripts": {
    "typecheck": "tsc -p tsconfig.json"
  }
}

Führe es einmal aus. Auf einer JavaScript-Codebasis mit abgeschaltetem checkJs sollte es bestehen oder nur ein paar Konfigurationsfehler zeigen. Behebe sie, committe, und du hast eine Ausgangsbasis. Ab jetzt bedeutet „der Build ist grün“, dass npm run typecheck und npm test beide bestehen.

Schritt 2: Fehler vor dem Umbenennen mit @ts-check ansehen

Bevor eine Datei umbenannt wird, kannst du sehen, was TypeScript von ihr hält. Füge // @ts-check als erste Zeile einer .js-Datei ein, und TypeScript meldet Fehler darin, wobei JSDoc-Kommentare als Typen dienen:

// @ts-check

/**
 * @param {number} cents
 * @param {string} currency
 * @returns {string}
 */
export function formatPrice(cents, currency) {
  return new Intl.NumberFormat('en', { style: 'currency', currency }).format(cents / 100);
}

Das ist eine gute erste Aufgabe für einen Agenten bei einer großen Datei: „Füge // @ts-check zu src/orders/pricing.js hinzu, behebe die Fehler nur mit JSDoc-Typen, ändere kein Verhalten.“ Du bekommst Typsicherheit ohne Umbenennung, und die spätere Konvertierung wird fast mechanisch. Wenn du den umgekehrten Weg bevorzugst, setz checkJs: true und schreib // @ts-nocheck in die Dateien, die noch nicht so weit sind; dann ist das Entfernen dieser Zeile der Schritt.

Schritt 3: die Reihenfolge festlegen, Blätter zuerst

Konvertiere zuerst Dateien, die nichts aus deinem eigenen Code importieren, dann die Dateien, die nur diese importieren, und so weiter bis zu den Einstiegspunkten. So kann sich jede konvertierte Datei auf Typen stützen, die es schon gibt.

Die Reihenfolge musst du nicht von Hand ermitteln. madge liest den Import-Graphen:

npx madge --leaves --extensions js,jsx src/
npx madge --circular --extensions js,jsx src/

--leaves listet Module ohne Abhängigkeiten, --circular listet Import-Zyklen. Zyklen solltest du vorher kennen: Dateien in einem Zyklus müssen zusammen konvertiert werden, also plane sie als einen Schritt.

Eine praktische Regel für die Aufteilung: Ein Schritt ist entweder eine große Datei oder ein Ordner mit kleinen Dateien, klein genug, dass der Diff in eine Review-Sitzung passt. Schreib die Liste in eine eingecheckte Datei wie MIGRATION.md, eine Zeile pro Schritt, und lass die Agenten sie abhaken. Diese Datei wird zum gemeinsamen Plan für jeden Agenten und jede Session.

Schritt 4: ein Konvertierungs-Prompt, eine Definition von fertig

Nutze für jeden Schritt dieselbe Prompt-Form, damit Agenten keine eigenen Regeln erfinden:

Convert src/billing/ from JavaScript to TypeScript.

- Rename with git mv so history follows the files (.js -> .ts, .jsx -> .tsx).
- Add types for parameters, return values and exported objects.
  Prefer types inferred from real usage over wide ones.
- Don't change runtime behaviour. No refactoring, no renaming,
  no "while I'm here" fixes. If you find a bug, note it in
  MIGRATION.md under "Found during migration" and leave it.
- No @ts-ignore, no @ts-nocheck. @ts-expect-error only with a reason
  on the same line. No new `any` beyond the budget in .any-budget.
- Don't edit tsconfig.json, package.json or src/types/.
  If you need a change there, stop and tell me what and why.

Done means: npm run typecheck passes, npm test passes,
npm run lint passes, and MIGRATION.md is updated.

Zwei Zeilen in diesem Prompt leisten die meiste Arbeit. „Don’t change runtime behaviour“ (kein Laufzeitverhalten ändern) hält den Diff reviewbar, denn eine reine Typmigration sollte nur Annotationen, Umbenennungen und Imports hinzufügen. „Don’t edit tsconfig.json“ (tsconfig.json nicht bearbeiten) versperrt den billigsten Weg zu Grün: den Compiler zu lockern.

Leg die stabilen Teile dieses Prompts in CLAUDE.md oder AGENTS.md, damit jede Session mit ihnen beginnt; CLAUDE.md und AGENTS.md erklärt, wie du einen Satz Regeln zwischen Agenten teilst.

Schritt 5: ein any-Budget, das nur sinkt

In einem Durchgang kommst du nicht auf null any, und ein komplettes Verbot führt oft zu schlimmeren Auswegen wie as unknown as Foo. Ein Budget ist ehrlicher: Du erlaubst eine Zahl, und die Zahl darf nur sinken.

Mach any und Unterdrückungskommentare zuerst mit typescript-eslint sichtbar:

// eslint.config.js (excerpt)
rules: {
  '@typescript-eslint/no-explicit-any': 'warn',
  '@typescript-eslint/ban-ts-comment': ['error', {
    'ts-expect-error': 'allow-with-description',
    'ts-ignore': true,
    'ts-nocheck': true,
    minimumDescriptionLength: 10,
  }],
}

ban-ts-comment mit diesen Optionen lehnt @ts-ignore und @ts-nocheck ab und akzeptiert @ts-expect-error nur mit einer schriftlichen Begründung von mindestens zehn Zeichen. @ts-expect-error ist ohnehin der bessere Ausweg: Sobald der Fehler behoben ist, wird der Kommentar selbst zum Fehler und kann so nicht veralten.

Dann zählst du explizite any und vergleichst sie mit einer Zahl, die im Repo liegt:

#!/usr/bin/env bash
# scripts/any-budget.sh
count=$(npx eslint src --format json \
  | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const r=JSON.parse(s);console.log(r.flatMap(f=>f.messages).filter(m=>m.ruleId==="@typescript-eslint/no-explicit-any").length)})')
budget=$(cat .any-budget)
echo "explicit any: $count (budget $budget)"
[ "$count" -le "$budget" ] || { echo "any budget exceeded"; exit 1; }

Führe es in der CI und als Teil der Definition von fertig des Agenten aus. Senkt ein Schritt die Zahl, senkst du .any-budget im selben Commit. Sag dem Agenten, wo das Budget liegt; Agenten halten sich an eine Zahl viel besser als an „vermeide any, wo möglich“.

Achte auf die anderen Auswege, die die Zählung nicht erfasst: as-Casts auf Werte, die von außen kommen (JSON.parse, Request-Bodies), Function und object als Parametertypen und eine Zeile declare module '*', die jeden Import zu any macht. Bitte den Reviewer, ob Mensch oder Agent, jeden neuen Cast im Diff aufzulisten.

Schritt 6: die Typprüfung zum Prüfschritt des Agenten machen

Ein Agent, der „fertig“ sagt, ohne tsc ausgeführt zu haben, rät. Mach die Prüfung zu einem Teil davon, wie der Agent einen Turn beendet, statt zu etwas, an das du denken musst.

In Claude Code kann ein Stop-Hook verhindern, dass der Turn endet, solange die Typprüfung fehlschlägt. Speichere das als .claude/hooks/typecheck.sh:

#!/usr/bin/env bash
# Exit 2 sends stderr back to Claude and keeps it working.
input=$(cat)
if [ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0   # already retried once; let the turn end
fi
npx tsc -p tsconfig.json --pretty false 1>&2 || exit 2

und registriere es in .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": ".claude/hooks/typecheck.sh" }
        ]
      }
    ]
  }
}

Endet ein Stop-Hook mit Exit-Code 2, hört Claude Code nicht auf und zeigt Claude das stderr des Hooks, sodass der Agent die Compilerfehler sieht und weiter behebt. Die Prüfung auf stop_hook_active lässt den Turn beim zweiten Versuch enden, statt in eine Schleife zu laufen. Der Leitfaden zu Claude-Code-Hooks behandelt Hooks ausführlicher. Ein PostToolUse-Hook auf Edit|Write kann nach jeder Bearbeitung eine schnellere Prüfung ausführen, wobei ein vollständiges tsc pro Bearbeitung in großen Projekten langsam wird.

Codex und Gemini CLI lesen die Hooks von Claude nicht, also schreib dieselbe Regel in AGENTS.md oder GEMINI.md: „Bevor du sagst, dass eine Aufgabe fertig ist, führe npm run typecheck und npm test aus und füge die letzten Zeilen der Ausgabe ein.“ Gerade die Bitte um die Ausgabe sorgt dafür, dass die Anweisung hängen bleibt.

Schritt 7: die Strictness Flag für Flag hochfahren

Sobald jede Datei .ts ist, oder ein Bereich, schaltest du die strict-Prüfungen in dieser Reihenfolge ein, jeweils mit eigenem Commit und eigener Agenten-Aufgabe:

1. noImplicitAny: Jeder Parameter und jede Variable braucht einen bekannten Typ. Das erzeugt die meisten Fehler und die nützlichsten Typen.
2. strictNullChecks: null und undefined werden zu eigenen Typen. Dieses Flag findet echte Bugs, die Sorte „cannot read property of undefined“.
3. Der Rest der strict-Familie: strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, noImplicitThis, useUnknownInCatchVariables. Meist jeweils weniger Fehler.
4. "strict": true ersetzt die einzelnen Flags, sobald sie alle bestehen.
5. Optionale Extras, die nicht zu strict gehören: noUncheckedIndexedAccess (indizierte Zugriffe können undefined sein) und exactOptionalPropertyTypes.

Du musst ein Flag nicht für das ganze Repo auf einmal umlegen. Eine zweite Konfiguration, die die erste erweitert und nur fertige Ordner abdeckt, hält strikten Code strikt, während der Rest aufholt:

{
  "extends": "./tsconfig.json",
  "compilerOptions": { "strict": true },
  "include": ["src/billing", "src/utils"]
}

Speichere sie als tsconfig.strict.json und führe tsc -p tsconfig.strict.json in der CI neben der Hauptprüfung aus. Jedes Mal, wenn ein Agent einen Ordner fertig hat, fügt er ihn zu include hinzu. Deckt include ganz src ab, verschiebst du strict: true in die Hauptkonfiguration und löschst die zweite Datei.

Eine Warnung zu strictNullChecks: Die schnellste Lösung für „possibly undefined“ ist die Non-Null-Assertion !. Ein paar davon sind in Ordnung; Dutzende bedeuten, dass der Agent das Problem versteckt. Verlange stattdessen eine Prüfung, einen Standardwert oder eine Typänderung und behandle neue ! im Review wie neue any.

Schritt 8: die Arbeit auf parallele Agenten verteilen

Eine Migration ist eine der wenigen Aufgaben, bei denen sich mehrere Agenten gleichzeitig wirklich lohnen, weil Ordner weitgehend unabhängig sind. Damit es funktioniert, teilst du nach Verzeichnissen auf und gibst jedem Agenten einen eigenen Git-Worktree:

git worktree add ../app-ts-billing -b ts/billing
git worktree add ../app-ts-orders  -b ts/orders
git worktree add ../app-ts-users   -b ts/users

Starte in jedem Ordner einen Agenten mit dem Schritt-Prompt von oben, ausgerichtet auf sein Verzeichnis. Ein paar Regeln verhindern, dass die Branches kollidieren:

• Gemeinsame Dateien haben einen Besitzer. tsconfig.json, package.json, die Lockfile, eslint.config.js und gemeinsame Deklarationen in src/types/ ändern sich nur auf dem Haupt-Branch, durch dich oder einen koordinierenden Agenten. Ordner-Agenten fordern Änderungen dort an, statt sie selbst zu machen.
• Gemeinsame Typen kommen zuerst. Brauchen mehrere Ordner denselben User- oder Order-Typ, mach daraus einen sequenziellen Schritt, bevor die parallelen beginnen. Sonst schreiben drei Agenten drei leicht unterschiedliche User-Interfaces.
• @types-Pakete zentral installieren. Zwei Branches, die jeweils ein anderes Paket hinzufügen, schreiben die Lockfile um und geraten jedes Mal in Konflikt.
• Einen Zyklus nicht parallelisieren. Ordner, die sich im Kreis importieren, gehören zu einem Agenten.
• Einen Branch nach dem anderen mergen und nach jedem Merge typprüfen. Zwei Branches können jeweils tsc bestehen und zusammen fehlschlagen, etwa wenn einer einen exportierten Typ ändert, auf den der andere angewiesen ist. Rebase den nächsten Branch auf das neue main, bevor du ihn mergst.

Git-Worktrees für parallele Agenten behandelt Einrichtung und Aufräumen im Detail. Drei oder vier Agenten sind ein vernünftiger Start; darüber hinaus wird meist das Reviewen der Branches zum Engpass, nicht das Schreiben.

Schritt 9: die Tests beweisen lassen, dass sich nichts geändert hat

Typen sagen dir, dass der Code in sich stimmig ist. Nur Tests sagen dir, dass er noch tut, was er getan hat. Während einer Migration:

• Führe nach jedem Schritt die ganze Suite aus, nicht nur die Tests des konvertierten Ordners. Ein geänderter Export kann einen Aufrufer anderswo kaputt machen.
• Konvertiere Testdateien nach dem Code, den sie testen, in einem eigenen Schritt, und ändere beim Konvertieren keine Assertions. Ein Test, dessen erwarteter Wert sich in einem „reinen Typ-Commit“ geändert hat, ist ein Warnsignal.
• Prüfe, ob der Test-Runner mit .ts umgehen kann. Vitest führt TypeScript-Dateien ohne zusätzliche Einrichtung aus; Jest braucht einen Transform wie ts-jest oder babel-jest mit dem TypeScript-Preset.
• Ergänze Tests dort, wo Typen nicht hinreichen. Code, der Eingaben parst, mit einer API spricht oder Umgebungsvariablen liest, bekommt zur Laufzeit Daten in any-Form, egal was die Typen sagen. Ein paar Tests dort sind mehr wert als perfekte Annotationen. Unit-Tests mit KI schreiben zeigt, wie du Agenten dazu bringst, nützliche zu schreiben.

Häufige Fehler

• require in import umzuwandeln ändert die Semantik. Default-Exports, module.exports = fn und Interop unterscheiden sich zwischen CommonJS und ES-Modulen. Mach die Änderung des Modulformats zu einem eigenen Schritt oder lass sie ganz aus der Migration heraus.
• Typen, die lügen. Ein Interface, das nach einem einzigen Beispielobjekt geschrieben wurde, übersieht vielleicht Felder, die nur manchmal auftauchen. Bevorzuge Typen, die aus echten Daten oder aus dem API-Schema entstehen.
• Verhaltens-„Fixes“, versteckt in einem Typ-Commit. Aus == wird ===, ein Standardparameter kommt dazu, ein if wird umgestellt. Jede dieser Änderungen kann Verhalten ändern. Lehne sie ab und verlange einen eigenen Commit.
• Den Compiler per Konfiguration stummschalten. skipLibCheck ist in Ordnung; ein strict-Flag abzuschalten, damit ein Branch besteht, nicht. Deshalb dürfen Agenten tsconfig.json nicht bearbeiten.
• Generierte oder eingebundene Fremddateien. Schließ sie in tsconfig.json aus, statt einen Agenten sie „typisieren“ zu lassen.

So geht es in AgentVera

AgentVera führt Claude Code, Codex, Gemini CLI und andere CLI-Agenten pro Projekt nebeneinander aus, was gut zu einer Migration passt, die in viele kleine Schritte aufgeteilt ist.

• Ein Worktree pro Ordner. Erstelle im Git-Panel für jedes Verzeichnis einen Worktree und starte darin mit einem Klick einen Agenten, wenn du willst Claude Code im einen Ordner und Codex im anderen.
• Dateibesitz. Gib dem koordinierenden Agenten tsconfig.json, package.json und src/types/**. Solange er läuft, werden Bearbeitungen anderer Agenten an diesen Dateien abgelehnt, bevor sie passieren, und die Agenten werden angewiesen, stattdessen den Besitzer zu fragen; Claude-Code-Agenten stoppt ein Hook, andere CLIs bekommen die Regel in ihre Anweisungen.
• Verify. Schreib „Typprüfung besteht, Tests bestehen, keine Test-Assertion geändert“ in deine Nachricht. Wenn der Turn endet, führt ein separater Verifier, der keine Dateien bearbeiten kann, die freigegebenen Testbefehle aus, liest den Diff und markiert jedes Kriterium mit Beleg als bestanden oder nicht bestanden.
• Code-Review. Ein zweites Modell liest jeden abgeschlossenen Turn und listet Befunde mit Datei:Zeile auf, ein guter Ort, um neue Casts und !-Assertions abzufangen.
• Merge Queue. Ordner-Branches landen einzeln auf dem neuesten main, und dein Prüfbefehl, etwa npm run typecheck && npm test, läuft auf dem gemergten Ergebnis, bevor irgendetwas gemergt wird.
• Parallel Team (Pro und Team). Ein Agent kann die Migration in bis zu acht Teile zerlegen, jeweils mit den Dateien, die der Teil anfassen darf, jeden Teil in einem eigenen Worktree ausführen, die fertigen Teile in einen Integrations-Branch mergen und die abschließende Prüfung ausführen, sodass du einen einzigen Pull Request reviewst.

Fazit

JavaScript mit KI zu TypeScript zu migrieren funktioniert, wenn Compiler und Tests das Sagen haben, nicht die Selbstsicherheit des Agenten. Starte mit einer Konfiguration, die JavaScript akzeptiert und bewusst strict: false setzt, konvertiere Blätter zuerst in kleinen Schritten, halte any in einem Budget, das nur schrumpft, mach tsc zur Abschlussprüfung des Agenten, fahre die Strictness Flag für Flag hoch und teile parallele Arbeit nach Verzeichnissen auf, wobei gemeinsame Dateien einem Agenten gehören. Jeder Schritt ist langweilig und reviewbar, und genau das willst du von einer Migration.

Wenn du die Agenten während der Migration Schritt für Schritt begleitest, erklärt Pair Programming mit KI, wann du den Agenten fahren lässt und wann du jeden Schritt reviewst.