GAIA: Der Spec-First-Entwicklungsharness für Claude Code

Für wen es geeignet ist

GAIA beschreibt sich selbst als "A serious harness for Claude Code": ein ernsthafter Engineering-Harness für Claude Code. Es macht „erst klar denken, dann bauen“ zum Prozess — Specs vor dem Code (Specs before code), ein Qualitätsgate bei jedem Commit, das Code Audit Team bei jedem Merge. Geeignet ist es für Entwickler, die:

• mit Claude Code echte Softwareentwicklung betreiben und wollen, dass jede Änderung zuerst auf einem Spec beruht, jeder Commit überprüfbar und jeder Merge auditierbar ist — statt Code, der in einer einzigen Konversation ungeprüft entsteht.
• bereit sind, Prozessschranken zu akzeptieren: Vor jedem Commit müssen Typcheck, Lint, Unit- und Storybook-Tests, Playwright E2E und ein Smoke-Test des Dev-Servers bestehen; erst wenn alles besteht, zählt der Commit als bestanden.
• die Laufzeitvoraussetzung erfüllen: Node.js >= 22.22.0.

In folgenden Fällen ungeeignet oder erst nach Rückfrage:

• Umgebungen ohne Claude Code: Offiziell wird es nur als Harness für Claude Code beschrieben; die Nutzung mit anderen Agents ist nicht angegeben.
• Situationen, in denen nur schnell Skripte erzeugt werden sollen, ohne Spec- und Testprozess: Es verlangt, zuerst einen Spec zu schreiben — der Vorlaufaufwand ist höher.
• Erwartungen an allgemeinen Chat oder reine Schreibhilfe: Die offizielle Beschreibung dreht sich ausschließlich um Einschränkungen des Entwicklungsprozesses; andere Verwendungszwecke werden nicht genannt.
• Neben Node.js >= 22.22.0 werden offiziell keine weiteren Umgebungseinschränkungen aufgeführt; die Systemkompatibilität gilt bis zur Bestätigung als unbekannt.

Erster Versuch in 3 Minuten

Empfohlen wird genau ein Hauptweg: zuerst das Projekt mit dem offiziellen Befehl anlegen, dann in Claude Code die Spec-Erstellung auslösen.

Voraussetzung: Node.js >= 22.22.0 ist lokal installiert und Claude Code ist verfügbar.

Installation: im Terminal ausführen

npx create-gaia@latest my-app

Offiziell wird ausdrücklich verlangt, Projekte auf diese Weise zu beginnen — nicht durch Klonen oder Forken des Repositorys. my-app im Befehl ist der Name des neuen Projekts; beim ersten Versuch den Namen beizubehalten, um Verwechslungen mit bestehenden Verzeichnissen zu vermeiden.

Aufgabe auslösen: In das neu angelegte my-app-Verzeichnis wechseln und in Claude Code /gaia-spec eingeben. Offiziell wird dieser Vorgang so beschrieben, dass er durch sokratisches Nachfragen (Socratic discovery) ein unveränderliches SPEC-Artefakt erstellt. Das heißt: Es erzeugt nicht sofort ein Dokument, sondern fragt die Anforderungen Punkt für Punkt ab und fasst die Antworten erst zusammen, nachdem du geantwortet hast, zu einem Spec. Nebenwirkung und Bestätigungspunkt: Es erzeugt ein Spec-Artefakt, das nach der Erzeugung unveränderlich (immutable) ist. Bestätige die Anforderungen daher vollständig, bevor du den Frageprozess abschließt; führe den ersten Durchlauf in diesem frischen Projekt aus und fasse bestehenden Code nicht an.

Erfolgssignal: Wenn das Frageverfahren endet und du das erzeugte SPEC-Artefakt vor dir hast, ist der Spec-Prozess abgeschlossen. Wenn du unterwegs mehrere Runden konvergierender Nachfragen siehst statt sofort den Volltext — genau das ist die Absicht: Es klärt Anforderungen durch Nachfragen.

Anwendungsfälle

Fall 1: Anforderungen vor Projektbeginn festschreiben. Szenario: Du startest ein neues Projekt und fürchtest, dass mündliche Anforderungen über mehrere Gesprächsrunden abdriften und jede Runde eine andere Umsetzungsrichtung liefert. Start: In einem mit npx create-gaia@latest my-app erzeugten Projekt gibst du in Claude Code /gaia-spec ein. Ablauf und Ergebnis: Der Agent klärt die Anforderungen Punkt für Punkt durch sokratisches Nachfragen und erzeugt am Ende ein unveränderliches SPEC-Artefakt; weil Specs-vor-Code die Arbeitsweise dieses Harness ist, wird das Artefakt zur verbindlichen Grundlage vor jeder späteren Programmierung. Das Artefakt ist unveränderlich, und die Fragerunde vor der Erzeugung ist der einzige Bestätigungspunkt — kläre die wichtigen Entscheidungen, bevor du antwortest. Dateiname und Ablageort des SPEC-Artefakts nennt die offizielle Seite nicht; der bestätigbare Endpunkt ist der Schritt „ein unveränderliches Artefakt wird erzeugt“.

Fall 2: Eine kleine Änderung committen und das Qualitätsgate vor dem Commit erleben. Szenario: Du hast in einem GAIA-Projekt eine Stelle im Code geändert und willst committen. Start: Führe wie gewohnt einen Commit aus. Ablauf und Ergebnis: Vor dem Commit läuft ein Qualitätsgate — Typcheck, Lint, Unit- und Storybook-Tests, Playwright E2E und ein Smoke-Test des Dev-Servers; der Commit geht nur weiter, wenn alles besteht, und scheitert vollständig, sobald ein Punkt durchfällt. Wähle am besten eine Änderung mit geringer Wirkung, um den Gesamtablauf des Gates zu beobachten; das Gate enthält E2E- und Smoke-Tests, die wirklich ausgeführt werden, daher dauert der erste Lauf meist länger als ein Commit ohne Gate, und die lokale Umgebung muss den Dev-Server starten können. Ob es einen Weg gibt, das Gate zu überspringen, ist offiziell nicht angegeben.

Grenzen der Nutzung

• Laufzeitumgebung: Als einzige offiziell bestätigte Anforderung gilt Node.js >= 22.22.0; weitere systemseitige Einschränkungen werden nicht genannt — prüfe die Umgebung vor der Nutzung selbst.
• Client-Voraussetzung: GAIA zielt auf Claude Code; ob es mit anderen Agents funktioniert, ist offiziell nicht angegeben.
• Nebenwirkungen und Bestätigungspunkt: /gaia-spec erzeugt ein unveränderliches SPEC-Artefakt, mit einer Fragerunde zur Bestätigung vor der Erzeugung; das durch Commits ausgelöste Gate führt Tests, E2E und den Dev-Server-Smoke-Test tatsächlich aus.
• Umfang des Gates: Die offiziell gelisteten Prüfungen sind genau Typcheck, Lint, Unit- und Storybook-Tests, Playwright E2E sowie der Dev-Server-Smoke-Test; ob es weitere Prüfungen gibt, ist nicht angegeben.
• Sandbox-Beschränkungen: Offiziell blockieren die Sandbox-Regeln das Lesen von .env-Dateien, Schlüssel- und Zertifikatsdateien sowie nach Zugangsdaten benannten Dateien (block reads of .env files, key and certificate files, credential-named files), um dem Agenten Zugänge zu sensiblen Zugangsdaten zu nehmen.
• Merge-Beschränkung: Bei jedem Merge prüft das Code Audit Team; Form und Dauer des Audits sind offiziell nicht angegeben.
• Noch unbestätigt: Welche Vorgänge es außer /gaia-spec gibt, wo SPEC-Artefakte gespeichert werden, ob es eine grafische Oberfläche gibt und welche Sprachen unterstützt werden — all das fehlt auf der offiziellen Seite; maßgeblich sind die tatsächlichen Hinweise im Projekt.