Arquitetura SPEC-Driven: o especialista como maestro do ecossistema de IA

O contexto que mudou tudo

Cinco anos atrás, "engenheiro sênior" significava domínio profundo de uma stack — Rails, Vue, Postgres — e capacidade de entregar features complexas dentro do domínio. Hoje, o mesmo profissional precisa, no mesmo dia, decidir se um trecho vai virar:

• código escrito por um humano,
• código gerado por um LLM em IDE com agentes,
• workflow automatizado em N8N,
• servidor MCP que expõe a função para múltiplos clientes,
• busca RAG sobre uma base existente,
• ou simplesmente uma planilha do cliente que ninguém precisa migrar.

Cada uma dessas opções tem um custo, um SLA, uma manutenibilidade e uma curva de produtividade diferente. Decidir cedo, e decidir com critério, é o novo trabalho técnico.

O que é SPEC-Driven Development

SDD é um padrão de trabalho onde a especificação — não o código, não o desenho — é o artefato central do projeto. A especificação descreve:

• Intenção: qual problema do negócio resolver e por quê.
• Contrato: quais entradas e saídas, quais invariantes, quais erros são esperados.
• Restrições: custo máximo, latência máxima, requisitos de LGPD/GDPR, prazo.
• Critérios de aceite: como saber, sem ambiguidade, que está pronto.

Dela derivam todos os outros artefatos: testes, código, prompts de LLM, configurações de servidor MCP, workflows N8N, documentação para o cliente. Mudou a especificação? Tudo abaixo é regenerado ou revisado. Não mudou? Não existe motivo para tocar no resto.

Quem trabalhou com TDD reconhece o esqueleto — só que aqui o "test first" virou "spec first", e a spec é executável o suficiente para validar geração de código por IA, não só para validar comportamento humano.

Por que isso só agora vira viável

Em 2020, escrever uma especificação detalhada e manter sincronia com o código era proibitivamente caro. A spec virava museu — escrita uma vez, esquecida.

Três coisas mudaram:

1. LLMs leem spec — uma especificação clara em markdown vira input direto para gerar código consistente, em vários ciclos. O custo de tradução spec→código caiu para perto de zero.
2. Ferramentas executam spec — sistemas de teste, geradores de schema, validadores de contrato consomem o mesmo documento. Spec virou fonte de verdade operacional.
3. MCP padronizou integrações — descrever uma capacidade no formato MCP é, na prática, escrever especificação executável.

O especialista como maestro: a postura

Maestro de orquestra não toca todos os instrumentos. Ele conhece cada um o suficiente para julgar se está afinado, e decide quando cada um entra. O engenheiro sênior em 2026 trabalha assim:

Conhece sem precisar dominar tudo

Um maestro técnico não escreve a melhor query SQL do time, não treina o melhor modelo, não desenha a melhor UI. Ele reconhece o que é bem-feito, identifica desvio, e tem opinião sobre custo/benefício. Profundidade em alguns instrumentos, leitura geral em todos.

Decide rápido, com critério explícito

"Faz LLM ou faz código?" — a resposta não é "depende". É um modelo mental treinado:

• É determinístico e tem regra clara? Código.
• Tem ambiguidade textual ou natural? LLM com prompt versionado.
• É processo com 3+ etapas em sistemas distintos? Workflow (N8N, Temporal).
• Vai ser usado por múltiplos clientes? Servidor MCP.
• Precisa pesquisar contexto na base da empresa? RAG.

Critério bom é compartilhável. O maestro escreve essa decisão na spec — a próxima pessoa que tocar entende por que a escolha foi essa.

Orquestra mais do que produz

O dia típico não é mais "8 horas escrevendo código". É mais parecido com:

• 1h refinando spec com o cliente (a parte que ninguém pode delegar).
• 1h conduzindo agentes em IDE (Cursor, Claude Code) para gerar a primeira versão a partir da spec.
• 2h revisando o que foi gerado, ajustando partes críticas à mão, completando edge cases.
• 1h conectando peças via MCP/N8N quando faz mais sentido que escrever cola.
• 1h em testes integrados — incluindo red team dos prompts e servidores MCP.
• 1h em comunicação assíncrona (revisão de PR, doc, atualização da spec).

Note como a "produção bruta de código" sumiu como bloco dedicado. Ela está distribuída e amplificada por agentes.

Stack típico do maestro em 2026

O ecossistema que vejo nos meus projetos B2B atuais:

• Especificação: markdown versionado em Git, com seções padronizadas (Intenção, Contrato, Restrições, Aceite). Esquemas em JSON Schema ou OpenAPI quando faz sentido.
• Geração: Cursor ou Claude Code com agentes acionados pela spec. Modelos: Claude Sonnet/Opus para arquitetura, Haiku para refactor mecânico.
• Integração: MCP servers para tudo que vai ser usado por mais de um cliente humano ou agente. Workflows N8N para processos cross-system.
• Conhecimento: RAG sobre documentos do cliente (políticas, manuais, casos passados) — alimenta tanto o agente do dev quanto o produto final.
• Observabilidade: logs estruturados, traces de chamadas a LLM e MCP, painel de custos por feature.
• Testes: unit + integration + eval (avaliação de saídas de LLM contra rubrica). O eval virou cidadão de primeira classe no CI.

Um exemplo concreto

Cliente: escritório jurídico que recebe ~50 dúvidas/dia de clientes via WhatsApp, maioria repetitiva. Quer reduzir tempo de resposta sem perder qualidade.

1. A spec (o ponto central)

Em ~3 páginas de markdown: o problema, fluxo desejado, contratos de mensagem, restrições de LGPD, critério de aceite ("85% das dúvidas resolvidas em < 2min, 0% de invenção factual sobre legislação").

2. As decisões do maestro (com base na spec)

• Recepção via WhatsApp Business API → código (determinístico).
• Roteamento por intenção → LLM com prompt versionado.
• Resposta com base em legislação → RAG sobre base documental curada (não vale buscar na internet aberta — risco de alucinação alta).
• Escalonamento para advogado humano → workflow N8N com critérios da spec (palavras-chave de risco, valor da causa).
• Acesso ao histórico do cliente pelos atendentes humanos → servidor MCP conectando ao sistema do escritório.

3. A execução

Em ~3 semanas, com agentes em IDE escrevendo a partir da spec, o maestro revisando saídas críticas e conectando os MCPs. Sem o padrão SDD, esse mesmo escopo tradicional levaria 6-10 semanas.

Métricas que importam para um time SDD

• Tempo da spec ao MVP — quanto demora do "spec aprovada" ao primeiro deploy útil.
• % de spec coberta por testes/eval — sinal de que a spec é executável de verdade.
• Custo por feature — soma de horas humanas + chamadas a LLM + infra. Maestro bom reduz isso ciclo a ciclo.
• Taxa de retrabalho pós-deploy — quando alta, indica spec ambígua ou agente sem critério suficiente.
• Lead time de mudança de spec — quanto demora propagar uma alteração de regra do cliente para todo o sistema.

Armadilhas que o maestro precisa evitar

1. Virar gargalo — quando todas as decisões passam por uma pessoa, o time para. Documente critérios para que outros decidam o trivial.
2. Spec virar museu — se ninguém atualiza, retorna o pesadelo dos anos 2010. Spec viva exige cultura.
3. Confiar cegamente no agente — código gerado precisa de revisão humana exatamente nos pontos onde a spec é menos precisa.
4. Otimizar tooling em vez de problema — sintoma comum de maestro novato: passar mais tempo escolhendo IDE/modelo/framework do que conversando com o cliente.
5. Esquecer pessoas não-técnicas — gerente, suporte, jurídico também precisam entender a spec. Linguagem clara é parte do papel.

Como virar maestro (caminho realista)

1. Tenha cicatrizes em pelo menos 2 stacks bem diferentes. Sem profundidade real em algum lugar, você não reconhece bom trabalho.
2. Use IA todo dia, com diferentes modelos. Quem só usa Claude ou só usa ChatGPT não tem critério para escolher.
3. Construa um servidor MCP do zero — uma tarde com docs oficiais. Quem nunca implementou não entende o protocolo de verdade.
4. Faça um RAG de fim de semana com pgvector e 100 documentos. Sentir embedding, chunking e avaliação na pele muda como você decide.
5. Escreva uma spec real e siga — pegue um problema seu, escreva a spec, gere código com agente, ajuste. Sentir o loop é insubstituível.
6. Dê e receba feedback técnico — code review, palestra, post, mentoria. Maestro bom articula por que escolheu cada nota.

Conclusão

SPEC-Driven Development não é metodologia para ser "vendida" em curso de uma tarde. É a forma que o trabalho de engenharia sênior já está tomando em times que abraçaram IA com seriedade. O nome é novo; a prática vem se formando há uns dois anos.

O especialista deixa de ser quem escreve mais — vira quem decide o que escrever, o que automatizar, o que ainda precisa de humano. O maestro do ecossistema. E a especificação é a partitura.

Se quer trazer essa postura para sua equipe — seja como consultoria pontual, mentoria de tech leads ou implementação de POC com a stack certa — o diagnóstico inicial é gratuito.