Na engenharia de software, há um momento decisivo antes da primeira linha de código ser escrita: a definição do que realmente será construído. Nesse ponto, duas abordagens costumam aparecer: o Spec-Driven Development e o Document-First Development. Embora pareçam semelhantes, a ordem e a intenção de cada uma mudam completamente a forma como o projeto se desenrola.
O Document-First Development parte da ideia de que todo sistema nasce de uma documentação bem estruturada. Antes de pensar em arquitetura, API ou testes, cria-se um documento que descreve de forma compreensível o problema, o domínio, os usuários e as interações esperadas. Esse documento não é apenas burocracia: é um artefato vivo, que servirá de referência compartilhada entre desenvolvedores, designers, clientes e stakeholders. É nesse momento que se estabelecem as bases do entendimento comum, como a linguagem, os termos e os limites do sistema. Em projetos complexos ou colaborativos, essa etapa é fundamental para evitar mal-entendidos e retrabalhos.
Já o Spec-Driven Development dá um passo adiante e transforma essa documentação em algo operacional. A especificação (ou spec) define formalmente o comportamento esperado do sistema: endpoints, contratos de API, regras de negócio, fluxos de interação e critérios de aceitação. Ela serve de base para gerar código, testes automáticos e até documentação técnica. Ferramentas modernas como Swagger (para APIs REST) ou GraphQL SDL exemplificam bem essa filosofia, em que a especificação se torna o centro da comunicação entre o front-end e o back-end.
A relação entre as duas abordagens é de continuidade. Primeiro, o Document-First Development organiza o pensamento e constrói o consenso. Depois, o Spec-Driven Development formaliza esse consenso em uma estrutura técnica que pode ser validada, testada e automatizada. Em outras palavras, o documento é o mapa; a spec é o contrato que garante que todos seguirão a mesma rota.
Muitos times pulam a etapa documental por pressa ou excesso de confiança, acreditando que a especificação técnica será suficiente. O problema é que, sem um documento anterior, a spec tende a se tornar um registro técnico de decisões já tomadas. Por isso, começar pelo Document-First Development é uma forma de garantir clareza, propósito e direção. A partir daí, o Spec-Driven Development entra como mecanismo de precisão e automação.
Assim, a resposta é simples: primeiro, escreva o documento; depois, derive dele a especificação. O código vem só depois que as palavras fizerem sentido.
Exemplo prático (sistema de estacionamento)
Considere o exemplo prático, do sistema de estacionamento, explorado na minha explicação sobre Spec-Driven Development e o Document-First Development. Uma sequência para o iniciar seria:
- Document-First:
Crie um documento descrevendo:- Como os veículos são cadastrados.
- Regras de cobrança.
- Fluxos de entrada e saída.
- Justificativas das decisões.
- Spec-Driven:
Depois, gere o arquivoopenapi.yamlcom os endpoints/entradas,/saidas,/pagamentos.
Esse arquivo é o contrato usado pelo backend e pelo frontend.
A tabela abaixo compara as duas abordagens.
| Etapa | Document-First | Spec-Driven |
|---|---|---|
| Propósito | Definir o porquê e o como conceitual | Definir o como técnico |
| Foco inicial | Documentação humana (requisitos, decisões, fluxo de uso) | Especificação formal (contratos, endpoints, schemas) |
| Ferramentas | Markdown, Notion, Google Docs, ADRs, RFCs | OpenAPI, GraphQL SDL, AsyncAPI, JSON Schema |
| Ordem ideal | Vem antes do Spec-Driven | Vem depois do Document-First |