O que é Spec-Driven Development (e por que abandonamos o vibe coding)

Existe uma forma de trabalhar com IA que parece produtiva, mas não é. Você escreve para o modelo "faça um formulário de cadastro", olha o que ele devolve, não gosta, diz "não, assim não", olha de novo, corrige mais uma vez. Você avança aos trancos. Isso se chama vibe coding: pedir à máquina para ver o que sai e negociar com o resultado. Funciona para um brinquedo. Desmorona no instante em que há algo real em jogo.

A falha não está no modelo nem no seu prompt. Está na ordem. Você começou pela execução sem ter escrito o que era "correto". Sem esse contrato prévio, qualquer saída é defensável e nenhuma é verificável. Na Qirava abandonamos essa forma de trabalhar e adotamos outra: primeiro a especificação, depois a execução. Chama-se Spec-Driven Development, SDD.

01 · a viradaA especificação primeiro, a execução depois

Spec-Driven Development significa exatamente o que diz: o desenvolvimento é conduzido pela especificação, não pelo impulso. Antes que um agente ou uma pessoa toque em qualquer coisa, existe um documento que fixa o que se quer, para quem, com que limites e como se saberá que ficou bom. Esse documento não é burocracia: é a fonte da verdade que governa tudo o que vem depois.

A diferença em relação ao prompting básico é de raiz. O prompt básico descreve uma tarefa solta e espera uma saída. A spec descreve o resultado esperado e os critérios de aceitação, e então a execução é medida contra ela. No vibe coding, você é o critério (o que você gostar passa). No SDD, o critério está escrito antes e independe do seu humor no dia.

No vibe coding, o critério de "correto" é você. No SDD, ele está escrito antes de começar.

Não é uma ideia nova da era da IA. A Amazon trabalha há mais de duas décadas "de trás para frente" (working backwards): antes de construir um produto, escreve-se o comunicado de imprensa e as perguntas frequentes que ele teria no dia do lançamento [1]. Primeiro se redige o resultado, e só se esse resultado convence é que se constrói. O SDD toma essa disciplina e a coloca na frente do desenvolvimento assistido por modelos.

02 · o governoA spec governa os agentes, e as comportas travam o prematuro

Na Qirava a spec não é um arquivo que alguém lê e esquece. É o que governa os agentes. Cada agente nasce sob governança: ao iniciar, carrega uma skill universal (qirava-llm-governance) mais a skill do seu papel. Ninguém executa "a seu critério".

Os papéis são pacotes de skills com uma estrutura fixa: uma universal que todos compartilham, uma primária própria do papel, secundárias de apoio e uma lista de skills proibidas para aquele papel. Assim, natalia.marketing.ai escreve campanhas mas não aprova arquitetura; santiago.architect.ai define estrutura mas não certifica qualidade; sofia.qa-sprint.ai valida; martin.legal.ai, beatriz.ciso.ai e marcos.scrum.ai cobrem o que lhes cabe; e libaniel.ceo.human aprova. Cada agente sabe o que pode fazer e o que lhe é vedado antes de mover um dedo.

Mas escrever a spec não basta: é preciso impedir que algo verde chegue longe. Para isso existem as comportas de maturidade. Nada avança sem passar pela sua. Um elemento nasce G0 (especificada). Só se passar na validação chega a G1 (rascunho). Só com aprovação do CEO chega a G2 (operativa). E o que aspira a decidir de forma ampla sobe a G3 (conselho). Não há atalhos: cada comporta é um filtro real.

03 · a mecânicaComo se sustenta no dia a dia: índice, skills e QA com regressão

Uma spec sem uma fonte de verdade se dispersa em versões que se contradizem. Por isso o método se apoia num DOCUMENT_INDEX: o índice documental que diz qual é o documento válido de cada coisa. As skills vivem num toolkit; o governo vive num vault; e os projetos as consomem por symlink, sem copiar nem bifurcar. Um só lugar manda; o resto aponta para ele.

A última peça é a qualidade. No SDD, QA não é apertar um botão até que "passe". É um ciclo com regressão profissional: testa-se, registram-se achados, corrigem-se, e testa-se de novo todo o conjunto, não só o que falhou, até certificar. Não se fazem retestes sob medida para dar verde. Certifica-se contra a spec ou não se certifica. Como a spec fixou de antemão o que era "correto", o QA tem um padrão contra o qual medir, e essa é justamente a peça que o vibe coding nunca teve.

Sem spec, o QA não tem contra o que medir. Com spec, "correto" deixou de ser uma opinião.

Junte as três partes e vê-se a mudança completa. A spec fixa o resultado antes de começar. O governo delimita o que cada agente pode fazer e as comportas travam o que não está maduro. O índice mantém uma só verdade e o QA certifica contra ela com regressão. Nada disso existe quando você pede a um modelo "para ver o que sai".

Por isso abandonamos o vibe coding. Não porque a IA seja ruim escrevendo, mas porque um resultado sem especificação não se pode governar, nem verificar, nem repetir. Da próxima vez que for pedir algo a um modelo, tente escrever primeiro, em duas linhas, o que seria estar pronto. Essa linha, não o prompt, é a que muda o que sai.