trailofbits/code-improver

Code Improver

Verbessern Sie jedes Code-Ziel durch Ausführen von /code-improver:improve – einem dynamischen Workflow, der den benannten Reviewer und einen Fixer-Subagenten in einer Schleife ausführt, bis ein Review null kritische/schwerwiegende Befunde meldet. Anschließend werden die eigenen Rückstände entfernt. Die Schleife, ihr Ergebniskonto und ihre Schutzmechanismen leben im Workflow; dieser Skill sammelt die drei Eingaben, die der generische Eintrag benötigt, und gibt das Ergebnis weiter.

Starten der Schleife

Der Benutzer hat bereitgestellt: $ARGUMENTS (falls leer, die Details aus dem Gespräch entnehmen).

1. Erfassen der drei erforderlichen Eingaben – kein Raten

1. Ziel (Target): der absolute Pfad zum zu verbessernden Verzeichnis. Relative Pfade relativ zum Arbeitsverzeichnis auflösen; prüfen, ob das Verzeichnis existiert.
2. Reviewer: der installierte Skill oder Agent, der jede Überprüfung durchführt. Der Benutzer muss ihn benennen – es gibt keinen Standard und keinen mitgelieferten Reviewer. Bestimmen Sie die Art:
   • ein namensraumbezogener Agent (z.B. plugin-dev:skill-reviewer) → "kind": "agent"
   • ein installierter Skill (z.B. pr-review-toolkit:review-pr) → "kind": "skill" Wenn der Name auf beide zutreffen könnte, die Skill-Auflistung der Sitzung prüfen; falls immer noch unklar, den Benutzer fragen. Wenn kein Reviewer benannt wurde, fragen – keinen auswählen.
3. Geltungsbereich (Scope): repo-relative Globs, die die Schleife berühren darf. Der generische Eintrag benötigt ihn explizit; falls der Benutzer keinen angegeben hat, das Zielverzeichnis vorschlagen (<repo-relative-target>/**) und vor dem Start bestätigen.

2. Auflösen des Schleifenskripts

Die Schleife ist der dynamische Workflow workflows/improve.js in diesem Plugin. Starten Sie sie über den Pfad: scriptPath erwartet einen aufgelösten absoluten Pfad, und das name des Workflow-Tools löst integrierte und Projekt-Workflows auf, sodass ein im Marktplatz installierter möglicherweise nicht auf code-improver:improve antwortet. In dieser Reihenfolge versuchen, der erste Treffer gewinnt – die Home-Verzeichnisse haben Vorrang vor ., sodass eine installierte Kopie einen Checkout dieses Marktplatzes schlägt:

1. Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"
2. Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js" (falls diese Variable stattdessen gesetzt ist)
3. Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null

Den Pfad exakt wie ausgegeben verwenden. Das Plugin-Verzeichnis – der Pfad mit entferntem /workflows/improve.js – ist pluginRoot. Falls alle drei Befehle leer zurückkommen, einmal {name: "code-improver:improve"} versuchen; falls auch das nicht verfügbar ist, anhalten und mitteilen, dass die Schleife nicht gefunden werden konnte. Keinen Pfad manuell zusammenbauen und die Schleife nicht improvisieren.

3. Workflow starten

Führen Sie ihn mit dem Workflow-Tool aus: {scriptPath: "<der Pfad aus Schritt 2>", args: {...}}:

{
  "target": "<absoluter Zielpfad>",
  "reviewer": { "kind": "agent|skill", "name": "<namensraumbezogener-Name>", "notes": "<was der Reviewer über das Ziel wissen sollte>" },
  "scope": ["<repo-relative-glob>/**"],
  "pluginRoot": "<das Plugin-Verzeichnis aus Schritt 2>",
  "maxRounds": 5
}

• maxRounds nur, wenn der Benutzer eine andere Obergrenze gewünscht hat.
• pluginRoot ermöglicht der Ausführung, ihren Metriksammler zu finden; den Schlüssel nur weglassen, wenn Schritt 2 auf den Workflow-Namen zurückgefallen ist – der Workflow sucht dann selbst.
• finalize ({"version_bump": bool, "narration_strip": bool, "docs_pass": bool}) nur, um die Standardeinstellungen zu überschreiben: Versionssprung, wenn das Ziel in einem Plugin liegt; Erzählungsbereinigung und Docs-Durchlauf immer.
• decision nur bei Fortsetzung (siehe unten).

Der Workflow läuft im Hintergrund und benötigt keine Beaufsichtigung: Er reviewt, repariert, reviewt erneut, prüft den Geltungsbereich nach jeder Reparaturrunde und kann nur bei einem sauberen Review abschließen. Er committet nie; alle Änderungen bleiben im Arbeitsbaum.

Wenn das Workflow-Tool nicht verfügbar oder verweigert wird, anhalten und dies mitteilen. Die Schleife nicht direkt mit Bearbeitungen improvisieren – das Ergebniskonto (Ledger), der Geltungsbereichsschutz und die Eskalationsgarantien leben im Workflow, und eine Inline-Imitation hat keine davon.

Wenn das Ergebnis halted: "reviewer-unavailable" ist, dies weitergeben und anhalten. Der genannte Reviewer ist in dieser Sitzung nicht installiert; dem Benutzer mitteilen, welches Plugin ihn bereitstellt, und nach der Installation erneut ausführen. Das Ziel nicht selbst reviewen.

Die Runde nicht beenden, während die Schleife läuft. Das Workflow-Tool gibt sofort eine Aufgaben-ID zurück; das Ergebnis kommt später. In einer interaktiven Sitzung ruft die Abschlussbenachrichtigung Sie erneut auf – warten Sie darauf. In einem nicht-interaktiven Lauf (skriptgesteuert, CI, Auswertung) gibt es keine spätere Runde: Ein Stopp bricht die Schleife mittendrin ab, daher nach dem Start die Aufgabe abfragen (TaskOutput mit der zurückgegebenen Aufgaben-ID, oder schlafen und erneut prüfen), bis sie abgeschlossen ist, dann das Ergebnis weitergeben. Eine Sitzung, die antwortet "die Schleife läuft, ich melde mich später", hat den Lauf verloren.

Weitergeben des Ergebnisses

Der Workflow gibt ein strukturiertes Ergebnis zurück. Es ehrlich melden – die Unterschiede sind wichtig:

• converged: true – die letzte Aktion war ein Review mit null kritischen/schwerwiegenden Befunden. Genutzte Runden, verbleibende minder schwere Befunde (open_minor_count) und die Artefaktpfade (ledger_path, metrics) melden.
• capped: true – das Reparaturbudget war aufgebraucht und das ENDGÜLTIGE Review hat immer noch blockierende Probleme gefunden. Klar sagen: gedeckelt (capped), NICHT konvergiert (converged) und open_blocking auflisten. Dies nicht als Erfolg präsentieren.
• escalation – die Schleife hat festgestellt, dass sie nicht konvergiert (wiederkehrende Befunde, nicht abnehmende Zählungen oder eine Reparatur, die ein Problem verlagert hat). Die Eskalationsnachricht und Befund-IDs an den Benutzer weitergeben: Dies erfordert eine Designentscheidung, nicht weitere Runden.
• halted – eine Schutzmaßnahme hat ausgelöst (Geltungsbereichsverletzung, nicht registrierte neue Dateien, ein toter oder nicht verfügbarer Reviewer oder ein Finalisierungsdurchlauf, dessen eigene Änderungen die darauf folgende Prüfung nicht bestanden haben). Die Pfade in violations/new_untracked_files, die Stellen in finalize_regressions und die Hinweise weitergeben.
• notes werden immer mit dem Ergebnis geliefert – sie hervorheben; sie enthalten laute Warnungen wie "ein Git-Repository wurde initialisiert".

Fortsetzen nach einer Eskalation

Die Schleife stoppt bei Eskalation absichtlich. Wenn der Benutzer entscheidet, einen neuen Durchlauf mit demselben target und reviewer sowie folgendem Parameter starten:

{ "decision": "<die Entscheidung des Benutzers, wörtlich>" }

Der neue Durchlauf lädt das auf der Festplatte befindliche Ergebniskonto neu, sodass jeder Befund, jede Ablehnung und jedes Urteil übertragen wird – Runden starten neu, eine erneute Ableitung erfolgt nicht.

Um eine laufende Schleife zu stoppen, die Workflow-Aufgabe anhalten (TaskStop); das Ergebniskonto auf der Festplatte ist bis zur letzten Runde aktuell und ein erneuter Durchlauf startet davon.

Wann NICHT verwenden

• Ein Claude Code Skill: den skill-improver-Eintrag verwenden – er verdrahtet den richtigen Reviewer
• Ein Branch / Pull Request: den pr-improver-Eintrag verwenden – er leitet den Geltungsbereich aus dem Diff ab
• Einmaliges Review: den Reviewer direkt aufrufen; der Wert der Schleife liegt in der Iteration
• Schnelle einzelne Korrekturen: die Datei direkt bearbeiten