Schnellstart

Deine erste Änderung, von der Idee bis zum Archivieren, in einem neuen oder bestehenden Projekt.

Bevor du beginnst, benötigst du die CLI auf deinem Rechner (Installation) und OpenSpec in deinem Projekt initialisiert (Projekt einrichten).

Start mit einem leeren Projekt

Du kannst ohne gewählten Stack oder vollständige Architektur starten. Initialisiere OpenSpec in deinem Projektordner und bitte dann deinen Agenten, die Optionen mit dir zu erkunden. In deinem KI-Chat:

Help me explore a task tracker from scratch. I have not picked a stack. Compare the options and help me choose the first behavior to build.

Entscheide, was die erste Änderung braucht, und lass spätere Architektur-Entscheidungen offen. Bitte deinen Agenten, diese eine Änderung vorzuschlagen, und folge dann den Schritten unten. Du kannst die Architektur überdenken, während das Projekt wächst.

Der Ablauf auf einen Blick

Jede Änderung durchläuft dieselben fünf Schritte: Du denkst die Idee mit deinem Agenten durch, er erstellt einen Plan, du korrigierst den Plan, bevor Code existiert, der Agent baut daraus, und das Archivieren aktualisiert deine Specs mit dem, was geliefert wurde.

flowchart LR
    explore["1 · Explore<br/>think it through together"] --> propose["2 · Propose<br/>agent drafts the plan"]
    propose --> review["3 · Review<br/>you correct the plan"]
    review --> apply["4 · Apply<br/>agent builds, task by task"]
    apply --> archive["5 · Archive<br/>specs absorb the change"]
    archive -. "next change" .-> explore

Jeder unten stehende Prompt geht in deinen KI-Chat, denselben Ort, an dem du um Code bittest. Die Beispiele verwenden einfache Sprache, damit sie über Tools hinweg funktionieren. Du kannst auch direkt einen Skill aufrufen; die Syntax variiert je nach Tool (unterstützte Tools).

Schritt 1: Erkunden

Denke die Idee mit deinem Agenten durch, bevor du nach einem Plan fragst. In deinem KI-Chat:

Help me explore how rate limiting should work in this app.

Erkunden ist ein Denkmodus. Der Agent untersucht deine Codebasis, stellt die wichtigen Fragen, skizziert Optionen und hinterfragt Annahmen. Er schreibt niemals Code. Er schreibt nichts weiter, es sei denn, du bittest ihn, das Festgelegte festzuhalten, oder sagst ja, wenn er es anbietet. Das Ergebnis ist eine schärfere Idee.

Bleib hier, solange das Problem es braucht. Wenn die Form stimmig wirkt, gib sie weiter:

Propose the change we just discussed.

Diese Zeile startet das Vorschlagen für dich und trägt alles mit, was ihr festgelegt habt. Überspringe den ersten Prompt in Schritt 2.

Schritt 2: Vorschlagen

Vorschlagen verwandelt die Idee in einen überprüfbaren Plan. Wenn du vom Erkunden kommst, läuft es bereits. Wenn du kalt startest, weil dir die Änderung klar ist, frage direkt. In deinem KI-Chat:

Propose a change to add rate limiting.

Der Agent fragt, was er braucht, und schreibt dann einen Änderungsordner:

openspec/changes/add-rate-limiting/
├── proposal.md    why, and what changes
├── specs/         what "done" means, as testable requirements
├── design.md      technical decisions (only when the change needs one)
└── tasks.md       the implementation checklist

Noch kein Code. Vorschlagen stoppt beim Plan.

Schritt 3: Plan überprüfen und korrigieren

Korrigiere den Plan, während es noch Worte sind und nichts gebaut wurde. Lies in dieser Reihenfolge:

• proposal.md: Ist das das richtige Problem, in der richtigen Größe?
• specs/: Die wertvollste Lektüre. Würdest du diese Anforderungen als erledigt akzeptieren?
• tasks.md: Decken die Aufgaben die Specs ab, und nichts weiter?

Um etwas zu korrigieren, funktioniert beides:

• Bearbeite die Datei selbst. Die Artefakte sind einfaches Markdown, und die Dateien sind der Plan.
• Sag deinem Agenten, was falsch ist ("der Spec fehlt der nicht authentifizierte Fall"). Er überarbeitet die Artefakte.

Schritt 4: Anwenden

Anwenden verwandelt den Plan in Code. Starte eine neue Chat-Sitzung, da die Implementierung in einem sauberen Kontextfenster besser läuft. In deinem KI-Chat:

Apply the add-rate-limiting change.

Der Agent liest den Änderungsordner und arbeitet dann tasks.md durch, wobei er jede Aufgabe abhakt, sobald sie umgesetzt ist.

• Unterbrochen oder Kontext erschöpft? Öffne eine neue Sitzung und bitte ihn, erneut anzuwenden. Er setzt bei der ersten nicht abgehakten Aufgabe fort.
• Plan stellt sich als falsch heraus? Korrigiere die Artefakte (auf die eine oder andere Weise aus Schritt 3) und fahre dann mit dem Anwenden fort.
• Fortschritt liegt in den tasks.md-Checkboxen. Es gibt keinen versteckten Zustand.

Schritt 5: Archivieren

Archivieren macht zwei Dinge: Es aktualisiert deine Haupt-Specs mit den Anforderungen der Änderung, und es verschiebt den Änderungsordner in das Archivverzeichnis (in /openspec/changes/archive/*).

Wenn jedes Kästchen in tasks.md abgehakt ist, in deinem KI-Chat:

Archive the add-rate-limiting change.

Gehe durch, was das Archivieren macht:

## The finished change
> Implementation is done. The delta spec (what this change adds) still sits inside the change folder; specs/ doesn't know about rate limiting yet.
  openspec/
  ├── specs/                                   (no rate-limiting spec yet)
  └── changes/
      └── add-rate-limiting/
          ├── proposal.md
          ├── tasks.md                         every box checked
          └── specs/
              └── rate-limiting/
                  └── spec.md                  the delta: ADDED requirements

## Requirements land in specs/
> Each requirement in the delta lands in the main spec: added ones append, modified ones replace their old version. A new capability gets a new spec file.
  openspec/
  ├── specs/
+ │   └── rate-limiting/
+ │       └── spec.md                          gains "Requirement: Rate limiting"
  └── changes/
      └── add-rate-limiting/
          └── specs/
              └── rate-limiting/
                  └── spec.md                  the delta, source of the merge

## The folder moves to archive/
> The whole change folder, delta included, moves into the archive under a date prefix. Nothing is deleted.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md
  └── changes/
-     └── add-rate-limiting/
+     └── archive/
+         └── 2026-08-08-add-rate-limiting/
+             ├── proposal.md
+             ├── tasks.md
+             └── specs/rate-limiting/spec.md

## Specs describe the system as built
> changes/ is clear for the next change. specs/ is the source of truth for what the system does; archive/ is the history of how it got there.
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md                          the spec as built
  └── changes/
      └── archive/
          └── 2026-08-08-add-rate-limiting/

Git ist ein separates Anliegen. Committe den Änderungsordner zusammen mit dem Code, und sonst ändert sich nichts an deinem Workflow.

Archivierte Änderungen behalten oder entfernen

openspec/changes/archive/ behält den Vorschlag, das Design, die Aufgaben und das Delta für jede abgeschlossene Änderung. Im Archiv-Ablauf oben hat das Delta bereits openspec/specs/ aktualisiert.

• Behalte den gesamten Änderungsordner, wenn du eine in sich geschlossene Aufzeichnung im aktuellen Checkout möchtest.
• Entferne den specs/-Ordner einer archivierten Änderung, wenn Git deine Spec-Historie ist. Committe zuerst das Archiv und lösche dann openspec/changes/archive/<change>/specs/. Der Vorschlag, das Design und die Aufgaben bleiben im Checkout. openspec validate --archived funktioniert weiterhin, da es die Aufgabenerledigung prüft, nicht angewendete Deltas.
• Entferne den gesamten Änderungsordner nur, wenn du seinen Vorschlag, sein Design oder seine Aufgabenhistorie im Checkout nicht mehr benötigst. Die aktuellen Specs ändern sich nicht, aber openspec validate --archived und Suchen im Checkout beziehen diese Änderung nicht mehr ein.

WARNING

Behalte den Archiv-Commit in deiner Repository-Historie, wenn Git die gelöschten Dateien behalten soll. Das Zusammenfassen des Archiv- und Cleanup-Commits entfernt diesen Zwischenstand.

OpenSpec entfernt archivierte Änderungen nicht automatisch und bietet keine Aufbewahrungseinstellung.

Weiterführendes

• Delta-Specs: wie man Verhaltensänderungen in einem Delta-Spec schreibt.
• Profile: optionale Workflows über den Kernsatz hinaus (Verifizierung vor dem Archivieren, inkrementelle Planung).

Fortgeschrittene Anleitungen

Noch nicht geschrieben; Anleitungen, die wir hinzufügen planen:

• Prototyp zuerst: Spike den Code vor jedem Spec und fülle den Vorschlag anhand der Erkenntnisse aus dem Prototyp nach.
• Iterativ bauen: eine Folge kleiner Änderungen statt eines großen Vorschlags.
• Eine implementierte Änderung überarbeiten: der Plan muss nach dem Anwenden wieder angepasst werden, aber die Änderung wurde noch nicht zusammengeführt oder archiviert.