Spec-Driven Guide
Guia prático de engenharia de software focado em especificações, governança e protocolos de entrega sem vazamento de contexto.
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 código é o subproduto natural de um planejamento documentado, não o ponto de partida.
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. |
| CLI (Command Line Interface, Interface de Linha de Comando) | Ferramenta que executa operações via comandos de texto no terminal. |
| 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:
- Spec First: nenhuma linha de código existe sem um contrato de intenção prévio.
- Context Integrity: deterioração de contexto é contida por protocolos rígidos de sessão.
- Zero-Leak Delivery: cada entrega está alinhada à narrativa técnica do projeto.
Stack técnica
| Tecnologia | Papel |
|---|---|
| JavaScript (ESM) | Motor nativo (Node.js >=24) |
| @inquirer/prompts | Interface interativa (wizards) |
| Markdown | Protocolos e SOPs estruturados |
| Husky & lint-staged | Automação de ganchos Git |
| Dedent | Formatação de saídas multilinhas |
| Tecnologia | Papel |
|---|---|
| Vite + Vinext | Framework RSC do site de apresentação |
| React 19 | Biblioteca de componentes de interface |
| Tailwind CSS v4 | Estilização utilitária |
| Framer Motion | Micro-animações e transições |
| Cloudflare Wrangler | Deploy na rede de borda (Edge) |
Arquitetura e governança
O ecossistema usa o SDG agents CLI para automatizar o ciclo de vida do desenvolvimento.
| Padrão | Descrição | Detalhes |
|---|---|---|
| Phase Protocol | Ciclo de 5 passos:SPEC → PLAN → CODE → TEST → END | Fluxo lógico imutável para execução de tarefas. |
| Narrative Guard | Validação semântica de commits. | Impede entregas que não seguem o padrão narrativo definido. |
| Token Discipline | Otimização de consumo de contexto. | Compressão linguística aplicada às respostas e artefatos. |
| Session Handoff | Continuidade entre devs e agentes. | Persistência de estado via backlog e arquivos de contexto. |
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 desde o bootstrap (configuração inicial) de projetos até o deploy (implantação/publicação). Traduz padrões de Staff Engineering (engenharia de software de alto nível) em comandos executáveis, mantendo a consistência do ecossistema.