Claude Code bei CI-Fehlern: Prompt-Vorlagen für kleine Fixes und Tests

Was schiefläuft, wenn CI fehlschlägt und AI rät

Ein CI‑Fehler ist normalerweise nicht mysteriös. Das Log sagt dir, wo es aufgehört hat, welcher Befehl fehlgeschlagen ist und die Fehlermeldung. Ein guter Run enthält einen Stacktrace, einen Compiler‑Fehler mit Datei und Zeilennummer oder einen Testbericht, der zeigt, welche Assertion fehlgeschlagen ist. Manchmal bekommst du sogar einen diff‑artigen Hinweis wie "expected X, got Y" oder einen klaren fehlschlagenden Schritt wie "lint", "build" oder "migrate database".

Das eigentliche Problem ist, dass Menschen (und AI) das Log oft als Hintergrundgeräusch behandeln. Wenn du ein langes Log einfügst und um "einen Fix" bittest, springen viele Modelle zu einer vertrauten Erklärung statt die letzten sinnvollen Zeilen zu lesen. Das Raten verschlimmert sich, wenn der Fehler vertraut aussieht ("module not found", "timeout", "permission denied"). Am Ende hast du ein großes Rewrite, eine neue Dependency oder den Rat "versuche alles zu aktualisieren", der nicht zum eigentlichen Fehler passt.

Das Ziel ist nicht "mach es irgendwie grün". Es ist einfacher:

• Lies die fehlgeschlagene Ausgabe.
• Identifiziere die kleinstmögliche Änderung, die den fehlschlagenden Schritt erfolgreich macht.
• Lass sonst alles unverändert.

In der Praxis ist der „kleinstmögliche Fix“ meist eines der folgenden: eine wenige‑Zeilen‑Codeänderung an einer Stelle, ein fehlender Import oder falscher Pfad, ein Konfigurationswert, der für die CI‑Umgebung offensichtlich falsch ist, oder das Zurücknehmen einer versehentlichen Breaking‑Änderung statt einem Redesign.

Ein nachfolgender Test ist ebenfalls wichtig. CI einmal grün zu bekommen ist nicht dasselbe wie Wiederholungen zu verhindern. Kam der Fehler von einem Edge‑Case (null‑Input, Zeitzone, Rundung, Berechtigungen), füge einen Regressions‑Test hinzu, der vor dem Fix fehlschlägt und danach besteht. Das macht aus einer einmaligen Rettung eine Schutzvorrichtung.

Was du sammeln solltest, bevor du um Hilfe bittest

Die meisten schlechten Fixes beginnen mit fehlendem Kontext. Wenn du nur die letzte rote Zeile einfügst, muss das Modell raten, was vorher passiert ist, und Vermutungen führen oft zu Rewrites.

Ziele darauf ab, genug Details zu liefern, damit jemand den Fehler von der ersten echten Fehlermeldung bis zum Ende nachvollziehen kann und dann so wenig wie möglich ändert.

Kopiere folgendes in deine Nachricht (wörtlich, wenn möglich):

• Das vollständige fehlgeschlagene Log ab der ersten Fehlerzeile bis zum Ende (nicht nur der finale Stacktrace).
• Der exakte Befehl, den CI ausgeführt hat (zum Beispiel go test ./..., npm test, flutter test, golangci-lint run).
• Die in der Fehlermeldung genannten Dateipfade sowie relevante Konfiguration (Test‑Config, Linter‑Config, Build‑Skripte).
• Was sich kürzlich geändert hat: PR‑Diff‑Zusammenfassung, Dependency‑Bumps, CI‑Config‑Edits.
• Ob es flaky ist: zwei oder drei Fehlversuche und ein erfolgreicher Lauf, falls vorhanden.

Füge Einschränkungen in klarer Sprache hinzu. Wenn du einen winzigen Fix willst, sag es: keine Refactors, keine Verhaltensänderungen, außer wenn nötig, halte den Patch auf den fehlschlagenden Bereich beschränkt.

Ein einfaches Beispiel: CI schlägt in einem Lint‑Schritt nach einem Dependency‑Bump fehl. Füge die Lint‑Ausgabe ab der ersten Warnung ein, nenne den von CI verwendeten Befehl und erwähne die einzelne Paket‑Version, die geändert wurde. Das reicht oft aus, um eine einzeilige Config‑Anpassung oder eine kleine Code‑Änderung vorzuschlagen, statt das halbe Repo neu zu formatieren.

Wenn du etwas Copy‑Paste‑Fähiges willst, ist diese Struktur meist ausreichend:

CI command:

Failing output (full):

Recent changes:

Constraints (smallest fix, no refactor):

Flaky? (runs attached):

Prompt‑Regeln, die das Modell zwingen, die fehlerhafte Ausgabe zu lesen

Wenn ein Modell bei einem CI‑Break danebengeht, liegt es meist daran, dass dein Prompt Vermutungen zulässt. Deine Aufgabe ist es, es dazu zu bringen, seine Arbeit zu zeigen, indem es die exakte fehlerhafte Ausgabe benutzt, und sich dann auf die kleinste Änderung festzulegen, die den Job grün macht.

Regeln, die das Modell ehrlich halten

Fordere Nachweise und einen kleinen Plan. Ein guter Prompt erzwingt fünf Dinge:

• Zitiere die exakten fehlgeschlagenen Zeilen aus dem CI‑Log (Fehler, Stacktrace, Datei:Zeile) und sage explizit „Ich benutze diese Zeilen.“
• Gib eine Ein-Satz‑Diagnose, ohne zu schwanken.
• Schlage einen minimalen Patch‑Plan mit 1–3 Änderungen vor und nenne die genauen Dateien, die betroffen sind.
• Vermeide nicht‑zusammenhängende Änderungen (kein Formatieren, Umbenennen, Refactor, Dependency‑Bumps) außer du gibst die Erlaubnis.
• Liste auf, worüber es unsicher ist und das eine Detail, das die Diagnose bestätigen würde.

Unsicherheit ist ok. Versteckte Unsicherheit ist das, was Zeit kostet.

Copy‑ready Prompt‑Fragment

Füge das oben in deine CI‑Frage ein:

Use ONLY the evidence in the CI output below.
1) Quote the exact failing lines you are using.
2) Give ONE sentence: the most likely cause.
3) Propose the smallest fix: 1-3 edits, with file paths.
4) Do NOT do formatting/renames/refactors or "cleanup".
5) List uncertainties + the one extra detail that would confirm the diagnosis.

Wenn das Log zum Beispiel „expected 200, got 500" plus einen Stacktrace nach user_service.go:142 sagt, lenkt diese Struktur die Antwort auf diese Funktion und eine kleine Guard‑ oder Error‑Handling‑Änderung, nicht auf ein Redesign des Endpunkts.

Eine Copy‑Paste‑Prompt‑Vorlage für CI‑Fehler

Die schnellsten Erfolge kommen von einem Prompt, der das Zitieren der Logs erzwingt, innerhalb der Einschränkungen bleibt und stoppt, wenn etwas fehlt.

You are helping me fix a CI failure.

Repo context (short):
- Language/framework:
- Test/build command that failed: <PASTE THE EXACT COMMAND>
- CI environment (OS, Node/Go/Python versions, etc.):

Failing output (verbatim, include the first error and 20 lines above it):
<PASTE LOG>

Constraints:
- Propose the smallest possible code change that makes CI pass.
- Do NOT rewrite/refactor unrelated code.
- Do NOT touch files you do not need for the fix.
- If behavior changes, make it explicit and justify why it is correct.

Stop rule (no guessing):
- If the log is incomplete or you need more info (missing stack trace, config, versions, failing test name), STOP and ask only the minimum questions needed.

Your response format (follow exactly):
1) Evidence: Quote the exact log lines that matter.
2) Hypothesis: Explain the most likely cause in 2-4 sentences.
3) Smallest fix: Describe the minimal change and why it addresses the evidence.
4) Patch: Provide a unified diff.
5) Follow-up: Tell me the exact command(s) to rerun locally to confirm.

Then, write ONE regression test (or tweak an existing one) that would fail before this fix and pass after it, to prevent the same failure class.
- Keep the test focused. No broad test suites.
- If a test is not feasible, explain why and propose the next-best guardrail (lint rule, type check, assertion).

Zwei Details, die Rückfragen reduzieren:

• Füge den exakten fehlschlagenden Befehl und den ersten Fehler ein (nicht nur die finale Zusammenfassung).
• Wenn mehrere Fehler vorhanden sind, sag, welchen du zuerst beheben willst (normalerweise der früheste echte Fehler im Log).

Wie du auf den kleinstmöglichen Fix drängst, nicht auf ein Rewrite

Der schnellste Weg, Zeit zu verlieren, ist, einem „Cleanup“-Patch zuzustimmen, der fünf Dinge auf einmal ändert. Definiere „minimal“ im Voraus: den kleinsten Diff, der den fehlschlagenden Job grün macht, mit dem geringsten Risiko und der schnellsten Verifikation.

Eine einfache Regel funktioniert gut: Behebe zuerst das Symptom, entscheide dann, ob ein größerer Refactor sinnvoll ist. Wenn das Log auf eine Datei, eine Funktion, einen fehlenden Import oder einen Edge‑Case zeigt, ziele genau dort. Vermeide „while we're here“-Edits.

Wenn du wirklich Alternativen brauchst, fordere zwei und nur zwei: „sicherster minimaler Fix“ vs. „schnellster minimaler Fix“. Du willst Trade‑offs, kein Menü.

Fordere außerdem lokale Verifikation, die mit CI übereinstimmt. Bitte um denselben Befehl, den die Pipeline ausführt (oder das nächstliegende Äquivalent), damit du in Minuten bestätigen kannst:

# run the same unit test target CI runs
make test
# or the exact script used in CI
npm test

Wenn die Antwort eine große Änderung vorschlägt, wehre dich mit: „Zeige den kleinsten Patch, der die fehlschlagende Assertion behebt, ohne unrelated Formatting oder Umbenennungen."

Prompting für einen Follow‑Up‑Test, der Wiederholungen verhindert

Ein Fix ohne Test ist eine Wette, dass der Fehler nicht wiederkommt. Fordere immer einen Follow‑Up‑Test, der vor dem Fix fehlschlägt und danach besteht.

Sei spezifisch, was „gut“ bedeutet:

• Wenn der Fehler ein Unit‑Test‑Crash war, willst du wahrscheinlich einen neuen Test oder eine stärkere Assertion.
• War es ein Build/Lint/Format‑Fehler, möchtest du eine Prüfung, die die Regel durchsetzt, damit derselbe Fehler nicht wieder reinkommt.

Ein nützliches Muster verlangt vier Dinge: wo der Test hinkommt, wie er heißen soll, welches Verhalten er abdeckt und 1–2 Sätze, warum er zukünftige Regressionen verhindert.

Copy‑ready Zusatz:

• Schreibe einen Regressions‑Test, der auf dem aktuellen main‑Branch fehlschlägt und nach deinem Fix besteht.
• Mache ihn zielgerichtet auf die Failure‑Klasse, nicht nur auf die exakte Codezeile.
• Platziere den Test in: <path or folder>. Benenne ihn nach: <deiner Konvention>.
• Wenn es ein Lint/Build‑Problem ist, füge eine Check/Rule hinzu oder passe sie an.
• Ergänze 2–3 Sätze: warum dieser Test ähnliche Bugs later fangen würde.

Beispiel: CI zeigt ein Panic, wenn ein API‑Handler eine leere String‑ID erhält. Frage nicht nach „einem Test für diese Zeile“. Frage nach einem Test, der ungültige IDs (leer, nur Whitespaces, falsches Format) abdeckt. Der kleinste Fix könnte eine Guard‑Clause sein, die 400 zurückgibt. Der Follow‑Up‑Test sollte Verhalten für mehrere ungültige Inputs prüfen, sodass künftige Parsing‑Refactors die CI sofort brechen würden.

Wenn dein Projekt Test‑Konventionen hat, gib sie an. Wenn nicht, bitte, die in der Nähe vorhandenen Tests zu spiegeln und halte den neuen Test minimal und lesbar.

Ein wiederverwendbarer Schritt‑für‑Schritt‑Workflow

1) Gib den Fehler so, wie er ist

Füge die CI‑Log‑Sektion ein, die den Fehler enthält und 20–40 Zeilen darüber. Füge auch den exakten Befehl ein, den CI ausgeführt hat, und wichtige Umgebungsdetails (OS, Runtime‑Versionen, wichtige Flags).

Bitte es dann, in einfachen Worten zu wiederholen, was fehlgeschlagen ist und auf welche Zeile(n) in der Ausgabe es sich stützt. Wenn es das Log nicht zitieren kann, hat es nicht wirklich gelesen.

2) Fordere zuerst den kleinsten Patch

Bitte um die kleinstmögliche Codeänderung, die den fehlschlagenden Befehl bestehen lässt. Wehre Refactors ab. Bevor du etwas anwendest, lass dir auflisten:

• Die Datei(en), die es ändern will
• Das genaue Verhalten, das sich ändert
• Was es nicht ändert

3) Führe denselben Befehl erneut aus, halte die Schleife eng

Wende den Patch an und führe lokal den exakt fehlschlagenden Befehl aus (oder denselben CI‑Job, wenn das deine einzige Option ist). Wenn es weiterhin fehlschlägt, füge nur die neue Fehlermeldung ein und wiederhole. Kleiner Kontext hält die Antwort fokussiert.

4) Füge einen Regressions‑Test für die Fehlerklasse hinzu

Sobald alles grün ist, füge einen fokussierten Test hinzu, der vorher fehlschlug und jetzt besteht. Halte ihn zielgerichtet: ein Test, ein Grund.

Führe den Befehl erneut mit dem neuen Test aus, um zu bestätigen, dass du den Fehler nicht nur unterdrückt hast.

5) Fertiges PR‑Paket

Bitte um eine kurze Commit‑Message und eine PR‑Beschreibung, die enthält, was fehlgeschlagen ist, was geändert wurde, wie du es verifiziert hast und welcher Test eine Wiederholung verhindert. Reviewer arbeiten schneller, wenn die Begründung klar ist.

Ein realistisches Beispiel: vom Fehleroutput zum Fix und Test

Ein typischer Fehler: Lokal funktioniert alles, dann macht eine kleine Änderung Tests auf dem CI‑Runner kaputt. Hier ein einfaches Beispiel aus einer Go‑API, bei dem ein Handler jetzt ein datum‑nur Format (2026-01-09) akzeptieren soll, der Code aber nur volle RFC3339‑Timestamps parst.

Das ist die Art von Snippet, die du einfügen solltest (kurz halten, aber die Fehlerzeile enthalten):

--- FAIL: TestCreateInvoice_DueDate (0.01s)
    invoice_test.go:48: expected 201, got 400
    invoice_test.go:49: response: {\"error\":\"invalid due_date: parsing time \\\"2026-01-09\\\" as \\\"2006-01-02T15:04:05Z07:00\\\": cannot parse \\\"\\\" as \\\"T\\\"\"}
FAIL
exit status 1
FAIL\tapp/api\t0.243s

Verwende dann einen Prompt, der Beweise, einen minimalen Fix und einen Test erzwingt:

You are fixing a CI failure. You MUST use the log to justify every claim.

Context:
- Language: Go
- Failing test: TestCreateInvoice_DueDate
- Log snippet:
<PASTE LOG>

Task:
1) Quote the exact failing line(s) from the log and explain the root cause in 1-2 sentences.
2) Propose the smallest possible code change (one function, one file) to accept both RFC3339 and YYYY-MM-DD.
3) Show the exact patch.
4) Add one regression test that fails before the fix and passes after.
Return your answer with headings: Evidence, Minimal Fix, Patch, Regression Test.

Eine gute Antwort zeigt auf das Parsing‑Layout‑Mismatch und ändert eine Funktion (z. B. parseDueDate in invoice.go), damit sie zuerst RFC3339 versucht und dann auf 2006-01-02 zurückfällt. Kein Refactor, keine neuen Packages.

Der Regressions‑Test ist die Schutzvorrichtung: sende due_date: "2026-01-09" und erwarte 201. Wenn später jemand die Fallback‑Logik entfernt, schlägt CI mit derselben Fehlerklasse fehl.

Häufige Fehler, die Zeit kosten (und wie du sie vermeidest)

Der schnellste Weg, eine Stunde zu verlieren, ist, nur eine beschnittene Sicht des Problems zu geben. CI‑Logs sind laut, aber der nützliche Teil ist oft 20 Zeilen über der finalen Fehlermeldung.

Eine Falle ist, nur die letzte rote Zeile einzufügen (z. B. „exit 1“) und die eigentliche Ursache früher im Log zu verbergen (fehlende Env‑Var, fehlgeschlagener Snapshot, oder der erste Test, der abgestürzt ist). Fix: Füge den fehlschlagenden Befehl plus das Log‑Fenster um die erste echte Fehlermeldung ein.

Ein weiterer Zeitfresser ist, das Modell „aufräumen“ zu lassen. Zusätzliche Formatierung, Dependency‑Bumps oder Refactors machen die Review schwerer und erhöhen das Risiko, etwas anderes zu brechen. Fix: Begrenze den Scope auf die kleinste nötige Code‑Änderung und lehne alles Unrelated ab.

Einige Muster, auf die du achten solltest:

• Nur die letzte Fehlerzeile eingefügt: füge den fehlschlagenden Befehl und die erste Fehlerzeile ein.
• Dem Modell erlauben, Dependencies oder unrelated Dateien zu ändern: verlange einen minimalen Diff und eine Begründung für jede geänderte Datei.
• Einen Fix akzeptieren, der nicht gegen den CI‑Befehl verifiziert wurde: führe denselben Befehl lokal aus.
• Einen Test schreiben, der den Bug nicht erneut erkennen würde: fordere einen Test, der auf altem Code fehlschlägt und nach dem Fix besteht.
• Flaky Tests mit echten Regressionen vermischen: entscheide, ob es nondeterministisch ist (Timing, Netzwerk, Reihenfolge) oder logische Determiniertheit und handle es entsprechend.

Wenn du Flakiness vermutest, kaschiere nicht mit Retries. Entferne die Zufälligkeit (feste Zeit, seedeten RNG, isolierte Temp‑Dirs), damit das Signal klar ist.

Kurze Checks, bevor du den Fix pushst

Bevor du pushst, mach eine kurze Sanity‑Pass. Ziel ist, sicherzustellen, dass die Änderung echt, minimal und reproduzierbar ist, nicht ein Glückslauf.

• Beweis: Zitiert die Erklärung die exakten fehlgeschlagenen Zeilen?
• Umfang: Sind die Änderungen auf das Nötige begrenzt?
• Kausalität: Erklärt es, warum die Änderung den Fehler von fail auf pass dreht?
• Repro: Hast du denselben CI‑Befehl erneut ausgeführt (gleiche Flags, Arbeitsverzeichnis)?
• Regression: Fällt der neue Test auf altem Code aus und besteht nach dem Fix?

Führe abschließend einen etwas breiteren Satz aus als nur den einen Job (z. B. lint plus Unit‑Tests). Eine häufige Falle ist ein Fix, der den ursprünglichen Job grün macht, aber ein anderes Ziel bricht.

Nächste Schritte: Mach diesen Workflow zur Gewohnheit

Wenn du das regelmäßig Zeit sparen willst, behandle deinen Prompt und die Antwortstruktur wie Team‑Prozess. Das Ziel sind wiederholbare Inputs, wiederholbare Outputs und weniger „mystery fixes“, die etwas anderes kaputtmachen.

Mach deinen besten Prompt zu einem geteilten Snippet und pinne ihn im Team‑Chat. Wenn alle dasselbe Format nutzen, gehen Reviews schneller, weil Reviewer wissen, wo sie schauen müssen.

Eine leichte Gewohnheitsschleife, die in den meisten Teams funktioniert:

• Speichere den Prompt als Repo‑Snippet und pinne ihn im Team‑Chat.
• Label CI‑Fehler nach Typ (lint, unit, integration, packaging, deploy).
• Wenn ein Label öfter auftaucht, füge einen Test oder Check hinzu, der es früher fangen würde.
• Halte riskante Experimente reversibel, damit du schnell zurückziehen kannst.

Wenn du einen Chat‑zentrierten Workflow für Bauen und Iterieren bevorzugst, kannst du dieselbe Fix‑und‑Test‑Schleife in Koder.ai laufen lassen, Snapshots zum Experimentieren nutzen und den Quellcode exportieren, wenn du bereit bist, ihn ins Repo zurückzuführen.