# 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.

**Type:** Prompt  
**Tools:** Cursor, Claude Code, Codex, Windsurf  
**Stack:** Next.js, TypeScript  
**Difficulty:** medium  
**Updated:** 2026-06-08

---

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

```txt title="Main 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

```txt
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

```bash
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

```txt title="Fix 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.
```