Spec-driven sem autoengano: cobertura, contrato, eval e OpenAPI não são a mesma prova

Equipes que adotam IA aprendem rapidamente a pedir evidência antes de aceitar uma mudança. O problema começa quando evidências diferentes são comprimidas em uma única palavra: “verde”. A suíte passou, a cobertura subiu, o contrato existe, o schema é válido e o eval melhorou. Logo, conclui-se que o sistema está correto.

Essa conclusão não acompanha as premissas. Cada mecanismo responde a uma pergunta diferente. Quando tratamos proximidade no pipeline como equivalência semântica, construímos um painel bonito para uma certeza que nunca foi produzida.

Spec-driven não significa escrever uma especificação e confiar nela. Significa manter uma cadeia rastreável entre intenção, propriedades, mecanismos de verificação, evidências e decisão de aceite.

Resumo executivo

Uma descrição OpenAPI informa como consumidores e ferramentas podem compreender uma interface HTTP; um diff de compatibilidade procura mudanças estruturais; um teste executado observa comportamento; uma métrica de cobertura informa o que foi exercitado; e um eval mede uma propriedade comportamental sob um conjunto de tarefas e graders. São camadas complementares, não substitutas. [API31-C1]

Mesmo dentro de uma única camada existem limites. O oasdiff documenta comparação de OpenAPI 3.1 e regras de breaking change, mas um diff verde não certifica compatibilidade de negócio. Percentual de cobertura, por sua vez, não prova relevância dos testes, correção nem cobertura de risco. [API31-C2] [API31-C4]

O desenho responsável começa por uma pergunta simples: qual propriedade este verde realmente autoriza afirmar? A resposta deve estar explícita antes do pipeline rodar.

Cinco mecanismos, cinco perguntas

A tabela não cria uma hierarquia fixa. Em uma biblioteca pura, contrato e teste unitário podem ser o centro. Em um agente que altera dados, policy, sandbox, eval e observabilidade podem ser mais importantes. A composição depende do risco.

Comece pela propriedade, não pela ferramenta

“Adicionar eval” não é um requisito verificável. “Em cem cenários representativos, o agente nunca envia uma mensagem sem consentimento válido e toda tentativa bloqueada gera evidência atribuível” é uma propriedade candidata.

Para cada propriedade, registre:

1. subject — qual versão do sistema está sendo examinada;
2. estímulo — tarefa, entrada e ambiente;
3. oráculo — quem ou o que decide o resultado;
4. limite — qual condição precisa ser satisfeita;
5. evidência — onde o resultado imutável pode ser inspecionado;
6. autoridade — qual decisão o verde pode liberar.

Sem subject, um relatório pode pertencer ao commit errado. Sem oráculo, a saída vira opinião. Sem limite, qualquer número pode ser chamado de melhora. Sem autoridade, o verde existe mas ninguém sabe o que ele desbloqueia.

OpenAPI é descrição; compatibilidade é uma decisão maior

A especificação OpenAPI define uma descrição de interface independente de linguagem para que pessoas e computadores compreendam capacidades de um serviço. Isso reduz ambiguidade na integração, mas não carrega toda a semântica de negócio.

Considere um campo limite_aprovado que continua numérico e obrigatório. A API pode permanecer estruturalmente compatível enquanto uma mudança de unidade, política ou arredondamento quebra a operação. O diff estrutural merece ficar verde; o teste de invariant de negócio merece falhar. São resultados coerentes porque examinam propriedades diferentes.

O erro não está na ferramenta. Está em apresentar “sem breaking change” como “sem impacto”.

Cobertura é mapa, não veredito

Cobertura mostra áreas visitadas durante a execução. Ela ajuda a localizar silêncio: branches nunca exercitados, módulos esquecidos, deltas sem teste. Mas uma linha executada pode estar mal verificada; um teste pode reproduzir a implementação em vez do requisito; um caso crítico pode representar uma fração pequena do código.

Na FORGE, a leitura útil separa ao menos linha, branch, escopo, delta e threshold. Ainda assim, esses campos são sinais de teste, não de risco resolvido. [API31-C4]

Para não transformar porcentagem em teatro:

• ligue cenários críticos às propriedades que protegem;
• use cobertura para descobrir lacunas, não para declarar correção;
• trate código novo e risco alto de forma diferente do histórico;
• exija evidência do teste que falha quando a propriedade é violada.

Eval é um experimento versionado

Um eval precisa de banco de tarefas, ambiente, configuração do sistema, grader, regra de agregação e baseline. Alterar qualquer um desses elementos muda o experimento.

Um número agregado pode esconder classes de falha. Um agente pode melhorar a média e piorar casos irreversíveis. Um grader por modelo pode preferir estilo e perder fatos. Um benchmark pode conter tarefas quebradas. Por isso, eval não é uma medalha; é uma infraestrutura de decisão.

O painel mínimo registra:

O teste mais importante: violar a propriedade

Um gate só demonstra força quando a condição proibida o faz falhar. Antes de confiar no pipeline, execute um caso negativo deliberado:

• remova um campo obrigatório e confirme a falha de contrato;
• introduza uma mudança incompatível e confirme o diff;
• apague o teste de uma branch crítica e observe a cobertura;
• faça o agente tentar ultrapassar uma authority e confirme o bloqueio;
• troque o subject da evidência e confirme que o binding falha.

O caso negativo distingue mecanismo executável de documentação aspiracional.

Uma matriz de evidência para o PR

A matriz não precisa cobrir cada linha do produto. Precisa cobrir as propriedades que sustentam a decisão sendo tomada.

O que este artigo prova — e o que não prova

As fontes e os contratos da FORGE sustentam a separação entre descrição, diff, execução, cobertura e eval. Elas não definem uma receita universal de ferramentas, thresholds ou número de testes. Um produto regulado e um protótipo interno precisam de perfis diferentes.

Também não existe independência automática porque um segundo modelo avaliou o primeiro. Se ambos compartilham contexto, incentivo, erro ou autoridade, há separação de chamadas, não necessariamente separação de controle.

Conclusão

Spec-driven é uma disciplina de rastreabilidade, não um selo.

Uma especificação declara intenção. Um contrato estrutura uma interface. Um teste observa exemplos. Cobertura revela áreas exercitadas. Um eval mede comportamento em um experimento. Quando cada verde mantém sua pergunta, seu subject e seu limite, o conjunto pode sustentar uma decisão defensável.

Quando todos viram apenas “CI passou”, o sistema perde exatamente a precisão que a engenharia deveria criar.

Leitura anterior: Engineering harness na prática. Próxima leitura: *Autonomia proporcional ao risco*, em 18/08 na Trustyu Forge.