Projekt einrichten

OpenSpec zu einem Projekt hinzufügen: init ausführen, sehen, was geschrieben wurde, und anpassen.

Wählen Sie, wo OpenSpec liegt

• Im Repository (die Standardeinstellung): Specs und Changes liegen neben dem Code, den sie beschreiben, und werden mit diesem versioniert. Der Rest dieser Seite folgt diesem Pfad.
• In einem Store: Ein separates Planungs-Repository, das von den verwendenden Repos geteilt wird, für Multi-Repo-Setups oder um Planung ganz aus dem Repo herauszuhalten. Stores (Beta) behandelt, wann das sinnvoll ist und wie man einen einrichtet.

Projekt initialisieren

Mit der installierten CLI (Installation) führen Sie init im Stammverzeichnis Ihres Projekts aus. In Ihrem Terminal:

cd <your-project>
openspec init

Init fragt, welche KI-Tools Sie verwenden, schreibt die Workflow-Dateien für die ausgewählten Tools und berichtet, was Sie erhalten haben:

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Starten Sie Ihre IDE neu, damit die neuen Befehle wirksam werden.

Das erneute Ausführen von init ist sicher:

• Tools, die bereits eingerichtet sind, zeigen Refreshed statt Created.
• Ein erneutes Ausführen von init mit einem neu ausgewählten Tool fügt dieses hinzu.
• Das Flag --tools überspringt die Auswahl (CLI-Referenz).

Vorhandene project.md migrieren

Init kopiert die Legacy-Datei openspec/project.md nicht in config.yaml. Es behält die Datei und gibt eine KI-gestützte Migrationsanfrage aus.

In Ihrem KI-Chat:

Review openspec/project.md and migrate its useful content to openspec/config.yaml.
Keep context concise: include only project-wide facts needed during artifact creation, apply, and archive.
Move artifact-specific guidance into rules for the matching artifacts.
Move guidance for apply or archive into the matching operations entry.
Leave out generic, outdated, or verbose material. Do not delete project.md.

Überprüfen Sie config.yaml und löschen Sie anschließend project.md, wenn Sie bereit sind.

Was init installiert

Das Ausführen von init erstellt zwei Dinge in Ihrem Projekt:

• Einen openspec/-Ordner im Stammverzeichnis des Repos
• Workflow-Dateien (Skills und Commands), die zum Ordner Ihres KI-Tools hinzugefügt werden (.agents/, .claude/ usw.)

Committen Sie alles wie den Rest Ihres Quellcodes. Init ändert nichts anderes in Ihrem Repo (falls es Überreste aus einer älteren OpenSpec-Version findet, fragt es, bevor es diese bereinigt).

Der openspec/-Ordner

Jedes OpenSpec-Artefakt liegt hier, im Stammverzeichnis Ihres Projekts. So sieht das aus:

openspec/
├── config.yaml     Projekteinstellungen und Kontext für die KI
├── specs/          Ihre Specs (vorerst leer)
└── changes/        In Bearbeitung befindliche Changes (vorerst leer)
    └── archive/    Abgeschlossene Changes werden hierhin verschoben

Projektkonfiguration behandelt config.yaml.

Die Workflow-Dateien (Skills und Commands)

Dies sind die OpenSpec-Workflows, die Aktionen, die Sie bei der Arbeit verwenden. Hier sind sie als installierte Skills im gemeinsamen .agents/-Ordner, den die meisten Tools verwenden:

.agents/skills/
├── openspec-explore/              Idee zuerst durchdenken
├── openspec-propose/              Change vorschlagen
├── openspec-apply-change/         Tasks eines Changes umsetzen
├── openspec-update-change/        Plan eines Changes überarbeiten
├── openspec-sync-specs/           Spec-Updates eines Changes in specs/ synchronisieren
├── openspec-archive-change/       Abgeschlossenen Change ins Archiv verschieben
├── openspec-verify-change/        Prüfen, ob die Umsetzung dem Plan entspricht (standardmäßig nicht enthalten)
└── openspec-bulk-archive-change/  Mehrere Changes auf einmal archivieren (standardmäßig nicht enthalten)

Dies ist das Standardset plus zwei optionale Workflows. Profile listet alle zwölf auf.

Standardmäßig installiert sich jeder Workflow in zwei Formen:

• Skill (openspec-apply-change): Anweisungen, die Ihr Agent eigenständig aufgreift, wenn Sie nach der Arbeit fragen.
• Command (/opsx:apply in Claude Code): Ein eintippbarer Einstiegspunkt für denselben Workflow, unter einem kürzeren Namen.

Beide sind funktional identisch. Der Skill und der Command eines Workflows enthalten dieselben Anweisungen.

Warum zwei: Commands kamen zuerst, und jedes Tool schreibt sie auf seine eigene Weise. Skills sind der neuere Standard, der von allen Tools geteilt wird, aber nicht jedes Tool kann einen Skill direkt aufrufen, daher bleiben Commands als Einstiegspunkt für diese Tools erhalten.

Einige Tools installieren nur in Skill-Form. Wo das Tool Skills direkt ausführt, überspringt init Commands und weist darauf hin (Commands skipped for: codex (uses skills)).

Wir bevorzugen Skills und erwarten, Commands irgendwann abzuschaffen.

Ändern, was installiert wird

Der interaktive Auswahl-Dialog ändert die Bereitstellungsform und den Workflow-Satz (Profile). In Ihrem Terminal:

openspec config profile

Hier wechseln Sie zu nur Skills:

Current profile settings
  Delivery: both

? What do you want to configure? Delivery only
? Delivery mode (how workflows are installed): Skills only

Config changes:
  delivery: both -> skills
? Apply changes to this project now? (Y/n) y

Mit "Ja" antworten, wird dies sofort auf das aktuelle Projekt angewendet. Andere Projekte übernehmen es bei ihrem nächsten openspec update. Die Einstellung ist global, pro Rechner.

Claude Code zeigt die Workflows nicht

Claude Code lädt OpenSpec-Workflows von einem oder beiden dieser Projektpfade, basierend auf Ihrer Bereitstellungseinstellung:

• Skills: .claude/skills/openspec-*/SKILL.md
• Commands: .claude/commands/opsx/<id>.md

Falls die Dateien fehlen, aktualisieren Sie das Projekt. In Ihrem Terminal:

openspec update

Falls die Command-Dateien existieren, /opsx: aber keine OpenSpec-Commands anzeigt, aktualisieren Sie Claude Code und starten Sie es neu. Falls Commands immer noch nicht geladen werden, aktivieren Sie auch Skills. In Ihrem Terminal:

openspec config set delivery both
openspec update

Starten Sie Claude Code neu und führen Sie dann /openspec-propose in dessen Chat aus. Falls nur einige Workflows fehlen, ändern Sie Ihr Profil.

Das Setup ist abgeschlossen. Der Quickstart führt von hier aus Ihren ersten Change durch.