Legacy-Code mit KI-Unterstützung verstehen

1. Warum Legacy-Code eine eigene KI-Strategie braucht

Legacy-Code in Magento-Projekten ist selten böswillig geschrieben, er ist meist unter Zeitdruck entstanden und nie wieder angefasst worden, weil er zuverlässig funktioniert hat. Ein Entwickler, der ein fremdes Modul aus dem Jahr 2017 übernimmt, steht fast immer vor derselben Situation: kein Changelog, keine Kommentare im Code, und die Kollegen, die das Modul geschrieben haben, sind längst nicht mehr im Unternehmen. Klassische Recherchewege wie git blame, die Ticket-Historie im Bugtracker oder Rückfragen im Team liefern oft nur Bruchstücke, aus denen sich das Gesamtbild nur mühsam zusammensetzen lässt.

Ein KI-Assistent wie Claude verändert diese Ausgangslage, weil er in Sekunden große Codemengen lesen, Muster erkennen und in verständlicher Sprache zusammenfassen kann, wofür ein Mensch sonst Stunden bräuchte. Das ist ein echter Zeitgewinn bei der Einarbeitung in unbekannte Module, bei Übergaben zwischen Teams und bei der Vorbereitung von Refactorings. Wichtig ist dabei von Anfang an eine klare Erwartungshaltung: Claude liest Code und erzeugt plausible Erklärungen, es hat aber keinen Zugriff auf das, was in den Köpfen der ursprünglichen Entwickler vorging. Diese Lücke lässt sich nur durch gezielte Verifikation schließen, nicht durch bessere Prompts allein.

2. Was Claude bei der Codeanalyse leisten kann und wo die Grenzen liegen

Claude ist stark darin, strukturelle Fragen an Code zu beantworten: Welche Klassen hängen von welchen ab, welche Events werden wo registriert, welche öffentlichen Methoden werden aus anderen Modulen heraus aufgerufen. Solche Fragen lassen sich direkt aus dem Quellcode beantworten, ohne zusätzliches Wissen über die Geschichte des Projekts. Bei Magento-Modulen mit ihrer klaren Struktur aus Observer, Plugin, Repository und Layout-XML liefert Claude hier zuverlässig brauchbare erste Antworten, die sich schnell gegen die Datei selbst prüfen lassen.

Schwieriger wird es bei Fragen nach Absicht und Kontext, etwa warum ein Grenzwert genau bei 500 Euro liegt oder warum eine Berechnung an dieser und nicht an einer anderen Stelle im Code passiert. Solche Antworten sind Interpretationen auf Basis von Namenskonventionen, Kommentaren und typischen Mustern aus Millionen Codebasen, mit denen das Modell trainiert wurde, keine gesicherten Fakten über dieses eine Projekt. Claude formuliert solche Vermutungen oft mit derselben Sicherheit wie belegte Fakten, was sie auf den ersten Blick überzeugender wirken lässt, als sie tatsächlich sind.

3. Ein unbekanntes Modul zusammenfassen lassen

Der pragmatischste Einstieg in ein fremdes Modul ist eine strukturierte Zusammenfassung durch Claude Code direkt im Terminal, mit Zugriff auf das tatsächliche Verzeichnis statt auf einzelne kopierte Codeschnipsel. Wichtig ist, den Kontext bewusst zu begrenzen: ein einzelnes Modulverzeichnis, keine komplette Codebasis, damit die Antwort fokussiert bleibt und nicht mit Informationen aus unbeteiligten Modulen vermischt wird. Ein expliziter Hinweis im Prompt, jede Aussage mit einer Datei- und Zeilenangabe zu belegen, verwandelt eine vage Zusammenfassung in eine prüfbare Liste von Behauptungen.

Das folgende Beispiel zeigt einen typischen Ablauf: zuerst die Dateistruktur und die Moduldeklaration sichten, dann Claude Code gezielt bitten, Zweck, Events und Abhängigkeiten zu benennen. Diese Reihenfolge ist bewusst gewählt, denn wer die Dateistruktur vorher selbst gesehen hat, erkennt sofort, wenn Claude eine Datei erwähnt, die es gar nicht gibt, oder eine wichtige Datei komplett übergeht.

# Build a compact, verifiable context bundle before asking Claude to summarize a module
cd src/app/code/Vendor/LegacyCatalog

# List all PHP files without vendor noise, sorted for a stable overview
find . -type f -name "*.php" | sort

# Show module dependencies and version from the module declaration
cat etc/module.xml

# Ask Claude Code to summarize with explicit instructions to cite file paths
claude "Read every file in this directory. Summarize what the module does, \
which events it observes, and which public methods other modules likely call. \
For every claim, name the exact file and line you base it on."

4. Eine Call-Chain durch mehrere Klassen verfolgen

Magento-Observer lösen häufig eine Kette von Aufrufen aus, die über mehrere Klassen und manchmal mehrere Module hinweg reicht, bevor sichtbar wird, was am Ende tatsächlich passiert. Claude kann diese Kette Schritt für Schritt nachzeichnen, von der Event-Registrierung in der events.xml über die execute-Methode des Observers bis zum Aufruf einer Service-Klasse, die schließlich Daten schreibt. Der entscheidende praktische Trick: Claude explizit bitten, die Kette als strukturierte Liste mit Dateipfad und Zeilennummer pro Schritt auszugeben, statt als Fließtext.

Eine strukturierte Ausgabe hat einen klaren Vorteil gegenüber einer Textzusammenfassung: Jeder Schritt lässt sich einzeln öffnen und gegen den echten Code prüfen, und Lücken werden sichtbar, wenn ein Schritt keine Datei- oder Zeilenangabe hat. Genau solche Lücken sind ein zuverlässiges Signal dafür, dass Claude an dieser Stelle eine Vermutung eingebaut hat, statt eine belegte Beobachtung. Das folgende Beispiel zeigt, wie eine solche Call-Chain-Trace für einen Observer aussehen kann, inklusive einer bewusst mit aufgenommenen unverifizierten Behauptung.

{
  "event": "sales_order_place_after",
  "trace": [
    {
      "step": 1,
      "component": "etc/events.xml",
      "claim": "Registers UpdateCustomerGroupObserver for sales_order_place_after",
      "verified_in_file": "app/code/Vendor/LegacyCatalog/etc/events.xml",
      "verified_at_line": 4
    },
    {
      "step": 2,
      "component": "Observer/UpdateCustomerGroupObserver.php",
      "claim": "execute() reads order customer_group_id and calls CustomerGroupUpdater::apply()",
      "verified_in_file": "app/code/Vendor/LegacyCatalog/Observer/UpdateCustomerGroupObserver.php",
      "verified_at_line": 27
    },
    {
      "step": 3,
      "component": "Model/CustomerGroupUpdater.php",
      "claim": "apply() writes directly to customer_entity via a raw connection, bypassing the repository",
      "verified_in_file": "app/code/Vendor/LegacyCatalog/Model/CustomerGroupUpdater.php",
      "verified_at_line": 41
    }
  ],
  "unverified_claims": [
    "Claude assumed this logic replaced a former Magento 1 observer, no source found for this"
  ]
}

5. Warum-Fragen: Undokumentierten Code historisch einordnen

Die schwierigste, aber oft wertvollste Frage an Legacy-Code lautet nicht "was macht dieser Code", sondern "warum existiert er in dieser Form". Claude beantwortet solche Fragen zwangsläufig auf Basis von Mustern, nicht auf Basis von Wissen über die tatsächliche Projektgeschichte, denn diese Information steht selten im Code selbst. Eine plausibel klingende Erklärung wie "das sieht nach einer Übergangslösung für ein früheres Zahlungsmodul aus" kann richtig sein, kann aber ebenso gut eine gut formulierte Vermutung ohne jede Grundlage sein.

Der zuverlässigste Weg, eine solche Vermutung zu prüfen, führt über die Git-Historie selbst, nicht über weitere Nachfragen an das Modell. Der ursprüngliche Commit, die Commit-Message, referenzierte Ticket-Nummern und das Erstellungsdatum liefern harte Fakten, die sich nicht interpretieren lassen. Ein kleines Skript, das die Git-Historie einer einzelnen Datei automatisiert ausliest, macht diesen Verifikationsschritt schnell genug, um ihn routinemäßig vor jeder Übernahme einer KI-Erklärung in die Dokumentation durchzuführen.

#!/usr/bin/env python3
"""Cross-check an AI-provided historical claim against real Git history."""
import subprocess

FILE_PATH = "app/code/Vendor/LegacyCatalog/Observer/UpdateCustomerGroupObserver.php"

def git_log_for_file(path: str) -> str:
    """Return the full commit history for a single file, oldest commit last."""
    result = subprocess.run(
        ["git", "log", "--follow", "--diff-filter=A", "--format=%H|%ad|%an|%s", "--", path],
        capture_output=True, text=True, check=True,
    )
    return result.stdout.strip()

if __name__ == "__main__":
    history = git_log_for_file(FILE_PATH)
    if not history:
        print("No creation commit found, claim about origin cannot be confirmed.")
    else:
        commit_hash, date, author, subject = history.split("\n")[-1].split("|")
        print(f"File created in {commit_hash[:8]} on {date} by {author}")
        print(f"Commit message: {subject}")
        # Compare this against Claude's claim before adding it to documentation

6. Praxisbeispiel: Eine alte Observer-Klasse untersuchen

Ein konkretes Beispiel macht den Unterschied zwischen KI-Erklärung und Verifikation greifbar. Die folgende Observer-Klasse aus einem echten Legacy-Modul reagiert auf das Event sales_order_place_after, enthält keine Kommentare, keine Tests und eine auf den ersten Blick unerklärliche Zahl im Code. Auf die Frage, was diese Klasse macht, liefert Claude typischerweise eine saubere Zusammenfassung: Bei Bestellungen über einem bestimmten Betrag wird die Kundengruppe auf eine feste ID gesetzt, vermutlich um eine Art VIP-Status abzubilden.

Diese Zusammenfassung ist bei genauem Hinsehen korrekt, was die reine Codelogik betrifft, aber die Interpretation "VIP-Status" ist eine Vermutung von Claude auf Basis der Grenzwert-Logik, nicht eine belegte Tatsache aus dem Code. Erst ein Blick in die Datenbank, ob Kundengruppe 7 tatsächlich so benannt ist, bestätigt oder widerlegt diese Interpretation zuverlässig. Diese Bestätigung dauert im Terminal wenige Sekunden, verhindert aber, dass eine falsche Annahme unbemerkt in die nächste technische Dokumentation übernommen wird.

<?php
declare(strict_types=1);

namespace Vendor\LegacyCatalog\Observer;

use Magento\Framework\Event\Observer as EventObserver;
use Magento\Framework\Event\ObserverInterface;
use Vendor\LegacyCatalog\Model\CustomerGroupUpdater;

/**
 * No PHPDoc, no comments, no tests, added in 2017 by a developer no longer at the company.
 */
class UpdateCustomerGroupObserver implements ObserverInterface
{
    private CustomerGroupUpdater $updater;

    public function __construct(CustomerGroupUpdater $updater)
    {
        $this->updater = $updater;
    }

    public function execute(EventObserver $observer)
    {
        $order = $observer->getEvent()->getOrder();
        $customerId = $order->getCustomerId();

        if (!$customerId) {
            return;
        }

        // Magic number 7 not explained anywhere in the codebase
        if ((float) $order->getGrandTotal() > 500) {
            $this->updater->apply((int) $customerId, 7);
        }
    }
}

7. KI-Erklärungen verifizieren statt blind vertrauen

Verifikation bedeutet nicht, jede einzelne Zeile einer KI-Antwort erneut manuell zu lesen, das würde den Zeitgewinn wieder zunichtemachen. Sinnvoll ist eine gestufte Prüfung: strukturelle Aussagen wie Klassenabhängigkeiten und Methodenaufrufe lassen sich mit einem gezielten grep oder einer IDE-Suche in Sekunden bestätigen, weil sie direkt im Code stehen. Interpretationen wie Geschäftsbedeutung, historischer Kontext oder vermutete Zusammenhänge zu anderen Systemen brauchen dagegen einen zweiten, unabhängigen Beleg, etwa aus der Datenbank, der Git-Historie oder einem bestehenden Test.

Ein praktikables Muster für Teams: Jede KI-generierte Erklärung, die in eine Doku, ein Ticket oder eine Entscheidung einfließt, bekommt vor der Übernahme mindestens eine unabhängige Bestätigung. Für kritischen Code, etwa alles, was Zahlungen, Kundendaten oder Preisberechnung betrifft, ist diese Prüfung nicht optional. Das folgende Beispiel zeigt drei schnelle Verifikationsschritte für die Observer-Klasse aus dem vorherigen Abschnitt, die zusammen wenige Minuten dauern und die zentrale Behauptung von Claude entweder bestätigen oder widerlegen.

# Verify Claude's claim that group ID 7 means "VIP customer" before trusting it
bin/mysql -e "SELECT customer_group_id, customer_group_code FROM customer_group WHERE customer_group_id = 7;"

# Confirm the observer is actually registered for the claimed event, not just referenced elsewhere
grep -rn "UpdateCustomerGroupObserver" src/app/code/Vendor/LegacyCatalog/etc/

# Run existing tests, if any, to see whether behavior matches the AI's description
bin/cli vendor/bin/phpunit --filter UpdateCustomerGroupObserverTest

8. Typische Fehlerquellen und Grenzen der KI-Codeanalyse

Die häufigste Fehlerquelle ist nicht eine offensichtlich falsche Antwort, sondern eine überzeugend formulierte, die auf einer unvollständigen Betrachtung des Codes beruht. Wenn ein Modul auf ein anderes Modul verweist, das nicht im geladenen Kontext enthalten war, füllt Claude die Lücke mit einer plausiblen Annahme, ohne das notwendigerweise explizit zu kennzeichnen. Gerade bei Magento-Projekten mit vielen ineinandergreifenden Modulen und Dependency Injection über Konfigurationsdateien ist diese Lücke leicht zu übersehen, weil die tatsächliche Klasse erst über einen Preference oder ein Plugin ausgetauscht wird.

Eine zweite Grenze betrifft veraltete oder mehrdeutige Magento-Konventionen: Ältere Module nutzen teils Muster aus Magento 1 oder frühen Magento-2-Versionen, die Claude mit aktuellen Best Practices verwechseln oder unbewusst vermischen kann. Eine dritte, oft übersehene Grenze ist Selbstbewusstsein in der Formulierung: Claude drückt eine begründete Vermutung sprachlich selten anders aus als eine belegte Tatsache, wenn nicht ausdrücklich danach gefragt wird. Der Prompt-Zusatz, unsichere Aussagen explizit als Vermutung zu kennzeichnen, reduziert dieses Risiko spürbar, ersetzt aber die eigene Prüfung nicht.

9. Legacy-Code-Analyse in den Entwickler-Workflow integrieren

KI-gestützte Legacy-Code-Analyse entfaltet ihren Wert erst, wenn sie ein fester, aber klar begrenzter Teil des bestehenden Workflows wird, statt eine gelegentliche Ad-hoc-Aktivität zu bleiben. Sinnvoll ist, Claude-generierte Zusammenfassungen immer mit einem Verifikationsstatus zu versehen, bevor sie in Confluence, ein Ticket oder einen Pull-Request-Kommentar wandern, damit spätere Leser erkennen, was geprüft wurde und was nicht. Für wiederkehrende Aufgaben wie die Einarbeitung neuer Teammitglieder lohnt sich ein festes Prompt-Template mit expliziter Aufforderung zur Quellenangabe, statt bei jeder Anfrage neu zu formulieren.

Die folgende Übersicht stellt unsicheren und empfohlenen Umgang mit KI-Erklärungen zu Legacy-Code gegenüber. Der Unterschied liegt fast nie in der Qualität der Antwort von Claude selbst, sondern darin, was ein Team mit dieser Antwort anschließend tut, bevor sie in dauerhafte Artefakte wie Dokumentation oder Architekturentscheidungen einfließt.

In der Praxis reicht diese eine Gewohnheit, jede Übernahme mit einer kurzen Prüfung zu verknüpfen, um die meisten Fehlinterpretationen abzufangen, bevor sie andere Entwickler in die Irre führen.

10. Zusammenfassung

Legacy-Code mit KI-Unterstützung zu verstehen funktioniert am besten als zweistufiger Prozess: Claude liefert schnell eine erste, meist strukturell korrekte Zusammenfassung von Modulen, Abhängigkeiten und Call-Chains, und ein Entwickler verifiziert anschließend gezielt die Aussagen, die über reine Code-Struktur hinausgehen. Strukturelle Fragen wie Klassenabhängigkeiten oder Event-Registrierungen lassen sich fast immer direkt im Code bestätigen. Interpretationen zu Geschäftslogik, historischem Kontext oder Absicht brauchen dagegen einen zweiten, unabhängigen Beleg aus Git-Historie, Datenbank oder bestehenden Tests, bevor sie in Dokumentation oder Entscheidungen einfließen.

Der entscheidende Unterschied zwischen produktivem und riskantem Einsatz liegt selten in der Qualität der KI-Antwort selbst, sondern in der Disziplin, mit der ein Team Verifikation zur festen Gewohnheit macht. Ein Prompt-Template mit expliziter Aufforderung zur Quellenangabe, ein kurzer Verifikationsschritt vor jeder Übernahme in Doku oder Ticket und besondere Vorsicht bei kritischem Code wie Zahlungen oder Kundendaten reichen aus, um die meisten Fehlinterpretationen frühzeitig abzufangen.

11. FAQ: Legacy-Code mit KI-Unterstützung verstehen