GAIA: desenvolvimento spec-first para Claude Code

Para quem é

O GAIA se descreve como "A serious harness for Claude Code": um arcabouço de engenharia sério para o Claude Code. Ele transforma "pensar bem antes de programar" em processo — a especificação antes do código (Specs before code), uma porta de qualidade em cada commit e a auditoria do Code Audit Team em cada merge. Ele serve a desenvolvedores que:

• usam o Claude Code para desenvolvimento de software de verdade e querem que cada mudança tenha antes uma base na especificação, commits verificáveis e merges auditáveis, em vez de código sem checagem produzido em uma única conversa.
• aceitam as restrições de processo: antes de cada commit precisam passar a verificação de tipos, o lint, os testes unitários e do Storybook, o Playwright E2E e um teste de fumaça do servidor de desenvolvimento; só com tudo passando vale como aprovado.
• atendem ao pré-requisito de execução: Node.js >= 22.22.0.

Os casos a seguir não servem ou exigem confirmação prévia:

• ambientes sem o Claude Code: oficialmente ele é descrito apenas como um arcabouço para o Claude Code, e o uso com outros agentes não é informado.
• cenários em que você só quer gerar scripts rápido, sem especificação nem testes: ele exige escrever a especificação primeiro, então o custo inicial é maior.
• expectativa de chat genérico ou de ajuda pura de escrita: a descrição oficial gira inteiramente em torno das restrições do processo de desenvolvimento e não menciona outros usos.
• além de Node.js >= 22.22.0, nenhuma outra limitação de ambiente é listada oficialmente; a compatibilidade com o sistema deve ser tratada como desconhecida até ser confirmada.

Primeira tentativa em 3 minutos

O caminho principal recomendado é um só: primeiro criar o projeto com o comando oficial e depois disparar a escrita da especificação dentro do Claude Code.

Pré-requisito: ter o Node.js >= 22.22.0 instalado na máquina e poder usar o Claude Code.

Instalação: execute no terminal

npx create-gaia@latest my-app

Oficialmente, é exigido começar o projeto assim, e não clonando ou fazendo fork do repositório. O my-app no comando é o nome do novo projeto; mantenha esse nome na primeira tentativa para evitar confusão com diretórios existentes.

Disparar a tarefa: entre no diretório my-app recém-criado e digite /gaia-spec no Claude Code. Oficialmente, essa operação redige um artefato SPEC imutável por meio de perguntas socráticas (Socratic discovery). Ou seja, ela não gera um documento de imediato: questiona os requisitos item a item e só converge para a especificação depois das suas respostas. Efeitos colaterais e ponto de confirmação: ela gera um artefato de especificação que se torna imutável (immutable) assim que criado; por isso, confirme bem os requisitos antes de encerrar as perguntas. Na primeira vez, faça isso dentro desse projeto novinho, sem tocar no código existente.

Sinal de sucesso: quando as perguntas terminam e você recebe o artefato SPEC gerado, a escrita da especificação está concluída. Se o que você vê são rodadas de perguntas convergentes em vez de um texto completo imediato, esse é justamente o desenho: ele esclarece os requisitos perguntando.

Casos de uso

Caso 1: fixar requisitos antes de começar um projeto novo. Cenário: você vai iniciar um projeto e teme que requisitos passados verbalmente se desviem ao longo de várias rodadas de conversa, com uma direção de implementação diferente a cada rodada. Início: em um projeto criado com npx create-gaia@latest my-app, envie /gaia-spec ao Claude Code. Processo e resultado: o agente esclarece os requisitos item a item com perguntas socráticas e no fim produz um artefato SPEC imutável; como a especificação primeiro é o modo de trabalhar deste arcabouço, esse artefato vira a base comum antes de escrever código. O artefato é imutável, e a rodada de perguntas anterior à criação é o único ponto de confirmação: resolva as decisões-chave antes de responder. O nome de arquivo e o local de armazenamento do artefato SPEC não são informados oficialmente; o ponto final verificável é a etapa "um artefato imutável é gerado".

Caso 2: fazer commit de uma mudança pequena e viver a porta de qualidade anterior ao commit. Cenário: você alterou um trecho de código em um projeto GAIA e vai fazer commit. Início: execute um commit como de costume. Processo e resultado: antes do commit roda uma porta de qualidade — verificação de tipos (Typecheck), lint, testes unitários e do Storybook, Playwright E2E e teste de fumaça do servidor de desenvolvimento — e o commit só segue se tudo passar; um único fracasso impede concluí-lo. Escolha uma mudança de baixo impacto para observar todo o processo; a porta inclui testes E2E e de fumaça que rodam de verdade, então a primeira execução costuma demorar mais que um commit sem porta, e o ambiente local precisa conseguir subir o servidor de desenvolvimento. Se existe alguma forma de pular a porta, não é informado oficialmente.

Limites de uso

• Ambiente de execução: o único requisito confirmado oficialmente é o Node.js >= 22.22.0; não há outras limitações de sistema informadas, então verifique o ambiente por conta própria antes de usar.
• Pré-requisito de cliente: o GAIA é voltado ao Claude Code; o uso com outros agentes não é informado oficialmente.
• Efeitos colaterais e ponto de confirmação: /gaia-spec gera um artefato SPEC imutável, com uma rodada de perguntas de confirmação antes da criação; a porta disparada pelo commit executa de fato os testes, o E2E e o teste de fumaça do servidor de desenvolvimento.
• Escopo da porta: as verificações listadas oficialmente são exatamente verificação de tipos, lint, testes unitários e do Storybook, Playwright E2E e teste de fumaça do servidor de desenvolvimento; não se informa se há outras.
• Restrições do sandbox: oficialmente, as regras do sandbox bloqueiam a leitura de arquivos .env, de arquivos de chaves e certificados e de arquivos com nomes de credenciais (block reads of .env files, key and certificate files, credential-named files), para reduzir as chances de o agente tocar em credenciais sensíveis.
• Restrição de merge: todo merge passa pela auditoria do Code Audit Team; a forma concreta e a duração da auditoria não são informadas oficialmente.
• Ainda não confirmado: quais operações existem além de /gaia-spec, onde os SPEC ficam guardados, se há interface gráfica e quais idiomas são aceitos não aparecem na página oficial; guie-se pelas instruções reais dentro do projeto.