O Problema de Ir Tentando

Imagina o seguinte: você tem uma feature bem definida na cabeça. Abre seu assistente de IA favorito, digita um pedido rápido e assiste enquanto ele reescreve metade do seu código com total confiança. Uma hora depois, você está olhando um PR que resolve um problema que você não tinha exatamente intenção de resolver — e de um jeito que quebra coisas que você não tinha intenção de quebrar.

Soa familiar? Você não está sozinho. Enquanto os agentes de IA evoluíram de respondedores de perguntas para editores de código, muitos devs estão descobrindo que aquela abordagem casual de prompting — que funciona tão bem em chatbots — não dá conta quando repositórios reais estão em jogo.

A solução não está em prompts mais detalhados. Está numa mudança fundamental na forma como мы pensamos nos documentos que enviamos para esses agentes.

Prompts vs. Specs: Uma Diferença Importante

Aqui está o ponto: prompts são otimizados para iniciar trabalho. São ótimos para explicações rápidas, scripts descartáveis e conversas exploratórias. Um prompt vive numa sessão de chat, pode usar abreviações e muitas vezes assume contexto que só o autor entende.

Isso funciona bem quando você está só fazendo perguntas.

Mas quando um agente de IA vai editar código compartilhado, rodar comandos no terminal e criar branches que colegas vão revisar? Seu prompt casual vira uma tarefa. E tarefas precisam de mais do que uma boa redação — precisam do contexto certo, limites claros, exemplos concretos e critérios de validação.

É aí que entram as specs.

Uma spec não é um prompt mais bonito. É um documento estruturado que captura qual problema você está resolvendo, qual comportamento deve mudar, o que deve permanecer igual e como você vai saber se o trabalho deu certo. Diferente de um prompt que desaparece assim que o agente começa a trabalhar, a spec fica visível durante todo o workflow — guiando o agente, informando revisores e ajudando mantenedores futuros a entender por que as decisões foram tomadas.

O Que Vai Numa Boa Spec Para Agente de IA

Você não precisa de um documento de 20 páginas. O que você precisa são cinco elementos-chave:

1. Contexto: Por que essa tarefa está acontecendo? Qual problema de usuário ou tech debt está motivando ela? Que restrições existem no codebase que o agente precisa entender?

2. Comportamento a mudar: Qual funcionalidade específica deve ser modificada, adicionada ou removida? Seja concreto — "usuários devem receber notificações por email quando X acontece" é melhor que "melhorar o sistema de notificações."

3. Restrições a preservar: O que absolutamente não pode mudar? Qual funcionalidade existente, contratos de API ou características de performance precisam permanecer intactas?

4. Exemplos de correção: Cenários concretos que demonstram o que é sucesso. Formato Dado/Quando/Então funciona bem aqui, mas até alguns casos de teste explícitos ajudam o agente a entender suas expectativas.

5. Critérios de validação: Como um revisor vai saber se o trabalho está completo? O que ele deve inspecionar? Que perguntas ele deve fazer?

Esse framework deve soar familiar se você já trabalhou com cenários de BDD, templates de issues com critérios de aceitação ou documentos de design. O formato específico importa menos do que ter a informação certa numa forma que possa ser compartilhada e revisada.

Onde as Specs Vivem no Seu Workflow

Uma das melhores coisas sobre specs é a flexibilidade. Elas não precisam ser documentos separados que te atrasam. Uma spec pode viver em qualquer lugar que faça sentido para seu time:

• Uma issue no GitHub com critérios de aceitação explícitos
• Uma descrição de PR que nomeia o comportamento sendo alterado
• Um cenário BDD nos seus arquivos de feature
• Uma nota de design leve antes da implementação
• Ferramentas como OpenSpec ou GitHub Spec Kit que formalizam esse padrão

A chave é tornar contexto e critérios de revisão visíveis e persistentes. Sua spec não deve desaparecer quando a sessão de chat termina. Ela deve viajar junto com o trabalho, dando aos colegas algo concreto para avaliar.

A Camada de Tarefa: Separando Intenção de Execução

É aqui que as coisas ficam realmente interessantes.

As specs mais fortes funcionam como pequenos contratos de comportamento. Elas separam três questões distintas:

1. Qual comportamento deve mudar? (O requisito)
2. Que restrições ou exemplos definem correção? (Os critérios de aceitação)
3. Qual caminho de implementação parece apropriado agora? (A abordagem técnica)

essas perguntas estão conectadas, mas não deveriam colapsar num blob de instruções.

Por que isso importa para agentes de IA? Porque quando você mistura intenção e implementação muito cedo, o agente pode otimizar pela coisa errada. Ele pode seguir fielmente um detalhe de implementação sugerido enquanto perde o comportamento que você realmente precisava. Ou pode produzir código que é tecnicamente interessante mas não resolve o problema stated.

Uma camada de tarefa mantém o requisito estável enquanto permite que a implementação evolua. Conforme o agente lê o codebase, descobre complicações e refina sua abordagem, a spec permanece como referência: "O trabalho satisfez isso?"

Isso é especialmente valioso para codebases existentes. A maioria do trabalho de engenharia não é greenfield — você está mudando comportamento que já existe. Uma boa spec diz: aqui está o comportamento atual, e aqui está o que precisa mudar. Revisores não precisam reconstruir mentalmente sua intenção a partir de detalhes de implementação.

Fazendo a Mudança

Se você está acostumado a tratar agentes de IA como search engines turbinados, isso pode parecer overthinking. Mas considere a alternativa: mudanças descontroladas em código compartilhado, PRs difíceis de revisar e trabalho que não Matches exatamente o que você imaginou.

A mudança para colaboração com IA orientada por specs não é sobre burocracia. É sobre dar tanto a humanos quanto a máquinas a clareza que precisam para trabalhar juntos de forma eficaz.

Comece pequeno. Da próxima vez que você estiver prestes a mandar um agente de IA dentro de um repositório, pause cinco minutos para anotar o contexto, a mudança de comportamento e os critérios de sucesso. Coloque em algum lugar visível — mesmo que seja só na descrição do PR.

Seu eu do futuro (e seus colegas) vão agradecer.

O ponto final: Agentes de IA são colaboradores poderosos. Trate-os como colaboradores. Dê a eles um briefing adequado, e você vai receber trabalho que vale a pena revisar.