Fehlerbehebung

Konkrete Lösungen für konkrete Probleme. Jeder Eintrag benennt ein Symptom, erklärt die wahrscheinliche Ursache in einem Satz und gibt Ihnen die Lösung. Falls Sie Ihr Problem hier nicht finden, kann die FAQ helfen, und der Discord definitiv auch.

Installation und Einrichtung

openspec: command not found

Die CLI ist nicht installiert oder Ihre Shell kann sie nicht finden. Installieren Sie sie global und prüfen Sie:

npm install -g @fission-ai/openspec@latest
openspec --version

Falls sie installiert wurde, aber immer noch nicht gefunden wird, ist Ihr globales npm-Bin-Verzeichnis wahrscheinlich nicht im PATH. Führen Sie npm prefix -g aus, um zu sehen, wo globale Pakete liegen: Auf macOS und Linux befinden sich die Binaries im bin/-Unterordner dieses Verzeichnisses, auf Windows direkt darin. Stellen Sie sicher, dass dieser Pfad im PATH steht. (npm bin -g wurde in npm 9 entfernt.)

Falls Sie die KI-gestützte Installation verwendet haben, ist dies der erwartete Übergabepunkt: Dieser Prompt weist Ihren Assistenten an, Ihnen die PATH-Änderung zu zeigen, anstatt Ihre Shell-Startdateien selbst zu bearbeiten.

"Requires Node.js 20.19.0 or higher"

OpenSpec läuft mit Node 20.19.0+. Prüfen Sie Ihre Version und aktualisieren Sie bei Bedarf:

node --version

Falls Sie bun verwenden, um OpenSpec zu installieren, beachten Sie, dass OpenSpec weiterhin mit Node läuft, sodass Sie unabhängig davon Node 20.19.0+ im PATH benötigen. Siehe Installation.

openspec init hat mein KI-Tool nicht konfiguriert

Init fragt, welche Tools eingerichtet werden sollen. Falls Sie Ihr Tool übersprungen haben oder ein weiteres hinzufügen möchten, führen Sie es einfach erneut aus oder verwenden Sie die nicht-interaktive Form:

openspec init --tools claude,cursor

Die vollständige Liste der Tool-IDs finden Sie in Unterstützte Tools. Verwenden Sie --tools all für alles, --tools none, um die Tool-Einrichtung zu überspringen.

Befehle erscheinen nicht

Falls /opsx:propose (oder das Äquivalent Ihres Tools) nicht erscheint oder nichts tut, arbeiten Sie diese Liste durch. Sie ist nach Geschwindigkeit der Überprüfung sortiert.

1. Sie befinden sich möglicherweise am falschen Ort. Slash-Befehle gehören in den Chat Ihres KI-Assistenten, nicht in Ihr Terminal. Falls Sie /opsx:propose in Ihre Shell eingegeben haben, liegt das Problem darin. Siehe Wie Befehle funktionieren.

2. Erzeugen Sie die Dateien neu. Aus Ihrem Projektstammverzeichnis:

   openspec update

   Dies schreibt die Skill- und Befehlsdateien für jedes konfigurierte Tool neu.

   Anweisungsdateien stammen aus der installierten CLI, sodass eine veraltete CLI alles als auf dem neuesten Stand meldet, ohne die neueren Workflows zu schreiben. openspec update prüft nun darauf und bietet ein Upgrade an — nehmen Sie das Angebot an, wenn es angezeigt wird.

3. Starten Sie Ihren Assistenten neu. Die meisten Tools scannen beim Start nach Skills und Befehlen. Ein neues Fenster reicht oft aus.

4. Bestätigen Sie, dass die Dateien existieren. Für Claude Code prüfen Sie, dass .claude/skills/ Ordner mit openspec-* enthält. Andere Tools verwenden eigene Verzeichnisse, alle aufgelistet in Unterstützte Tools.

5. Prüfen Sie, ob Sie dieses Projekt initialisiert haben. Skills werden pro Projekt geschrieben. Falls Sie ein Repo geklont oder Ordner gewechselt haben, führen Sie dort openspec init (oder openspec update) aus.

6. Bestätigen Sie, dass Ihr Tool Befehlsdateien unterstützt. Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent und das gemeinsame .agents-Ziel erhalten keine generierten opsx-*-Befehlsdateien; sie verwenden stattdessen skill-basierte Aufrufe, sodass /opsx für sie nie automatisch vervollständigt wird. Geben Sie in Codex $openspec-propose ein, in Kimi Code /skill:openspec-propose und in den übrigen /openspec-propose. Das gemeinsame .agents-Ziel ist vendor-neutral, sodass /openspec-propose die übliche, aber nicht garantierte Form ist — falls Ihr Assistent nicht darauf antwortet, prüfen Sie in dessen Dokumentation, wie es einen Skill aufruft. Amazon Q erhält zwar Befehlsdateien, lädt sie aber in seine Prompt-Bibliothek statt in sein Slash-Menü — geben Sie dort @opsx-propose ein, nicht /opsx. Die Aufrufform jedes Tools ist in Aufrufmethoden aufgelistet.

Arbeiten mit Änderungen

"Change not found"

Der Befehl konnte nicht feststellen, welche Änderung Sie meinen. Benennen Sie sie explizit oder prüfen Sie, was existiert:

openspec list                    # aktive Änderungen anzeigen
/opsx:apply add-dark-mode        # Änderung im Chat benennen

Bestätigen Sie außerdem, dass Sie sich im richtigen Projektverzeichnis befinden.

"No artifacts ready"

Jedes Artefakt ist entweder bereits erstellt oder blockiert auf eine Abhängigkeit. Sehen Sie, was blockiert:

openspec status --change <name>

Erstellen Sie dann zuerst die fehlende Abhängigkeit. Denken Sie an die Reihenfolge: Proposal ermöglicht Specs und Design; Specs und Design zusammen ermöglichen Tasks.

openspec validate meldet Warnungen oder Fehler

Die Validierung prüft Ihre Specs und Änderungen auf strukturelle Probleme. Lesen Sie die Meldung: Sie benennt die Datei und das Problem.

openspec validate <name>           # ein Element validieren
openspec validate --all            # alles validieren
openspec validate --all --strict   # strengere Prüfungen, gut für CI
openspec validate --archived       # fehlschlagen, wenn archivierte Änderungen unvollständige Tasks haben

Häufige Ursachen sind ein fehlender Pflichtabschnitt (wie eine Spec ohne Szenarien) oder ein fehlerhafter Delta-Header. Korrigieren Sie die Datei und führen Sie den Befehl erneut aus. Die CLI-Referenz dokumentiert das Ausgabeformat.

Eine Meldung verdient einen eigenen Hinweis:

MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"

Ein MODIFIED-Anforderungsblock ersetzt den gesamten Anforderungsblock, sodass er jedes Szenario enthalten muss, das die Änderung übersteht, nicht nur die, die Sie bearbeitet haben. Kopieren Sie die genannten Szenarien aus openspec/specs/<capability-path>/spec.md zurück in den Delta, wobei Sie alle Domänenverzeichnisse im Pfad beibehalten. Dies tritt häufig bei einer älteren Änderung auf, nachdem jemand anderes ein Szenario zur gleichen Anforderung hinzugefügt hat — Archive lehnt diese Änderung auf jeden Fall ab, und die Validierung meldet dies nun, bevor Sie sie implementieren.

Die KI hat unvollständige oder falsche Artefakte erstellt

Die KI hatte nicht genug Kontext. Einige Hebel helfen:

• Fügen Sie Projektkontext in openspec/config.yaml hinzu, damit Ihr Stack und Ihre Konventionen in jeden Request injiziert werden. Siehe Anpassung.
• Fügen Sie pro Artefakt rules: hinzu für Richtlinien, die nur für beispielsweise Specs gelten.
• Geben Sie bei der Vorschlagsstellung eine detailliertere Beschreibung.
• Verwenden Sie den erweiterten /opsx:continue, um ein Artefakt nach dem anderen zu erstellen und jedes zu überprüfen, statt /opsx:ff, das alles auf einmal erledigt.

Archive wird nicht abgeschlossen oder warnt vor unvollständigen Tasks

Archive blockiert nicht bei unvollständigen Tasks, warnt Sie aber, da Archivieren normalerweise bedeutet, dass die Arbeit erledigt ist. Falls Tasks absichtlich verbleiben (Sie stellen eine teilweise Änderung ein), fahren Sie fort. Andernfalls schließen Sie die Tasks zuerst ab. Archive bietet außerdem an, Ihre Delta-Specs in die Haupt-Specs zu synchronisieren, falls Sie dies noch nicht getan haben; sagen Sie ja, es sei denn, Sie haben einen Grund dagegen.

"User force closed the prompt with 0 null"

Etwas hat openspec archive ausgeführt, wo niemand eine Frage beantworten kann — ein KI-Agent, der es aus einem Tool aufruft, ein CI-Job oder eine Shell mit geschlossenem stdin. Archive fragt bis zu drei Bestätigungen ab, und eine unbeantwortbare führte früher zu dieser rohen Meldung.

Übergeben Sie --yes, um sie im Voraus zu beantworten:

openspec archive <change-name> --yes

Behalten Sie alle Flags bei, die Sie bereits übergeben haben — --skip-specs und --no-validate ändern, was Archive tut, sodass ein nacktes --yes-Neuaufruf nicht derselbe Befehl ist. Aktuelle Versionen benennen das Flag für Sie und geben eine Fix:-Zeile aus, die Sie kopieren können. Falls Sie aus einer Liste auswählen wollten, übergeben Sie den Änderungsnamen explizit: Der Picker benötigt ebenfalls eine Antwort.

Falls Sie stattdessen Archive mit umgeleitetem Output ausgeführt haben oder von einem Tool erfasst wurde und tatsächlich eine Antwort gepipet haben (printf 'y\n' | openspec archive …), schrieben ältere Versionen Terminal-Escape-Codes in diese Erfassung, während sie den Prompt zeichneten — in einigen Umgebungen genug, um die Datei stark aufzublähen. Aktuelle Versionen lesen die Bestätigungsanfragen als Klartext, wann immer stdout kein Terminal ist, und ein openspec archive ohne Argumente (das andernfalls einen interaktiven Änderungspicker zeichnen würde) fragt Sie stattdessen, einen Änderungsnamen im Voraus zu übergeben, anstatt ein Menü in die Erfassung zu rendern. Auf jeden Fall bleiben umgeleitete und Agent-Läufe sauber; das Übergeben von --yes (mit Änderungsnamen) überspringt die Prompts vollständig.

Konfiguration

Meine config.yaml wird nicht angewendet

Drei übliche Verdächtige:

1. Falscher Dateiname. Er muss openspec/config.yaml sein, nicht .yml.
2. Ungültiges YAML. Führen Sie es durch einen beliebigen YAML-Validator; die CLI meldet auch Syntaxfehler mit Zeilennummern.
3. Sie erwarteten einen Neustart. Sie brauchen keinen. Konfigurationsänderungen wirken sofort.

"Unknown artifact ID in rules: X"

Ein Schlüssel unter rules: entspricht keinem Artefakt in Ihrem Schema. Für das Standard-spec-driven-Schema sind die gültigen IDs proposal, specs, design, tasks. Um die IDs für jedes Schema zu sehen:

openspec schemas --json

"Context too large"

Das Feld context: ist bewusst auf 50 KB begrenzt, da es in jeden Request injiziert wird. Fassen Sie es zusammen oder verlinken Sie auf längere Dokumente, anstatt sie einzufügen. Schlanker Kontext erzeugt außerdem bessere und schnellere Ergebnisse.

"Schema not found"

Der Schema-Name, den Sie referenziert haben, existiert nicht. Listen Sie die verfügbaren auf und prüfen Sie die Schreibweise:

openspec schemas                    # verfügbare Schemas auflisten
openspec schema which <name>        # anzeigen, wo ein Schema aufgelöst wird
openspec schema init <name>         # ein benutzerdefiniertes erstellen

Siehe Anpassung.

Migration vom Legacy-Workflow

"Legacy files detected in non-interactive mode"

Sie befinden sich in CI oder einer nicht-interaktiven Shell, und OpenSpec hat alte Dateien gefunden, die bereinigt werden sollen, kann Sie aber nicht fragen. Genehmigen Sie automatisch:

openspec init --force

Für Codex kann OpenSpec alte verwaltete Prompt-Dateien in $CODEX_HOME/prompts oder ~/.codex/prompts erkennen. Diese Bereinigung ist auf die von OpenSpec erlaubten Legacy-Codex-Prompt-Dateinamen beschränkt, und nicht-interaktives openspec init entfernt nur die Dateien, deren Ersatz-Skills .agents/skills/openspec-* existieren. Nicht-interaktives openspec update lässt alle Legacy-Bereinigungen unberührt, es sei denn, Sie übergeben --force.

Befehle erschienen nach der Migration nicht

Starten Sie Ihre IDE neu. Skills werden beim Start erkannt. Falls sie immer noch nicht erscheinen, führen Sie openspec update aus und prüfen Sie die Dateistandorte in Unterstützte Tools.

Meine alte project.md wurde nicht migriert

Das ist beabsichtigt. OpenSpec löscht project.md nie automatisch, da es Kontext enthalten kann, den Sie geschrieben haben. Verschieben Sie die nützlichen Teile in den context:-Abschnitt von config.yaml und löschen Sie es dann selbst. Der Migrationsleitfaden führt Sie durch diesen Vorgang, einschließlich eines Prompts, den Sie Ihrer KI zur Destillation geben können.

Immer noch festgefahren?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Aus Ihrem Terminal: openspec feedback "what went wrong" öffnet ein Issue für Sie.

Wenn Sie ein Problem melden, fügen Sie Ihre OpenSpec-Version (openspec --version), Ihre Node-Version (node --version), Ihr KI-Tool sowie den genauen Befehl und die Ausgabe bei. Das beschleunigt die Hilfe erheblich.