Migration zu OPSX
Dieser Leitfaden unterstützt Sie bei der Umstellung vom legacy OpenSpec-Workflow auf OPSX. Die Migration ist so konzipiert, dass sie reibungslos verläuft – Ihre bestehenden Arbeiten bleiben erhalten, und das neue System bietet mehr Flexibilität.
Was ändert sich?
OPSX ersetzt den alten phasenfixierten Workflow durch einen fließenden, aktionsbasierten Ansatz. Hier ist die wesentliche Änderung:
| Aspekt | Legacy | OPSX |
|---|---|---|
| Befehle | /openspec:proposal, /openspec:apply, /openspec:archive | Standard: /opsx:propose, /opsx:explore, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive (erweiterte Workflow-Befehle optional) |
| Workflow | Alle Artefakte werden gleichzeitig erstellt | Inkrementell oder alle auf einmal erstellen – Ihre Wahl |
| Rückgängigmachen | Umständliche Phasengrenzen | Natürlich – jedes Artefakt kann jederzeit aktualisiert werden |
| Anpassung | Feste Struktur | Schema-basiert, vollständig anpassbar |
| Konfiguration | CLAUDE.md mit Markern + project.md | Saubere Konfiguration in openspec/config.yaml |
Die philosophische Veränderung: Arbeit ist nicht linear. OPSX tut nicht so, als wäre sie es.
Bevor Sie beginnen
Ihre vorhandene Arbeit ist sicher
Der Migrationsprozess ist mit Blick auf den Erhalt konzipiert:
- Aktive Änderungen in
openspec/changes/— Vollständig erhalten. Sie können sie mit OPSX-Befehlen fortsetzen. - Archivierte Änderungen — Unberührt. Ihre Historie bleibt intakt.
- Hauptspezifikationen in
openspec/specs/— Unberührt. Diese sind Ihre Quelle der Wahrheit. - Ihre Inhalte in CLAUDE.md, AGENTS.md usw. — Erhalten. Nur die OpenSpec-Marker-Blöcke werden entfernt; alles, was Sie geschrieben haben, bleibt.
Was entfernt wird
Nur OpenSpec-verwaltete Dateien, die ersetzt werden:
| Was | Warum |
|---|---|
| Legacy-Slash-Befehl-Verzeichnisse/-Dateien | Durch das neue Skills-System ersetzt |
openspec/AGENTS.md | Veralteter Workflow-Auslöser |
OpenSpec-Marker in CLAUDE.md, AGENTS.md usw. | Nicht mehr benötigt |
Legacy-Befehlsorte nach Tool (Beispiele – Ihr Tool kann abweichen):
- Claude Code:
.claude/commands/openspec/ - Cursor:
.cursor/commands/openspec-*.md - Devin Desktop, ehemals Windsurf:
.windsurf/workflows/openspec-*.md - Cline:
.clinerules/workflows/openspec-*.md - Roo:
.roo/commands/openspec-*.md - GitHub Copilot:
.github/prompts/openspec-*.prompt.md(nur IDE-Erweiterungen; nicht in Copilot CLI unterstützt) - Codex: OpenSpec verwendet nun den kanonischen Pfad
.agents/skills/openspec-*. OpenSpec-verwalteteSKILL.md-Dateien unter dem ehemaligen Pfad.codex/skillswerden erst abgeglichen, nachdem Ersetzungen vorhanden sind; benutzerdefinierte Dateien und abweichende Kopien bleiben an Ort und Stelle. Wenn ein nicht markierter.agents-Baum bereits OpenSpec-Skills enthält, bewahrt OpenSpec dessen bestehende Codex- ($openspec-*) oder generische (/openspec-*) Darstellung, anstatt aus dem Legacy-Verzeichnis zu raten. Wählen Siecodexexplizit mitopenspec initaus, um die Eigentümerschaft zu wechseln. Die Legacy-Prompt-Bereinigung zielt weiterhin nur auf OpenSpecs auf der Zulassungsliste stehende Dateinamen in$CODEX_HOME/promptsoder~/.codex/prompts. - Und andere (Augment, Continue, Amazon Q usw.)
Die Migration erkennt, welche Tools Sie konfiguriert haben, und bereinigt deren Legacy-Dateien.
Die Entfernungsliste mag lang erscheinen, aber das sind alles Dateien, die OpenSpec ursprünglich erstellt hat. Ihre eigenen Inhalte werden nie gelöscht.
Was Ihre Aufmerksamkeit erfordert
Eine Datei erfordert manuelle Migration:
openspec/project.md — Diese Datei wird nicht automatisch gelöscht, da sie möglicherweise von Ihnen geschriebenen Projektkontext enthält. Sie müssen:
- Den Inhalt überprüfen
- Nützlichen Kontext nach
openspec/config.yamlverschieben (siehe Anleitung unten) - Die Datei löschen, wenn Sie bereit sind
Warum wir diese Änderung vorgenommen haben:
Die alte project.md war passiv – Agents könnten sie lesen oder auch nicht, könnten vergessen, was sie gelesen haben. Wir stellten fest, dass die Zuverlässigkeit inkonsistent war.
Der neue config.yaml-Kontext wird aktiv in jede OpenSpec-Planungsanfrage injiziert. Das bedeutet, dass Ihre Projektkonventionen, Ihr Technologie-Stack und Ihre Regeln immer präsent sind, wenn die KI Artefakte erstellt. Höhere Zuverlässigkeit.
Der Kompromiss:
Da der Kontext in jede Anfrage injiziert wird, sollten Sie prägnant sein. Konzentrieren Sie sich auf das, was wirklich wichtig ist:
- Technologie-Stack und wichtige Konventionen
- Nicht offensichtliche Einschränkungen, die die KI kennen muss
- Regeln, die zuvor häufig ignoriert wurden
Machen Sie sich keine Sorgen, es perfekt zu machen. Wir lernen noch, was hier am besten funktioniert, und wir werden die Funktionsweise der Kontextinjektion im Laufe unserer Experimente verbessern.
Durchführen der Migration
Sowohl openspec init als auch openspec update erkennen Legacy-Dateien und führen Sie durch denselben Bereinigungsprozess. Verwenden Sie, was zu Ihrer Situation passt:
- Neue Installationen verwenden standardmäßig das Profil
core(propose,explore,apply,update,sync,archive). - Migrierte Installationen erhalten Ihre zuvor installierten Workflows, indem bei Bedarf ein
custom-Profil geschrieben wird.
Verwenden von openspec init
Führen Sie dies aus, wenn Sie neue Tools hinzufügen oder neu konfigurieren möchten, welche Tools eingerichtet sind:
openspec initDer Init-Befehl erkennt Legacy-Dateien und führt Sie durch die Bereinigung:
Upgrade auf das neue OpenSpec
OpenSpec verwendet jetzt Agent-Skills, den aufkommenden Standard
für Coding-Agents. Dies vereinfacht Ihre Einrichtung und hält
alles weiterhin funktionsfähig.
Zu entfernende Dateien
Kein Benutzerinhalt zu erhalten:
• .claude/commands/openspec/
• openspec/AGENTS.md
Zu aktualisierende Dateien
OpenSpec-Marker werden entfernt, Ihre Inhalte bleiben erhalten:
• CLAUDE.md
• AGENTS.md
Erfordert Ihre Aufmerksamkeit
• openspec/project.md
Wir werden diese Datei nicht löschen. Sie kann nützlichen
Projektkontext enthalten.
Die neue openspec/config.yaml hat einen "context:"-Abschnitt
für Planungskontext. Dieser wird in jede OpenSpec-Anfrage
aufgenommen und funktioniert zuverlässiger als der alte
project.md-Ansatz.
Überprüfen Sie project.md, verschieben Sie nützliche Inhalte
in den context-Abschnitt von config.yaml und löschen Sie die
Datei, wenn Sie bereit sind.
? Upgraden und Legacy-Dateien bereinigen? (Y/n)Was passiert, wenn Sie mit Ja antworten:
- Legacy-Slash-Befehl-Verzeichnisse werden entfernt
- OpenSpec-Marker werden aus
CLAUDE.md,AGENTS.mdusw. entfernt (Ihre Inhalte bleiben) openspec/AGENTS.mdwird gelöscht- Neue Skills werden in
.claude/skills/installiert openspec/config.yamlwird mit einem Standard-Schema erstellt
Verwenden von openspec update
Führen Sie dies aus, wenn Sie nur migrieren und Ihre vorhandenen Tools auf die neueste Version aktualisieren möchten:
openspec updateDer Update-Befehl erkennt und bereinigt ebenfalls Legacy-Artefakte und aktualisiert dann generierte Skills/Befehle, damit sie zu Ihrem aktuellen Profil und Ihren Lieferungseinstellungen passen.
Nicht-interaktive / CI-Umgebungen
Für skriptgesteuerte Migrationen:
openspec init --force --tools claudeDas --force-Flag überspringt Eingabeaufforderungen und akzeptiert die Bereinigung automatisch.
Dies umfasst die Bereinigung OpenSpec-verwalteter Codex-Prompt-Dateien im globalen Codex-Prompt-Verzeichnis. Die Bereinigung zielt nur auf OpenSpecs auf der Zulassungsliste stehende Legacy-Codex-Prompt-Dateinamen, entfernt sie erst, nachdem Ersatz-Skills unter .agents/skills/openspec-* vorhanden sind, und bewahrt alle anderen Dateien.
Migration von project.md zu config.yaml
Die alte openspec/project.md war eine frei formatierte Markdown-Datei für Projektkontext. Die neue openspec/config.yaml ist strukturiert und – entscheidend – wird in jede Planungsanfrage injiziert, sodass Ihre Konventionen immer präsent sind, wenn die KI arbeitet.
Vorher (project.md)
# Projektkontext
Dies ist ein TypeScript-Monorepo mit React und Node.js.
Wir verwenden Jest für Tests und befolgen strenge ESLint-Regeln.
Unsere API ist RESTful und in docs/api.md dokumentiert.
## Konventionen
- Alle öffentlichen APIs müssen Abwärtskompatibilität wahren
- Neue Funktionen sollten Tests enthalten
- Verwenden Sie das Given/When/Then-Format für SpezifikationenNachher (config.yaml)
schema: spec-driven
context: |
Technologie-Stack: TypeScript, React, Node.js
Tests: Jest mit React Testing Library
API: RESTful, dokumentiert in docs/api.md
Wir wahren Abwärtskompatibilität für alle öffentlichen APIs
rules:
proposal:
- Rollback-Plan für riskante Änderungen einfügen
specs:
- Given/When/Then-Format für Szenarien verwenden
- Vorhandene Muster referenzieren, bevor neue erfunden werden
design:
- Sequenzdiagramme für komplexe Abläufe einfügenHauptunterschiede
| project.md | config.yaml |
|---|---|
| Frei formatierter Markdown | Strukturiertes YAML |
| Ein Textklumpen | Getrennter Kontext und Regeln pro Artefakt |
| Unklar, wann er verwendet wird | Kontext erscheint in ALLEN Artefakten; Regeln erscheinen nur in passenden Artefakten |
| Keine Schema-Auswahl | Explizites schema:-Feld legt den Standard-Workflow fest |
Was behalten, was verwerfen
Seien Sie bei der Migration selektiv. Fragen Sie sich: „Braucht die KI das für jede Planungsanfrage?“
Gute Kandidaten für context:
- Technologie-Stack (Sprachen, Frameworks, Datenbanken)
- Wichtige Architekturmuster (Monorepo, Microservices usw.)
- Nicht offensichtliche Einschränkungen („wir können Bibliothek X nicht verwenden, weil...“)
- Kritische Konventionen, die oft ignoriert werden
Stattdessen zu rules: verschieben
- Artefaktspezifische Formatierung („Given/When/Then in Spezifikationen verwenden“)
- Überprüfungskriterien („Vorschläge müssen Rollback-Pläne enthalten“)
- Diese erscheinen nur für das passende Artefakt und halten andere Anfragen schlanker
Ganz weglassen
- Allgemeine Best Practices, die die KI bereits kennt
- Ausführliche Erklärungen, die zusammengefasst werden könnten
- Historischer Kontext, der die aktuelle Arbeit nicht beeinflusst
Migrationsschritte
config.yaml erstellen (falls nicht bereits durch init erstellt):
yamlschema: spec-drivenIhren Kontext hinzufügen (seien Sie prägnant – dies geht in jede Anfrage):
yamlcontext: | Ihr Projekt-Hintergrund kommt hierher. Konzentrieren Sie sich darauf, was die KI wirklich wissen muss.Regeln pro Artefakt hinzufügen (optional):
yamlrules: proposal: - Ihre vorgabenspezifische Anleitung specs: - Ihre Regeln zum Schreiben von Spezifikationenproject.md löschen, sobald Sie alles Nützliche verschoben haben.
Überdenken Sie es nicht zu sehr. Beginnen Sie mit dem Wesentlichen und iterieren Sie. Wenn Sie bemerken, dass der KI etwas Wichtiges fehlt, fügen Sie es hinzu. Wenn der Kontext aufgebläht wirkt, kürzen Sie ihn. Dies ist ein lebendiges Dokument.
Hilfe benötigt? Verwenden Sie diese Eingabeaufforderung
Wenn Sie unsicher sind, wie Sie Ihre project.md destillieren sollen, fragen Sie Ihren KI-Assistenten:
Ich migriere von OpenSpecs alter project.md zum neuen config.yaml-Format.
Hier ist meine aktuelle project.md:
[fügen Sie den Inhalt Ihrer project.md ein]
Bitte helfen Sie mir, eine config.yaml zu erstellen mit:
1. Einem prägnanten `context:`-Abschnitt (dieser wird in jede Planungsanfrage injiziert, also halten Sie ihn knapp – konzentrieren Sie sich auf Technologie-Stack, wichtige Einschränkungen und Konventionen, die oft ignoriert werden)
2. `rules:` für bestimmte Artefakte, falls Inhalte artefaktspezifisch sind (z. B. gehört „Given/When/Then verwenden“ zu den Spezifikationsregeln, nicht zum globalen Kontext)
Lassen Sie alles Generische weg, das KI-Modelle bereits kennen. Seien Sie kompromisslos kurz.Die KI hilft Ihnen zu erkennen, was wesentlich ist und was gekürzt werden kann.
Die neuen Befehle
Die Verfügbarkeit der Befehle ist profilabhängig:
Standard (core-Profil):
| Befehl | Zweck |
|---|---|
/opsx:propose | Eine Änderung erstellen und Planungsartefakte in einem Schritt generieren |
/opsx:explore | Ideen ohne Struktur durchdenken |
/opsx:apply | Aufgaben aus tasks.md umsetzen |
/opsx:update | Planungsartefakte einer Änderung überarbeiten und kohärent halten |
/opsx:sync | Delta-Spezifikationen in Hauptspezifikationen zusammenführen |
/opsx:archive | Die Änderung abschließen und archivieren |
Erweiterter Workflow (benutzerdefinierte Auswahl):
| Befehl | Zweck |
|---|---|
/opsx:new | Ein neues Änderungsgerüst starten |
/opsx:continue | Das nächste Artefakt erstellen (einzeln) |
/opsx:ff | Schnellvorlauf – Planungsartefakte auf einmal erstellen |
/opsx:verify | Validieren, dass die Implementierung den Spezifikationen entspricht |
/opsx:bulk-archive | Mehrere Änderungen auf einmal archivieren |
/opsx:onboard | Geführter End-to-End-Onboarding-Workflow |
Aktivieren Sie erweiterte Befehle mit openspec config profile und führen Sie dann openspec update aus.
Befehlszuordnung von Legacy
| Legacy | OPSX-Äquivalent |
|---|---|
/openspec:proposal | /opsx:propose (Standard) oder /opsx:new dann /opsx:ff (erweitert) |
/openspec:apply | /opsx:apply |
/openspec:archive | /opsx:archive |
Neue Funktionen
Diese Funktionen sind Teil des erweiterten Workflow-Befehlssatzes.
Granulare Artefakterstellung:
/opsx:continueErstellt ein Artefakt nach dem anderen basierend auf Abhängigkeiten. Verwenden Sie dies, wenn Sie jeden Schritt überprüfen möchten.
Erkundungsmodus:
/opsx:exploreDenken Sie Ideen mit einem Partner durch, bevor Sie sich auf eine Änderung festlegen.
Verständnis der neuen Architektur
Von phasenbasiert zu fluid
Der Legacy-Workflow erzwang einen linearen Fortschritt:
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ PLANNING │ ───► │ IMPLEMENTING │ ───► │ ARCHIVING │
│ PHASE │ │ PHASE │ │ PHASE │
└──────────────┘ └──────────────┘ └──────────────┘
Wenn Sie sich in der Implementierungsphase befinden und feststellen, dass das Design falsch ist?
Pech gehabt. Phasengrenzen (Phase Gates) lassen keinen einfachen Rückgriff zu.OPSX verwendet Aktionen, keine Phasen:
┌───────────────────────────────────────────────┐
│ ACTIONS (not phases) │
│ │
│ new ◄──► continue ◄──► apply ◄──► archive │
│ │ │ │ │ │
│ └──────────┴───────────┴─────────────┘ │
│ any order │
└───────────────────────────────────────────────┘Abhängigkeitsgraph
Artefakte bilden einen gerichteten Graphen. Abhängigkeiten sind Ermöglicher, keine Hürden:
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)Wenn Sie /opsx:continue ausführen, prüft es, was bereit ist, und bietet das nächste Artefakt an. Sie können auch mehrere bereite Artefakte in beliebiger Reihenfolge erstellen.
Skills vs. Commands
Das Legacy-System verwendete toolspezifische Befehlsdateien:
.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.mdOPSX verwendet den aufkommenden Standard Skills:
.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...Skills werden von mehreren KI-Coding-Tools erkannt und bieten reichhaltigere Metadaten.
Codex unterstützt in OPSX nur Skills. OpenSpec generiert keine benutzerdefinierten Prompt-Dateien mehr für Codex; verwenden Sie stattdessen die generierten Verzeichnisse .agents/skills/openspec-*.
Fortsetzen bestehender Änderungen
Ihre laufenden Änderungen funktionieren nahtlos mit den OPSX-Befehlen.
Haben Sie eine aktive Änderung aus dem Legacy-Workflow?
/opsx:apply add-my-featureOPSX liest die vorhandenen Artefakte und setzt dort fort, wo Sie aufgehört haben.
Möchten Sie weitere Artefakte zu einer bestehenden Änderung hinzufügen?
/opsx:continue add-my-featureZeigt an, was basierend auf dem bereits Vorhandenen erstellt werden kann.
Möchten Sie den Status einsehen?
openspec status --change add-my-featureDas neue Konfigurationssystem
Struktur von config.yaml
# Erforderlich: Standardschema für neue Änderungen
schema: spec-driven
# Optional: Projektkontext (max. 50 KB)
# Wird in ALLE Artefaktanweisungen eingefügt
context: |
Ihr Projekt-Hintergrund, Tech-Stack,
Konventionen und Einschränkungen.
# Optional: Regeln pro Artefakt
# Nur in passende Artefakte eingefügt
rules:
proposal:
- Rollback-Plan einschließen
specs:
- Given/When/Then-Format verwenden
design:
- Fallback-Strategien dokumentieren
tasks:
- In maximal 2-Stunden-Schritte unterteilenSchema-Auflösung
Bei der Bestimmung des zu verwendenden Schemas prüft OPSX in folgender Reihenfolge:
- CLI-Flag:
--schema <name>(höchste Priorität) - Änderungs-Metadaten:
.openspec.yamlim Änderungsverzeichnis - Projekt-Konfiguration:
openspec/config.yaml - Standard:
spec-driven
Verfügbare Schemata
| Schema | Artefakte | Geeignet für |
|---|---|---|
spec-driven | proposal → specs → design → tasks | Die meisten Projekte |
Alle verfügbaren Schemata auflisten:
openspec schemasEigene Schemata
Erstellen Sie Ihren eigenen Workflow:
openspec schema init my-workflowOder forken Sie ein vorhandenes:
openspec schema fork spec-driven my-workflowDetails finden Sie unter Customization.
Fehlerbehebung
„Legacy files detected in non-interactive mode“
Sie führen dies in einer CI- oder nicht-interaktiven Umgebung aus. Verwenden Sie:
openspec init --forceBefehle erscheinen nach der Migration nicht
Starten Sie Ihre IDE neu. Skills werden beim Start erkannt.
„Unknown artifact ID in rules“
Stellen Sie sicher, dass die Schlüssel in Ihrem rules:-Abschnitt mit den Artefakt-IDs Ihres Schemas übereinstimmen:
- spec-driven:
proposal,specs,design,tasks
Führen Sie diesen Befehl aus, um gültige Artefakt-IDs anzuzeigen:
openspec schemas --jsonKonfiguration wird nicht angewendet
- Stellen Sie sicher, dass sich die Datei unter
openspec/config.yamlbefindet (nicht.yml) - Überprüfen Sie die YAML-Syntax
- Konfigurationsänderungen wirken sich sofort aus – kein Neustart erforderlich
project.md wurde nicht migriert
Das System bewahrt project.md absichtlich bei, da es möglicherweise benutzerdefinierte Inhalte enthält. Überprüfen Sie diese manuell, übertragen Sie nützliche Teile in config.yaml und löschen Sie sie anschließend.
Möchten Sie sehen, was bereinigt würde?
Führen Sie init aus und lehnen Sie den Bereinigungs-Prompt ab – Sie erhalten dann die vollständige Erkennungszusammenfassung, ohne dass Änderungen vorgenommen werden.
Schnellreferenz
Dateien nach der Migration
project/
├── openspec/
│ ├── specs/ # Unverändert
│ ├── changes/ # Unverändert
│ │ └── archive/ # Unverändert
│ └── config.yaml # NEU: Projektkonfiguration
├── .claude/
│ └── skills/ # NEU: OPSX Skills
│ ├── openspec-propose/ # Standard-Core-Profil
│ ├── openspec-explore/
│ ├── openspec-apply-change/
│ ├── openspec-update-change/
│ ├── openspec-sync-specs/
│ ├── openspec-archive-change/
│ └── ... # Erweitertes Profil fügt new/continue/ff/etc. hinzu
├── CLAUDE.md # OpenSpec-Marker entfernt, eigener Inhalt erhalten
└── AGENTS.md # OpenSpec-Marker entfernt, eigener Inhalt erhaltenWas entfernt wurde
.claude/commands/openspec/— ersetzt durch.claude/skills/openspec/AGENTS.md— veraltetopenspec/project.md— inconfig.yamlmigrieren, dann löschen- OpenSpec-Markerblöcke in
CLAUDE.md,AGENTS.mdusw.
Befehlsübersicht
/opsx:propose Schnell starten (Standard-Core-Profil)
/opsx:apply Aufgaben implementieren
/opsx:archive Abschließen und archivieren
# Erweiterter Workflow (falls aktiviert):
/opsx:new Änderung vorbereiten
/opsx:continue Nächstes Artefakt erstellen
/opsx:ff Planungsartefakte erstellenHilfe erhalten
- Discord: discord.gg/YctCnvvshC
- GitHub Issues: github.com/Fission-AI/OpenSpec/issues
- Dokumentation: docs/opsx.md für die vollständige OPSX-Referenz