SpecGuard – CLI/Codex-Plugin, das Spezifikationen vor dem AI-Coding prüft

Hallo, ich entwickle gerade ein Open-Source-Tool namens SpecGuard.

Wenn man AI-Coding-Tools wie Codex oder Claude Code verwendet, wird die Implementierung definitiv schneller. Nach mehreren Wiederholungen wurde mir aber klar, dass das Problem, auf das ich in der Praxis häufig stoße, weniger „die AI kann keinen Code schreiben“ ist, sondern eher „die Spezifikation, die ich der AI übergebe, ist selbst unvollständig“.

Wenn die Spezifikation Mängel hat, implementiert die AI die Lücken nach eigenem Ermessen. Anfangs wirkt das plausibel, aber je weiter die Entwicklung fortschreitet, desto größer werden die folgenden Probleme.

• Die Qualität und Struktur des Codes zerfallen nach und nach.
• Spezifikation und Code passen immer weniger zusammen.
• Später ist nur noch schwer zu unterscheiden, ob der Code falsch ist, die Spezifikation veraltet ist oder die ursprünglichen Anforderungen von Anfang an unklar waren.

Deshalb dachte ich, dass ein Code-Review nach der Implementierung allein nicht ausreicht. Bevor eine fehlerhafte Spezifikation unverändert an den Implementierungs-Agenten weitergegeben wird, braucht es einen Schritt, der zuerst die Lücken in der Spezifikation selbst sichtbar macht.

SpecGuard ist ein CLI-/Codex-Plugin, das ich entwickelt habe, um dieses Problem zu verringern. Es ist kein Tool, das Ergebnisse nach der Codegenerierung prüft, sondern eines, das die Spezifikation prüft, bevor man die Implementierung der AI übergibt.

Der grundlegende Ablauf, den ich beabsichtigt habe, sieht so aus.

1. Ein Mensch schreibt die Produktspezifikation.
2. Die Spezifikation wird mit SpecGuard geprüft.
3. Bei NOT_READY wird die Spezifikation ergänzt.
4. Wenn READY erreicht ist, wird sie an einen Implementierungs-Agenten wie Codex oder Claude Code übergeben.

SpecGuard sucht vor allem nach solchen Arten von Lücken.

• Unklare Authentifizierungs-/Berechtigungsgrenzen
• Fehlender tenant-/user-ownership-Bereich
• Keine Behandlung von idempotency, replay oder race condition
• Unklare Regeln für Ablauf, Widerruf oder Zustandsübergänge
• Keine Richtlinien für externe Nebenwirkungen, Webhooks oder Wiederholungen von Background Jobs
• Anforderungen, die sich nur auf Client-seitige Validierung verlassen

Die Ergebnisse sind im Wesentlichen drei Kategorien.

• READY: Kann an den Implementierungs-Agenten übergeben werden
• READY_WITH_WARNINGS: Kann übergeben werden, aber es gibt Punkte, auf die man achten sollte
• NOT_READY: Es gibt Critical-/Major-Probleme, daher muss die Spezifikation ergänzt werden

Der Standardpfad ist die heuristische Prüfung mit --no-llm. Für CI oder PR Review sind schnelle und reproduzierbare Ergebnisse aus meiner Sicht wichtig. Detaillierte Reviews auf Basis der OpenAI Platform oder von Codex lassen sich ebenfalls anhängen, derzeit aber nur als optionaler Zusatzpfad, wenn man tiefer hineinschauen möchte.

Neu in v0.4.0

In dieser Version v0.4.0 habe ich ein Codex-App-Plugin-MVP hinzugefügt.

pip install spec-guard  
specguard --help  
codex plugin marketplace add KoreaNirsa/spec-guard --ref main  

Wenn man in der Codex-App die Quelle SpecGuard Plugins auswählt und das Plugin SpecGuard installiert, kann man die Ausführung von SpecGuard direkt in Codex anfordern. Nachdem man zum Beispiel eine Beispiel-Spezifikation erstellt hat,

specguard example copy specs/your-feature-name --force  

kann man in Codex den entsprechenden Ordner öffnen und so anfragen.

1. @SpecGuard führe SpecGuard für specs/your-feature-name aus.  
2. @SpecGuard führe SpecGuard für das Spezifikationspaket specs/your-feature-name aus und fasse den READY-/NOT_READY-Status sowie die wichtigsten Findings zusammen.  
3. @SpecGuard führe SpecGuard für specs/your-feature-name aus. Nutze die standardmäßige heuristische Prüfung und fasse den Ergebnisstatus sowie die nächsten Schritte zusammen.  

Das Plugin implementiert die SpecGuard-Engine nicht neu. Es ruft die vorhandene specguard-CLI auf, liest die erzeugten Ergebnisse und fasst den aktuellen Status sowie die nächsten Schritte zusammen.

Sobald SpecGuard den Status READY erzeugt, ist der beabsichtigte Ablauf, ein Handover-Dokument für den Implementierungs-Agenten zu erstellen und anschließend die Implementierung in Codex zu starten.

PR Review wird ebenfalls unterstützt

Es gibt außerdem einen GitHub-Actions-basierten SpecGuard-PR-Review-Workflow.

Dabei wird SpecGuard Review ausgeführt, wenn sich in einem PR das Spezifikationspaket geändert hat, und das Ergebnis wird im PR hinterlassen. Diese Funktion arbeitet durch Aufrufe an OpenAI.

Das Ziel ist nicht „Code-Review von AI-erzeugtem Code“, sondern „Review der Spezifikation als Eingabeartefakt, bevor sie an die AI übergeben wird“.

Das kann genutzt werden, wenn ein Team Regeln wie die folgenden einführen möchte.

• NOT_READY-Spezifikationen nicht an die Implementierung weitergeben
• Critical-/Major-Findings zuerst im PR sichtbar machen
• Zuerst die Qualität der Anforderungs-Eingaben statt der Implementierungsergebnisse steuern

Die Installation kann über specguard actions install-pr-review in der CLI erfolgen oder durch eine Anfrage an Codex wie @specguard richte den SpecGuard-PR-Review-Workflow ein.

Da es sich aber noch um eine experimentelle Funktion handelt, wird automatisches Setup derzeit nicht unterstützt. Daher müssen in den GitHub Secrets die folgenden Werte gesetzt werden.

SPECGUARD_OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx  
SPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano  
SPECGUARD_REVIEW_SPEC_PATHS=specs/your-feature-name  

Aktueller Stand und Grenzen

Es ist noch eine frühe Version, daher ist es noch kein Tool, das jede Spezifikation perfekt beurteilen kann.

Wenn Sie aber beim AI-Coding das Problem erlebt haben, dass Implementierungen durch schwache Spezifikationen entgleisen, könnte es als eine Art Sicherheitsbarriere dienen, einmal vor der Implementierung zu filtern.

Ich würde mich über Feedback freuen. Besonders interessieren mich die folgenden Punkte.

• Für welche Arten von Spezifikationen es gut passt
• Welche Findings zu streng oder zu schwach sind
• Ob der Codex-Plugin-Workflow in der Praxis tatsächlich brauchbar ist
• Ob eine Durchsetzung per PR Review zum Team-Workflow passt

Der aktuelle Stand liegt noch vor einer Beta und die Entwicklung hat gerade erst begonnen, aber ich möchte daraus ein Projekt machen, das sich künftig gut in der Praxis einsetzen lässt.

Issues und PRs von Interessierten sind willkommen. Im Repository werden Issues und PRs derzeit überwiegend auf Englisch verwaltet, Beiträge auf Koreanisch sind aber ebenfalls in Ordnung.

GitHub : https://github.com/KoreaNirsa/spec-guard

[veltrix]

Ausführlichere Informationen zu diesem Projekt finden Sie unter https://nirsa.tistory.com/487.