Issue Sessions

Eine Issue Session ist ein KI-gestützter Scanning-Prozess, der Ihre Codebasis analysiert und automatisch Probleme, Bugs, Verbesserungen und Aufgaben entdeckt. Die Session läuft in einer Cloud-Sandbox, sodass der KI-Agent vollen Zugriff auf Ihren Repository-Code hat, und erzeugt eine strukturierte JSON-Liste von Issues, die zur Verfolgung und Behebung in CodeCourier importiert werden. Zusätzlich zu Issues erzeugen Sessions Fragen und Annahmen - strukturierte Artefakte, die festhalten, worüber der Agent beim Scanning unsicher war und was er ohne explizite Anleitung angenommen hat.

Was ist eine Issue Session?

Stellen Sie sich eine Issue Session als automatisiertes Code-Review mit einem bestimmten Fokus vor. Sie geben einen Discovery-Prompt an - etwa “Scanne nach Sicherheitslücken und Performance- Problemen” - und CodeCourier provisioniert eine Sandbox, klont Ihr Repository und führt einen KI-Agent aus, der die Codebasis gemäß Ihren Anweisungen untersucht. Der Agent gibt seine Ergebnisse als strukturierte Issue-Liste aus, jeweils mit Titel, Beschreibung, Priorität und vorgeschlagenem Fix. Er erfasst auch Fragen, die er aus der Codebasis allein nicht beantworten konnte, sowie die Annahmen, die er getroffen hat, als er ohne Antworten fortgefahren ist.

Konfiguration des Issue Agents

Vor dem Start einer Session konfigurieren Sie den Issue Agent auf der Issues-Setup-Seite unter /p/{projectId}/issues-setup. Diese Konfiguration gilt für alle Issue Sessions im Projekt. Auf der Setup-Seite können Sie festlegen:

Eine Session starten

Um eine Issue Session zu starten, navigieren Sie zur Issues-Seite und klicken Sie auf Neue Session. Sie müssen angeben:

1. Discovery-Prompt (erforderlich) - Anweisungen an den KI-Agent, wonach gesucht werden soll. Formulieren Sie ihn so spezifisch wie möglich für bessere Ergebnisse.
2. Sandbox-Konfiguration (optional) - Überschreibt Standard-Sandbox-Einstellungen einschließlich Template, Speicher, CPU-Anzahl und Timeout.

Beispiel-Discovery-Prompts:

# Security-focused scan
"Analyze the codebase for security vulnerabilities including XSS, SQL injection,
authentication bypasses, and insecure defaults. Focus on API routes and user input handling."

# Performance scan
"Identify performance bottlenecks, memory leaks, N+1 queries, unnecessary re-renders,
and large bundle size contributors."

# General code quality
"Find bugs, error handling gaps, untested edge cases, and code that doesn't follow
the project's established patterns and conventions."

# Architecture review
"Identify architectural inconsistencies, missing abstractions, leaky abstractions,
and components that have grown beyond a single responsibility."

Lebenszyklus einer Session

Jede Issue Session durchläuft mehrere Phasen:

1. Initiierung

Wenn Sie die Session abschicken, validiert CodeCourier Ihre Authentifizierung und API-Keys, erstellt einen Session-Datensatz im Status active und startet einen Trigger.dev- Hintergrund-Task, der die Scanning-Arbeit übernimmt.

2. Sandbox-Ausführung

Der Hintergrund-Task provisioniert eine E2B-Sandbox mit der Umgebungskonfiguration Ihres Projekts. Ist eine GitHub-Repository- URL konfiguriert, wird das Repository in die Sandbox geklont. Der KI-Agent wird dann mit Ihrem Discovery-Prompt ausgeführt, analysiert Dateien, verfolgt Code-Pfade und identifiziert Issues. Der Agent schreibt seine Ergebnisse nach /home/user/issues.json und seine Fragen nach /home/user/questions.json innerhalb der Sandbox.

Der Session-Fortschritt wird über zwei Zähler im Session-Datensatz verfolgt:

• currentIteration - Die aktuelle Iterations- zahl des Agents, in Echtzeit aktualisiert. Sie spiegelt wider, wie viele Scanning-Durchläufe oder Reasoning-Zyklen der Agent abgeschlossen hat.
• maxIterations - Die konfigurierte Obergrenze für Iterationen. Sobald currentIteration den Wert maxIterations erreicht, schließt der Agent ab und schreibt seine finale Ausgabe. Eine höhere Grenze ermöglicht tiefere, gründlichere Scans, auf Kosten zusätzlicher Laufzeit und Tokens.

3. Issue-Extraktion

Wenn die Session abgeschlossen ist (oder manuell beendet wird), liest CodeCourier die Ausgabe issues.json aus der Sandbox. Der Extraktionsparser verarbeitet mehrere JSON-Formate:

• Gewrappte Arrays: { "issues": [...] } oder { "results": [...] }
• Direkte Arrays: [{ "title": "...", "description": "..." }, ...]
• Alternative Feldnamen: name wird auf title abgebildet, goal auf description
• Partielles JSON mit Fallback-Regex-Extraktion bei fehlerhafter Ausgabe

4. Extraktion von Fragen und Annahmen

Zusätzlich zu Issues extrahiert die Session Fragen und Annahmen aus questions.json. Diese werden in den Feldern questionsJson und assumptionsJson des Session-Datensatzes gespeichert. Jede Frage erfasst, worüber der Agent unsicher war, und jede Annahme dokumentiert, wie der Agent in Abwesenheit einer expliziten Antwort vorgegangen ist.

Diese Fragen und Annahmen bilden die Eingabe für eine optionale Answering Session, die nach Abschluss der Issue Session läuft.

5. Erstellung der Issue-Datensätze

Jedes extrahierte Issue wird validiert (Titel und Beschreibung müssen vorhanden sein) und als individueller Issue-Datensatz erstellt, der mit der Session verknüpft ist. Die Priorität wird auf eine der vier unterstützten Stufen normalisiert; bei fehlender oder nicht erkannter Angabe wird medium als Standard verwendet. Alle Issues starten mit dem Status new.

Die Session löst außerdem das Dispatchen von Learnings und alle für das Projekt konfigurierten Review-Hooks aus, sodass Judge- und Evaluator-Rollen an der Session-Bewertung mitwirken können, bevor die Issues bearbeitet werden.

Session-Status

Session-Parameter konfigurieren

Beim Start einer Session können Sie die Sandbox-Konfiguration anpassen:

Eine Answering Session starten

Sobald eine Issue Session abgeschlossen ist und Fragen/Annahmen extrahiert wurden, können Sie optional direkt von der Issue-Session- Detailseite eine Answering Session starten. Klicken Sie dazu auf die Schaltfläche Answering Session starten.

Die Answering Session nutzt einen separaten Answering Agent (konfiguriert auf der Answering-Setup-Seite), um die Fragen zu prüfen und verfeinerte, handlungsleitende Annahmen zu erzeugen. Sie überprüfen anschließend jede Annahme einzeln - genehmigen, lehnen ab oder korrigieren sie. Genehmigte Annahmen werden als strukturierter Kontext gespeichert, der bei der Ausführung der resultierenden Issues in Workflow-Runs injiziert werden kann.

Eine vollständige Anleitung zu diesem Ablauf finden Sie in der Dokumentation zu Answering Sessions.

Einzelne Issues ausführen

Sobald Issues aus einer Session extrahiert (oder manuell erstellt) wurden, können Sie jedes davon einzeln ausführen:

1. Klicken Sie auf Issue ausführen in der Issue-Karte
2. Wählen Sie einen Workflow-Blueprint für die Ausführung
3. Konfigurieren Sie optional eine GitHub-Repository-URL und einen Branch-Namen
4. Bestätigen Sie, um den Workflow-Run zu starten

Der Run verwendet den suggestedPrompt des Issues sofern vorhanden, andernfalls die description als Prompt. Wenn für diese Issue Session bereits eine Answering Session abgeschlossen wurde, stehen die genehmigten Annahmen als zusätzlicher Kontext für den Run zur Verfügung. Der Issue-Status wechselt zu running und wird automatisch mit dem Ergebnis des Runs synchronisiert.

Sessions verwalten

In der Session-Liste können Sie:

• Umbenennen - Vergeben Sie der Session einen aussagekräftigen Namen
• Killen - Beenden Sie eine aktive Session (Teilergebnisse werden gerettet)
• Archivieren - Verschieben Sie abgeschlossene Sessions aus der aktiven Liste
• Löschen - Soft-Delete einer Session
• Massenlöschen - Mehrere Sessions auf einmal löschen
• Answering Session starten - Starten Sie eine Answering Session für eine abgeschlossene Session mit Fragen/Annahmen

Nächste Schritte