Spec-Driven Guide

O Spec-Driven Guide (SDG) é um guia prático de engenharia de software centrado em especificações. Ele funciona como a fonte da verdade para fluxos de trabalho assistidos por IA: o planejamento documentado vem primeiro, e o código é escrito a partir dele.

Como autor desta metodologia, construí o ecossistema que sustenta a documentação e a automação do ciclo de vida.

Conceitos fundamentais

Conceito	O que é
SDD (Spec-Driven Design, Design Orientado por Especificações)	Metodologia que exige um contrato de intenção antes de qualquer linha de código.
SSoT (Single Source of Truth, Fonte Única da Verdade)	Fonte de dados única que evita inconsistências entre sistemas e agentes.
agente de IA	Assistente que lê e escreve código no projeto (Claude Code, Cursor, Windsurf, Copilot, Codex e outros). O SDG instala instruções que qualquer um deles lê.
Phase Protocol (protocolo de fases)	O ciclo de 5 fases que estrutura qualquer tarefa: SPEC → PLAN → CODE → TEST → END.
Work Checklist (checklist de trabalho)	Lista recitada pelo agente antes da primeira escrita de arquivo, em duas seções binárias: Intent (intenção: reset mental, arquivos-alvo, nomes, testes, segurança) e Form (forma: densidade vertical, prefixo booleano, retornos explicativos), esta verificada na fase TEST.
Circuit Breaker (disjuntor)	Regra de 3 tentativas que interrompe laço de regressão: o agente para e reporta ao repetir o mesmo erro 3 vezes ou ficar 3 turnos sem progresso.
skill (competência)	Unidade de instrução independente, carregada só quando o ciclo precisa dela. Cobrem code style, testes, segurança, API, dados, observabilidade, CI/CD, cloud, SQL, UI/UX, revisão, performance e modelagem de domínio.
Impact Map (mapa de impacto)	Arquivo temporário criado na fase PLAN e apagado na END, que lista o raio de alcance da mudança. Diz ao agente quais arquivos carregar, mantendo o contexto enxuto.
flavor (sabor arquitetural)	O padrão estrutural do projeto, escolhido na instalação: vertical slice, MVC, lite ou legacy.
CLI (Command Line Interface, Interface de Linha de Comando)	Ferramenta que executa operações via comandos de texto no terminal.
bootstrap (configuração inicial)	A primeira instalação do projeto: o CLI cria a estrutura de arquivos e as instruções que o agente vai ler dali em diante.
build (construção)	Etapa que monta os arquivos finais a partir do código-fonte, antes de publicar.
deploy (publicação)	Envio do resultado do build para o servidor que atende o público. Aqui, a rede de borda da Cloudflare.
ESM (ECMAScript Modules, Módulos ECMAScript Nativos)	Sistema de módulos nativo do JavaScript, sem necessidade de transpilação.
RSC (React Server Components, Componentes React de Servidor)	Componentes React executados exclusivamente no servidor, sem JavaScript no cliente.

Filosofia: Spec-driven design (SDD)

O projeto se apoia em três pilares:

1. Spec First (especificação primeiro): nenhuma linha de código existe sem um contrato de intenção prévio.
2. Context Integrity (integridade de contexto): protocolos rígidos de sessão impedem que o contexto se degrade ao longo do trabalho.
3. Zero-Leak Delivery (entrega sem vazamento): cada entrega segue a narrativa técnica do projeto.

Stack técnica

Arquitetura e governança

O ecossistema usa o SDG agents CLI para automatizar o ciclo de vida do desenvolvimento.

Site de apresentação

O site specdrivenguide.org apresenta a metodologia. Construído com Vinext e React 19, prioriza legibilidade técnica e navegação entre os protocolos de engenharia.

SDG agents CLI

O CLI automatiza a governança do projeto, do bootstrap ao build e ao deploy. Traduz padrões de Staff Engineering (engenharia de software sênior, voltada a decisões que afetam vários times) em comandos executáveis e mantém a consistência entre os projetos.

Um npx sdg-agents instala no projeto um conjunto de arquivos Markdown de instrução. Não há biblioteca para importar nem runtime para subir: o que o CLI entrega é texto que o agente lê antes de trabalhar.

O que instala	Quanto
Skills carregadas sob demanda	16, de code style e testes a segurança, API, dados, observabilidade, CI/CD, cloud, SQL, UI/UX, revisão, performance e domínio
Comandos de ciclo	6: feat:, fix:, docs:, audit:, land: e end:
Flavors arquiteturais	4: vertical slice, MVC, lite e legacy
Testes do próprio CLI	254

O que fica no projeto depois da instalação

A pasta .ai/backlog/ é a memória entre sessões, e é ela que resolve o problema do contexto que se perde quando a janela do agente acaba:

• context.md guarda o resumo do projeto e o objetivo atual.
• tasks.md é a fonte da verdade do estado do trabalho, então qualquer agente, em qualquer sessão, continua de onde o anterior parou.
• stack.md traz as linguagens e versões declaradas pelo dev no ciclo land:, e a fase CODE lê esse arquivo em vez de adivinhar idiomas da stack.
• learned.md acumula o que deu certo e as correções recebidas.
• impact-map.md é temporário: nasce na fase PLAN com o raio de alcance da mudança e é apagado na END.

O CLI é compatível com qualquer agente. O arquivo canônico é .ai/skills/AGENTS.md, e o CLAUDE.md na raiz é gerado a partir dele para o Claude Code; outras ferramentas apontam para o mesmo arquivo com uma linha de configuração.