Anpassung

OpenSpec bietet drei Ebenen der Anpassung:

Ebene	Funktion	Am besten geeignet für
Projektkonfiguration	Standards festlegen, Kontext/Regeln einfügen	Die meisten Teams
Benutzerdefinierte Schemas	Eigene Workflow-Artefakte definieren	Teams mit besonderen Prozessen
Globale Überschreibungen	Schemas über alle Projekte hinweg teilen	Power-User

---

Projektkonfiguration

Die Datei openspec/config.yaml ist der einfachste Weg, OpenSpec für Ihr Team anzupassen. Sie ermöglicht Folgendes:

• Ein Standardschema festlegen – --schema bei jedem Befehl überspringen
• Projektkontext einfügen – Die KI sieht Ihren Technologie-Stack, Konventionen usw.
• Regeln pro Artefakt hinzufügen – Benutzerdefinierte Regeln für bestimmte Artefakte
• Anleitung pro Operation hinzufügen – Beratende Präferenzen für Apply- und Archivierungsarbeiten
• Integrationsentscheidungen speichern – z. B. das Opt-in für den GitHub Copilot Cloud-Coding-Agenten

Schnelleinrichtung

openspec init

Dies führt Sie interaktiv durch die Erstellung einer Konfiguration. Alternativ können Sie eine manuell erstellen:

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

operations:
  apply:
    guidance:
      - Run focused tests before the full suite
  archive:
    guidance:
      - Keep the completion summary concise

# Set by `openspec init` when you choose (or decline) the GitHub Copilot
# cloud coding agent; controls whether `init`/`update` generate its files.
githubCopilot:
  cloudAgent: false

So funktioniert es

Standardschema:

# Ohne Konfiguration
openspec new change my-feature --schema spec-driven

# Mit Konfiguration – Schema wird automatisch verwendet
openspec new change my-feature

Kontext- und Regel-Einspritzung:

Beim Generieren eines beliebigen Artefakts werden Ihr Kontext und Ihre Regeln in den KI-Prompt eingefügt:

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Schema's built-in template]
</template>

• Kontext erscheint in ALLEN Artefakten
• Regeln erscheinen NUR für das passende Artefakt

Operationsanleitung:

operations.apply.guidance und operations.archive.guidance sind optionale Arrays mit beratenden Anweisungen dafür, wie ein Agent diese Operationen durchführen soll. Sie sind getrennt von rules: Operationsanleitung schränkt den Artefaktinhalt nicht ein, und Artefaktregeln werden niemals als Operationsanleitung umbenannt.

Apply und Archivierung rufen diese Eingaben zur Ausführungszeit ab:

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

Beide Oberflächen geben den aktuellen Projekt-context und die passende operationGuidance als separate optionale Felder zurück. Jeder Aufruf liest eine frische Momentaufnahme aus dem aufgelösten Stammverzeichnis. Wenn --store <id> ausgewählt ist, stammen die Änderung, der Kontext und die Anleitung alle aus diesem Store und nicht aus dem aktuellen Repository. Der Archivierungs-Anweisungsbefehl ist schreibgeschützt: Er prüft oder führt keine Delta-Specs zusammen, schreibt keine Haupt-Specs, verschiebt die Änderung nicht und führt keinen statischen Archivierungs-Workflow aus.

Projektkontext ist eine erforderliche Eingabe auf Prompt-Ebene. Generierte Workflows lesen ihn und wenden relevante Projektfakten, Konventionen und Einschränkungen an. Operationsanleitung ist optionaler ergänzender Rat: Workflows berücksichtigen jeden Eintrag und befolgen Einträge, die anwendbar und mit dem integrierten Workflow kompatibel sind.

Beide Felder bleiben getrennt von CLI-gesteuertem Zustand, aufgelösten Pfaden, integrierten Schritten, expliziten Benutzerentscheidungen und Artefaktregeln. Ein Workflow meldet Kontextkonflikte, während er den kontrollierenden Wert beibehält. Er befolgt keine unzutreffende oder widersprüchliche Anleitung und erklärt, warum. Keines der Felder ist eine durchsetzbare Prüfung, und Workflows kopieren deren Text nicht in Implementierungsdateien, Specs, Änderungsartefakte oder Zusammenfassungen, sofern der Benutzer diesen Inhalt nicht separat anfordert.

Eingabesicherheit bei Archivierung und Spec-Synchronisierung:

Archivierung, Sammelarchivierung und eigenständige Synchronisierung verwenden artifactPaths.specs.existingOutputPaths aus openspec status --json als einzige Delta-Spec-Quelle. Ein Schema ohne specs-Artefakt oder eine Änderung, deren konkrete Ausgabeliste leer ist, hat nichts zu synchronisieren; andere Artefakte werden nicht verwendet, um Delta-Specs abzuleiten.

Bevor eine semantische Zusammenführung eine Haupt-Spec schreibt, konsumiert der Workflow die aktuelle openspec instructions specs --change <name> --json-Ausgabe. Die zurückgegebenen specs-Regeln beschränken nur die Haupt-Specs, die durch diese Zusammenführung erzeugt werden. Einzelne Archivierung übergibt diese Momentaufnahme an die Inline-Synchronisierung, eigenständige Synchronisierung ruft sie direkt ab, und Sammelarchivierung erhält jede erforderliche Momentaufnahme vor ihrem ersten Spec-Schreiben. Eine Nicht-Null- oder ungültige JSON-Archivierungs-/Specs-Anweisungsantwort ist ein Lookup-Fehler, keine leere Eingabe: Der Workflow stoppt vor dem betroffenen Spec-Schreiben oder der Änderungsverschiebung (bei Sammelarchivierung vor jedem Stapel-Schreiben oder -Verschieben).

Diese Konfiguration ändert nicht die Ausführungsphasen der Archivierung, Benutzeraufforderungen, Dateisystemoperationen, den Besitz der semantischen Zusammenführung, den direkten openspec archive-Befehl oder die Struktur und Ausgabe von Artefakt-rules.

Schema-Auflösungsreihenfolge

Wenn OpenSpec ein Schema benötigt, prüft es in dieser Reihenfolge:

1. CLI-Flag: --schema <name>
2. Änderungsmetadaten (.openspec.yaml im Änderungsordner)
3. Projektkonfiguration (openspec/config.yaml)
4. Standard (spec-driven)

---

Custom Schemas

Wenn die Projekt-Konfiguration nicht ausreicht, erstellen Sie ein eigenes Schema mit einem vollständig benutzerdefinierten Workflow. Benutzerdefinierte Schemas befinden sich im Verzeichnis openspec/schemas/ Ihres Projekts und werden gemeinsam mit Ihrem Code versioniert.

your-project/
├── openspec/
│   ├── config.yaml        # Project config
│   ├── schemas/           # Custom schemas live here
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # Your changes
└── src/

Bestehendes Schema forken

Der schnellste Weg zur Anpassung besteht darin, ein eingebautes Schema zu forken:

openspec schema fork spec-driven my-workflow

Dies kopiert das gesamte spec-driven-Schema nach openspec/schemas/my-workflow/, wo Sie es frei bearbeiten können.

Was Sie erhalten:

openspec/schemas/my-workflow/
├── schema.yaml           # Workflow definition
└── templates/
    ├── proposal.md       # Template for proposal artifact
    ├── spec.md           # Template for specs
    ├── design.md         # Template for design
    └── tasks.md          # Template for tasks

Bearbeiten Sie nun schema.yaml, um den Workflow zu ändern, oder bearbeiten Sie die Templates, um zu ändern, was die KI generiert.

Schema von Grund auf erstellen

Für einen völlig neuen Workflow:

# Interactive
openspec schema init research-first

# Non-interactive
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

Schema-Struktur

Ein Schema definiert die Artefakte in Ihrem Workflow und deren Abhängigkeiten voneinander:

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: My team's custom workflow

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document
    template: proposal.md
    instruction: |
      Create a proposal that explains WHY this change is needed.
      Focus on the problem, not the solution.
    requires: []

  - id: design
    generates: design.md
    description: Technical design
    template: design.md
    instruction: |
      Create a design document explaining HOW to implement.
    requires:
      - proposal    # Can't create design until proposal exists

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

Wichtige Felder:

Feld	Zweck
id	Eindeutige Kennung, wird in Befehlen und Regeln verwendet
generates	Ausgabe-Dateiname (unterstützt Globs wie specs/**/*.md)
template	Template-Datei im templates/-Verzeichnis
instruction	KI-Anweisungen für die Erstellung dieses Artefakts
requires	Abhängigkeiten – welche Artefakte zuerst vorhanden sein müssen

Listen Sie die Artefakte in der Reihenfolge auf, in der sie geschrieben werden sollen. requires bestimmt, was möglich ist; die Reihenfolge der artifacts:-Liste bestimmt, was zuerst kommt, wenn mehrere Artefakte gleichzeitig bereitstehen.

Templates

Templates sind Markdown-Dateien, die die KI leiten. Sie werden in den Prompt injiziert, wenn das jeweilige Artefakt erstellt wird.

<!-- templates/proposal.md -->
## Why

<!-- Explain the motivation for this change. What problem does this solve? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities or modifications. -->

## Impact

<!-- Affected code, APIs, dependencies, systems -->

Templates können Folgendes enthalten:

• Abschnittsüberschriften, die die KI ausfüllen soll
• HTML-Kommentare mit Anweisungen für die KI
• Beispielformate, die die erwartete Struktur zeigen

Schema validieren

Validieren Sie ein benutzerdefiniertes Schema, bevor Sie es verwenden:

openspec schema validate my-workflow

Dies prüft:

• Die Syntax von schema.yaml ist korrekt
• Alle referenzierten Templates existieren
• Keine zirkulären Abhängigkeiten
• Artefakt-IDs sind gültig

Benutzerdefiniertes Schema verwenden

Sobald erstellt, verwenden Sie Ihr Schema mit:

# Specify on command
openspec new change feature --schema my-workflow

# Or set as default in config.yaml
schema: my-workflow

Schema-Auflösung debuggen

Nicht sicher, welches Schema verwendet wird? Prüfen Sie mit:

# See where a specific schema resolves from
openspec schema which my-workflow

# List all available schemas
openspec schema which --all

Die Ausgabe zeigt, ob es aus Ihrem Projekt, dem Benutzerverzeichnis oder dem Paket stammt:

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

---

Hinweis: OpenSpec unterstützt auch benutzerdefinierte Schemas auf Benutzerebene unter ~/.local/share/openspec/schemas/ zum Teilen zwischen Projekten. Projektschemas in openspec/schemas/ werden jedoch empfohlen, da sie gemeinsam mit Ihrem Code versioniert werden.

---

Beispiele

Rapid Iteration Workflow

Ein minimaler Workflow für schnelle Iterationen:

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Fast iteration with minimal overhead

artifacts:
  - id: proposal
    generates: proposal.md
    description: Quick proposal
    template: proposal.md
    instruction: |
      Create a brief proposal for this change.
      Focus on what and why, skip detailed specs.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

Review-Artefakt hinzufügen

Forken Sie das Standard-Schema und fügen Sie einen Review-Schritt hinzu:

openspec schema fork spec-driven with-review

Bearbeiten Sie anschließend schema.yaml, um Folgendes hinzuzufügen:

  - id: review
    generates: review.md
    description: Pre-implementation review checklist
    template: review.md
    instruction: |
      Create a review checklist based on the design.
      Include security, performance, and testing considerations.
    requires:
      - design

  - id: tasks
    # ... existing tasks config ...
    requires:
      - specs
      - design
      - review    # Now tasks require review too

---

Community-Schemas

OpenSpec unterstützt auch von der Community gepflegte Schemas, die über eigenständige Repositories verteilt werden. Diese bieten durchdachte Workflows, die OpenSpec mit anderen Tools oder Systemen integrieren, ähnlich wie der github/spec-kit Community Extension Catalog für spec-kit funktioniert.

Community-Schemas werden nicht in den OpenSpec-Kern übernommen – sie befinden sich in eigenen Repositories mit eigenem Release-Takt. Um eines zu verwenden, kopieren Sie das Schema-Bundle in das Verzeichnis openspec/schemas/<schema-name>/ Ihres Projekts (die README jedes Repositories enthält Installationsanweisungen).

Schema	Maintainer	Repository	Beschreibung
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	Erfasst die Absicht einer Änderung, das beobachtbare Verhalten, das technische Design und dauerhafte Architektur-Entscheidungen vor der Implementierung. Fügt ein change-lokales ADR-Review-Manifest hinzu und schreibt qualifizierende langfristige Entscheidungen als unveränderliche, ersetzbare ADRs.
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	Integriert die Artefakt-Governance von OpenSpec mit den Ausführungsfähigkeiten von obra/superpowers (Brainstorming, Writing-Plans, TDD über Subagents, Code Review, Finishing). Fügt ein evidenzbasiertes retrospective-Artefakt hinzu, das eine Lücke schließt, die Superpowers nicht nativ abdeckt.
nanopm	@nmrtn	nmrtn/nanopm	PM-first-Workflow. Führt die Planungspipeline von nanopm (Audit → Strategie → Roadmap → PRD) vor der Implementierung aus. Verbindet Produktplanung mit dem spec-driven Engineering-Workflow von OpenSpec. Artefakte werden aus .nanopm/ gelesen, falls vorhanden – Proposal nutzt das Audit, Design nutzt die Strategie und Tasks nutzt die PRD-Aufschlüsselung.
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	End-to-End-Test-Runbooks auf Fähigkeits-Ebene. Jede Fähigkeit erhält ein unveränderliches Spec, eine unveränderliche Tasks-Vorlage und einen zeitgestempelten Laufbericht pro Ausführung. Assertions beziehen sich ausschließlich auf beobachtbares Verhalten (HTTP-Status, Response-Body, persistenter Zustand – niemals Log-Teilstücke); jeder Lauf erfasst Start-/End-UTC, Dauer und die geschätzte LLM-Token-Verbrauch.
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	Spec-driven-Workflow mit TDD-Disziplin und einem adversarialen Review-Schritt. Ablauf: proposal → specs → design → review → test-plan → tasks → apply → verify. review wird von einem Reviewer mit neuem Kontext und schreibgeschütztem Zugriff verfasst (ein zweites Modell, wenn eines verfügbar ist) und gibt eine VERDICT:-Zeile aus, die den Agenten anweist, test-plan, tasks und apply zu blockieren; OpenSpec prüft nur, ob Artefakte existieren, erzwingen Sie das Gate daher mit Ihrem eigenen CI oder Hook. test-plan ordnet jedes Spec-Szenario einem benannten Test zu und dient gleichzeitig als Red/Green-Ledger, das verify auditiert.

Möchten Sie ein Community-Schema beisteuern? Erstellen Sie ein Issue mit einem Link zu Ihrem Repository oder reichen Sie einen PR ein, der eine Zeile zu dieser Tabelle hinzufügt.

---

Siehe auch

• CLI Reference: Schema Commands - Vollständige Befehlsdokumentation