Skip to content
Da Vibe Coding à Engenharia Agêntica

Capítulo 6 — Especificação: transforme intenção em contrato verificável

O prompt não é a especificação

Section titled “O prompt não é a especificação”

Um prompt pode pedir implementação.

Uma especificação precisa dizer o que conta como implementação correta.

Essa diferença parece pequena quando o trabalho é simples. Ela se torna decisiva quando um agente consegue gerar centenas de linhas, alterar vários arquivos e produzir uma solução plausível antes que alguém tenha definido claramente o resultado esperado.

No fluxo deste livro, a Spec vem depois de Intent, Domain e Architecture.

Isso significa que ela não precisa descobrir tudo ao mesmo tempo.

Ela recebe:

  • o resultado desejado;
  • os conceitos e invariantes do domínio;
  • as fronteiras arquiteturais;
  • e transforma isso em um contrato de mudança.

O gargalo migra para Specify e Verify

Section titled “O gargalo migra para Specify e Verify”

Tantithamthavorn descreve um ciclo em que specification quality e verification rigour se tornam gargalos centrais à medida que a geração acelera. O trabalho humano se concentra especialmente em Specify e Verify. 1

Isso muda a pergunta principal.

Em vez de perguntar “como faço o modelo gerar melhor?”, a pergunta passa a ser:

como descrevo a mudança de forma que eu consiga verificar objetivamente se ela foi entregue?

Esse é o centro da especificação agêntica.

Uma Spec deve reduzir interpretação desnecessária

Section titled “Uma Spec deve reduzir interpretação desnecessária”

Especificar não significa escrever um documento enorme.

Significa tornar explícitas as decisões que não devem ser improvisadas durante a geração.

Uma Spec útil deve registrar, na profundidade adequada:

  • outcome;
  • ator ou usuário afetado;
  • escopo;
  • fora de escopo;
  • invariantes;
  • restrições;
  • interfaces relevantes;
  • critérios de aceitação;
  • evidências esperadas;
  • condições de escalada;
  • risco e permissões quando aplicáveis.

Algumas tarefas cabem em poucas linhas.

Outras precisam de exemplos, estados, contratos e cenários de erro.

A medida não é tamanho.

A medida é: o agente consegue agir e o revisor consegue decidir com base no mesmo contrato?

Critério de aceitação antes da geração

Section titled “Critério de aceitação antes da geração”

Specification-first é mais forte quando os critérios de verificação existem antes do código.

Isso impede que o sistema redefina sucesso depois de ver o que o agente produziu.

No nosso método, todo critério importante deve buscar a evidência mais barata e confiável disponível:

  • teste;
  • type check;
  • lint/static analysis;
  • schema validation;
  • benchmark;
  • screenshot;
  • health check;
  • revisão humana;
  • runtime metric.

A Spec não precisa implementar o gate.

Mas deve deixar claro que propriedade precisa ser provada.

Verificar contra intenção, não contra aparência

Section titled “Verificar contra intenção, não contra aparência”

Tantithamthavorn define verification como a comparação entre saída gerada e especificação. Checks automatizados são a primeira linha, mas não são suficientes para todas as violações de intenção. 2

Isso explica por que uma suíte verde pode coexistir com uma implementação errada.

Os testes podem cobrir o comportamento que foi escrito.

A Spec define o comportamento que deveria ter sido escrito.

Quando essas duas coisas divergem, “passou nos testes” não encerra a revisão.

É por isso que Spec e Evidence formam um par.

A Spec declara propriedades.

A Evidence Architecture demonstra quais delas foram satisfeitas.

A especificação também é memória

Section titled “A especificação também é memória”

Hassan et al. tratam o brief para agentes como artefato estruturado e versionado, não como mensagem efêmera. O BriefingScript é pensado como especificação para ação que pode ser legível por máquina, testável e refinada ao longo da tarefa. 3

A consequência para este livro é direta:

Specs importantes devem viver no repositório.

Isso cria:

  • provenance;
  • histórico;
  • revisão;
  • comparação entre intenção e diff;
  • base para aprender com rework;
  • possibilidade de reutilizar partes estáveis.

A conversa pode desaparecer.

O contrato não deveria.

Spec não é waterfall

Section titled “Spec não é waterfall”

Existe um risco inverso: transformar specification-first em tentativa de prever tudo antes de começar.

Esse não é o objetivo.

Uma boa Spec pode evoluir.

Quando a verificação descobre um caso não considerado, a disciplina é atualizar o contrato antes de simplesmente pedir outra geração.

O ciclo fica:

Specify → Generate → Verify → Refine

4

Refine não significa “tente de novo”.

Significa incorporar aprendizado:

  • adicionar um caso de borda;
  • esclarecer uma regra;
  • proibir uma dependência;
  • corrigir um pressuposto;
  • redefinir um critério de aceitação.

A Spec se torna o lugar onde a equipe preserva a razão da correção.

Escopo é também permissão

Section titled “Escopo é também permissão”

Uma Spec define o que deve mudar.

Por consequência, também define o que não deve mudar.

Esse segundo lado é essencial para agentes.

Se a tarefa é corrigir validação de um formulário, isso não autoriza:

  • trocar o framework;
  • refatorar autenticação;
  • alterar schema de banco;
  • adicionar dependências;
  • redesenhar APIs relacionadas.

O bloco “fora de escopo” reduz a tentação de melhorar coisas adjacentes durante a execução.

Autonomia sem boundary vira expansão silenciosa de escopo.

Escalada faz parte do contrato

Section titled “Escalada faz parte do contrato”

Uma especificação madura também define quando o agente deve parar.

Exemplos:

  • a mudança exige alterar arquitetura;
  • uma regra de domínio está ambígua;
  • há conflito entre documentação e código;
  • um teste existente contradiz o acceptance criterion;
  • uma permissão extra seria necessária;
  • a solução exige uma migração não prevista;
  • o custo ou blast radius mudou.

Escalar não é falha do agente.

É comportamento correto quando o contrato foi desenhado para reconhecer seus próprios limites.

O SPEC.md do Companion

Section titled “O SPEC.md do Companion”

O artefato operacional deste capítulo é o SPEC.md.

Ele existe para condensar o contrato em campos simples:

  • Outcome
  • Actor
  • Risk
  • In scope
  • Out of scope
  • Constraints
  • Acceptance criteria
  • Expected evidência
  • Agent boundary

Não é um padrão universal.

É uma implementação reproduzível da tese do capítulo.

O valor será medido pelo que acontece nos Change Episodes: menos rework, menor ambiguidade, diffs mais focados ou melhor capacidade de revisão — se os dados realmente mostrarem isso.

Da Spec à decomposição

Section titled “Da Spec à decomposição”

Uma Spec pode definir bem a mudança e ainda ser grande demais para uma única unidade de execução.

Antes de montar Context para o agente, precisamos responder:

essa mudança deve ser executada como um único lote ou precisa ser decomposta em unidades com contratos próprios?

A Spec define o que precisa ser verdadeiro. O próximo capítulo decide como dividir esse trabalho sem perder significado, dependências ou verificabilidade.

Só depois dessa decomposição faz sentido construir o Context específico de cada unidade.

Fronteira de confiança

Section titled “Fronteira de confiança”

A Spec delimita o envelope de autonomia. Decisões fora de escopo, mudanças de arquitetura, novas permissões, ambiguidades de domínio e aumento relevante de risco devem interromper a execução e escalar.

Evidência exigida

Section titled “Evidência exigida”

Antes da geração, a Spec deve indicar como cada propriedade crítica será demonstrada. O pacote pode combinar verificações mecânicas, revisão humana e evidência de runtime conforme risco e reversibilidade.

Rollback e recuperação

Section titled “Rollback e recuperação”

Especificações de mudanças com impacto operacional devem indicar condições de reversão, efeitos persistentes e sinais de que o rollout precisa ser interrompido. Rollback não deve ser inventado depois da falha.

Proveniência das fontes

Section titled “Proveniência das fontes”

Rastreabilidade deste capítulo:

  • CLM-009 — Tantithamthavorn, Specify → Generate → Verify → Refine;
  • CLM-028 — Tantithamthavorn, specification quality e verification rigour como novos gargalos;
  • CLM-029 — Tantithamthavorn, verification contra a Spec e limites de checks automáticos;
  • CLM-030 — Hassan et al., BriefingScript como artefato estruturado/versionado para ação.

Fontes de acesso limitado não foram usadas como autoridade factual neste capítulo.

Recursos complementares

Section titled “Recursos complementares”

Recursos relacionados:

  • SPEC.md;
  • Spec Builder;
  • Evidence Gate;
  • futura ligação Spec → Change Episode → Evidence IDs;
  • futura visualização de acceptance criteria → evidência produzida.

Living Book Expanded · capítulo executável

Spec verificável: abrir Spec Lab. A camada expandida preserva o texto estável e mantém repo/arquivo/commit e What changed? separados do manuscrito canônico.

Footnotes

Section titled “Footnotes”

  1. Kla Tantithamthavorn, Agentic Software Engineering (2026), Chapter 6: Agentic Software Engineering: A New Paradigm, p. 100. Rastreabilidade interna: CLM-028. ↩

  2. Kla Tantithamthavorn, Agentic Software Engineering (2026), Chapter 6: Agentic Software Engineering: A New Paradigm, pp. 101–102. Rastreabilidade interna: CLM-029. ↩

  3. Hassan et al., Agentic Software Engineering: Foundational Pillars and a Research Roadmap, The Art of the Briefing / Briefing Engineering, pp. 9–14. Rastreabilidade interna: CLM-030. ↩

  4. Kla Tantithamthavorn, Agentic Software Engineering (2026), How This Book Approaches Generative AI, p. 349. Rastreabilidade interna: CLM-009. ↩