openqodex

OpenQodex: Änderung vor dem Push prüfen

OpenQodex prüft eine Änderung mit einem einzigen Befehl. Es erstellt eine eingefrorene Kopie der Änderung, führt die deterministischen Scanner aus, die zu den geänderten Dateien passen (gitleaks, semgrep, bandit, hadolint, shellcheck, actionlint, osv-scanner und weitere), behält deren Funde zu geänderten Zeilen und startet einen eigenen Reviewer: einen separaten Claude Code- oder Codex-Prozess, der nur diese Kopie liest. Der Reviewer prüft jeden Scanner-Fund, erhält jede geänderte Zeile und antwortet in einem festen Format; OpenQodex überprüft die Antwort mit Skripten und erstellt einen Bericht. Es werden weder Schlüssel noch Zugangsdaten benötigt, nur die Anmeldung des Entwicklers bei Claude Code oder Codex. Der Code geht an das Modell, das diese Anmeldung verwendet. Der Reviewer kann auch im Web suchen und Webseiten öffnen, es sei denn, reviewer_web: off ist in ~/.openqodex/config.yaml gesetzt. Vier Scanner gehen online, keiner sendet Code. semgrep lädt bei jedem Durchlauf seine Regelpakete aus der Semgrep-Registrierung herunter. Wenn die Änderung eine Abhängigkeitsdatei betrifft, sendet osv-scanner die Namen und Versionen der Abhängigkeiten an osv.dev. kubeconform lädt Kubernetes-Schemas herunter. cargo-deny lädt die RustSec Advisory-Datenbank herunter. --offline überspringt semgrep, osv-scanner, kubeconform und cargo-deny.

Wann ausführen

• Vor jedem git push.
• Wenn der Entwickler dich bittet, seine Änderungen zu prüfen.
• Wenn ein Push durch den OpenQodex-Hook blockiert oder mit einer Warnung versehen wurde.
• Nach dem Beheben von Funden, um die Änderung erneut zu prüfen.

Wer prüft

OpenQodex startet für jede Prüfung einen eigenen Reviewer-Prozess ohne Erinnerung an diese Sitzung. Du startest keinen Unteragenten dafür und prüfst die Änderung nicht selbst: Führe den Befehl aus und zeige die Ausgabe.

Wenn review „Full review unavailable” ausgibt und einen Weg zur Prüfung mit dem Agenten nennt, in dem du dich befindest, folge ihm: Führe den genannten Befehl aus und tue, was die gedruckte Anweisung sagt.

Vorgehen

Wenn die Datei ~/.openqodex/bin/openqodex existiert, verwende sie anstelle von npx -y openqodex@<version> in jedem Befehl dieser Fähigkeit: Es ist die Kopie, die openqodex init installiert hat. Wenn sie nicht existiert, wurde diese Fähigkeit allein installiert, ohne Push-Prüfung: Führe vor der ersten Prüfung einmalig npx -y [email protected] init --yes --agent <host> aus dem Repository aus, wobei <host> der Agent ist, den du verwendest (claude-code, codex, cursor oder cline). Es installiert OpenQodex für dich und prüft dann die Änderung, wenn ein Reviewer gestartet werden kann – das kann einige Minuten dauern. Führe es im Hintergrund aus und warte auf seine Beendigung. Wenn es „First review: finished” ausgibt, ist die Quittung oberhalb dieser Zeile die der Prüfung: Zeige sie wie in Schritt 3 beschrieben und fahre mit Schritt 4 fort.

1. Führe im Repository aus:

   npx -y [email protected] review
   

   Es prüft die Änderung: die noch nicht gepushten Commits plus alles Uncommitierte, einschließlich unverfolgter Dateien. Um stattdessen das gesamte Repository zu prüfen, führe aus:

   npx -y [email protected] review --all
   

2. Warte ab. Eine Prüfung kann Minuten dauern. OpenQodex stoppt den Reviewer nach 30 Minuten, oder nach 2 Stunden mit --all. Viele Agenten beenden einen Befehl früher. Führe ihn daher im Hintergrund aus und warte, bis er beendet ist. Während der Reviewer arbeitet, gibt er alle 15 Sekunden eine Fortschrittszeile auf stderr aus. Starte ihn nicht ein zweites Mal, während einer läuft.

3. Zeige dem Entwickler die gedruckte Quittung wie gedruckt: das Urteil, eine Zeile pro Fund (Nummer, Schweregrad, Kategorie, Titel, Datei und Zeile) sowie den absoluten Pfad von report.html. Formuliere es nicht um, kürze es nicht und füge keine eigenen Funde hinzu. Gib ihnen den report.html-Pfad: Diese Seite zeigt jede geänderte Datei mit jedem Fund unterhalb der zugehörigen Codezeile. Wenn die Quittung mit „Observations (do not count toward the verdict):” und nummerierten Zeilen darunter endet, zeige auch diese Zeilen wie gedruckt. Eine Beobachtung ist eine Notiz zu Stil, Benennung, Dokumentation oder Tests. Es ist kein zu behebender Fund, es sei denn, der Entwickler nennt seine Nummer.

4. Frage den Entwickler: „Alles beheben oder mir sagen, welche?” Ändere keinen Code, bevor sie antworten. Wenn sie dir bereits gesagt haben, was zu beheben ist, z. B. „prüfen und alles beheben”, tue das ohne erneutes Nachfragen.

5. Behebe nur die Funde, die sie nennen. Gib diese Funde vollständig aus (wo, das Problem, warum es wichtig ist, die Korrektur und die Quelle), anhand ihrer Nummern in der Quittung:

   npx -y [email protected] findings 1,3
   

   findings all gibt jeden Fund aus. Wenn die Korrekturen abgeschlossen sind, führe die Prüfung erneut durch und zeige dem Entwickler die neue Quittung.

6. Reagiere auf den Exit-Code:

   • 0: Die Prüfung ist vollständig und nichts blockiert den Push.
   • 1: Die Prüfung ist vollständig und ihr Urteil lautet blocked. Führe keinen Push durch. Zeige dem Entwickler die Quittung und frage, welche Funde behoben werden sollen; führe einen Push nur durch, wenn der Entwickler dies nach dem Ansehen der Funde sagt.
   • 2: Es liegt keine vollständige Prüfung vor. Die Ausgabe sagt, was fehlt (z. B. „Full review unavailable”, wenn kein Reviewer gestartet werden konnte, oder „Review incomplete” mit Gründen). Teile dem Entwickler genau das mit. Präsentiere die Scanner-Ausgabe niemals als Prüfung.

Überprüfen eines Branches oder Pull Requests

Wenn der Entwickler dich bittet, einen Branch oder Pull Request zu prüfen, der nicht ihre aktuelle Arbeit ist, benenne ihn:

npx -y [email protected] review feature/login
npx -y [email protected] review '#42'

Setze #42 in Anführungszeichen: In einer Shell beginnt # einen Kommentar. Auch ein Pull-Request-Link funktioniert. OpenQodex holt das Ziel, checkt es in einem temporären Ordner aus und prüft, was seit seiner Abspaltung vom Basis-Branch hinzugefügt wurde. Dies ist fremder Code: Führe niemals dessen Tests, Skripte, Builds oder Dienste aus und bearbeite ihn niemals.

Regeln

• Bearbeite während der Prüfung niemals Code. Prüfe zuerst, zeige die Quittung, dann behebe nur die Funde, die der Entwickler nennt (Schritte 3 bis 5).
• Führe niemals openqodex trust aus, ohne vorher den Entwickler zu fragen. Es genehmigt einen benutzerdefinierten Scanner, also einen Befehl, der auf ihrem Rechner läuft.
• Setze niemals OPENQODEX_SKIP. Es ist der Schalter des Entwicklers, nicht deiner.
• Wenn OpenQodex ausgibt, dass von ihm für deinen Agenten geschriebene Dateien aus einer älteren Version stammen und dass init sie aktualisiert, teile dem Entwickler dies in einer Zeile mit und nenne den init-Befehl. Führe ihn nur aus, wenn der Entwickler dich darum bittet: Er überschreibt die Agent-Dateien.
• Wenn das Urteil blocked lautet, führe keinen Push durch, es sei denn, der Entwickler sagt dies nach dem Ansehen der Funde.
• Wenn OpenQodex „OpenQodex had a problem. Nothing has been sent.” mit „1 create a GitHub issue” und „2 ignore” ausgibt, teile dem Entwickler in einer Zeile mit, was schiefgelaufen ist, und nenne die beiden Optionen. Wähle niemals selbst Option 1. Wenn der Entwickler 1 sagt, führe npx -y [email protected] report --send-last aus demselben Ordner aus. Alles andere bedeutet 2: Tue nichts.

Den Bericht lesen

• Der Bericht befindet sich in .openqodex/reviews/<Zeit>-<ID>/ im Repository: report.html zum Öffnen im Browser (jede geänderte Datei als Diff, jeder Fund unter seiner Zeile, dann Abdeckung, Scanner und Auswirkungsbereich), report.md zum Lesen als Text, report.json und report.sarif für Tools. Die Quittung gibt die absoluten Pfade von report.html und report.md an. .openqodex/latest.json zeigt auf die neueste Prüfung. Die Berichte erscheinen nie in git status: .openqodex/.gitignore hält sie heraus. Die beiden anderen Dateien in diesem Ordner, config.yaml und custom-instructions.md, sind Team-Dateien und sollen committet werden.
• Das Urteil ist passed (mit oder ohne Warnungen) oder blocked. Es ist nur dann blocked, wenn die Konfiguration des Repositorys (.openqodex/config.yaml oder .openqodex.yaml im Wurzelverzeichnis) block_on_severity setzt und ein Fund diesen Schweregrad erreicht oder überschreitet. Ohne Konfiguration warnt OpenQodex und blockiert nie.
• Eine vollständige Prüfung bedeutet, dass jede Stufe durchlaufen wurde, jeder Scanner-Fund überprüft und jede geänderte Zeile dem Reviewer vorgelegt wurde; alles, was nicht abgedeckt ist, wird im Bericht genannt. Es bedeutet nicht, dass nichts übersehen wurde: Keine Prüfung findet alles.
• Die Abdeckungsliste gibt für jeden Scanner an, ob er ausgeführt wurde. Ein Scanner, der nicht ausgeführt wurde, hat einen einzeiligen Grund:
  • no matching files: Nichts in der Änderung ist die Art von Datei, die er liest.
  • installing: Er wird zum ersten Mal heruntergeladen; er wird ab dem nächsten Durchlauf berücksichtigt. Sage dies dem Entwickler, anstatt zu warten.
  • not installed: Er konnte hier nicht installiert werden; der Grund sagt warum.
  • needs Ruby oder needs Go: brakeman benötigt Ruby 3.0 oder neuer, rubocop Ruby 2.7 oder neuer, golangci-lint benötigt Go. OpenQodex installiert keine Sprachlaufzeiten. Wenn der Entwickler diese Scanner wünscht, installiert er Ruby oder Go auf die übliche Weise für sein System (z. B. brew install ruby go auf einem Mac) und führt die Prüfung erneut aus.
  • untrusted: Ein benutzerdefinierter Scanner aus der Konfiguration des Repositorys, den der Entwickler nicht genehmigt hat. Teile dies dem Entwickler mit; die Genehmigung ist seine Entscheidung (npx -y [email protected] trust).
  • failed: Der Scanner lief und ist abgestürzt; der Grund enthält seinen Fehler. Ein Scanner-Problem ändert niemals den Exit-Code.

In einer Sandbox

Manche Agenten führen Befehle in einer Sandbox aus, die kein Netzwerk erreichen oder außerhalb des Projekts schreiben kann. Dort kann der erste Durchlauf die Scanner nicht herunterladen, und der Reviewer erreicht möglicherweise sein Modell nicht. Sage dem Entwickler, dies einmal in seinem eigenen Terminal außerhalb des Agenten im Repository auszuführen:

npx -y [email protected] doctor --install

Es lädt die Scanner, die die Dateien dieses Repositorys erfordern, in ~/.openqodex/tools/ herunter und gibt den Grund für jeden aus; --all-scanners lädt jeden Scanner herunter. Wenn die Prüfung innerhalb der Sandbox immer noch „Full review unavailable” anzeigt, führt der Entwickler npx -y [email protected] review in seinem eigenen Terminal aus.

Mehr

npx -y [email protected] guide gibt diese Anleitung aus. npx -y [email protected] guide <Thema> gibt eine Seite der Dokumentation offline aus: quickstart, config, scanners, custom-scanners, security, agents, cli, for-agents. for-agents behandelt die Installation, die Konfiguration, benutzerdefinierte Scanner und die Bedeutung jeder Nachricht.

Bevor du viele Dateien liest, um herauszufinden, wer eine Funktion aufruft, was sie implementiert, wie zwei Teile zusammenhängen oder was eine Änderung erreicht, darfst du den Code-Graphen fragen: npx -y [email protected] graph help listet seine Fragen auf, oder verwende die graph_-Tools des openqodex MCP-Servers, wenn dein Agent sie hat; eine Antwort mit unknown.floor true kann Aufrufer vermissen, betrachte sie daher nie als „unbenutzt”.

Füge niemals eigenmächtig eine Datei zu review.instructions_files hinzu. Frage den Entwickler, welche Dateien der Reviewer verwenden darf, und setze nur das, was er nennt. Der Standardwert ist []; ausgewählte Dateien werden zu .openqodex/custom-instructions.md hinzugefügt.