Prompt zum sicheren Refactoring einer React-Komponente

Strukturierter KI-Agent-Prompt zum Refactoring einer komplexen React-Komponente mit einem Lese-Audit-Refactor-Verify-Zyklus, der Regressionen verhindert.

Verwenden Sie diesen Prompt, um ein diszipliniertes Refactoring der Komponente durchzuführen – der Agent prüft (audit), bevor er Änderungen vornimmt, extrahiert Unterkomponenten einzeln und überprüft nach jedem Schritt die Typen, anstatt die gesamte Datei auf einmal neu zu schreiben.

Haupt-Prompt

You are refactoring a React component in a Next.js App Router TypeScript project.
The target file is: [INSERT PATH, e.g. src/components/ProductCard.tsx]

Refactor goal: split a large monolithic component into smaller, reusable pieces without
changing any observable behavior or UI output.

Follow these phases exactly — do not skip or combine them.

Phase 1 — Audit (no changes):
  - List every `useState` and `useEffect` call and what it manages.
  - List every prop the component accepts (with types).
  - List any inline sub-sections that could be extracted (e.g., a header, a list, a footer).
  - Identify any duplicated logic (e.g., the same conditional repeated).
  Output the audit as a numbered list. Stop and wait for my review.

Phase 2 — Extract pure sub-components (one at a time):
  - For each extractable section identified: create a new file, move the JSX and its
    required props, export a typed interface for the props, import and use it in the parent.
  - After each extraction: run `bun run typecheck`. If it fails, fix the error before
    the next extraction.

Phase 3 — Extract custom hooks:
  - If any `useEffect` + `useState` pair manages a single concern (e.g., a data fetch,
    a keyboard listener), extract it to `src/hooks/use<Name>.ts`.
  - After each extraction: run `bun run typecheck`.

Phase 4 — Remove duplication:
  - Consolidate any repeated conditional logic into a shared helper.
  - Do NOT change the logic — only the structure.

Phase 5 — Final verify:
  - Run `bun run typecheck`.
  - Show a summary of all files created or edited.
  - Do NOT change any business logic, API calls, or UI output.

After each phase, show the diff and wait for my confirmation before proceeding.

Implementierungshinweise

Die wichtigste Einschränkung ist die Verhaltensbewahrung: Das Refactoring muss eine rein strukturelle Änderung sein. Bitten Sie den Agenten, dies nach jeder Phase zu bestätigen, indem er prüft, ob der Diff keine Logikänderungen enthält.
TypeScript ist hier das Sicherheitsnetz: Das Ausführen von typecheck nach jeder Extraktion erkennt sofort fehlende Props oder falsche Type Narrowing.
Die Extraktion von benutzerdefinierten Hooks ist nur sicher, wenn der Zustand des Hooks auf eine einzelne Komponenteninstanz beschränkt ist. Wenn der Zustand geteilt werden muss, extrahieren Sie nicht – notieren Sie es und stoppen Sie.

Erwartete Dateiänderungen

src/components/<name>.tsx            (edited — original component, slimmed down)
src/components/<name>Header.tsx      (new — extracted sub-component)
src/components/<name>List.tsx        (new — extracted sub-component)
src/hooks/use<name>.ts               (new — extracted hook, if applicable)

Akzeptanzkriterien

bun run typecheck beendet sich nach jeder Phase mit Exit-Code 0.
Das Props-Interface der übergeordneten Komponente bleibt unverändert.
Es werden keine any-Typen eingeführt.
Die UI-Ausgabe ist vor und nach dem Refactoring pixelgenau (überprüft durch visuelle Inspektion oder Snapshot-Tests).

Testbefehle

bun run typecheck
bun run build
# if snapshot tests exist:
bun test --update-snapshots   # run BEFORE refactor to capture baseline
# then after refactor:
bun test                       # snapshots should pass without update

Häufige KI-Fehler

Ändern des Verhaltens eines Callbacks beim Extrahieren in eine Unterkomponente (z. B. Hinzufügen von useCallback mit falschen Abhängigkeiten, wodurch sich der Ausführungszeitpunkt stillschweigend ändert).
Extrahieren eines Hooks, der einen von mehreren Komponenteninstanzen gemeinsam genutzten Zustand hält, was zu Zustandsverlust führt.
Einführen von any-Typen bei den Props der extrahierten Komponente, um die Auflösung komplexer Generics zu vermeiden.
Überspringen von typecheck zwischen den Phasen, wodurch sich Fehler ansammeln, die schwer nachvollziehbar sind.

Korrektur-Prompt

A type error appeared after an extraction or behavior changed. Fix in order:
1. Run `bun run typecheck` and show me only the errors — do not fix anything yet.
2. For each error: if it is a missing prop, add it to the extracted component's props interface.
   If it is an `any` type, resolve it using the type from the parent component's existing interface.
3. If any logic changed (a conditional, an effect dependency, a callback), revert that specific
   change only. Show the revert diff before applying it.