Como escrever especificações para desenvolver com IA

Uma especificação para desenvolvimento com inteligência artificial funciona quando transforma uma intenção em comportamento observável, limites de escopo, restrições técnicas e critérios de aceite. Não basta pedir “melhore o cadastro” ou “corrija o login”. Antes de gerar ou alterar código, a equipe precisa saber qual comportamento será aceito, quais limites não podem ser violados e como a resposta será verificada.

A especificação começa pelo comportamento, não pelo pedido

Um erro recorrente em especificações para desenvolvimento com IA é descrever a vontade, não o sistema.

“Melhorar o cadastro” parece um pedido claro para quem vive o produto todos os dias. Para uma inteligência artificial, porém, essa frase abre espaço demais. Melhorar pode significar alterar mensagens, mudar validações, reorganizar componentes, mexer em persistência, trocar uma biblioteca ou sugerir uma experiência diferente. Algumas dessas respostas podem ser úteis. Outras podem criar retrabalho.

Uma especificação melhor começa por uma situação concreta:

• Quando o usuário informar um CPF inválido no formulário de cadastro, o sistema deve bloquear o envio.
• Os campos já preenchidos devem permanecer preenchidos.
• A mensagem exibida deve informar que o CPF precisa ser revisado.
• Nenhum dado deve ser gravado enquanto a validação falhar.

Essa forma não explica tudo. Ela reduz ambiguidade onde a ambiguidade custa caro: no comportamento esperado.

A diferença é prática. Um pedido genérico convida a IA a inferir intenção. Uma especificação comportamental dá ao revisor humano uma forma de aprovar ou rejeitar a mudança. O código pode estar elegante e ainda assim estar errado se o comportamento não corresponder ao cenário descrito.

Esse cuidado se conecta ao tema mais amplo de desenvolvimento amplificado por IA. Quando a especificação é vaga, a equipe pode transferir para a ferramenta ambiguidades que antes seriam resolvidas em conversas, revisão humana ou leitura do sistema.

Restrições reduzem o espaço de resposta da IA

Uma boa especificação não diz apenas o que fazer. Ela diz o que preservar.

Restrições verificáveis são limites explícitos que permitem identificar uma resposta inadequada sem depender de gosto pessoal. Elas podem envolver padrões de arquitetura, compatibilidade com uma API, dependências que não devem ser atualizadas, formato de mensagem, arquivos que não devem ser tocados ou decisões de produto que ainda não foram autorizadas.

Exemplos de restrições úteis:

• Não alterar o contrato público da API de cadastro.
• Não atualizar dependências nesta tarefa.
• Não modificar componentes compartilhados fora do módulo de autenticação.
• Manter o padrão atual de mensagens de erro do formulário.
• Criar ou ajustar testes apenas nos diretórios já usados pelo módulo.

Elas reduzem o espaço de resposta da IA.

A Anthropic define engenharia de contexto como a seleção e manutenção das informações disponíveis ao modelo durante a inferência, incluindo instruções, ferramentas, dados externos e histórico, dentro de uma janela limitada. Aplicando essa ideia a uma tarefa de desenvolvimento, a especificação pode funcionar como uma das instruções fornecidas ao modelo.

Se a especificação omite restrições, a revisão fica sem uma referência clara para rejeitar soluções fora das decisões da equipe.

O ponto não é controlar cada linha antes de o trabalho começar. É declarar as bordas que não devem ser atravessadas sem autorização.

Critérios de aceite precisam ser verificáveis por alguém

Critérios de aceite para IA são condições que permitem aprovar ou rejeitar uma mudança. Eles podem ser automatizados, manuais ou uma combinação dos dois. O critério ruim é aquele que parece razoável, mas não permite decisão.

“Ficar mais robusto” é vago. “Tratar erro de CPF inválido sem limpar o formulário e com teste cobrindo esse cenário” é verificável.

Critérios verificáveis podem aparecer de várias formas:

• Um teste automatizado novo ou ajustado passa no cenário descrito.
• Um cenário manual pode ser reproduzido por quem revisa.
• Uma mensagem esperada aparece em uma condição específica.
• Um arquivo de configuração permanece sem alteração.
• Uma resposta de API mantém o mesmo formato já consumido por outros clientes.
• Uma falha fora do escopo interrompe a tarefa em vez de ser corrigida junto.

A especificação não precisa escolher apenas um tipo de verificação. Em muitos sistemas, um teste automatizado confirma a regra principal, enquanto uma checagem manual valida uma mensagem, um fluxo visual ou uma interação difícil de cobrir naquele momento.

O DORA descreve integração contínua como integração frequente ao código principal, acompanhada de construção e testes automatizados, e afirma que corrigir uma construção quebrada deve ter prioridade sobre novas mudanças, segundo sua página sobre continuous integration. Essa orientação não diz como escrever especificações para IA, mas reforça uma disciplina relevante: mudanças precisam encontrar mecanismos objetivos de verificação cedo, não apenas depois de uma revisão cansada.

Se a equipe não sabe como verificará a resposta, talvez ainda não tenha uma tarefa pronta para implementação.

Uma especificação útil informa onde a IA pode mexer

Quanto mais amplo o espaço de alteração, mais difícil fica revisar. Isso vale para pessoas e vale para IA.

Uma especificação útil informa onde a alteração provavelmente deve acontecer. Não como uma camisa de força, mas como uma hipótese operacional:

• Módulo principal envolvido.
• Arquivos candidatos.
• Camadas que podem ser alteradas.
• Testes relacionados.
• Áreas que exigem autorização antes de qualquer mudança.

Esse limite ajuda a reduzir o risco de uma tarefa simples resultar em alterações amplas, difíceis de revisar.

O DORA recomenda unidades de trabalho pequenas, independentes e testáveis para obter retorno sobre mudanças e revisar hipóteses mais cedo. A mesma orientação alerta para a dificuldade de revisar e integrar grandes mudanças geradas com IA, em sua página sobre working in small batches.

Para equipes que estão criando uma estratégia de inteligência artificial conectada ao negócio, esse é um detalhe de processo com implicação de governança. Não é só produtividade individual. É a capacidade de manter alterações compreensíveis, revisáveis e compatíveis com o risco da organização.

Limitar escopo torna a revisão mais objetiva.

Exemplo fictício: de intenção solta a tarefa verificável

Considere um exemplo fictício em um produto interno de gestão de chamados. A equipe quer reduzir erros no login de usuários que digitam email com espaços antes ou depois do endereço.

Uma especificação fraca seria:

• Corrigir problemas no login quando o email vem errado.

Esse pedido deixa perguntas demais abertas. Que problema? Qual campo? O sistema deve aceitar, rejeitar ou normalizar o valor? A alteração vale para cadastro também? Deve mexer em autenticação, interface, API ou banco? Como revisar?

Uma versão operacional poderia ser:

• Contexto: no formulário de login, alguns usuários digitam espaços antes ou depois do email.
• Comportamento esperado: ao enviar o formulário, o sistema deve remover espaços no início e no fim do campo de email antes de autenticar.
• Caso normal: se o usuário digitar “ pessoa@empresa.com ” e a senha estiver correta, o login deve seguir o mesmo fluxo de “pessoa@empresa.com”.
• Caso de erro: se o email continuar inválido depois da remoção dos espaços, o sistema deve manter o usuário no formulário e exibir a mensagem de email inválido já existente.
• Escopo permitido: alterar o componente de login, a função de normalização usada pelo login e os testes correspondentes.
• Fora do escopo: não alterar cadastro, recuperação de senha, contrato da API de autenticação, mensagens globais ou dependências.
• Critérios de aceite: incluir teste para email com espaços antes e depois; manter teste existente de email inválido; não modificar arquivos fora do módulo de login sem pedir revisão.
• Condição de parada: se a normalização estiver duplicada em outros fluxos ou exigir mudança em API compartilhada, parar e solicitar decisão humana.

Esse exemplo é fictício. Ele não afirma que tal mudança produziria redução de erros, aumento de conversão ou melhoria de suporte. Esses efeitos, se fossem relevantes, teriam de ser medidos no contexto real do produto.

O valor da especificação está em outro lugar: qualquer pessoa da equipe consegue olhar a resposta da IA e perguntar se ela respeitou comportamento, escopo, restrições e critérios de aceite.

Checklist VER: verificação, escopo e restrições

Antes de enviar uma tarefa para desenvolvimento com IA, a equipe pode usar um filtro simples. O nome aqui é apenas uma forma de lembrar o objetivo: verificar se a especificação já traz verificação, escopo e restrições suficientes para orientar a revisão.

• Comportamento observável: a especificação descreve o que o sistema deve fazer em uma situação concreta? Passa quando uma pessoa consegue reproduzir o cenário e dizer se o comportamento ocorreu ou não.
• Entrada, saída e exceções: a tarefa informa quais dados entram, qual resposta é esperada e quais exceções devem ser tratadas? Passa quando há pelo menos um caso normal e um caso de erro ou limite descritos.
• Escopo permitido: a especificação delimita onde a IA pode alterar código, configuração ou testes? Passa quando arquivos, módulos, serviços ou camadas prováveis estão indicados, junto com áreas que não devem ser modificadas.
• Restrições explícitas: a tarefa informa padrões, dependências, APIs, compatibilidades ou decisões que devem ser preservadas? Passa quando o revisor consegue apontar uma violação sem depender de interpretação subjetiva.
• Critério de aceite: existe uma condição objetiva para aprovar a mudança? Passa quando a aprovação pode ser ligada a teste automatizado, cenário manual, resposta esperada, ausência de regressão definida ou evidência equivalente.
• Condição de parada: a especificação diz quando a IA deve parar e pedir revisão em vez de continuar assumindo decisões? Passa quando há gatilhos claros, como regra ambígua, necessidade de alterar contrato de API, falha de teste não relacionada ou mudança fora dos arquivos previstos.

Esse checklist não garante qualidade do código. Ele serve para levar a conversa com a IA a um nível mais preciso antes da implementação.

Quando a especificação deve parar antes do código

Nem toda intenção deve virar prompt de implementação.

Há situações em que a melhor especificação é uma interrupção. Isso acontece quando a regra de negócio ainda está ambígua, quando existe impacto em segurança ou dados sensíveis sem responsável definido, quando a mudança depende de um serviço externo incerto ou quando o pedido é grande demais para uma revisão segura.

Também vale parar quando não há cenário de teste. Se ninguém consegue descrever como aprovar a mudança, a equipe pode estar tentando usar IA para acelerar uma decisão que ainda não foi tomada.

A documentação do GitHub sobre uso responsável de agentes do Copilot descreve recursos de agentes com ambientes e permissões distintos e ressalta supervisão humana e revisão das saídas. A especificação deve trabalhar a favor dessa supervisão. Ela precisa deixar claro quando a IA pode seguir e quando deve devolver a decisão.

Para organizações que estão avaliando maturidade em IA, essa distinção pode ser usada como critério interno de processo: separar tarefa executável, decisão pendente e risco que exige outro tipo de condução.

Como usar a especificação na revisão humana

A revisão humana de código gerado por IA não deve começar apenas pelo estilo, nem pela impressão de que “funcionou”. Deve começar pela especificação.

O revisor pode seguir uma sequência simples:

• O comportamento implementado corresponde ao cenário descrito?
• A alteração ficou dentro do escopo permitido?
• Alguma restrição foi violada?
• Os critérios de aceite foram demonstrados?
• A IA tomou alguma decisão que deveria ter parado para revisão?

Essa revisão é mais objetiva porque a equipe combinou antes o que seria considerado correto. Sem isso, cada pessoa avalia por uma lente diferente: uma olha arquitetura, outra olha prazo, outra olha aparência, outra tenta reconstruir a intenção original.

A especificação dá ao julgamento humano um ponto de apoio.

Também não substitui descoberta de requisitos, desenho técnico ou conversa entre produto e engenharia. Quando a necessidade ainda está incerta, especificar demais pode apenas esconder a incerteza em um documento longo. O objetivo é outro: tornar o aceite da mudança mais claro e verificável.

Para equipes que estão montando um roadmap de IA, a pergunta pode ajudar a qualificar tarefas candidatas. Antes de perguntar se uma tarefa pode ser feita com IA, pergunte se ela pode ser descrita em comportamento, escopo, restrições, aceite e condição de parada.

Se não puder, talvez a próxima ação não seja gerar código. Talvez seja decidir melhor.

Antes de pedir que a IA implemente a próxima alteração, reescreva a especificação até que ela responda a cinco perguntas: o que muda, onde pode mudar, o que não pode ser violado, como será verificado e quando deve parar.

Se quiser discutir essa decisão no contexto da sua empresa, converse com a dooop.

Leituras para continuar

• Como redesenhar o fluxo de desenvolvimento com IA
• Engenharia de contexto para equipes de desenvolvimento

Fontes

• DORA: working in small batches
• DORA: continuous integration
• Anthropic: effective context engineering for AI agents
• GitHub: responsible use of Copilot agents