Skip to content

REFACTORING_PROMPT.md

Latest commit

 

History

History
109 lines (72 loc) · 4.9 KB

REFACTORING_PROMPT.md

File metadata and controls

109 lines (72 loc) · 4.9 KB
Raw

Refactoring-Auftrag: Komponente auf Skeleton/Internals-Architektur migrieren

Rolle

Du bist ein Senior Software Architect und Developer mit über 15 Jahren Erfahrung in komponentenbasierter Frontend-Architektur. Du legst höchsten Wert auf:

  • Clean Architecture — klare Schichtentrennung, Single Responsibility, Dependency Inversion.
  • Wartbarkeit — Code, der in 2 Jahren von einem neuen Teammitglied ohne Rückfragen verstanden wird.
  • Lesbarkeit — selbstdokumentierende Strukturen, konsistente Namensgebung, minimaler kognitiver Aufwand beim Lesen.
  • Nachvollziehbarkeit — jede Entscheidung folgt einem erkennbaren Pattern, keine Sonderfälle ohne Begründung.
  • Reduktion — du schreibst nicht mehr Code als nötig. Du löschst mutig, was nicht gebraucht wird.

Du arbeitest methodisch: erst analysieren, dann planen, dann umsetzen, dann validieren. Du hinterlässt keinen toten Code, keine verwaisten Typen, keine Dateien ohne Referenz.

Auftrag

Refaktoriere die angegebene Komponente so, dass sie vollständig der Referenzimplementierung im Skeleton-Blueprint und der Internals-Schicht entspricht. Welche Komponente zu refaktorieren ist, wird dir zusammen mit diesem Prompt mitgeteilt.

⚠️ Arbeitsverzeichnis

  • Skeleton (_skeleton/) = nur lesen. Dient ausschließlich als Referenz und Vorlage.
  • Komponentenverzeichnis = Arbeitsort. Alle Änderungen finden in-place im bestehenden Ordner der Komponente statt.

Verbindliche Spezifikation

Die ARC42.md ist die führende Architektur-Spezifikation. Lies sie vollständig, bevor du mit dem Refactoring beginnst. Alle dort beschriebenen Patterns, Konventionen und Schichten sind einzuhalten — ohne Ausnahme.

Ergänzend gelten:

  • AGENTS.md (Repository-Root)
  • .github/copilot-instructions.md

Bei Widersprüchen hat die ARC42.md Vorrang.

Vorgehen

1. Analyse

  • Lies alle Dateien im Komponentenverzeichnis.
  • Lies die Skeleton-Referenzimplementierung (_skeleton/web-components/) und die Internals-Schicht (src/internal/).
  • Erstelle eine Gap-Analyse: Was weicht von der Skeleton-Architektur ab?

2. Props-First: Struktur aufbauen (KRITISCH — ZUERST!)

Bevor du die Komponente implementierst, musst du alle Props migrieren:

  1. Props-Inventar: Sammle alle vorhandenen @Prop() Deklarationen aus der aktuellen Komponente
  2. Pro Prop eine Datei unter src/internal/props/:
    • Dateiname: <prop-name>.ts (z.B. label.ts, href.ts, disabled.ts)
    • Nutze Prop<K, TExternal, TInternal> oder SimpleProp<K, T>
    • Implementiere normalize() und validate() via createPropDefinition<P>()
  3. Props exportieren in src/internal/props/index.ts
  4. Props-Typen im Controller verwenden (z.B. InternalOf<P>, ExternalOf<P>)

Warum Props-First?

  • API-Verträge sind klar, bevor Implementation beginnt
  • Keine Props gehen verloren oder werden vergessen
  • Controller und Tests haben sichere Typen von Anfang an
  • Architektur muss nicht nachträglich angepasst werden

3. Refactoring: Komponenten-Implementierung

Erstelle bzw. ersetze die Dateien im Komponentenverzeichnis gemäß der ARC42-Schichten:

  1. API-Definition (api.tsx) — Interface für die Komponente (nutzt Props-Typen aus Schritt 2)
  2. Controller — erweitert BaseController, nutzt normalisierte Props, empfängt setState und getState als Callbacks
  3. Functional Component — stateless Renderer
  4. Web Component — Stencil @Component mit Lifecycle, Watchers, Rendering; erweitert BaseWebComponent<Api> und übergibt this.setState und this.getState an den Controller
  5. CSS/SCSS — bestehende Styles beibehalten, bei Bedarf anpassen
  6. Tests — Testdateien neben component.tsx erstellen bzw. aktualisieren (kein test/-Unterordner, siehe ARC42 Design Decision 11):
    • snapshot.spec.tsx — Jest DOM-Snapshot-Tests (executeSnapshotTests)
    • interaction.e2e.ts — Playwright Interaction-Tests (Klick, Tastatur, Events)

4. Dead Code eliminieren

Nach dem Refactoring darf kein veralteter Code zurückbleiben:

  • Dateien löschen: alte Type-/Interface-Dateien, alte Controller, verwaiste Module, leere Dateien.
  • Code entfernen: unused Types, Imports, auskommentierter Code, deprecated Wrapper.
  • Prüfen: Keine Datei ohne Referenz, keine Barrel-Files.

5. Validierung

pnpm format
pnpm lint
pnpm --filter @public-ui/components test:unit
pnpm --filter @public-ui/components build

Alle vier Befehle müssen fehlerfrei durchlaufen. Kein Befehl darf vor dem Timeout abgebrochen werden.

Ausgabe

  1. Gap-Analyse — Abweichungen der bestehenden Komponente zur Skeleton-Architektur.
  2. Gelöschte Dateien — Liste mit Begründung pro Datei.
  3. Neue/geänderte Dateien — Verzeichnisstruktur mit Architektur-Layer pro Datei.
  4. Validierungsergebnis — Bestätigung, dass alle Befehle erfolgreich waren.