Das Halluzinationsproblem bei KI-Programmierassistenten: Wie man spezifikationsgetriebene Entwicklung mit OpenSpec erreicht

02.04.2026

Das Halluzinationsproblem bei KI-Programmierassistenten: Wie man spezifikationsgetriebene Entwicklung mit OpenSpec erreicht

KI-Programmierassistenten sind leistungsfaehig, aber sie generieren oft Code, der nicht zu den tatsaechlichen Anforderungen passt oder Projekt-Konventionen verletzt. Dieser Artikel teilt, wie das HagiCode-Projekt den OpenSpec-Workflow verwendet, um spezifikationsgetriebene Entwicklung umzusetzen und das Risiko von KI-Halluzinationen durch einen strukturierten Vorschlagsmechanismus erheblich zu reduzieren.

Hintergrund

Jeder, der GitHub Copilot oder ChatGPT zum Programmieren verwendet hat, hat diese Erfahrung wahrscheinlich gemacht: der von der KI generierte Code sieht auf den ersten Blick gut aus, aber sobald man ihn tatsaechlich verwendet, tauchen Probleme ueberall auf. Vielleicht verwendet er die falsche Komponente des Projekts, vielleicht ignoriert er die Coding-Standards des Teams, oder vielleicht schreibt er eine grosse Logik basierend auf Annahmen, die ueberhaupt nicht existieren.

Dies ist das sogenannte „KI-Halluzinations”-Problem. Bei der Programmierung aeussert es sich als Code, der auf den ersten Blick vernuenftig erscheint, aber tatsaechlich nicht zum realen Zustand des Projekts passt.

Es gibt noch etwas Frustrierendes daran. Je weiter KI-Programmierassistenten verbreitet werden, desto ernster wird das Problem. Schliesslich fehlt der KI das Verstaendnis fuer Projekthistorie, Architekturentscheidungen und Coding-Konventionen, und wenn ihr zu viel Freiheit gegeben wird, kann sie „kreativ” Code generieren, der nicht zur Realitaet passt. Es ist ein bisschen wie beim Schreiben eines Artikels: Ohne Struktur laeuft man leicht in Phantasie ab, obwohl die wirkliche Situation weit bodenstaendiger ist.

Um diese Schmerzpunkte zu loesen, fassten wir einen mutigen Entschluss: Anstatt zu versuchen, die KI schlauer zu machen, setzten wir sie in einen „Spezifikations”-Kaefig. Die Veraenderung, die dieser Entschluss brachte, war wahrscheinlich groesser, als Sie erwarten wuerden, und ich werde das gleich erklaeren.

Ueber HagiCode

Der in diesem Artikel geteilte Ansatz stammt aus unserer praktischen Erfahrung im HagiCode-Projekt. HagiCode ist ein Open-Source-KI-Programmierassistent-Projekt, das sich der Loesung echter Probleme in der KI-Programmierung durch strukturierte Engineering-Praktiken widmet.

Die Ursachen von KI-Halluzinationen

Bevor wir in die Loesung eintauchen, lassen Sie uns zuerst betrachten, woher das Problem wirklich kommt. Schliesslich: Wenn man sich selbst und den Gegner kennt, kann man hundert Schlachten ohne Niederlage schlagen. Auf die KI angewandt ist dieses Sprichwort ueberraschend passend.

Fehlender Kontext

KI-Modelle werden auf oeffentlichen Coderepositories trainiert, aber Ihr Projekt hat seine eigene Historie, Konventionen und Architekturentscheidungen. Die KI kann nicht direkt auf dieses „implizite Wissen” zugreifen, sodass der generierte Code oft vom tatsaechlichen Projekt losgeloest ist.

Das ist nicht ganz die Schuld der KI. Sie hat noch nie in Ihrem Projekt gelebt, wie sollte sie also alle Ihre ungeschriebenen Regeln kennen? Wie ein brandneuer Praktikant ist es normal, die oertlichen Gepflogenheiten nicht zu verstehen. Das einzige Problem ist, dass die Kosten recht hoch sein koennen.

Zu viel Freiheit

Wenn Sie die KI bitten, „Helfen Sie mir, eine Benutzer-Authentifizierungsfunktion zu implementieren”, kann sie Code in fast jeder Form generieren. Ohne klare Einschraenkungen wird die KI die Dinge auf die Weise implementieren, die sie „fuer vernuenftig” hält, anstatt den Anforderungen Ihres Projekts zu folgen.

Das ist, als wuerde man jemanden bitten, der Ihre Projektstandards nie gelernt hat, frei zu improvisieren. Wie koennte das nicht zu Problemen fuehren? Es ist nicht einmal so, dass die KI unverantwortlich waere; sie weiss einfach nicht, was Verantwortung in diesem Kontext bedeutet.

Fehlende Validierung

Nachdem die KI Code generiert hat, kann Code, der auf falschen Annahmen basiert, direkt in das Repository gelangen, wenn kein strukturierter Prüfprozess existiert. Bis das Problem beim Testen oder gar in der Produktion entdeckt wird, sind die Kosten bereits viel zu hoch.

OpenSpec: Die Antwort auf spezifikationsgetriebene Entwicklung

HagiCode waehlte OpenSpec als Loesung. Die Kernidee ist einfach: alle Codeaenderungen muessen einen strukturierten Vorschlags-Workflow durchlaufen, wodurch abstrakte Ideen in ausfuehrbare Implementierungsplaene verwandelt werden.

Das mag grossartig klingen, bedeutet in einfachen Worten aber nur, dass die KI das Anforderungsdokument schreiben muss, bevor sie den Code schreibt. Wie das alte Sprichwort sagt: Wer nicht plant, plant zu scheitern.

Was ist OpenSpec

OpenSpec ist ein npm-basiertes Kommandozeilenwerkzeug (@fission-ai/openspec), das eine standardisierte Vorschlagsdateistruktur und einen Validierungsmechanismus definiert. Kurz gesagt, es laesst die KI „das Anforderungsdokument” schreiben, bevor sie Code schreibt.

Ein dreistufiger Workflow zur Verhinderung von Halluzinationen

OpenSpec stellt die Vorschlagsqualitaet durch einen dreistufigen Workflow sicher:

Schritt 1: Proposal initialisieren - Den Sitzungszustand auf Openspecing setzen Schritt 2: Zwischenverarbeitung - Den Openspecing-Zustand beibehalten, waehrend die Artefakte schrittweise verfeinert werden Schritt 3: Proposal abschliessen - In den Reviewing-Zustand uebergehen

In diesem Design gibt es ein clevere Detail: Der erste Schritt verwendet den Typ ProposalGenerationStart, und das Abschliessen loest keine Zustandsuebergaenge aus. Dadurch wird sichergestellt, dass die Prüfungsstufe nicht zu frueh betreten wird, bevor der gesamte mehrstufige Workflow abgeschlossen ist.

Standardisierte Dateistruktur

Jeder OpenSpec-Vorschlag folgt derselben Verzeichnisstruktur:

openspec/
├── changes/                    # Aktive und archivierte Aenderungen
│   ├── {change-name}/
│   │   ├── proposal.md        # Vorschlagsbeschreibung
│   │   ├── design.md          # Designdokument
│   │   ├── specs/             # Technische Spezifikationen
│   │   └── tasks.md           # Ausfuehrbare Aufgabenliste
│   └── archive/               # Archivierte Aenderungen
└── specs/                     # Eigenstaendige Spezifikationsbibliothek

Laut Statistiken aus dem HagiCode-Projekt gibt es bereits mehr als 4.000 archivierte Aenderungen und ueber 150.000 Zeilen Spezifikationsdateien. Diese historische Akkumulation gibt der KI nicht nur klare Leitlinien, sondern stellt dem Team auch eine wertvolle Wissensbasis zur Verfuegung.

Mehrschichtiger Validierungsmechanismus

Das System implementiert mehrere Validierungsschichten, um die Vorschlagsqualitaet sicherzustellen:

// Pruefen, ob erforderliche Dateien existieren
ValidateProposalFiles()

// Voraussetzungen vor der Ausfuehrung pruefen
ValidateExecuteAsync()

// Startbedingungen pruefen
ValidateStartAsync()

// Archivierungsbedingungen pruefen
ValidateArchiveAsync()

// Vorschlagsnamenformat pruefen (kebab-case)
ValidateNameFormat()

Diese Validierungen sind wie Torwächter an mehreren Kontrollpunkten. Nur wirklich qualifizierte Vorschlaege kommen durch. Es mag muehsam aussehen, ist aber immer noch viel besser, als schlechten Code ins Repository gelangen zu lassen.

Prompt-Vorlageneinschraenkungen

Wenn die KI innerhalb von HagiCode laeuft, verwendet sie vordefinierte Handlebars-Vorlagen. Diese Vorlagen enthalten explizite Schritt-fuer-Schritt-Anweisungen und Schutzschranken. Zum Beispiel:

• Nicht fortfahren, bevor die Absicht des Nutzers verstanden ist
• Keinen nicht validierten Code generieren
• Den Nutzer bitten, den Namen erneut anzugeben, wenn er ungueltig ist
• Wenn die Aenderung bereits existiert, stattdessen die Verwendung des Continue-Befehls vorschlagen

Diese Art des „Tanzens in Fesseln” hilft der KI tatsaechlich, sich mehr auf das Verstaendnis von Anforderungen und die Generierung von Code zu konzentrieren, der Standards folgt. Einschraenkungen sind nicht immer etwas Schlechtes. Manchmal ist zu viel Freiheit genau das, was Chaos erzeugt.

Praxis: OpenSpec in einem Projekt verwenden

Installation und Initialisierung

npm install -g @fission-ai/openspec@1
openspec --version  # Installation ueberpruefen

Die Ordnerstruktur openspec/ wird automatisch im Projektstammverzeichnis erstellt.

Einen Vorschlag erstellen

In der HagiCode-Gespraechsoberflaeche verwenden Sie den Kurzbefehl:

/opsx:new

Oder geben Sie einen Aenderungsnamen und ein Ziel-Repository an:

/opsx:new "add-user-auth" --repos "repos/web"

Einen Vorschlag zu erstellen ist wie der Entwurf eines Artikels vor dem Schreiben. Sobald Sie einen Entwurf haben, wird der Rest viel einfacher.

Artefakte generieren

Verwenden Sie /opsx:continue, um die erforderlichen Artefakte schrittweise zu generieren:

proposal.md - Beschreibt den Zweck und Umfang der Aenderung design.md - Detailliertes technisches Design specs/ - Technische Spezifikationen und Testszenarien tasks.md - Ausfuehrbare Aufgabenliste

Pruefen und anwenden

Nachdem alle Artefakte fertiggestellt sind:

/opsx:apply

Die KI liest alle Kontextdateien und fuehrt die Aufgaben schrittweise gemaess der Checkliste in tasks.md aus. An diesem Punkt ist die Qualitaet des generierten Codes aufgrund der klaren Spezifikation deutlich hoeher.

Archivieren

Nach Abschluss der Aenderung:

/opsx:archive

Verschieben Sie die abgeschlossene Aenderung in das Verzeichnis archive/, sodass sie spaeter geprueft und wiederverwendet werden kann.

Hinweise und bewaehrte Praktiken

Benennungsregeln fuer Vorschlaege

Verwenden Sie kebab-case, beginnen Sie mit einem Buchstaben und schliessen Sie nur Kleinbuchstaben, Zahlen und Bindestriche ein:

• ✅ add-user-auth
• ❌ AddUserAuth
• ❌ add--user-auth

Haeufige Fehler vermeiden

1. Falschen Typ im ersten Schritt des dreistufigen Workflows verwenden - Dies fuehrt zu einem zu fruehen Zustandsuebergang
2. Vergessen, den Zustandsuebergang im letzten Schritt auszuloesen - Der Workflow bleibt im Openspecing-Zustand stecken
3. Pruefung ueberspringen und direkt ausfuehren - Sie sollten zuerst validieren, ob alle Artefakte vollstaendig sind

Session-Zustandsautomat verstehen

Das Verstehen von Zustandsuebergaengen hilft bei der Fehlerbehebung:

Init → Drafting → Openspecing → Reviewing → Executing → ExecutionCompleted → Completed → Archived

• Openspecing: Plan wird generiert
• Reviewing: Unter Pruefung (Artefakte koennen wiederholt ueberarbeitet werden)
• Executing: In Ausfuehrung (tasks.md wird angewendet)

Zusammenfassung

Durch den OpenSpec-Workflow hat das HagiCode-Projekt erhebliche Ergebnisse bei der Bewaeltigung des KI-Halluzinationsproblems erzielt:

1. Weniger Halluzinationen - Die KI muss einer strukturierten Spezifikation folgen, anstatt willkuerlich Code zu generieren
2. Hoehere Qualitaet - Mehrschichtige Validierung stellt sicher, dass Aenderungen den Projektstandards entsprechen
3. Schnellere Zusammenarbeit - Archivierte Aenderungen bieten Referenzen fuer kuenftige Entwicklung
4. Nachvollziehbarkeit - Jede Aenderung hat einen vollstaendigen Datensatz von Vorschlag, Design, Spezifikation und Aufgaben

Dieser Ansatz macht die KI nicht schlauer. Er setzt die KI in einen „Spezifikations”-Kaefig. Die Praxis hat gezeigt, dass Tanzen in Fesseln tatsaechlich zu einer besseren Leistung fuehren kann.

Das Prinzip ist einfach. Einschraenkungen sind nicht unbedingt schlecht. Wie beim Schreiben fuehrt ein Format, dem man folgen kann, oft zu besseren Ergebnissen.

Wenn Sie ebenfalls KI-Programmierassistenten verwenden und auf aehnliche Probleme gestossen sind, probieren Sie OpenSpec aus. Spezifikationsgetriebene Entwicklung mag zusaetzliche Schritte bedeuten, aber diese fruehe Investition zahlt sich in der Codequalitaet und Wartungseffizienz vielfach aus.

Manchmal ist es tatsaechlich der schnellste Weg nach vorne, ein wenig langsamer zu werden.

Referenzmaterialien

• OpenSpec npm-Paket: www.npmjs.com/package/@fission-ai/openspec
• HagiCode-Projekt-Repository: github.com/HagiCode-org/site
• HagiCode offizielle Website: hagicode.com
• 30-minütiges praktisches Demo ansehen: www.bilibili.com/video/BV1pirZBuEzq/
• Ein-Klick-Installation mit Docker Compose: docs.hagicode.com/installation/docker-compose
• Schnellinstallation fuer Desktop: hagicode.com/desktop/

---

Wenn Ihnen dieser Artikel geholfen hat, geben Sie uns gerne einen Star auf GitHub. Die oeffentliche Beta von HagiCode hat bereits begonnen, und Sie koennen der Erfahrung beitreten, indem Sie sie jetzt installieren.

---

Das reicht fuer diesen Artikel. Es gibt nichts besonders Tiefgründiges hier, nur eine Zusammenfassung einiger praktischer Lektionen. Ich hoffe, es ist nuetzlich fuer alle. Teilen ist eine gute Sache: Man lernt selbst etwas, und andere lernen auch etwas.

Dennoch ist ein Artikel nur ein Artikel. Praxis ist es, was wirklich zaehlt.

Copyright-Hinweis

Vielen Dank fuer das Lesen. Wenn Sie diesen Artikel nuetzlich fanden, koennen Sie ihn gerne liken, speichern und teilen. Dieser Inhalt wurde mit KI-unterstuetzter Zusammenarbeit erstellt, die endgueltige Version wurde vom Autor geprueft und genehmigt.

• Autor: newbe36524
• Originallink: https://docs.hagicode.com/blog/2026-04-02-ai-coding-assistant-hallucination-openspec-spec-driven-development/
• Copyright: Sofern nicht anders angegeben, sind alle Artikel auf diesem Blog unter BY-NC-SA lizenziert. Bitte geben Sie beim Weiterveröffentlichen die Quelle an.

Tags:

• AI coding
• OpenSpec
• Specification-driven development
• HagiCode
• Development workflow

Hermes installieren und verwenden: Ein Schnellstart von der lokalen CLI bis zur Feishu-Integration