GAIA: desarrollo spec-first para Claude Code

A quién va dirigido

GAIA se describe a sí mismo como "A serious harness for Claude Code": un andamiaje de ingeniería serio para Claude Code. Convierte «pensar bien antes de programar» en un proceso: primero la especificación (Specs before code), una puerta de calidad en cada commit y la auditoría del Code Audit Team en cada merge. Está pensado para desarrolladores que:

• usan Claude Code para desarrollo de software real y quieren que cada cambio se apoye primero en una especificación, que cada commit sea verificable y cada merge auditable, en lugar de código sin revisar producido en una sola conversación.
• aceptan las restricciones de proceso: antes de cada commit deben pasar la comprobación de tipos, el lint, las pruebas unitarias y de Storybook, Playwright E2E y una prueba de humo del servidor de desarrollo; solo con todo en verde se considera superada.
• cumplen el requisito de ejecución: Node.js >= 22.22.0.

Los siguientes casos no encajan o requieren confirmación previa:

• entornos sin Claude Code: oficialmente solo se describe como un andamiaje para Claude Code, y no se indica si sirve con otros agentes.
• escenarios en los que solo se quiere generar scripts rápido, sin especificación ni pruebas: exige escribir primero la especificación, así que el coste inicial es mayor.
• expectativas de chat genérico o de ayuda pura para escribir: la descripción oficial gira por completo en torno a las restricciones del proceso de desarrollo y no menciona otros usos.
• aparte de Node.js >= 22.22.0, no se enumeran oficialmente otras limitaciones de entorno; la compatibilidad con el sistema debe considerarse desconocida hasta confirmarla.

Primer intento en 3 minutos

Solo hay un camino principal recomendado: crear primero el proyecto con el comando oficial y luego disparar la redacción de la especificación dentro de Claude Code.

Requisito previo: tener Node.js >= 22.22.0 instalado en la máquina y poder usar Claude Code.

Instalación: ejecuta en la terminal

npx create-gaia@latest my-app

Oficialmente se exige empezar el proyecto de esta forma, no clonando ni haciendo fork del repositorio. my-app en el comando es el nombre del nuevo proyecto; consérvalo en el primer intento para evitar confusiones con directorios existentes.

Disparar la tarea: entra en el directorio my-app recién creado y escribe /gaia-spec en Claude Code. Oficialmente, esta operación redacta un artefacto SPEC inmutable mediante preguntas socráticas (Socratic discovery). Es decir, no genera un documento de inmediato: pregunta los requisitos punto por punto y solo converge en la especificación después de tus respuestas. Efectos secundarios y punto de confirmación: genera un artefacto de especificación que queda inmutable (immutable) en cuanto se crea; por eso, confirma bien los requisitos antes de cerrar el cuestionario. Para la primera vez, hazlo dentro de este proyecto recién creado, sin tocar código existente.

Señal de éxito: cuando terminan las preguntas y recibes el artefacto SPEC generado, la redacción de la especificación ha concluido. Si lo que ves son rondas de preguntas convergentes en vez de un texto completo inmediato, es exactamente el diseño: aclara los requisitos preguntando.

Casos de uso

Caso 1: fijar los requisitos antes de arrancar un proyecto nuevo. Escenario: vas a iniciar un proyecto y te preocupa que los requisitos verbales se desvíen a lo largo de varias rondas de conversación, con una dirección de implementación distinta en cada ronda. Inicio: en un proyecto creado con npx create-gaia@latest my-app, lanza /gaia-spec a Claude Code. Proceso y resultado: el agente aclara los requisitos punto por punto con preguntas socráticas y termina produciendo un artefacto SPEC inmutable; como la especificación primero es el modo de trabajo de este andamiaje, ese artefacto se convierte en la referencia común antes de escribir código. El artefacto es inmutable y la ronda de preguntas previa a su creación es el único punto de confirmación: deja claras las decisiones clave antes de responder. El nombre de archivo y la ubicación del artefacto SPEC no se indican oficialmente; el punto final verificable es el paso «se genera un artefacto inmutable».

Caso 2: hacer commit de un cambio pequeño y vivir la puerta de calidad previa al commit. Escenario: has modificado un fragmento de código en un proyecto GAIA y vas a hacer commit. Inicio: ejecuta un commit como de costumbre. Proceso y resultado: antes del commit se ejecuta una puerta de calidad —comprobación de tipos (Typecheck), lint, pruebas unitarias y de Storybook, Playwright E2E y prueba de humo del servidor de desarrollo—, y el commit solo continúa si todo pasa; con un solo fallo no se puede completar. Elige un cambio de bajo impacto para observar todo el proceso; la puerta incluye pruebas E2E y de humo que se ejecutan de verdad, así que la primera pasada suele tardar más que un commit sin puerta, y el entorno local debe poder arrancar el servidor de desarrollo. Que exista alguna forma de saltarse la puerta no se indica oficialmente.

Límites de uso

• Entorno de ejecución: el único requisito confirmado oficialmente es Node.js >= 22.22.0; no se dan otras limitaciones a nivel de sistema, así que verifica el entorno por tu cuenta antes de usarlo.
• Requisito de cliente: GAIA está orientado a Claude Code; no se indica oficialmente si funciona con otros agentes.
• Efectos secundarios y punto de confirmación: /gaia-spec genera un artefacto SPEC inmutable, con una ronda de preguntas de confirmación antes de crearlo; la puerta disparada por el commit ejecuta de verdad las pruebas, el E2E y la prueba de humo del servidor de desarrollo.
• Alcance de la puerta: las comprobaciones enumeradas oficialmente son exactamente la comprobación de tipos, el lint, las pruebas unitarias y de Storybook, Playwright E2E y la prueba de humo del servidor de desarrollo; no se indica si existen otras.
• Restricciones del sandbox: oficialmente, las reglas del sandbox bloquean la lectura de archivos .env, de archivos de claves y certificados y de archivos con nombres de credenciales (block reads of .env files, key and certificate files, credential-named files), para reducir las ocasiones en que el agente toca credenciales sensibles.
• Restricción de merge: cada merge pasa por la auditoría del Code Audit Team; la forma concreta y la duración de la auditoría no se indican oficialmente.
• Aún sin confirmar: qué operaciones existen además de /gaia-spec, dónde se guardan los SPEC, si hay interfaz gráfica y qué idiomas se admiten no aparecen en la página oficial; guíate por la documentación real del proyecto.