¶Bekannte Einschränkungen

¶Ein frei geschriebenes Ticket wird nur gefunden, wenn es markiert oder genannt ist

Die Suite findet Tickets per Suche. Ihre eigenen Tickets nennen ein Tool oder ein Modul in einfachen Worten, sodass eine Suche nach diesem Thema sie findet. Ein Ticket, das du in deinen eigenen Worten geschrieben hast, hat keinen solchen Anhaltspunkt. Auf einem großen Tracker, der auch andere Arbeit enthält, wird es nur in zwei Fällen aufgegriffen: Dein Tracker-Abschnitt sagt, wie Refactoring-Tickets markiert werden (die Operation Candidate), und das Ticket trägt diese Markierung, oder du nennst das Ticket im Aufruf.

Was tun: Lege eine Markierung für Refactoring-Tickets fest – die Suite schlägt eine vor, wenn sie auf einem solchen Tracker zum ersten Mal ein strukturelles Ticket anlegt –, oder nenne das Ticket: /continuous-refactoring Ticket 42.

¶Die Suite kann keinen Skill ausführen, den nur du aufrufen kannst

Ein Skill, der nur für Menschen markiert ist, erscheint nicht unter den Skills, die ein Agent sieht, ein Run kann ihn also weder empfehlen noch starten. Um ein Ticket mit einem solchen Skill zu planen oder umzusetzen, nimm diesen Schritt in eine eigene Session mit: Ein Run bietet das am Design-Schritt an und noch einmal, wenn der Plan vorliegt, endet dort, und ein späterer Run macht mit dem Plan, dem Branch oder dem Merge Request weiter, den er vorfindet. Ein autonomer Run nutzt immer die eigenen Verfahren der Suite.

¶Ein Run braucht ein sauberes Arbeitsverzeichnis

Bevor die Umsetzung ihren Branch auscheckt, schaut die Suite auf git status. Änderungen, die sie selbst geschrieben hat, bietet sie an, in einem eigenen Merge Request zu liefern; Änderungen, die sie nicht geschrieben hat, lässt sie in Ruhe und bittet dich aufzuräumen – ein autonomer Run endet dort. Dateien, die dein Projekt ignoriert, zählen nicht.

¶Parallele Merge Requests können kollidieren

Nichts begrenzt, wie viele Merge Requests der Suite gleichzeitig offen sind, und jeder startet vom Default-Branch. Zwei davon können dieselben Zeilen berühren – zwei Tools, die dieselben Dateien umschreiben, etwa. Jeder lässt sich für sich sauber mergen; nachdem der erste gemergt ist, kann der zweite kollidieren.

Was tun: Das aufzulösen ist deine Sache, wie bei zwei beliebigen Branches. Merge in der Reihenfolge, in der sich die Tickets blockieren, oder lass weniger nebeneinander laufen, indem du reviewst, bevor du erneut aufrufst.

¶Auf einem Tracker, in den Fremde schreiben können, werden ihre Kommentare auf dem Housekeeping-Ticket gewichtet wie die aller anderen

Ein Housekeeping-Run liest die Kommentare auf seinem Ticket als Refactoring-Ideen, egal wer sie geschrieben hat. Auf einem öffentlichen Tracker greift ein autonomer Run deshalb den Kommentar eines Fremden als Vorschlag auf. Was das begrenzt, ist die Art der Änderung, nicht der Autor: Eine Idee wird nur als verhaltenserhaltende Strukturänderung in Code umgesetzt, den Tests oder ein Tool abdecken. Ein Kommentar, der etwas anderes verlangt – einen auszuführenden Befehl, eine Dependency, CI, Zugangsdaten –, wird liegen gelassen. Und was umgesetzt wird, kommt in einem Merge Request an, den ein Mensch reviewt, ein Commit oder einige pro Idee.

Was tun: Reviewe die Ideen-Commits eines Housekeeping-Merge-Requests so, wie du den Beitrag eines Fremden reviewen würdest – auf einem öffentlichen Tracker kann es genau das sein.

¶Bei täglichem Rhythmus läuft die Tooling-Nachprüfung täglich

Die Vorlage, die die Suite vorschlägt, enthält die Aufgabe, die Safety Net und Guardrails nachprüft – ein vollständiger Scan beider, das Teuerste, was die Suite tut. Sie läuft so oft, wie der Rhythmus der Vorlage sagt.

Was tun: Verschiebe diese Aufgabe bei täglichem Rhythmus von Hand in eine zweite Vorlage mit seltenerem Rhythmus („eine monatliche neben der täglichen“).

¶Ein Vorschlag, den du nicht angelegt hast, wird nicht gemerkt

Was ein Scan oder eine Erkundung anbietet und du weder anlegst noch ablehnst, wird nirgends gespeichert. Ein so belassenes Tool gilt ab dann als erledigt, bis ein Scan, um den du bittest, oder die Nachprüfung im Housekeeping es wieder anbietet; ein struktureller Befund kann in einer späteren Erkundung wieder auftauchen oder auch nicht.

Was tun: Lege an, was du behalten willst, lehne ab, was du nie willst, und bitte um einen Scan, wenn du den Rest wieder sehen willst.

¶GitHub App: CI-/Check-Status kann auch nach Freigabe von „Actions“ unlesbar sein

GitHub Apps trennen den Scope Actions (Zugriff auf Workflow-Runs) von Checks (die Checks-API, auf die gh pr checks, der Merge-Status eines PRs und Check-Runs angewiesen sind). Nur „Actions: Read/Write“ in den Repo-Berechtigungen der App freizugeben, gewährt keinen Lesezugriff auf die Checks-API – das CI-Ergebnis eines Merge Requests zu lesen, liefert dann 403 oder nichts Verwertbares, obwohl der Mensch scheinbar die richtige Berechtigung erteilt hat.

Fix: Gib der GitHub App Checks: Read (Repository-Berechtigung), getrennt von Actions. Einmalig, pro Zielrepo, über die Installationseinstellungen der App in GitHubs UI – keine Automatisierung seitens der Suite; das ist eine Admin-Aktion, die der Bot nicht an sich selbst ausführen kann.

Wenn das nicht behoben wird: Der Run endet trotzdem mit einem offenen Merge Request; sein Abschlussbericht sagt, dass das CI-Ergebnis nicht gelesen werden konnte, und nennt die lokal gelaufenen Checks, statt einen Status zu behaupten, den er nicht bestätigen konnte.

¶Kein Remote, keine Forge: Es wird nichts gepusht

Ohne erreichbares Git-Remote gibt es keinen Ort zum Pushen oder Öffnen eines Merge Requests. Der Run bereitet den Branch und seine Commits lokal vor, nennt den Branch in einem Kommentar auf dem Ticket und hört dort auf.

Was tun: Merge den Branch selbst in den Default-Branch, oder pushe ihn und öffne den Merge Request, sobald es eine Forge gibt. Bis der Branch gemergt ist, behandeln spätere Runs das Ticket als im Review.

¶Merge Requests werden über das Tool gelesen, das deine Tracker-Datei nennt

Gemergte und geschlossene Merge Requests abzugleichen und zu erkennen, welche Tickets im Review sind, läuft über das Tool, das unter Merge requests genannt ist (gh, glab). Das Onboarding prüft einmal, dass es antwortet, bevor es dir die Zusammenfassung zur Bestätigung zeigt.

Fix: Halte dieses Tool für das Ziel installiert und authentifiziert.

¶Die Suite folgt den Konventionen deines Trackers, sie setzt sie nicht

Welchen Status ein Ticket bekommt, wenn die Arbeit beginnt, wie ein Merge Request auf sein Ticket verweist, und Sprache und Markup von Tickettexten sind Konventionen deines Projekts. Die Suite folgt dem, was docs/agents/issue-tracker.md und dein Contribution-Guide sagen, und fragt im Onboarding wenig davon ab. Eine Konvention, die diese Dateien nicht nennen, ist eine, der ein Run nicht folgt.

¶Der Kommentar eines Agenten an einem wartenden Ticket zählt als deine Antwort

Ein Ticket mit einer offenen Frage wartet, bis ein Kommentar folgt, der weder der Plan der Suite noch eine weitere ihrer Fragen ist. Wer ihn geschrieben hat, zählt nicht, denn Agenten posten oft mit deinem eigenen Account: Die Suite kann deine Antwort nicht vom Kommentar eines Agenten unterscheiden und liest beides als die Antwort.

Was tun: Ein Agent, der für dich Runs steuert (Driver) – oder sie reviewt –, lässt wartende Tickets in Ruhe und fragt dich woanders.

¶Ein Run in einem Subagenten macht jeden Schritt in seinem eigenen Kontext

Ein Run gibt manche Schritte, die nur lesen und beurteilen – das Review seiner Änderung, die Beurteilung eines Scans –, an eigene Subagenten ab. Ein Run, der in einem Subagenten gestartet wurde, kann in Claude Code keine weiteren starten, also macht er diese Schritte in seinem eigenen Kontext, der sich schneller füllt. So gesteuerte Runs haben verkürzte Schritte: ein Review, das durch kurzes Lesen ersetzt wird, ein Plan, der nicht gepostet wird.

Was tun: Der Agent, der die Runs steuert (Driver), reviewt jeden Merge Request vor dem Mergen in einem eigenen Subagenten und prüft, dass das Ticket den Plan trägt.

¶Ein Gate, das deine CI ausführt, läuft vielleicht nicht lokal

Bevor sie einen Merge Request öffnet, führt die Suite jedes Gate, das deine CI über das ganze Projekt ausführt, etwa einen Coverage-Floor, vollständig aus. Manche davon brauchen etwas, das der lokalen Maschine fehlt, zum Beispiel einen Coverage-Treiber. Der Merge Request wird dann trotzdem geöffnet und nennt dieses Gate als lokal nicht ausgeführt, und die CI hat dort das letzte Wort.

Was tun: Schau dir vor dem Mergen das Ergebnis dieses Gates in der CI an oder installiere lokal, was es braucht.

¶Ein autonomer Run klärt das BC-Versprechen nicht auf Verdacht

Ob dein Projekt Code außerhalb davon Stabilität verspricht – den Nutzern deines Pakets, den Addons deiner Anwendung –, entscheidet, ob eine alte API gelöscht werden darf. Ein autonomer Run übernimmt ein Versprechen, das er in genau einem Dokument gefunden hat, entscheidet aber nie, dass es keins gibt: Findet er kein Dokument oder mehrere, lässt er die Frage offen, und bis du antwortest, behandelt er Code, den etwas außerhalb des Projekts erreichen könnte, als abgedeckt. Restrukturierungen behalten dann alte APIs neben neuen, wo eine Löschung in Ordnung gewesen wäre.

Was tun: Beantworte die Frage in einem interaktiven Run oder ergänze den Punkt BC promise in docs/agents/issue-tracker.md selbst – ein Pfad oder none.

¶Der strenge Coverage-Check braucht PHPUnit 10 und funktioniert nicht mit Pest

Die zweite Stufe zu den Coverage-Metadaten lässt einen Test fehlschlagen, wenn er Code ausführt, den er weder abdeckt noch als genutzt nennt. Sie braucht PHPUnit 10 oder neuer, und Pest bietet keine Möglichkeit, dass ein Test nennt, was er nutzt. Auf PHPUnit 9 oder auf Pest schlägt die Suite nur die erste Stufe vor, dass jeder Test sagt, was er abdeckt. PHPUnit führt den Check außerdem nur aus, wenn es Coverage sammelt, also besteht ein Testlauf ohne Coverage, wo der Coverage-Job fehlschlägt.

Was tun: Auf PHPUnit 9 wird die Stufe vorgeschlagen, sobald du auf PHPUnit 10 wechselst. Führe die Tests lokal so aus wie dein Coverage-Job, bevor du pushst.

¶Troubleshooting: Warum endete der Run ohne Merge Request?

Die Status-Zeile des Abschlussberichts sagt immer, warum. Die üblichen Gründe: