Construindo este site com Spec-Driven Development

Este site está sendo construído com uma metodologia que talvez você não conheça: Spec-Driven Development (SDD). É uma abordagem que aprendi na prática, depois de anos liderando times de engenharia de dados — e que resolve exatamente o problema que todo desenvolvedor solo enfrenta: o escopo que nunca fecha.

O problema

Quando comecei a planejar o ramirosilva.com.br, sabia exatamente o que queria:

• Um hub de autoridade em inteligência de dados públicos
• Zero JavaScript nas páginas de artigo
• Deploy em menos de 60 segundos
• Lighthouse ≥ 95 em todas as categorias

Mas também sabia que, sem disciplina, o projeto iria derivar. Uma página de projetos aqui, uma versão em inglês ali, um CMS visual acolá. Em duas semanas, eu teria um site meia-boca com seis funcionalidades incompletas em vez de uma bem-feita.

A solução: um documento que governa

Antes de escrever uma linha de HTML, eu escrevi um documento de 30 seções: o roteiro SDD. Ele tem quatro partes:

1. Constituição — 7 princípios inegociáveis (exemplo: “JavaScript é exceção”, “Conteúdo antes de recurso”, “Estático por padrão”)
2. 9 especificações — em ordem de dependência, cada uma com critérios de aceitação verificáveis
3. Plano de conteúdo — 3 artigos de lançamento, um por pilar editorial
4. Checklist de lançamento — 15 itens, de Lighthouse a compliance

Orçamentos técnicos

A parte mais útil da constituição são os orçamentos. Eles são numéricos e a build falha se estourar:

Métrica	Limite
JS na rota de artigo	0 KB
Peso total da home	< 150 KB
LCP (mobile, 4G)	< 1,5 s
Lighthouse	≥ 95
Build	< 60 s

Isso elimina discussão. “Posso adicionar uma biblioteca de gráficos?” Não, porque o JS no artigo iria a 50 KB. “Posso adicionar uma imagem pesada?” Não, porque o LCP iria para 3 segundos.

A stack

A escolha técnica foi direta:

• Astro 7 — geração estática, ilhas de JS quando necessário (zero por padrão)
• Tailwind CSS v4 — tokens de design via CSS custom properties
• Cloudflare Pages — deploy em segundos, edge network global
• MDX — conteúdo em markdown com componentes importados

Como as specs funcionam

Cada spec segue o ciclo: escrever → planejar → implementar → verificar. Nenhuma spec começa antes da anterior passar na verificação.

S1 fundação ──┬── S2 design system ── S3 layout base ──┬── S4 artigos
              │                                        ├── S5 home
              │                                        ├── S6 sobre
              │                                        └── S7 lab
              └──────────────────────────────────────── S8 newsletter
                                                          S9 SEO/deploy

O elefante na sala: GitHub

Meus repositórios estão em quarentena desde um incidente de segurança em agosto de 2026. Isso significa que este site está sendo versionado em git local e deployado via wrangler pages deploy, sem integração contínua com GitHub.

A boa notícia: o Cloudflare Pages aceita deploy por CLI perfeitamente. A build roda em 4 segundos. O deploy leva mais 3. Não é ideal, mas não bloqueia.

O roteiro SDD inclui uma nota explícita sobre isso na Parte 2: repositórios de hardware (firmware ESP32, modelos 3D) podem voltar ao GitHub primeiro, porque não contêm credenciais de cliente nem dados de trabalho. Este repositório será o segundo.

Lições até agora

1. Escrever a spec antes do código economiza tempo. Descobri que o design system precisava de três fontes auto-hospedadas (em vez de duas que eu achava) antes de escrever CSS — porque a spec exigiu verificação de contraste AA.
2. Orçamentos numéricos > preferências estéticas. Saber que a home precisa pesar menos de 150 KB me fez escolher fontes Latin-only woff2 (157 KB combinadas) em vez de Google Fonts CDN.
3. O conteúdo é o produto. O SDD dedica uma parte inteira ao plano de conteúdo de lançamento — e determina que o site só vai ao ar com 3 artigos publicados. Blog vazio no lançamento queima a primeira impressão.

---

Este artigo é o terceiro de três no lançamento. Se você leu até aqui e se interessou por SDD para projetos de dados, me acompanhe — os bastidores continuam nos próximos artigos.