GAIA : développement spec-first pour Claude Code

À qui il s'adresse

GAIA se décrit lui-même comme "A serious harness for Claude Code" : un harnais d'ingénierie sérieux pour Claude Code. Il transforme « bien penser avant de coder » en processus — les specs avant le code (Specs before code), une barrière de qualité à chaque commit, et l'équipe Code Audit Team à chaque merge. Il convient aux développeurs qui :

• utilisent Claude Code pour du vrai développement logiciel et veulent que chaque changement s'appuie d'abord sur une spec, que chaque commit soit vérifiable et chaque merge auditable — plutôt que du code non vérifié produit en une seule conversation ;
• acceptent les contraintes de processus : avant chaque commit, la vérification des types, le lint, les tests unitaires et Storybook, Playwright E2E et un test de fumée du serveur de développement doivent tous passer ;
• remplissent le prérequis d'exécution : Node.js >= 22.22.0.

Les cas suivants ne conviennent pas ou exigent une confirmation préalable :

• les environnements sans Claude Code : il n'est officiellement décrit que comme un harnais pour Claude Code, et son usage avec d'autres agents n'est pas précisé ;
• les situations où l'on veut juste générer rapidement des scripts, sans spec ni tests : il impose d'écrire une spec d'abord, ce qui coûte plus cher en amont ;
• l'attente d'un chat généraliste ou d'une aide à la rédaction : la description officielle ne porte que sur les contraintes du processus de développement, sans mention d'autres usages ;
• au-delà de Node.js >= 22.22.0, aucune autre limite d'environnement n'est listée officiellement ; la compatibilité système doit être considérée comme inconnue tant qu'elle n'est pas confirmée.

Première tentative en 3 minutes

Le chemin principal recommandé est unique : créer d'abord le projet avec la commande officielle, puis déclencher la rédaction de la spec dans Claude Code.

Prérequis : Node.js >= 22.22.0 installé en local et accès à Claude Code.

Installation : exécuter dans un terminal

npx create-gaia@latest my-app

Officiellement, il faut commencer le projet de cette façon, et non en clonant ou en forkant le dépôt. my-app dans la commande est le nom du nouveau projet ; conservez-le pour la première tentative afin d'éviter toute confusion avec des dossiers existants.

Déclencher la tâche : entrez dans le dossier my-app fraîchement créé et tapez /gaia-spec dans Claude Code. Officiellement, cette commande rédige un artefact SPEC immuable via un questionnement socratique (Socratic discovery). Autrement dit, elle ne produit pas un document d'emblée : elle interroge les exigences point par point et ne converge vers une spec qu'après vos réponses. Effets de bord et point de confirmation : elle génère un artefact de spec qui devient immuable (immutable) dès sa création ; assurez-vous donc d'avoir bien validé vos exigences avant de clore le questionnement. Pour la première fois, faites-le dans ce projet tout neuf, sans toucher au code existant.

Signal de succès : quand les questions s'arrêtent et que vous recevez l'artefact SPEC généré, la rédaction de la spec est terminée. Si vous voyez défiler des rounds de questions convergentes plutôt qu'un texte complet immédiat, c'est voulu : l'outil clarifie les exigences en posant des questions.

Cas d'usage

Cas 1 : figer les exigences avant de démarrer un nouveau projet. Scénario : vous lancez un nouveau projet et craignez que des exigences formulées à l'oral ne dérivent au fil des tours de conversation, avec une direction d'implémentation différente à chaque tour. Lancement : dans un projet créé avec npx create-gaia@latest my-app, envoyez /gaia-spec à Claude Code. Déroulé et résultat : l'agent clarifie les exigences point par point par questionnement socratique et produit finalement un artefact SPEC immuable ; puisque la spec d'abord est la façon de travailler de ce harnais, cet artefact devient la base commune avant toute écriture de code. L'artefact est immuable et la phase de questions précédant sa génération est le seul point de confirmation : tranchez les décisions clés avant de répondre. Le nom de fichier et l'emplacement de l'artefact SPEC ne sont pas précisés officiellement ; le terminus vérifiable est l'étape « un artefact immuable est généré ».

Cas 2 : commiter une petite modification et vivre la barrière de qualité avant commit. Scénario : vous avez modifié un morceau de code dans un projet GAIA et vous vous apprêtez à commiter. Lancement : effectuez un commit comme d'habitude. Déroulé et résultat : avant le commit, une barrière de qualité s'exécute — vérification des types (Typecheck), lint, tests unitaires et Storybook, Playwright E2E, test de fumée du serveur de développement — et le commit ne peut poursuivre que si tout passe ; un seul échec empêche de le finaliser. Choisissez de préférence une modification à faible impact pour observer l'ensemble du processus ; la barrière inclut des tests E2E et de fumée réellement exécutés, donc le premier passage prend généralement plus de temps qu'un commit sans barrière, et l'environnement local doit pouvoir démarrer le serveur de développement. L'existence d'un moyen de contourner la barrière n'est pas documentée officiellement.

Limites d'usage

• Environnement d'exécution : la seule exigence officiellement confirmée est Node.js >= 22.22.0 ; aucune autre limite système n'est donnée, vérifiez l'environnement vous-même avant usage.
• Prérequis client : GAIA cible Claude Code ; la compatibilité avec d'autres agents n'est pas précisée officiellement.
• Effets de bord et point de confirmation : /gaia-spec génère un artefact SPEC immuable, précédé d'une phase de questions de confirmation ; la barrière déclenchée par le commit exécute réellement les tests, l'E2E et le test de fumée du serveur de développement.
• Périmètre de la barrière : les contrôles officiellement listés sont exactement la vérification des types, le lint, les tests unitaires et Storybook, Playwright E2E et le test de fumée du serveur de développement ; rien n'indique s'il existe d'autres contrôles.
• Restrictions du bac à sable : officiellement, les règles du bac à sable bloquent la lecture des fichiers .env, des fichiers de clés et de certificats et des fichiers nommés d'après des identifiants (block reads of .env files, key and certificate files, credential-named files), afin de réduire les occasions pour l'agent d'accéder à des secrets sensibles.
• Contrainte de merge : chaque merge passe par l'audit du Code Audit Team ; la forme concrète et la durée de l'audit ne sont pas précisées officiellement.
• Pas encore confirmé : les opérations au-delà de /gaia-spec, l'emplacement de stockage des SPEC, l'existence d'une interface graphique et l'étendue des langues prises en charge sont absents de la page officielle ; fiez-vous à la documentation réelle du projet.