Migration weg von einer veralteten Library

Library-Migrationen sind perfekte Arbeit für KI-Agenten. Sie sind mechanisch, präzise definiert und ermüdend - genau die Kombination, die Menschen ausbrennt und zu inkonsistenten Ergebnissen führt. Dieser Guide beschreibt das vollständige Playbook für die Migration einer veralteten Library in einer echten Codebase per Sprint Chain. Rechnen Sie mit mehreren Tagen Laufzeit. Das ist normal und gut.

1. Die Migration vor dem Start kartieren

Bevor ein Agent ins Spiel kommt, schreiben Sie die Migration in menschenlesbarer Form auf. Sie brauchen ein einseitiges Dokument, das jede Quell-API und ihr Ziel-Äquivalent auflistet, Edge Cases markiert, die manuell behandelt werden müssen, und einen Smoke-Test pro migriertem Modul definiert.

Dieses Dokument wird zur Source-of-Truth für jeden Agentenlauf. Ohne es improvisiert der Agent - und Improvisation über 200 Dateien produziert subtile Verhaltens-Regressionen.

2. Surface Area kartieren

Starten Sie eine einzelne Discovery-Issue-Session mit einer Researcher-Persona auf der Codebase. Ihre Aufgabe ist read-only: ein strukturierter Report jeder Datei, die die veraltete Library importiert, gruppiert nach Nutzungsmuster.

task: Verwendung von `legacy-http` im Monorepo erheben.
output:
  - Dateien nach Nutzungsmuster gruppieren (basic GET, streaming, auth-wrapped, etc.).
  - Pro Muster Vorkommen zählen und eine repräsentative Datei nennen.
  - Ungewöhnliche oder einmalige Verwendungen markieren.

Diesen Report speichern. Er ist Input für Ihre Sprint Chain.

3. Eine Migrations-Persona bauen

Klonen Sie das Senior-Engineer-Template und schreiben Sie eine Persona, deren gesamte Aufgabe diese eine Migration ist. Der System-Prompt bettet Ihr Mapping-Dokument wörtlich ein. Verbinden Sie sie mit einem Coder-Toolset, das pnpm test ausführen kann, damit die Persona unterwegs validiert.

Setzen Sie einen strengen Judge: Jeder PR muss exakt dem Mapping-Dokument entsprechen; Abweichungen werden abgelehnt. Mechanische Arbeit verlangt mechanisches Review.

4. Sprint Chain komponieren

Eine Sprint Chain führt eine Folge von Issue Sessions in Reihenfolge aus - optional parallel, mit geteiltem Kontext zwischen Läufen. Für diese Migration wollen Sie eine Session pro Nutzungsmuster aus dem Discovery-Report. Kleine Dateien in einer Session gruppieren, komplexe Verwendungen isolieren.

• Session 1: Basic-GET-Verwendung in allen Dateien dieser Gruppe migrieren. Ein PR.
• Session 2: Streaming-Verwendung migrieren. Ein PR.
• Session 3: Auth-wrapped-Verwendung migrieren. Ein PR.
• Session N: Long Tail einzeln abarbeiten.

Ein PR pro Muster. Nicht ein PR pro Datei, nicht ein PR für die gesamte Migration. PRs in Mustergröße sind reviewable; die anderen Größen nicht.

5. Chain auf dem kleinsten Repo zuerst laufen lassen

Suchen Sie Ihr kleinstes Repo und lassen Sie die volle Chain dort laufen. Behandeln Sie es als Generalprobe. Beobachten Sie jeden PR, mergen oder überarbeiten Sie ihn selbst, und erklären Sie die Chain erst dann als reif, wenn das kleinste Repo vollständig migriert ist und CI auf main grün ist.

Die meisten Teams entdecken hier ein oder zwei Edge Cases. Aktualisieren Sie das Mapping-Dokument, lassen Sie die betroffenen Sessions erneut laufen - und erst dann zum nächsten Repo.

6. Auf die restliche Flotte ausrollen

Sobald die Chain stabil ist, lassen Sie sie über die restlichen Repos parallel laufen - CodeCourier handhabt die Concurrency, Ihre CI handhabt die Last. Sie bekommen eine Welle von Pull Requests. Reviewen Sie sie in Repo-Batches, nicht chronologisch; das wahrt Ihr mentales Modell jeder Codebase.

7. Den Deprecation-Termin tracken

Legen Sie einen Recurring Task an, der jeden Montagmorgen einen Grep nach der veralteten Library laufen lässt und einen Count pro Repo emittiert. Wenn der Count flottenweit auf null fällt, archivieren Sie Persona und Chain unter einem klaren Namen wie legacy-http-deprecation-2026-q2-complete. Migrationen sind erst fertig, wenn Sie den Nachweis haben.

8. Nächste Schritte

Operate CodeCourier in production ist die natürliche Folgelektüre - das Operations-Handbuch deckt RBAC, Budgets und Alerting ab, die zählen, sobald mehrtägige Chains unbeaufsichtigt laufen.