GAIA: A Spec-First Development Harness for Claude Code

Who It's For

GAIA describes itself as "A serious harness for Claude Code": a serious engineering harness for Claude Code. It turns "think it through before you build" into process — specs before code, a quality gate on every commit, and a Code Audit Team review on every merge. It suits developers who:

• Use Claude Code for real software development and want every change backed by a spec first, verifiable commits, and auditable merges — not unchecked code produced in a single conversation.
• Are willing to accept process constraints: before each commit, typecheck, lint, unit and Storybook tests, Playwright E2E, and a dev-server smoke test must all pass; only when everything passes does the commit go through.
• Meet the runtime prerequisite: Node.js >= 22.22.0.

The following cases are a poor fit or need confirmation first:

• Environments without Claude Code: officially it is described only as a harness for Claude Code, and whether it works with other agents is not stated.
• Situations where you just want to generate scripts quickly, without a spec and test process: it requires writing a spec first, so the upfront cost is higher.
• Expectations of general chat or pure writing assistance: the official description revolves entirely around development process constraints and mentions no other uses.
• Apart from Node.js >= 22.22.0, no other environment limits are listed officially; system compatibility should be treated as unknown until confirmed.

First Attempt in 3 Minutes

There is exactly one recommended main path: create the project with the official command first, then trigger spec authoring inside Claude Code.

Prerequisite: Node.js >= 22.22.0 installed locally and access to Claude Code.

Install: run in a terminal

npx create-gaia@latest my-app

The official guidance is explicit that projects should start this way, not by cloning or forking the repository. my-app in the command is the name of the new project; keep it for the first attempt to avoid confusion with existing directories.

Trigger the task: enter the newly created my-app directory and type /gaia-spec in Claude Code. Officially, this operation authors an immutable SPEC artifact through Socratic discovery. In other words, it does not generate a document right away; it asks about your requirements item by item and only converges the answers into a spec after you have responded. Side effects and confirmation point: it generates a spec artifact that becomes immutable once created, so confirm your requirements clearly before wrapping up the questioning; do the first run inside this brand-new project and do not touch existing code.

Success signal: when the questioning ends and you receive the generated SPEC artifact, the spec-authoring flow is complete. If what you see along the way is round after round of converging questions rather than an immediate full document, that is exactly the design — it clarifies requirements by asking.

Use Cases

Case 1: Pin down requirements before a new project starts. Scenario: You are starting a new project and worry that verbal requirements will drift across multiple conversation rounds, with a different implementation direction each round. Initiation: In a project created with npx create-gaia@latest my-app, issue /gaia-spec to Claude Code. Process and result: The agent clarifies requirements item by item through Socratic questioning and finally produces an immutable SPEC artifact; because specs-before-code is how this harness works, that artifact becomes the consistent baseline before any later coding. The artifact is immutable, and the questioning before generation is the only confirmation point — settle the key decisions before you answer. The file name and storage location of the SPEC artifact are not stated officially; the confirmable endpoint is the step "an immutable artifact is generated".

Case 2: Commit a small change and experience the pre-commit quality gate. Scenario: You have modified one piece of code in a GAIA project and are about to commit. Initiation: Run one commit as part of your normal workflow. Process and result: Before the commit, a quality gate runs — typecheck, lint, unit and Storybook tests, Playwright E2E, and a dev-server smoke test — and the commit can only proceed when everything passes; a single failure makes the commit impossible to complete. Pick a low-impact change so you can observe the whole gate; the gate includes E2E and smoke tests that actually run, so the first run usually takes longer than a commit without a gate, and your local environment must be able to start the dev server. Whether the gate can be skipped is not stated officially.

Boundaries

• Runtime environment: the only officially confirmed requirement is Node.js >= 22.22.0; no other system-level limits are given, so verify your environment yourself before use.
• Client prerequisite: GAIA targets Claude Code; whether it works with other agents is not stated officially.
• Side effects and confirmation point: /gaia-spec generates an immutable SPEC artifact, with a questioning step to confirm before generation; the gate triggered by a commit actually runs tests, E2E, and a dev-server smoke test.
• Gate scope: the checks officially listed are exactly typecheck, lint, unit and Storybook tests, Playwright E2E, and the dev-server smoke test; whether other checks exist is not stated.
• Sandbox restrictions: officially, sandbox rules block reads of .env files, key and certificate files, and credential-named files, reducing the agent's chances of touching sensitive credentials.
• Merge constraint: every merge goes through a Code Audit Team review; the concrete form and duration of the audit are not stated officially.
• Not yet confirmed: which operations exist beyond /gaia-spec, where SPEC artifacts are stored, whether there is a GUI, and the range of supported languages are all absent from the official page — rely on the actual documentation inside the project.