Magento-Fehleranalyse mit Claude beschleunigen

1. Warum Magento-Fehleranalyse zeitintensiv ist

Magentos Architektur aus Plugins, Observern, Layout-XML und Dependency Injection macht Stack Traces häufig lang und schwer lesbar. Ein einzelner Fehler durchläuft oft mehrere around-, before- und after-Plugins verschiedener Vendoren, bevor die eigentliche Ursache sichtbar wird. Entwickler verbringen dadurch viel Zeit damit, Framework-internen Code zu lesen, der mit dem eigentlichen Problem nichts zu tun hat, nur um die eine Zeile im eigenen Modul zu finden, die den Fehler tatsächlich auslöst.

Der klassische Debugging-Zyklus, Fehler reproduzieren, Trace lesen, Vermutung aufstellen, var_dump einbauen, neu laden, Ergebnis prüfen, wiederholt sich bei einem hartnäckigen Plugin-Konflikt oft ein Dutzend Mal und kann leicht eine halbe Stunde oder mehr verschlingen. Genau in dieser Orientierungsphase, bevor überhaupt klar ist, wo man mit dem Debugging ansetzen sollte, kann eine KI-gestützte erste Einschätzung wertvolle Zeit sparen, ohne die eigentliche Verifikationsarbeit zu ersetzen.

2. Stack Traces und Exception-Logs richtig aufbereiten

Magento schreibt Exceptions standardmäßig nach var/log/exception.log, jeweils mit einer eindeutigen Report-ID, unter der zusätzliche Details abgelegt werden. Ein häufiger Fehler beim Einsatz von KI-Assistenten ist, nur die letzten paar Zeilen des Traces zu kopieren, weil sie am nächsten am eigenen Code liegen. Damit geht aber oft der Kontext verloren, der die Ursache erst erklärbar macht, etwa welcher Controller oder welches Kommando die Ausführungskette überhaupt gestartet hat.

Sinnvoller ist es, den vollständigen Trace ab der Report-ID zu extrahieren und parallel in var/log/system.log nach Einträgen mit derselben Zeitmarke zu suchen, weil dort oft zusätzliche Warnungen stehen, die im Exception-Log fehlen. Für Claude ist der erste Frame außerhalb des Magento-Kerns meist der wichtigste Anhaltspunkt, weil er zeigt, wo der eigene oder ein Drittanbieter-Code zuerst betroffen ist. Ein kleines Extraktionsskript spart hier bei wiederkehrenden Analysen viel manuelles Kopieren.

#!/usr/bin/env bash
# Extract a single exception report and correlated system.log lines
set -euo pipefail

REPORT_ID="${1:?Usage: extract-trace.sh <report-id>}"
EXC_LOG="var/log/exception.log"
SYS_LOG="var/log/system.log"

echo "== Exception report ${REPORT_ID} =="
grep -A 60 "report #${REPORT_ID}" "$EXC_LOG" | head -n 60

# Find the timestamp of the report to correlate with system.log
TS=$(grep -B 2 "report #${REPORT_ID}" "$EXC_LOG" | grep -oE '^\[[0-9-]+ [0-9:]+\]' | head -n 1)

echo
echo "== Correlated system.log entries around ${TS} =="
grep -F "${TS%]*}" "$SYS_LOG" || echo "No correlated entries found"

3. Claude als schneller erster Blick: Hypothesen statt Antworten

Claude ist auf einer sehr großen Menge an PHP- und Magento-Code trainiert und erkennt dadurch typische Fehlermuster schnell wieder, etwa eine fehlende Null-Prüfung nach einem getItemsCollection()-Aufruf oder eine Plugin-Reihenfolge, die die Ausführung eines Basisverhaltens verhindert. Diese Mustererkennung ist wertvoll für den ersten Überblick, ersetzt aber keine Kenntnis des konkreten Laufzeitzustands im untersuchten Shop.

Deshalb lohnt es sich, Claude gezielt nach mehreren nummerierten Hypothesen mit jeweiliger Eintrittswahrscheinlichkeit und einem konkreten Verifikationsschritt zu fragen, statt nach einer einzelnen Lösung. Eine Antwort wie „Wahrscheinlichste Ursache: das Plugin greift auf die Adresse zu, bevor die Quote vollständig geladen ist, prüfbar durch einen Breakpoint direkt vor dem Aufruf“ ist deutlich nützlicher als ein fertiger Codevorschlag, den man ungeprüft übernehmen könnte. Die Formulierung als Hypothese statt als Tatsache verändert, wie man mit der Antwort weiterarbeitet.

4. Praxisbeispiel: TypeError in einem Checkout-Plugin diagnostizieren

Ein reales Beispiel aus der Praxis: Nach dem Deployment eines Plugins für individuelle Versandregeln wirft der Checkout bei bestimmten Warenkörben plötzlich TypeError: Argument #1 ($item) must be of type Magento\Quote\Model\Quote\Item, null given. Der Fehler tritt nicht bei jedem Warenkorb auf, sondern nur bei asynchronen Aktualisierungen über AJAX, was die Reproduktion erschwert. Der Trace zeigt eine lange Kette aus mehreren Plugins, bevor die eigentliche Fehlerzeile im eigenen Modul erscheint.

Claude bekommt den vollständigen Trace sowie den Quellcode des Plugins vorgelegt und schlägt drei Hypothesen vor: Erstens wird das Plugin bei einer Zwischenanfrage mit noch leerer Quote ausgeführt. Zweitens sortiert eine andere Erweiterung ihr Plugin vor dem eigenen ein und ruft die Elternmethode zu früh auf. Drittens greift eine Race Condition zwischen Session-Schreibvorgang und AJAX-Request. Alle drei Hypothesen sind plausibel formuliert, aber ohne Prüfung bleibt unklar, welche tatsächlich zutrifft.

# Show the plugin code that throws the TypeError
cat -n app/code/Mironsoft/CustomShipping/Plugin/Checkout/ShippingRatePlugin.php

     1	<?php
     2	declare(strict_types=1);
     3
     4	namespace Mironsoft\CustomShipping\Plugin\Checkout;
     5
     6	use Magento\Quote\Model\Quote\Item;
     7	use Magento\Quote\Model\ShippingMethodManagement;
     8
     9	class ShippingRatePlugin
    10	{
    11	    /**
    12	     * Adjusts shipping rates for bundled items.
    13	     *
    14	     * @param ShippingMethodManagement $subject
    15	     * @param array $result
    16	     * @param int $cartId
    17	     * @return array
    18	     */
    19	    public function afterEstimateByExtendedAddress(
    20	        ShippingMethodManagement $subject,
    21	        array $result,
    22	        int $cartId
    23	    ): array {
    24	        // BUG: getItemsCollection() can be empty right after an ajax
    25	        // cart update, first() then returns null instead of an Item
    26	        /** @var Item $firstItem */
    27	        $firstItem = $subject->getQuote($cartId)->getItemsCollection()->getFirstItem();
    28	        $this->applyBundleDiscount($firstItem);
    29
    30	        return $result;
    31	    }
    32	}

5. Hypothesen verifizieren: Breakpoints, var_dump und Xdebug

Um die drei Hypothesen aus dem vorherigen Abschnitt zu prüfen, wird Xdebug aktiviert und ein Breakpoint direkt vor der Zeile mit getFirstItem() in Zeile 27 gesetzt. Beim Reproduzieren des Fehlers zeigt der Debugger, dass getItemsCollection() tatsächlich eine leere Collection zurückgibt, obwohl der Warenkorb im Frontend Artikel enthält. Damit ist die erste Hypothese bestätigt: Das Plugin wird bei einer Zwischenanfrage ausgeführt, bevor die Quote vollständig aus der Datenbank neu geladen wurde.

In Fällen, in denen ein IDE-Breakpoint wegen eines asynchronen AJAX-Requests unpraktisch ist, liefert ein gezieltes error_log() mit Zeitstempel und Quote-ID oft schneller verwertbare Daten als ein blockierender Breakpoint. Wichtig ist, nicht bei der ersten bestätigten Hypothese aufzuhören, sondern auch kurz zu prüfen, ob die anderen beiden tatsächlich ausgeschlossen sind, denn mehrere Ursachen können in seltenen Fällen gleichzeitig zum selben Symptom beitragen.

# Enable Xdebug for step debugging inside the container
bin/xdebug enable

# Reproduce the checkout error while a breakpoint is set
# at ShippingRatePlugin.php line 27 in the IDE

# Lightweight alternative when a breakpoint is impractical
# (e.g. during a fast AJAX round trip)
bin/cli "grep -n 'getItemsCollection' app/code/Mironsoft/CustomShipping/Plugin/Checkout/ShippingRatePlugin.php"

# Confirm the quote item count at the exact failure moment
bin/log exception.log | tail -n 80

6. Wo die KI-Analyse an ihre Grenzen stößt

Claude hat keinen Zugriff auf den tatsächlichen Laufzeitzustand des untersuchten Shops, keine Datenbankverbindung und keine Einsicht in Sitzungsdaten. Jede Hypothese basiert ausschließlich auf dem Text, der übergeben wurde, und auf Mustern aus dem Training. Das führt dazu, dass eine Erklärung überzeugend klingen kann, obwohl sie an der konkreten Konfiguration des Projekts vorbeigeht, etwa wenn ein individuell angepasstes Drittanbieter-Modul ein Standardverhalten überschreibt, das im Trainingsmaterial nicht vorkam.

Besonders riskant ist die stillschweigende Übernahme der ersten Erklärung, ohne sie mit dem tatsächlichen Verhalten abzugleichen, sogenannte Bestätigungsverzerrung. Wer eine plausible KI-Erklärung sofort als Wahrheit behandelt, baut den Fix auf einer ungeprüften Annahme auf und riskiert damit, das eigentliche Problem zu übersehen oder sogar einen neuen Fehler einzuführen. Auch versionsspezifisches Verhalten, etwa Änderungen zwischen Magento 2.4.7 und 2.4.8 bei der Indexer-Ausführung, kennt ein Modell nur so gut, wie es in seinen Trainingsdaten vertreten war.

7. Effektives Prompting für Fehleranalysen

Ein guter Prompt für eine Fehleranalyse enthält immer den vollständigen Stack Trace statt eines Ausschnitts, die konkrete Magento-Version, die Ausgabe von bin/magento module:status für den relevanten Bereich sowie den vollständigen Quellcode der Klasse, in der der Fehler auftritt. Fehlt dieser Kontext, füllt das Modell die Lücken mit den wahrscheinlichsten Annahmen, was in einem individuell angepassten Projekt schnell in die falsche Richtung führt.

Ebenso wichtig ist die Formulierung der Frage selbst. Statt „Behebe diesen Fehler“ liefert eine Bitte um mehrere geordnete Hypothesen mit jeweiligem Verifikationsschritt deutlich brauchbarere Ergebnisse, weil sie zum Nachprüfen einlädt statt zu einer einzigen, möglicherweise falschen Antwort zu verleiten. Suggestivfragen wie „Ist das ein Problem mit dem Session-Handling?“ sollten vermieden werden, weil sie das Modell in eine vorgegebene Richtung lenken, statt eine unvoreingenommene Einschätzung zu liefern.

8. Log-Auszüge systematisch vorbereiten und automatisieren

Wer regelmäßig Fehler mit Claude analysiert, profitiert von einer kleinen Automatisierung, die den relevanten Trace, den Codeausschnitt und die Projektmetadaten zu einem strukturierten Kontextpaket zusammenfasst. Ein solches Paket lässt sich als JSON-Struktur ablegen und entweder manuell in den Chat einfügen oder über ein Skript direkt an die Claude API übergeben, was besonders bei wiederkehrenden Analysen während der Entwicklung Zeit spart.

Wichtig ist, dass ein solches Skript nur die Aufbereitung übernimmt, nicht die Entscheidung. Die eigentliche Bewertung der Hypothesen und die Verifikation im Code bleiben weiterhin Aufgabe des Entwicklers. Die Automatisierung reduziert lediglich den manuellen Aufwand des Kopierens und Formatierens, der bei jedem neuen Fehler sonst erneut anfällt.

{
  "error_context": {
    "magento_version": "2.4.8-p4",
    "report_id": "a1b2c3d4",
    "stack_trace": "TypeError: Argument #1 ($item) must be of type Magento\\Quote\\Model\\Quote\\Item, null given, called in vendor/magento/module-quote/Model/ShippingMethodManagement.php on line 118",
    "affected_file": "app/code/Mironsoft/CustomShipping/Plugin/Checkout/ShippingRatePlugin.php",
    "affected_line": 26,
    "reproduction_steps": [
      "Add two products to cart",
      "Trigger AJAX cart update on checkout shipping step",
      "Error appears intermittently within 1-2 seconds of the update"
    ],
    "installed_modules_relevant": [
      "Mironsoft_CustomShipping",
      "Magento_Quote",
      "Magento_Checkout"
    ]
  },
  "request": "List ranked hypotheses with a concrete verification step for each"
}

#!/usr/bin/env python3
# Bundle a Magento exception report and send it to Claude for triage
import json
import subprocess
import anthropic

def extract_report(report_id: str) -> str:
    result = subprocess.run(
        ["bin/log", "exception.log"],
        capture_output=True, text=True, check=True
    )
    lines = result.stdout.splitlines()
    start = next(i for i, line in enumerate(lines) if report_id in line)
    return "\n".join(lines[start:start + 60])

def ask_claude(context: dict) -> str:
    client = anthropic.Anthropic()
    message = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{
            "role": "user",
            "content": (
                "Given this Magento error context, list ranked hypotheses "
                "with a concrete verification step for each:\n\n"
                + json.dumps(context, indent=2)
            )
        }]
    )
    return message.content[0].text

if __name__ == "__main__":
    trace = extract_report("a1b2c3d4")
    context = {"magento_version": "2.4.8-p4", "stack_trace": trace}
    print(ask_claude(context))

9. Naive vs. strukturierte Nutzung im Vergleich

Der Unterschied zwischen einer schnellen, oberflächlichen Nutzung von Claude bei der Fehleranalyse und einer strukturierten Herangehensweise zeigt sich vor allem darin, wie viel Kontext übergeben wird und was mit der Antwort anschließend geschieht. Die folgende Übersicht stellt beide Vorgehensweisen für die typischen Arbeitsschritte gegenüber.

Auffällig ist, dass keiner der empfohlenen Schritte einen zusätzlichen Werkzeugkauf voraussetzt. Es geht ausschließlich darum, denselben Aufwand, der ohnehin für eine gründliche Fehleranalyse nötig wäre, gezielter einzusetzen und die KI-Antwort an der richtigen Stelle im Prozess zu platzieren, nämlich am Anfang der Orientierung und nicht am Ende der Verifikation.

10. Zusammenfassung

Magento-Fehleranalyse mit Claude funktioniert am besten als beschleunigter erster Blick, nicht als Ersatz für echtes Debugging. Ein vollständiger Stack Trace mit Report-ID, der betroffene Codeausschnitt, die Magento-Version und die relevante Modulliste liefern Claude genug Kontext, um mehrere geordnete Hypothesen mit Verifikationsschritt vorzuschlagen. Jede dieser Hypothesen muss anschließend durch Breakpoints, var_dump oder gezielte error_log()-Ausgaben tatsächlich bestätigt werden, bevor ein Fix in Produktion geht.

Der größte Stolperstein ist nicht die Technik, sondern die Versuchung, die erste plausible Erklärung ungeprüft zu übernehmen. Wer stattdessen Claude gezielt nach mehreren Hypothesen mit Verifikationsschritt fragt und die Log-Aufbereitung für wiederkehrende Analysen automatisiert, gewinnt spürbar Zeit in der Orientierungsphase, ohne die Sorgfalt bei der eigentlichen Ursachenklärung zu opfern.

11. FAQ: Magento-Fehleranalyse mit Claude