Do prompt ao spec: como uma especificação governa os agentes

Você pede a um agente "faça o módulo de faturamento" e ele te devolve algo. Funciona pela metade, inventou uma regra que ninguém pediu e apagou outra que importava de verdade. O modelo não falhou: falhou a encomenda. Você deu a ele um desejo, não um contrato. Essa é a diferença entre um prompt e uma especificação, e é a linha que separa o vibe coding do trabalho governado.

Na Qirava paramos de pedir à IA "vamos ver no que dá". Não escrevemos prompts soltos na esperança de que o modelo adivinhe certo. Primeiro escrevemos o spec: o que vai ser construído, com que critérios se aceita e o que fica de fora. Depois, e só depois, executa. A esse método chamamos SDD, Spec-Driven Development: a especificação manda, a execução obedece.

01 · o problemaUm prompt pede, um spec governa

Um prompt é um pedido em linguagem natural. É rápido, flexível e ambíguo por design. Serve para explorar, para perguntar, para tatear. Mas a ambiguidade que o torna cômodo é a mesma que o torna perigoso quando o resultado precisa estar correto: o modelo preenche as lacunas que você deixou, e as preenche pelo critério dele, não pelo seu.

Um spec é outra coisa. É um documento que fixa o contrato: o escopo (o que entra e o que não entra), as entradas e saídas esperadas, as regras de negócio e, acima de tudo, os critérios de aceitação, aquelas condições verificáveis que decidem se o trabalho está certo ou errado. Um prompt se responde. Um spec se cumpre ou não se cumpre, e isso dá para comprovar.

O prompt te dá o que o modelo acha que você quis. O spec exige o que você definiu.

A diferença não é de formato, é de poder. Quando um agente recebe um prompt, a fonte de verdade vive na cabeça de quem o escreveu. Quando recebe um spec, a fonte de verdade é um documento que ambos podem citar, revisar e auditar. Essa ideia de "escreva primeiro o resultado desejado, depois construa de trás para frente" não fomos nós que inventamos: é o coração do método working backwards da Amazon, onde um produto começa pelo seu comunicado de imprensa e suas perguntas frequentes antes de existir uma única linha de código [1].

02 · a governançaO spec governa o agente, não o contrário

Aqui está a virada que muda tudo: na Qirava, cada agente nasce sob governança. Não é um assistente genérico ao qual você joga um prompt. Ao iniciar, carrega duas coisas: uma skill universal, qirava-llm-governance, que fixa as regras do jogo para todos, e a skill do seu papel, que lhe dá o seu ofício.

Os papéis se montam como pacotes de skills com quatro camadas: universal, primária, secundária e proibida. Essa última camada importa tanto quanto as outras: define o que aquele agente não pode fazer. Um papel de marketing não toca em arquitetura; um papel de QA não aprova o que ele mesmo produziu. Assim é o elenco:

O spec é o que diz a cada um desses agentes o que construir e com que critério se aceita. Sem spec, um agente governado sabe como se comportar mas não o que alcançar. Com spec, tem as duas coisas: o ofício e a encomenda, o marco e a meta. Por isso rende mais: deixa de gastar capacidade adivinhando o objetivo e a investe em cumpri-lo. A indústria caminha na mesma direção; ferramentas como GitHub Spec Kit existem justamente para colocar a especificação, e não o prompt improvisado, no centro do desenvolvimento com IA [2].

03 · a fronteiraDeliberar não é executar: a linha que nenhum rascunho cruza

Há um princípio que sustenta todo o método e convém dizê-lo sem rodeios: os rascunhos deliberam, mas não simulam execução. Deliberar é propor, avaliar e decidir. Executar é fazer a mudança real. São coisas distintas e não devem se misturar.

Um agente em estado de rascunho pode analisar um spec, discutir alternativas, apontar riscos e recomendar um caminho. O que não pode é fingir que já fez o trabalho, nem tocar o sistema real como se estivesse aprovado. Essa fronteira é o que evita que uma proposta se cole como um fato, e é a razão pela qual as comportas de maturidade fazem sentido: um rascunho vive na G1, delibera o quanto for preciso, mas só cruza para a G2 (operacional) quando o CEO aprova. Só então executa.

E quando finalmente executa, não se dá por bom de primeira. QA na Qirava é um laço com regressão profissional: testa-se contra os critérios de aceitação do spec até certificar, não se fazem retestes forjados só para "passar". Se algo quebrou em outra parte, a regressão o caça. O spec fecha o ciclo: definiu o critério no começo e é a régua com que se mede no fim.

Tudo isso se apoia numa fonte documental de verdade, um DOCUMENT_INDEX que diz qual é a versão válida de cada coisa. As skills vivem num toolkit; a governança, num vault; consomem-se por symlink. Não há cópias soltas nem verdades paralelas. Um agente que precisa saber "qual é a regra" não a improvisa: busca-a no índice.

Um prompt confia na memória de quem o escreveu. Um spec confia num documento que qualquer um pode auditar.

No fim, passar do prompt ao spec não é burocracia: é o que converte um agente esperto mas solto num agente esperto e governado. O prompt pergunta "o que sai?". O spec responde antes: "isto é o que tem que sair, e assim saberemos se saiu". Com esse contrato em mãos, o agente deixa de adivinhar e começa a cumprir.