Skip to content

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:

AspektLegacyOPSX
Befehle/openspec:proposal, /openspec:apply, /openspec:archiveStandard: /opsx:propose, /opsx:explore, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive (erweiterte Workflow-Befehle optional)
WorkflowAlle Artefakte werden gleichzeitig erstelltInkrementell oder alle auf einmal erstellen – Ihre Wahl
RückgängigmachenUmständliche PhasengrenzenNatürlich – jedes Artefakt kann jederzeit aktualisiert werden
AnpassungFeste StrukturSchema-basiert, vollständig anpassbar
KonfigurationCLAUDE.md mit Markern + project.mdSaubere 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:

WasWarum
Legacy-Slash-Befehl-Verzeichnisse/-DateienDurch das neue Skills-System ersetzt
openspec/AGENTS.mdVeralteter 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-verwaltete SKILL.md-Dateien unter dem ehemaligen Pfad .codex/skills werden 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 Sie codex explizit mit openspec init aus, um die Eigentümerschaft zu wechseln. Die Legacy-Prompt-Bereinigung zielt weiterhin nur auf OpenSpecs auf der Zulassungsliste stehende Dateinamen in $CODEX_HOME/prompts oder ~/.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:

  1. Den Inhalt überprüfen
  2. Nützlichen Kontext nach openspec/config.yaml verschieben (siehe Anleitung unten)
  3. 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:

bash
openspec init

Der 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:

  1. Legacy-Slash-Befehl-Verzeichnisse werden entfernt
  2. OpenSpec-Marker werden aus CLAUDE.md, AGENTS.md usw. entfernt (Ihre Inhalte bleiben)
  3. openspec/AGENTS.md wird gelöscht
  4. Neue Skills werden in .claude/skills/ installiert
  5. openspec/config.yaml wird 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:

bash
openspec update

Der 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:

bash
openspec init --force --tools claude

Das --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) ​

markdown
# 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 Spezifikationen

Nachher (config.yaml) ​

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ügen

Hauptunterschiede ​

project.mdconfig.yaml
Frei formatierter MarkdownStrukturiertes YAML
Ein TextklumpenGetrennter Kontext und Regeln pro Artefakt
Unklar, wann er verwendet wirdKontext erscheint in ALLEN Artefakten; Regeln erscheinen nur in passenden Artefakten
Keine Schema-AuswahlExplizites 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 ​

  1. config.yaml erstellen (falls nicht bereits durch init erstellt):

    yaml
    schema: spec-driven
  2. Ihren Kontext hinzufügen (seien Sie prägnant – dies geht in jede Anfrage):

    yaml
    context: |
      Ihr Projekt-Hintergrund kommt hierher.
      Konzentrieren Sie sich darauf, was die KI wirklich wissen muss.
  3. Regeln pro Artefakt hinzufügen (optional):

    yaml
    rules:
      proposal:
        - Ihre vorgabenspezifische Anleitung
      specs:
        - Ihre Regeln zum Schreiben von Spezifikationen
  4. project.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):

BefehlZweck
/opsx:proposeEine Änderung erstellen und Planungsartefakte in einem Schritt generieren
/opsx:exploreIdeen ohne Struktur durchdenken
/opsx:applyAufgaben aus tasks.md umsetzen
/opsx:updatePlanungsartefakte einer Änderung überarbeiten und kohärent halten
/opsx:syncDelta-Spezifikationen in Hauptspezifikationen zusammenführen
/opsx:archiveDie Änderung abschließen und archivieren

Erweiterter Workflow (benutzerdefinierte Auswahl):

BefehlZweck
/opsx:newEin neues Änderungsgerüst starten
/opsx:continueDas nächste Artefakt erstellen (einzeln)
/opsx:ffSchnellvorlauf – Planungsartefakte auf einmal erstellen
/opsx:verifyValidieren, dass die Implementierung den Spezifikationen entspricht
/opsx:bulk-archiveMehrere Änderungen auf einmal archivieren
/opsx:onboardGefü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 ​

LegacyOPSX-Ä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:continue

Erstellt ein Artefakt nach dem anderen basierend auf Abhängigkeiten. Verwenden Sie dies, wenn Sie jeden Schritt überprüfen möchten.

Erkundungsmodus:

/opsx:explore

Denken 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.md

OPSX 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-feature

OPSX 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-feature

Zeigt an, was basierend auf dem bereits Vorhandenen erstellt werden kann.

Möchten Sie den Status einsehen?

bash
openspec status --change add-my-feature

Das neue Konfigurationssystem ​

Struktur von config.yaml ​

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 unterteilen

Schema-Auflösung ​

Bei der Bestimmung des zu verwendenden Schemas prüft OPSX in folgender Reihenfolge:

  1. CLI-Flag: --schema <name> (höchste Priorität)
  2. Änderungs-Metadaten: .openspec.yaml im Änderungsverzeichnis
  3. Projekt-Konfiguration: openspec/config.yaml
  4. Standard: spec-driven

Verfügbare Schemata ​

SchemaArtefakteGeeignet für
spec-drivenproposal → specs → design → tasksDie meisten Projekte

Alle verfügbaren Schemata auflisten:

bash
openspec schemas

Eigene Schemata ​

Erstellen Sie Ihren eigenen Workflow:

bash
openspec schema init my-workflow

Oder forken Sie ein vorhandenes:

bash
openspec schema fork spec-driven my-workflow

Details 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:

bash
openspec init --force

Befehle 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:

bash
openspec schemas --json

Konfiguration wird nicht angewendet ​

  1. Stellen Sie sicher, dass sich die Datei unter openspec/config.yaml befindet (nicht .yml)
  2. Überprüfen Sie die YAML-Syntax
  3. 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 erhalten

Was entfernt wurde ​

  • .claude/commands/openspec/ — ersetzt durch .claude/skills/
  • openspec/AGENTS.md — veraltet
  • openspec/project.md — in config.yaml migrieren, dann löschen
  • OpenSpec-Markerblöcke in CLAUDE.md, AGENTS.md usw.

Befehlsübersicht ​

text
/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 erstellen

Hilfe erhalten ​