FAQ

Schnelle Antworten auf die häufigsten Fragen. Falls Ihre Frage eher eine „etwas ist kaputt"-Frage ist, ist die Seite Troubleshooting die bessere Wahl. Falls Sie eine Begriffserklärung suchen, siehe Glossar.

Die Grundlagen

Was ist OpenSpec, in einem Satz?

Eine leichte Schicht, die Sie und Ihren KI-Coding-Assistenten dazu bringt, schriftlich festzulegen, was gebaut werden soll, bevor auch nur eine Zeile Code geschrieben wird.

Warum sollte ich das wollen?

Weil KI-Assistenten selbst dann selbstbewusst antworten, wenn sie falsch liegen. Wenn die Anforderungen nur in einem Chat-Thread existieren, füllt die KI Lücken mit Vermutungen, und Sie erfahren es erst, nachdem der Code existiert. OpenSpec verlagert die Einigung früher, wo Fehler noch günstig zu beheben sind. Den vollständigen Fall finden Sie in Kernkonzepte auf einen Blick.

Muss ich es für alles verwenden?

Nein. Verwenden Sie es dort, wo Einigung wichtig ist – also bei den meisten nicht-trivialen Arbeiten. Für eine Ein-Zeichen-Tippfehler-Korrektur lohnt sich der Aufwand wahrscheinlich nicht, und das ist völlig in Ordnung.

Kann ich es auf einem großen bestehenden Codebase verwenden, oder nur bei neuen Projekten?

Bestehende Codebases sind der Hauptfall. OpenSpec ist brownfield-first: Sie dokumentieren Ihre gesamte App nicht im Voraus. Sie schreiben Spezifikationen nur für das, was jede Änderung betrifft, und Ihre Spezifikationen füllen sich im Laufe der Zeit um die Arbeit herum, die Sie tatsächlich leisten. Es gibt einen dedizierten Leitfaden: OpenSpec in einem bestehenden Projekt verwenden.

Ist es an ein bestimmtes KI-Tool gebunden?

Nein. OpenSpec funktioniert mit über 30 Assistenten, darunter Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex und weitere. Die vollständige Liste und die Details pro Tool finden Sie in Unterstützte Tools.

Befehle ausführen

Wo tippe ich /opsx:propose?

In dem Chat Ihres KI-Assistenten, nicht in Ihrem Terminal. Dies ist der häufigste Punkt der Verwirrung, daher hat er eine eigene Seite: Wie Befehle funktionieren. Kurz gesagt: openspec ... läuft im Terminal, /opsx:... läuft im Chat.

Wie starte ich den „interaktiven Modus"?

Es gibt keinen separaten Modus zum Starten. Sie öffnen Ihren KI-Assistenten wie gewohnt und tippen einen Slash-Befehl in dessen Chat. Der Slash-Befehl ist die Art, wie Sie OpenSpec „aufrufen". (Die einzige wirklich interaktive Terminal-Funktion ist openspec view, ein Dashboard zum Durchsuchen von Spezifikationen und Änderungen.) Die vollständige Erklärung finden Sie in Wie Befehle funktionieren.

Ich habe einen Slash-Befehl eingegeben und nichts passierte. Warum?

Am wahrscheinlichsten haben Sie ihn im Terminal statt im KI-Chat eingegeben, Sie haben eine Schreibweise verwendet, die Ihr Tool nicht erkennt, oder die Befehle sind noch nicht installiert. Falls die Dateien fehlen – oder Sie das Tool nie eingerichtet haben – führen Sie openspec init aus; openspec update aktualisiert nur Dateien, die bereits existieren. Starten Sie anschließend Ihren Assistenten neu und verwenden Sie die unter „Getting started" angezeigte Form – siehe Aufrufen. Troubleshooting enthält die vollständige Checkliste.

Warum lautet die Syntax in einem Tool /opsx:propose und in einem anderen /opsx-propose?

Jedes KI-Tool stellt benutzerdefinierte Befehle etwas anders dar, und OpenSpec schreibt sie so, wie Ihr Tool die von ihm geschriebene Datei lädt. Eine Befehlsdatei namens opsx-propose.md wird als /opsx-propose eingegeben; eine unter commands/opsx/ abgelegte Datei wird als /opsx:propose eingegeben. Tools, die Skills statt Befehle verwenden, nutzen den Skill-Namen – Codex benötigt $openspec-propose, Kimi Code /skill:openspec-propose. Die „Getting started"-Zeile von openspec init gibt bereits die richtige Form für die von Ihnen gewählten Tools aus; die vollständige Tabelle finden Sie in Aufrufen.

Was ist der Unterschied zwischen einem Skill und einem Befehl?

Beide sind Dateien, die OpenSpec schreibt, damit Ihr Assistent den Workflow ausführen kann. Skills (.../skills/openspec-*/SKILL.md) sind der neuere Tool-übergreifende Standard; Befehle (.../commands/opsx-*) sind die älteren Tool-spezifischen Slash-Dateien. Sie müssen sich nicht entscheiden. Sie tippen einfach den Slash-Befehl, und OpenSpec installiert, was Ihr Tool verwendet.

Der Workflow

Wo sollte ich anfangen, wenn ich nicht sicher bin, was ich bauen soll?

Mit /opsx:explore. Es ist ein risikofreier Denkpartner, der Ihren Codebase liest, Optionen darlegt und ein vages Problem in einen konkreten Plan verwandelt – all das, bevor eine Änderung oder ein Code existiert. Es ist im Standardprofil enthalten und daher immer verfügbar. Wenn der Plan klar ist, übergibt er an /opsx:propose. Dies ist die beste Gewohnheit, die Sie entwickeln können, denn sie verhindert, dass eine eifrige KI selbstbewusst das Falsche baut. Siehe Erst erkunden.

Was ist der einfachste mögliche Ablauf?

/opsx:explore (optional)   dann   /opsx:propose <was Sie wollen>   dann   /opsx:apply   dann   /opsx:archive

Erkunden Sie, um es durchzudenken, schlagen Sie vor, um den Plan zu entwerfen, wenden Sie an, um es zu bauen, archivieren Sie, um es abzulegen. Überspringen Sie „erkunden", wenn Sie bereits genau wissen, was Sie wollen.

Was ist der Unterschied zwischen /opsx:propose und /opsx:new?

/opsx:propose ist der Standard-Ein-Schritt-Befehl: Er erstellt die Änderung und entwirft alle Planungsdokumente auf einmal. /opsx:new ist Teil des erweiterten Befehlssatzes und erstellt nur eine leere Änderung, sodass Sie die Dokumente einzeln mit /opsx:continue (oder alle auf einmal mit /opsx:ff) erstellen. Verwenden Sie propose, es sei denn, Sie möchten Schritt-für-Schritt-Kontrolle. Siehe Befehle.

Was sind core- und erweiterte Profile?

Ein Profil bestimmt, welche Slash-Befehle installiert werden. Core (der Standard) bietet Ihnen propose, explore, apply, update, sync, archive. Der erweiterte Satz fügt new, continue, ff, verify, bulk-archive und onboard für feinere Kontrolle hinzu. Wechseln Sie mit openspec config profile, wenden Sie anschließend mit openspec update an.

Muss ich /opsx:sync ausführen?

In der Regel nicht. Sync fügt die Delta-Spezifikationen einer Änderung in Ihre Hauptspezifikationen ein, und /opsx:archive bietet an, dies für Sie zu tun. Führen Sie Sync nur manuell aus, wenn Sie die Spezifikationen vor dem Archivieren zusammenführen möchten, beispielsweise bei einer lang laufenden Änderung. Siehe Befehle.

Wie bearbeite ich einen Vorschlag, eine Spezifikation oder eine Aufgabe, nachdem ich angefangen habe?

Bearbeiten Sie einfach die Datei. Jedes Artefakt ist reines Markdown in openspec/changes/<name>/, und es gibt keine gesperrte Phase oder speziellen Bearbeitungsmodus. Ändern Sie es von Hand oder bitten Sie Ihre KI, es zu überarbeiten („aktualisiere das Design, um eine Warteschlange zu verwenden"), und fahren Sie dann fort. Die KI arbeitet immer von den aktuellen Dateiinhalten aus. Vollständiger Leitfaden: Änderungen bearbeiten und iterieren.

Kann ich zurückgehen und den Plan ändern, nachdem ich einen Teil davon implementiert habe?

Ja, jederzeit. Der Workflow ist fließend, daher sind Überprüfung und Bearbeitung keine Phasen, aus denen Sie ausgeschlossen werden. Bearbeiten Sie das Artefakt und fahren Sie dann fort. Wenn Sie einen strukturierten Check möchten, ob der Code noch zum Plan passt, führen Sie /opsx:verify aus. Siehe Änderungen bearbeiten und iterieren.

Ich habe den Code von Hand bearbeitet. Wie bringe ich ihn mit der Spezifikation in Einklang?

Bringen Sie sie vor dem Archivieren wieder in Einklang, da das Archivieren Ihre Spezifikationen zur Wahrheit macht. Wenn der Code jetzt korrekt ist, aktualisieren Sie die Delta-Spezifikation, um dem zu entsprechen, was Sie ausgeliefert haben; wenn die Spezifikation korrekt ist, bauen Sie weiter, bis der Code übereinstimmt. /opsx:verify zeigt die Abweichungen an. Siehe Änderungen bearbeiten und iterieren.

Wann sollte ich eine bestehende Änderung aktualisieren und wann eine neue starten?

Aktualisieren Sie, wenn es sich um dieselbe Arbeit handelt, verfeinert. Starten Sie neu, wenn sich die Absicht grundlegend geändert hat oder der Umfang in verschiedene Arbeiten explodiert ist. Eine Entscheidungsflussdiagramm und Beispiele finden Sie in Workflows.

Was ist, wenn meine Sitzung den Kontext erschöpft oder sich Anforderungen während der Implementierung ändern?

Hier verdienen sich Spezifikationen ihren Lohn. Weil der Plan in Dateien lebt (nicht nur im Chat-Verlauf), können Sie Ihren Kontext leeren, eine neue KI-Sitzung starten und mit /opsx:apply fortfahren; es liest die Artefakte und setzt bei der ersten nicht abgehakten Aufgabe fort. Wenn sich Anforderungen ändern, bearbeiten Sie die Artefakte, um der neuen Realität zu entsprechen, und fahren Sie fort. Ein sauberer Kontextfenster erzeugt auch bessere Ergebnisse; leeren Sie es vor der Implementierung.

Sollte ich den openspec/-Ordner in Git committen?

Ja. Ihre Spezifikationen, aktiven Änderungen und das Archiv sind Teil der Projektgeschichte. Committen Sie sie wie jede andere Quelle. Das Archiv wird insbesondere zu einem dauerhaften Nachweis dafür, warum Ihr System so funktioniert, wie es funktioniert.

Spezifikationen und Änderungen

Was gehört in eine Spezifikation und was in ein Design?

Eine Spezifikation beschreibt beobachtbares Verhalten: was das System tut, seine Eingaben, Ausgaben und Fehlerbedingungen. Ein Design beschreibt, wie Sie es bauen werden: der technische Ansatz, Architektur-Entscheidungen, Dateiänderungen. Wenn sich die Implementierung ändern könnte, ohne dass sich das extern sichtbare Verhalten ändert, gehört es ins Design, nicht in die Spezifikation. Konzepte geht tiefer ein.

Was ist eine Delta-Spezifikation?

Eine Spezifikation, die nur beschreibt, was sich ändert, mit ADDED, MODIFIED und REMOVED-Abschnitten, anstatt die gesamte Spezifikation neu zu formulieren. So behandelt OpenSpec Änderungen an bestehenden Systemen sauber. Siehe Konzepte.

Wo landen archivierte Änderungen?

In openspec/changes/archive/YYYY-MM-DD-<name>/, mit allen Änderungsartefakten erhalten. Die Änderung wird aus Ihrer aktiven Liste entfernt. Eine Änderung, die explizit retire_capabilities: true deklariert, kann auch eine Hauptfähigkeits-Spezifikation löschen, wenn sie die letzte Anforderung dieser Fähigkeit entfernt.

Konfiguration und Anpassung

Wie teile ich der KI meinen Tech-Stack mit?

Tragen Sie ihn in openspec/config.yaml unter context: ein. Dieser Text wird in jeden Planungsauftrag injiziert, sodass die KI immer Ihren Stack und Ihre Konventionen kennt. Siehe Anpassung.

Kann ich Spezifikationen in einer anderen Sprache als Englisch generieren?

Ja. Fügen Sie eine Sprachanweisung in den context: Ihres Konfigurationsdateis hinzu. Mehrsprachigkeit enthält Copy-Paste-Snippets für mehrere Sprachen.

Kann ich den Workflow selbst ändern?

Ja, mit benutzerdefinierten Schemas. Ein Schema definiert, welche Artefakte existieren und wie sie voneinander abhängen. Verzweigen Sie den Standard mit openspec schema fork spec-driven my-workflow und bearbeiten Sie ihn anschließend. Siehe Anpassung.

Modelle, Datenschutz und Upgrades

Welches KI-Modell sollte ich verwenden?

OpenSpec funktioniert am besten mit hochleistungsfähigen Reasoning-Modellen. Das README empfiehlt Modelle wie Codex 5.5 und Opus 4.7 sowohl für Planung als auch für Implementierung. Halten Sie außerdem Ihr Kontextfenster sauber: Leeren Sie es vor der Implementierung für beste Ergebnisse.

Sammelt OpenSpec Daten?

Es sammelt anonyme Nutzungsstatistiken: nur Befehlsnamen und Version. Keine Argumente, Pfade, Inhalte oder personenbezogenen Daten, und es ist in CI automatisch deaktiviert. Opt-out mit export OPENSPEC_TELEMETRY=0 oder export DO_NOT_TRACK=1.

Wie aktualisiere ich OpenSpec?

Zwei Schritte. Aktualisieren Sie das Paket (npm install -g @fission-ai/openspec@latest), führen Sie anschließend openspec update in jedem Projekt aus, um die generierten Skills und Befehle zu aktualisieren.

Wie deinstalliere ich OpenSpec?

Es gibt keinen Deinstallationsbefehl, da es sich nur um ein globales Paket plus Dateien in Ihrem Projekt handelt. Entfernen Sie das Paket (npm uninstall -g @fission-ai/openspec) und löschen Sie optional den openspec/-Verzeichnis und die generierten Tool-Dateien. Schritt-für-Schritt-Anleitung, einschließlich was sicher behalten werden kann, finden Sie in Installation: Deinstallieren.

Hilfe erhalten

Wo kann ich Fragen stellen oder Fehler melden?

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

Diese Dokumentation ist falsch oder verwirrend. Was soll ich tun?

Sagen Sie uns Bescheid oder korrigieren Sie es. Dokumentations-PRs sind willkommen und geschätzt. Erstellen Sie ein Issue oder senden Sie einen Pull Request.