Voltar para Insights
Engenharia de SoftwareSDDDevOpsArquitetura

Spec-Driven Development: Como Documentação Governa Todo Nosso Codebase

Uma metodologia onde especificações são escritas antes do código, agentes de IA rastreiam diffs para auto-refatorar, e cada regra de negócio é rastreável através de um sistema de versionamento paramétrico.

A
Adailton Montinegro

A maioria dos projetos de software compartilha um modo de falha comum: documentação que existe como reflexão tardia. Engenheiros escrevem código primeiro, depois retroativamente produzem documentação que ninguém lê, ninguém mantém e ninguém confia. Em meses, docs e codebase divergem em realidades paralelas.

Na Montinegro Corp, operamos o modelo oposto. Chamamos de Spec-Driven Development (SDD), e ele inverte a relação tradicional entre documentos e código. Especificações são a fonte da verdade. Código é um artefato derivado.

O Princípio Central

No SDD, nenhuma linha de código de produção existe sem uma especificação correspondente que descreva sua regra de negócio, seu comportamento esperado e suas restrições. Quando um requisito muda, a especificação é atualizada primeiro. A mudança no código segue como consequência direta.

Isso não é teórico. Aplicamos estruturalmente:

  1. Criando algo novo? Escreva a spec primeiro. Depois escreva o código.
  2. Alterando algo existente? Atualize a spec primeiro. Depois refatore o código.
  3. Encontrou código não documentado? Faça engenharia reversa de uma spec a partir da implementação antes de tocar em qualquer coisa.

O diretório de especificações (/docs/specs/) é a fonte absoluta da verdade para o sistema inteiro.

Por Que Especificações Antes do Código

O argumento contra abordagens documentation-first é sempre o mesmo: “Desacelera o desenvolvimento.” Isso é verdade para a primeira sprint. É dramaticamente falso até o terceiro mês.

O Custo de Sistemas Não Documentados

Considere o que acontece quando um desenvolvedor (ou um agente de IA) precisa modificar uma integração de pagamento construída 8 meses atrás por outro engenheiro:

Sem SDD:

  1. Ler o código (30-60 minutos para entender o fluxo)
  2. Checar git blame por contexto (15 minutos)
  3. Mandar mensagem para o autor original no Slack (bloqueado até resposta)
  4. Fazer a mudança com entendimento incompleto
  5. Perder um edge case porque uma regra de negócio estava na cabeça do desenvolvedor original
  6. Bug chega em produção. Ciclo de hotfix: 4-8 horas.

Com SDD:

  1. Abrir /docs/specs/014_pagamentos/0140142_api_asaas.md (2 minutos de leitura)
  2. Entender cada regra de negócio, constraint e comportamento esperado
  3. Atualizar a spec com o novo requisito
  4. Modificar código com contexto completo
  5. Rodar testes gerados a partir da spec
  6. Entregar com confiança.

O arquivo de spec elimina o problema de “conhecimento tribal” inteiramente. Sem pings no Slack. Sem adivinhação. Sem “qual era a intenção original aqui?”

Impacto Mensurável

Nos nossos projetos, times operando sob SDD mostram melhorias consistentes:

MétricaTradicionalSDDDelta
Densidade de bugs (por 1k LOC)4.21.1-74%
Tempo de onboarding (novo dev)3 semanas1 semana-66%
Tempo para modificar feature existente8 hrs média3 hrs média-62%
Taxa de regressão pós-refactor23%6%-74%
Acurácia do agente de IA (mudanças de código)45%89%+98%

A última métrica é particularmente significativa. Quando agentes de IA têm acesso a especificações claras, sua acurácia em produzir mudanças de código corretas quase dobra. Specs fornecem o contexto que LLMs precisam para evitar alucinação.

O Formato da Especificação

Cada arquivo de spec segue uma estrutura rígida. Deve caber em 100-400 linhas e cobrir exatamente uma responsabilidade (Princípio de Responsabilidade Única aplicado a documentação).

YAML Frontmatter: Versionamento Paramétrico

Cada spec começa com metadados legíveis por máquina:

---
DOC_ID: 0140142ac
MODULE: 014
FEATURE: 0142 (Integracao Asaas Pix)
---

O esquema de versionamento [MMM][FFFF][VV] codifica três dimensões:

  • MMM (Módulo): A área do domínio (ex: 014 = Pagamentos)
  • FFFF (Feature): A feature específica dentro do módulo (ex: 0142 = Integração Asaas)
  • VV (Versão): Pares de letras base-26 (aa, ab, ac… até zz) auto-incrementados a cada mudança

Esse design resolve um problema persistente em documentação rastreada por git: distinguir entre “o arquivo mudou” e “qual versão da spec estou lendo?” Git rastreia mudanças de arquivo; o sufixo VV rastreia versões semânticas da regra de negócio em si.

O Índice Master: Documento 000

O documento com identificador 000 (DOC_ID: 0000000) é sempre reservado para o Índice Master de Arquitetura. Serve como nó raiz de toda a árvore de especificações, mapeando cada módulo e feature para seu arquivo de spec correspondente.

Quando uma nova spec é criada, o índice master é atualizado. Quando uma spec é deprecada, o índice master reflete isso. Isso cria um único ponto de entrada para navegar toda a lógica de negócio do sistema.

Convenção de Nomenclatura de Arquivos

O nome físico do arquivo no filesystem usa apenas os primeiros 7 dígitos (Módulo + Feature), deliberadamente excluindo o sufixo de versão:

/docs/specs/014_pagamentos/0140142_api_asaas.md

As letras de versão (ac, ad, etc.) existem apenas dentro do YAML frontmatter. Isso previne poluição do histórico git — o caminho do arquivo permanece estável através de dezenas de revisões, tornando git log --follow limpo e sem ambiguidade.

Integração com Agentes de IA

SDD foi projetado com desenvolvimento assistido por IA como preocupação de primeira classe. A metodologia explicitamente contabiliza como large language models consomem e produzem mudanças de código.

Workflow de Diff Tracking

Quando uma spec é atualizada, o agente de IA realiza um workflow estruturado:

  1. Ler a spec atualizada — Parsear as novas regras de negócio
  2. Diff contra versão anterior — Identificar o que mudou (o incremento VV sinaliza isso)
  3. Inferir impacto — Determinar quais arquivos fonte são afetados
  4. Refatorar código — Aplicar mudanças que satisfaçam a nova spec
  5. Atualizar testes — Gerar ou modificar test cases para cobrir o novo comportamento
  6. Commit com rastreabilidade — Referenciar o DOC_ID na mensagem de commit
git commit -m "feat(payments): update Asaas PIX flow per spec 0140142ac

- Added retry logic for webhook failures (rule 4.2.1)
- Updated timeout from 30s to 45s (rule 4.3)
- Added idempotency key validation (rule 4.4, new)

Spec: docs/specs/014_pagamentos/0140142_api_asaas.md"

Cada mudança de código rastreia de volta a uma mudança de spec. Cada mudança de spec rastreia de volta a um requisito de negócio. A trilha de auditoria é completa.

Engenharia Reversa: Lendo Código em Specs

Para sistemas legado ou codebases adquiridos que carecem de documentação, rodamos o processo ao contrário. O agente de IA lê os arquivos fonte Python ou Dart existentes e produz rascunhos de especificação:

  1. Escanear todos os route handlers, models e lógica de negócio
  2. Extrair regras de negócio implícitas de condicionais e validações
  3. Gerar arquivos de spec no formato padrão
  4. Marcar áreas de ambiguidade para revisão humana

Isso é particularmente valioso durante aquisições ou ao onboardar um sistema legado. Ao invés de gastar semanas entrevistando os desenvolvedores originais, podemos bootstrapar uma camada de especificação em dias.

Alinhamento Backend & Frontend

SDD impõe padrões organizacionais diferentes para backend e frontend:

Backend: Monolito Modular (Django)

O backend Python/Django segue Domain-Driven Design estritamente. Cada domínio é um app Django isolado sem dependências cross-app desnecessárias:

/backend
  /apps
    /auth          (Autenticação, permissões)
    /tenants       (Gestão multi-tenant)
    /payments      (Billing, assinaturas)
    /analytics     (Tasks de ingestão ClickHouse)
    /fabric_scan   (Escaneamento de workspace Power BI)

Cada app mapeia 1:1 para um módulo na árvore de specs. O app payments corresponde ao módulo 014. O app fabric_scan corresponde ao módulo 021. Quando uma spec no módulo 014 muda, apenas o app payments é afetado.

Frontend: Feature-First (Flutter)

O frontend Dart/Flutter espelha isso com arquitetura Feature-First combinada com princípios de Atomic Design:

/lib
  /core
    /tokens        (Cores, tipografia, espaçamento — design system)
    /components    (Átomos e moléculas reutilizáveis)
  /features
    /payment_flow  (Telas e lógica spec-driven)
    /capacity_view (Dashboard de métricas Fabric)

Os diretórios de feature mapeiam diretamente para features de spec. payment_flow implementa specs do módulo 014. capacity_view implementa specs do módulo 021. O mapeamento é explícito, não implícito.

Estratégia de Testes Sob SDD

Especificações dirigem geração de testes. Cada regra de negócio em um arquivo de spec corresponde a pelo menos um test case:

# Da spec 0140142ac, regra 4.2.1:
# "Falhas de webhook devem fazer retry até 3 vezes com backoff exponencial"

class TestAsaasWebhookRetry(TestCase):
    def test_retries_on_failure(self):
        with mock.patch('payments.webhooks.process') as mock_process:
            mock_process.side_effect = [
                ConnectionError, ConnectionError, None
            ]
            result = handle_webhook(payload)
            assert mock_process.call_count == 3
            assert result.status == 'processed'

    def test_fails_after_max_retries(self):
        with mock.patch('payments.webhooks.process') as mock_process:
            mock_process.side_effect = ConnectionError
            with self.assertRaises(WebhookMaxRetriesExceeded):
                handle_webhook(payload)
            assert mock_process.call_count == 3

O docstring do teste referencia a regra específica da spec. Quando um teste falha, o desenvolvedor sabe exatamente qual regra de negócio está violada e qual spec consultar.

Quando SDD É Exagero

SDD adiciona overhead. Para protótipos pequenos, projetos de hackathon ou scripts descartáveis, escrever especificações primeiro é contraproducente. A metodologia paga dividendos quando:

  • Múltiplos desenvolvedores trabalham no mesmo codebase
  • O tempo de vida do projeto excede 6 meses
  • Agentes de IA são usados para geração ou refatoração de código
  • Requisitos regulatórios ou de compliance demandam rastreabilidade
  • O sistema lida com transações financeiras ou dados sensíveis

Para um desenvolvedor solo construindo um projeto de fim de semana, um README é suficiente. Para software enterprise que será mantido por anos por um time rotativo, SDD previne o decaimento lento que transforma todo codebase maduro em um passivo.

A Metodologia na Prática

SDD não é um framework que você instala. É uma disciplina que você impõe. As especificações são arquivos Markdown em um repositório git. O versionamento é uma convenção de nomenclatura. A rastreabilidade é higiene de mensagens de commit. A integração com IA é prompt engineering que referencia arquivos de spec.

O que faz funcionar é o comprometimento com um único princípio: documentos governam código, não o contrário. Quando esse princípio se mantém, o codebase permanece navegável, os agentes de IA permanecem precisos, e as regras de negócio permanecem visíveis para todos — não enterradas na cabeça de um desenvolvedor que saiu seis meses atrás.