Toda mudança que vale a pena construir começa com uma intenção

Uma semana de SDD: de uma primeira versão a uma ferramenta que verifica o próprio trabalho.

De dia sou engenheiro de software e arquiteto sênior. À noite e nos fins de semana pinto sob o nome de Sam Grudge: corações, em óleo sobre tela, construídos camada por camada até a cor brilhar (hearts-colors.com). As duas vidas parecem muito distantes. Cada vez mais, elas se encontram em uma única pergunta: o que quero fazer com minhas próprias mãos, e o que posso entregar a uma máquina?

O SDD vem do meu trabalho diário. É uma metodologia de desenvolvimento guiada por especificações para agentes de codificação de IA (Claude Code e Codex), e é open source no GitHub. A ideia é simples. Antes de o agente escrever código, ele redige uma breve especificação: requisitos e exemplos concretos de como devem se comportar, inclusive quando algo dá errado. Eu aprovo. Depois o agente a constrói primeiro com testes, verifica-a em relação à especificação, e mantém um registro vivo de como o sistema se comporta.

O que mudou em uma semana

A primeira versão saiu em 7 de outubro. Ela lidava com pequenas mudanças de ponta a ponta, com uma única aprovação, tarefas baseadas em testes primeiro e uma especificação viva. Sete dias e quatorze versões depois:

• Trabalhos maiores seguem seu próprio caminho. Uma mudança maior recebe três aprovações em vez de uma: a especificação, o plano e os resultados.
• Uma especificação aprovada fica bloqueada. Alterá-la depois exige uma emenda registrada e aprovada. Os bugs seguem seu próprio fluxo, e um teste de regressão é incluído na especificação viva para que o bug não possa voltar silenciosamente.
• Um crítico revisa a especificação antes de qualquer coisa ser construída. Ele audita cada requisito e só me faz as perguntas que cabem a mim decidir, no máximo cinco.
• O SDD agora desenvolve o SDD. Desde a versão 0.5, o projeto funciona com seu próprio método, com rigor de "produção": o segundo mais alto de seus quatro níveis.
• A suíte de testes passou de 82 para 208 testes.

A ferramenta encontrou falhas em si mesma

A primeira mudança que o SDD aplicou a si mesmo foi um bug que havia descoberto em suas próprias aprovações. A aprovação final de "resultados" não lia o veredito do revisor, de modo que um trabalho marcado com falhas ainda podia ser aprovado. A constituição do projeto, suas regras não negociáveis, podia ser editada após a aprovação sem que ninguém percebesse, inclusive para reduzir o nível de rigor.

Ambos os problemas foram corrigidos. Uma aprovação agora cobre exatamente o que foi aprovado. O portão de resultados só aceita um veredito aprovado, e a constituição carrega uma impressão digital: qualquer edição posterior é relatada e bloqueia o progresso até que eu aprove novamente.

O que mais gostei foi como se chegou lá. A verificação foi executada três vezes, cada uma em uma sessão nova sem memória do trabalho anterior. As duas primeiras rodadas revelaram lacunas: regras que a especificação declarava, mas nenhum teste comprovava. A cada vez, a especificação era emendada, os testes faltantes eram escritos, e o revisor olhava novamente. A terceira rodada passou. Nada foi aprovado sem comprovação.

Camadas

Um dos meus quadros é feito de camadas. As primeiras desaparecem sob a cor, mas sustentam tudo. O SDD funciona da mesma forma: intenção, depois especificação, plano, testes e verificação, cada um visível e verificável sob o código.

No meu site eu digo que toda história que vale a pena contar começa com um coração. No software, toda mudança que vale a pena construir começa com uma intenção. Essa parte permanece comigo. Assim como as decisões e aprovações, que carregam minhas próprias palavras.

Delegando a rotina pesada

Nem toda camada precisa da mão de um mestre. Uma rodada de verificação levava cerca de 14 minutos e quase 180.000 tokens, e boa parte disso era mecânica: repetir testes sobre código antigo, quebrar regras de propósito para provar que um teste as detecta, reunir evidências. Um script pode fazer esse trabalho, sem nenhum modelo.

Esse é o próximo passo. Um modelo principal vai orquestrar: ele conversa comigo, mantém os pontos de controle e distribui o trabalho. Revisores independentes funcionarão como agentes separados nos modelos mais fortes. Tarefas rotineiras irão para modelos mais baratos e rápidos. Cada tipo de trabalho vai para a ferramenta que lhe convém, assim como um pincel serve a um traço e uma espátula a outro.

Essa é a promessa da IA que me importa. Ela não tira o ofício. Ela tira a rotina pesada ao redor do ofício, para que eu mantenha a parte que amo. No escritório, isso é arquitetura e julgamento. No ateliê, é o próximo coração.

O SDD é open source sob a licença MIT: github.com/fpapleux/sdd-skill. As notas de versão listam cada versão.