A Metodologia Spec-Driven Development (SDD)

Na era do desenvolvimento auxiliado por Inteligência Artificial, a velocidade de output deixou de ser o principal gargalo — hoje, consistência e rastreabilidade são os verdadeiros desafios. À medida que as equipes de engenharia fazem a transição da programação manual para a orquestração de Agentes de IA, o risco de derivação arquitetural (architectural drift), mudanças ocultas e “alucinações estruturais” torna-se a maior ameaça à longevidade de uma base de código.

Para solucionar isso, a Montinegro Corp desenvolveu e lapidou a Metodologia Spec-Driven Development (SDD): Um framework tático rigoroso em que especificações em Markdown atuam como a fonte absoluta da verdade, ditando todo o comportamento do sistema antes que uma única linha de código seja criada ou alterada.

A Filosofia Central do SDD

O Spec-Driven Development baseia-se em uma regra inegociável: O código é meramente um reflexo volátil da especificação.

Se uma feature precisa ser adicionada, consertada ou modificada, os desenvolvedores (e os Agentes de IA) não tocam no código-fonte primeiro. Em vez disso, atualizam o texto humano da especificação. A diferença sintática e semântica entre a Spec original e a nova define o escopo arquitetural das modificações necessárias.

1. O Sistema de Rastreadores de 9 Dígitos

Para garantir compatibilidade histórica absoluta nas árvores do Git e evitar as detecções fantasmas de deleção de arquivos, forçamos um versionamento alfanumérico estrito. Todos os documentos seguem a anatomia [MMM][FFFF][VV]:

[MMM] (Módulo): Código de 3 dígitos da área de negócio (Ex: 014 para Pagamentos).
[FFFF] (Feature): Código de 4 dígitos para a ramificação específica da funcionalidade (Ex: 0142 para Integração Pix).
[VV] (Revisão): Código base-26 de 2 letras que acompanha revisões incrementais (indo de aa até zz).

Na prática, isso resulta em arquivos que não sofrem alterações violentas de nomenclatura, como: /docs/specs/014_pagamentos/0140142_api_asaas.md.

2. Versionamento Interno por YAML

Para que todo esse processo seja legível computacionalmente, todo documento de Spec inicia com uma injeção de parâmetros Frontmatter (YAML):

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

Quando a IA realiza qualquer mudança lógica na documentação, ela é orientada a auto-incrementar a hash [VV] internamente. Isso garante que esteiras de CI/CD e mecanismos de auditoria saibam exatamente a “idade” e o escopo da regra de negócio daquele arquivo.

3. O Índice Mestre [000]

Códigos que possuem o prefixo 000 são reservados para a Raiz Arquitetural. Eles funcionam de espelho primário (traduzindo sua nomenclatura estrita em “SemVer” pro mundo humano). Por exemplo, DOC_ID: 0000100an se converte visualmente num painel para o usuário moderno como a flag de controle da versão v.01.00.14 do SaaS global.

O Fluxo Ativo da Inteligência Artificial

A inteligência do nosso maquinário repousa no fluxo de uso do SDD:

Construção: Para criar o novo, a Spec nasce antes. Mantemos entre 100~400 linhas para preservar princípios de Single Responsibility (S.R.P).
Mutação (Diff Tracking): Para alterar, altera-se o arquivo .md. A IA avalia o “git diff” desse arquivo de texto, levanta inferências de segurança e aplica as deleções/criações refatorando de trás para frente no repositório.
Engenharia Reversa: Quando importados códigos legados, o agente de IA escaneia classes e rotas inteiras em Python/Dart para gerar retroativamente os arquivos estáticos formatados da Especificação.

Restrições de Arquitetura

O backend reflete essa estruturação ao utilizar um Monolito Modular centrado no DDD (Domain-Driven Design), utilizando Python + Django. Cada domínio é um app encapsulado, garantindo que o rastreio de diretórios na engine equivalha 1-pra-1 aos códigos do documento.

Por outro lado, o Client Side em Flutter mapeia tudo através de orientações Feature-First atreladas ao Atomic Design. Da spec em Markdown nascem os Tokens, em seguida os Componentes, e por fim as Páginas nativas finalizadas.

Conclusão

Ao adotar o SDD, não operamos mais baseados em “achismos” nem toleramos alucinações de modelos generativos (LLMs). O Markdown de Especificações transformou-se numa planta-baixa industrial inviolável. O Spec-Driven Development converteu a IA numa “célula programática cirúrgica” operando sob trilhas restritas, blindando a nossa arquitetura de longo prazo contra a corrosão.