Cases / Especificação para dois leitores

Especificação para dois leitores — SDD para humanos e agentes

Uma especificação escrita para pessoas tolera ambiguidade, porque a pessoa pergunta. Um agente não pergunta: ele decide. O case mostra o que precisou mudar quando o leitor do requisito deixou de ser só humano.

FunçãoAnalista de requisitos e desenvolvedor (projeto autoral)
Período2026
SituaçãoEm uso, repositórios abertos
Screenshot ampliado — Especificação para dois leitores

O problema

O backlog em épicos e histórias, com critério de aceite em Gherkin, funcionava enquanto quem implementava era uma pessoa, porque a pessoa, diante de uma ambiguidade, pergunta. Quando parte da implementação passou a ser feita por um agente, três lacunas apareceram: critérios verificáveis em princípio mas que ninguém consegue executar, decisões deliberadas que moravam na memória de alguém e, o caso mais caro, a correção óbvia que está errada.

Um exemplo real e público: no Compras Públicas SC, a ingestão deixou de ser automática quando a fonte parou de publicar. A correção óbvia, de qualquer pessoa ou agente, seria religar o processo agendado. Isso recarregaria a base do zero e apagaria em silêncio o histórico de 2011 a 2020, que só existe ali. Nenhum teste falharia. O registro do porquê é o que impede esse erro.

Decisões técnicas

  • Constituição: regra curta, ligada a um fato. As regras não negociáveis ficam num arquivo próprio, cada uma com o motivo que a originou. A primeira delas proíbe dado operacional do host em spec de repositório público, e o motivo está escrito ali mesmo: uma investigação anterior registrou esse tipo de dado numa spec, e a regra nasceu da correção. Regra sem motivo é obedecida enquanto ninguém discorda; regra com o incidente anexado sobrevive à discordância.
  • EARS: gatilho, resposta e limite numa frase. Um requisito real, da spec 030: "QUANDO o arquivo informado estiver vazio, não existir, ou o cabeçalho não bater exatamente com as 51 colunas esperadas (mesma ordem, comparação case-insensitive), o sistema DEVE abortar sem alterar raw.contratos, com mensagem de erro visível." Em uma frase estão a condição, a resposta e o que não pode acontecer, e nada disso depende de perguntar ao autor.
  • Aceite executável: de asserção aberta para saída literal. Esta foi a mudança que mais alterou o resultado. O critério em Gherkin do backlog dizia: "Então datas e valores devem ser normalizados corretamente". É verificável em princípio, mas quem decide o que é "corretamente"? O formato atual exige comando e saída esperada, literal, nunca "funciona" ou "deve passar" sem o comando que prova. Um exemplo está publicado ao lado da spec a que pertence, declarado como reconstruído a partir de uma execução já registrada: select count(*), min(ano_assinatura) from stg_contratos; devolvia 104574 | 1994 antes e 79637 | 2016 depois. O critério mede o estado antes e depois da mudança, não só o resultado final: sem o antes, não há como provar que a mudança fez alguma coisa. O contraste com o Gherkin não é entre prosa e comando, é entre uma asserção que precisa de interpretação e uma que pode ser reprovada por uma máquina.
  • Já era assim em dados. Um teste de dbt é uma consulta que falha se devolver linha. Aceite executável numa spec é exatamente isso, aplicado ao processo em vez do dado: a condição de reprovação é explícita e alguém, ou algo, pode rodá-la sem interpretar. Quem já escreve teste de dado reconhece o formato na hora; a diferença é o que está sob teste.
  • A spec mais recente prevalece, porque documento envelhece. A regra existe por necessidade, e o próprio repositório mostra por quê: na spec 030, a tabela de decisões ainda registra a rotina automática como mantida ativa; a anotação de que ela foi superada está no requisito REQ-7, mais acima. Quem lê só aquela tabela se engana; quem segue a regra de precedência, não. Documentar a decisão superada, em vez de apagá-la, é o que impede alguém de refazer o caminho já descartado.

Resultado

O método está aberto em dois repositórios públicos, com 62 specs, mais as constituições e os documentos de arquitetura. O backlog original em Gherkin continua visível, arquivado no compras-publicas-sc, como registro da matéria-prima. O exemplo de aceite executável também está publicado, acompanhando a spec 034 e declarado como reconstruído.

Na spec 030, o aceite registrado mostra o formato funcionando: a ingestão manual levou a base de 95.508 para 104.574 registros, com 9.066 novos, 6.172 atualizados e 1.119 preservados por design, nunca apagados. A carga foi validada com o dbt build completo sem erro, 108 de 108 testes.

Não há métrica do método em si: nenhuma medida de retrabalho evitado ou de taxa de acerto do agente. Inventar um número aqui seria o contrário do que este case defende. O que existe é verificável: as specs estão abertas, os critérios estão escritos e qualquer um pode conferir se eles podem ser reprovados.

Uma especificação só está pronta quando algo pode reprová-la.