Escreva uma spec antes de dar o primeiro prompt a um agente de código com IA

Digitar um pedido direto em um agente de código parece mais rápido do que escrever qualquer coisa antes, e para uma tarefa realmente trivial muitas vezes é. O problema começa em qualquer coisa que tenha mais de uma interpretação razoável: o agente escolhe uma, constrói em cima dela, e você só percebe que ele escolheu a errada quando está lendo o código pronto. Cada ida e volta a partir daí custa mais do que os poucos minutos que uma spec teria levado.

Uma spec muda a ordem das coisas. Antes de qualquer código ser escrito, você registra três itens em linguagem simples: o que a coisa deve fazer, para quem é e os critérios de pronto que provam que funciona. Nada disso é um documento técnico. Está mais para o bilhete que você deixaria para um assistente competente que nunca te conheceu: detalhe suficiente para que ele não precise adivinhar o que importa.

Funciona por um motivo simples. O agente deixa de preencher as lacunas do seu pedido com suposições próprias, porque sobram menos lacunas. E você deixa de descobrir o que queria olhando a resposta do agente depois do fato, porque já escreveu isso antes de pedir qualquer coisa.

Nada disso é específico de uma ferramenta. Claude Code, Codex, Copilot, Cursor e todos os outros agentes de código funcionam do mesmo jeito básico: instruções em linguagem simples entram, código e comandos saem. A spec muda o que entra, o que muda o que volta, com qualquer um deles.

O Spec Kit do GitHub é um kit de código aberto, mantido no repositório do próprio GitHub sob a licença MIT, criado para dar aos agentes de código com IA processos estruturados, modelos reutilizáveis e resultados documentados, em vez de conversas avulsas. Ele é instalado por uma ferramenta de linha de comando própria, e o README do projeto o descreve como um kit para começar com desenvolvimento orientado por spec, ou com qualquer outro processo estruturado que você queira que um agente siga.

O fluxo central de desenvolvimento orientado por spec, segundo a documentação do projeto, passa por uma sequência nomeada de seis comandos: um define os princípios do projeto, outro escreve a spec em si, outro transforma essa spec em um plano técnico, outro divide o plano em uma lista ordenada de tarefas, outro executa as tarefas e escreve o código, e o último verifica o quanto o resultado convergiu para a spec. A orientação do próprio projeto é executar esses comandos um de cada vez, revisando cada resultado antes de continuar, e repetir as etapas de implementar e convergir até que a convergência indique que o trabalho convergiu, em vez de entregar o trabalho inteiro ao agente de uma só vez.

O kit também traz extensões separadas que você adiciona ao fluxo central, de novo segundo a documentação: um conjunto de comandos voltado a avaliar e corrigir um bug específico, e outro voltado a levar uma ideia ainda crua por pesquisa e definição antes de decidir se vale construí-la.

Quanto aos agentes aos quais ele se conecta, a documentação de instalação do Spec Kit cita vários por uma chave de integração que você informa na hora de instalar, incluindo Claude Code e GitHub Copilot, e remete à sua documentação própria para conectar outros agentes além dos citados diretamente. Trate qualquer lista de agentes, inclusive esta, como um retrato do momento: consulte a documentação atual do Spec Kit antes de presumir que uma ferramenta é ou não é compatível hoje.

Para quem não é desenvolvedor e está construindo uma coisa pequena, rodar o fluxo completo do Spec Kit pode ser mais cerimônia do que a tarefa pede. A spec em três partes, sozinha, digitada como sua primeira mensagem ao agente que você já usa, faz a maior parte do trabalho real, sem nada para instalar.

Cole a spec e deixe o agente fazer perguntas de esclarecimento antes de escrever qualquer coisa. Um agente competente pergunta quando algo não está claro, e a spec dá a ele algo concreto sobre o que perguntar, em vez de adivinhar em silêncio e construir a coisa errada com toda a confiança.

Essa versão simples do hábito vale em qualquer lugar. O mesmo briefing em três partes funciona seja você conversando com Claude Code, Codex, Copilot, Cursor ou qualquer outro agente de código, porque nada dele depende de um recurso exclusivo de uma ferramenta. É um hábito que você constrói, não um plugin que você instala.

Para uma construção pequena e isolada, uma spec simples em três partes digitada direto no chat basta, e é mais rápida do que instalar qualquer coisa. A maioria dos exemplos deste guia foi escrita para esse caso.

O Spec Kit começa a compensar o custo de instalação quando você repete isso no mesmo projeto, quer que seus princípios sejam aplicados automaticamente a cada nova funcionalidade, ou prefere a estrutura própria das extensões de correção de bugs e de avaliação de ideias em vez de inventar sua própria versão delas a cada vez.

De qualquer forma, a habilidade de fundo é a mesma: dizer o que faz, para quem é e como você vai saber que está pronto, antes de uma única linha de código ser escrita. O kit apenas automatiza o registro disso de forma consistente, quando o hábito já é algo a que você recorre com frequência suficiente para valer a automação.