Antes de pedir código

“Faça um sistema para mim” parece um pedido. Para uma inteligência artificial capaz de escrever código, também é um convite para decidir uma quantidade enorme de coisas que ninguém disse.

Quem pode ver os dados? O que acontece quando uma operação falha? Duas pessoas podem alterar o mesmo registro? O que precisa ficar pronto agora e o que pode esperar? Se essas perguntas não aparecem na conversa, as respostas podem aparecer dentro do programa. Só que escolhidas por quem estava completando as lacunas.

Foi essa passagem, quase invisível, entre completar uma frase e tomar uma decisão que me levou a fazer quatro pesquisas sobre regras para agentes de código, confiabilidade em IA e desenvolvimento orientado por especificações. Depois, pedi ao Claude que me ajudasse a transformar o raciocínio em uma skill. A adaptação e a implementação local continuaram no Codex.

A ideia inicial era simples: criar um ambiente em que a IA precisasse ajudar a definir o sistema antes de começar a construí-lo. Dei a isso o nome de Sandbox de Especificação. Ao tentar fazê-lo funcionar, descobri que o próprio pedido precisava de revisão.

O código pode chegar antes da decisão

Imagine um pedido fictício: “Quero um painel simples para acompanhar oportunidades comerciais”. Em poucos minutos, pode existir uma tela com cartões, filtros e um botão de cadastro. É um resultado visível. Já a pergunta sobre quem pode acessar cada oportunidade continua sem resposta.

O problema aparece quando o protótipo ganha aparência de produto e suas escolhas provisórias começam a ser tratadas como definitivas. A tela funciona, mas funciona segundo regras que talvez ninguém tenha escolhido conscientemente.

Minha hipótese é que, quando fica mais fácil produzir código, ganha importância o trabalho de decidir o que esse código deve fazer. A velocidade da execução torna mais urgente distinguir uma decisão tomada de uma suposição conveniente.

Isso não significa que todo projeto deva começar com um documento longo. Um experimento descartável pode servir justamente para descobrir o que queremos. Nesse caso, “descartável” precisa ser uma escolha explícita, com limites de uso, para que a experiência não vire sistema de produção por inércia.

Do desejo ao comportamento observável

Uma especificação útil permite discordar de algo concreto. “O sistema deve ser seguro” expressa uma intenção importante, mas não diz o que vamos conferir. “Um vendedor não pode consultar oportunidades de outro vendedor” já abre perguntas verificáveis sobre identidade, permissão e acesso.

Esse exemplo não resolve toda a segurança do sistema. Resolve uma parte do pedido e mostra o que ainda falta discutir: supervisores, transferências de carteira, registros de acesso, integrações. A precisão ajuda a enxergar as lacunas.

O trabalho é sair de adjetivos e chegar a situações, comportamentos e critérios de aceitação. Ainda existe interpretação. Um requisito escrito em linguagem natural pode estar errado, incompleto ou em conflito com outro. Sua vantagem é oferecer um objeto que alguém pode ler, questionar e revisar antes de ele se espalhar pelo código.

A ideia tem antecedentes. O Spec Kit, do GitHub, organiza um fluxo de desenvolvimento orientado por especificações. O estudo ClarifyGPT investiga como detectar ambiguidades e fazer perguntas para esclarecer requisitos antes da geração de código. São referências para o raciocínio; não são validações da skill que construí.

O que mudou no meu próprio pedido

Eu havia proposto quatro fases: entender o produto, definir a arquitetura, criar a estrutura inicial de pastas e só então decompor o trabalho em tarefas. Também havia pedido um bloqueio absoluto de código antes da aprovação.

Havia uma contradição ali. Criar a estrutura inicial — o chamado scaffolding — já envolve escolhas: bibliotecas, configuração, organização e dependências. Se eu queria revisar essas decisões antes da execução, não fazia sentido autorizar sua materialização no meio da especificação.

O fluxo adaptado começa pela descoberta do problema. Depois registra requisitos, arquitetura e contratos — os acordos sobre como as partes do sistema trocam informações — e um plano de tarefas verificáveis. A estrutura inicial passa a ser uma tarefa de implementação, quando necessária, depois dos aceites.

O segundo ajuste foi de proporção. Trocar o texto de um botão não deveria exigir o mesmo ritual de um sistema novo. Por isso, existe uma via leve: uma especificação curta com escopo, critérios e plano. A pergunta é quanto precisamos esclarecer para esta mudança, considerando sua complexidade e suas consequências.

O terceiro ajuste foi abandonar a ideia de uma especificação intocável. Aprender durante a implementação faz parte do trabalho. Se a descoberta exige outra arquitetura, o fluxo deve permitir a revisão e tornar visíveis as aprovações que perderam validade. Congelar um erro não aumenta a qualidade.

Uma regra escrita não é uma trava

Escrever “a IA deve se recusar a gerar código” define uma orientação. Não cria, por si só, um mecanismo que impeça a escrita. Esse foi o ponto mais importante da passagem do prompt para a implementação.

A skill reúne instruções de trabalho e pequenos programas que registram o estado do projeto, conferem a estrutura dos documentos e vinculam aprovações às versões dos arquivos. Se um documento aprovado muda, o registro anterior deixa de autorizar a continuidade daquele fluxo.

Ela também inclui uma verificação antes do commit, o registro de uma mudança no Git, e adaptadores opcionais para interceptar certas ações dos agentes. São camadas diferentes: orientar o comportamento, detectar divergências e bloquear operações nos pontos em que existe integração.

O nome “sandbox” precisa, portanto, de uma ressalva: aqui ele descreve um fluxo de trabalho delimitado. Esta versão não cria um ambiente isolado pelo sistema operacional. Quem controla o mesmo usuário da máquina pode alterar scripts, desligar verificações ou contornar mecanismos locais. E uma confirmação digitada no terminal, sozinha, não prova que havia uma pessoa do outro lado.

Há pesquisas sobre controles externos às instruções do modelo, como o ContextCov, que avalia um mecanismo de verificação de restrições em tarefas de programação. O interesse está em conferir comportamentos, além de pedir obediência. Os resultados daquele experimento pertencem ao mecanismo e às condições estudadas. Não podem ser emprestados como resultados deste pacote.

Também existe um limite menos técnico: um documento pode passar em todas as verificações de estrutura e continuar descrevendo o produto errado. Um teste pode passar e conferir a coisa errada. A revisão precisa alcançar o conteúdo das decisões, não apenas a existência de arquivos e sinais verdes.

Onde pode estar o valor

A utilidade que quero testar é bastante concreta: diminuir decisões acidentais e facilitar a retomada do trabalho. Ao voltar a um projeto, deve ser possível descobrir o que foi combinado, o que falta decidir, qual tarefa está em execução e como seu resultado será conferido.

Isso pode ser especialmente útil quando a conversa atravessa sessões ou ferramentas diferentes. O acordo fica em arquivos do projeto, disponíveis para leitura e revisão. O histórico do chat continua sendo uma fonte de contexto, mas deixa de ser o único lugar onde as decisões existem.

Há um custo. Escrever, revisar e manter esses registros leva tempo. Um processo exagerado pode fazer a pessoa aprovar documentos que não leu, ou gastar mais energia preenchendo etapas do que entendendo o problema. Nesse caso, o método fabrica aparência de controle.

Para saber se valeu a pena, eu observaria mudanças comparáveis: quanto retrabalho veio de requisitos mal compreendidos, quantas decisões precisaram ser refeitas, quanto tempo a revisão consumiu e se outra pessoa conseguiu retomar o projeto. Ainda não tenho essa avaliação. A redução de retrabalho é uma hipótese, não um resultado demonstrado da skill.

O pacote passou por 52 testes automatizados locais, incluindo cenários com repositórios Git temporários, e a cópia extraída do arquivo de distribuição foi testada novamente. Isso sustenta afirmações sobre esses casos do controlador e do instalador. Não demonstra a qualidade de um produto futuro, nem a obediência de todos os modelos. O teste em outro dispositivo e a avaliação completa dos adaptadores nos aplicativos continuam pendentes.

Foi assim que a ideia ficou mais útil para mim: ao substituir uma promessa de controle absoluto por decisões que podem ser examinadas. Antes de pedir que a IA avance, criar condições para entender o que estamos autorizando. E deixar um caminho claro para mudar de ideia quando aprendermos algo novo.

Este artigo parte de quatro pesquisas exploratórias e do processo de criação da skill com apoio de IA. As referências públicas estão ligadas às afirmações que sustentam. O exemplo de oportunidades comerciais é ilustrativo.