Nébula: Transformando LLMs de "Programadores Imaginativos" em Automação Confiável
Nébula: Transformando LLMs de "Programadores Imaginativos" em Automação Confiável
Há cerca de um mês, compartilhei aqui no TabNews a ideia do Nébula Spec Kit — um framework documental baseado em Spec-Driven Development (Desenvolvimento Orientado por Especificação), combinando minha experiência em desenvolvimento com os padrões de comportamento de LLMs.
O framework é perfeitamente utilizável de forma manual. O fluxo é simples: você pega um template como brief.md, contextualiza para o LLM e pede a saída:
"Carregue o template
brief.mde gere obrief.mdfinal para meu projeto de app de delivery."
O LLM processa e constrói o brief. Repita isso para cada um dos 15 documentos do Nébula, e você terá uma especificação completa o suficiente para guiar toda a implementação.
Cada documento é rastreável individualmente por IDs, garantindo aderência de execução e aderência de confronto documental. Nada se perde, nada se contradiz.
Por que usar arquivos .md como contrato?
Usar documentos Markdown diretamente — em vez de depender de IDEs especializadas — traz vantagens concretas:
1. Documentação como contrato
O LLM não alucina sobre o que fazer. Ele simplesmente executa o que está documentado. O Brief.md diz o escopo, o Architecture.md diz a estrutura, o Contract.yaml diz as APIs. A margem para invenção desaparece.
2. De agente imaginativo para agente de automação
Em vez de um "programador de IA" que decide stacks, padrões e arquiteturas no calor do momento, o LLM se torna um gerador de código orientado por especificação. Pense menos em "copiloto criativo" e mais em "executor de contratos bem definidos".
3. Controle real sobre o que é desenvolvido
Você elimina comportamentos hardcoded tanto em nível macro (arquitetura, fluxos) quanto micro (implementação de funções). Se algo está fora da especificação, o agente simplesmente não faz. O control.db registra todas as decisões, tentativas e invariantes — você sempre sabe o que foi feito e por quê.
4. Controle de gastos com tokens e contexto
O Nébula resolve um problema clássico: o custo de tokens que cresce proporcionalmente ao tamanho do projeto. Como cada sessão carrega apenas o contexto cirúrgico da tarefa corrente (300-600 tokens em média), o custo permanece estável do dia 1 ao dia 90.
5. Customização por documento
Cada documento do Spec Drive pode ser adaptado para um padrão diferente de análise. Um exemplo prático: implementei testes anti-mock como padrão nos meus projetos.
O problema dos testes mock e a solução anti-mock
Usando LLMs para codar, encontrei um problema recorrente: testes com mocks, stubs e placeholders geravam falsos positivos constantes. O LLM, em vez de usar os testes como contrato de validação da implementação, começava a forçar a aprovação — refatorando o código de teste para passar, não o código de produção para funcionar.
O ciclo era perverso: o teste mock falhava, a IA "corrigia" o mock para corresponder ao código (mesmo que o código estivesse errado), o teste passava, e o bug continuava lá. Falso positivo perfeito.
Minha solução: testes que validam diretamente a implementação real:
- Testcontainers para bancos e serviços externos — nada de mock de banco, sobe um container real
- Scripts
.shecurlpara validação de contratos de API — se a rota responde errado, o teste falha - Testes de integração que executam contra ambientes reais — sem atalhos, sem placeholders
- Testes de componente com dependências concretas — se depende de um serviço, ele está lá rodando
- Testes de comportamento esperado sem atalhos de mock — o usuário faz X, o sistema responde Y
O resultado são suítes de teste que cobrem cenários realistas: integração real, comportamento de componentes isolados e fluxos completos do usuário. Se o teste passa, o código funciona — sem asteriscos, sem "na minha máquina funciona", sem mock que mente.
E o melhor: como cada task do Nébula referencia os documentos de especificação, os testes são gerados a partir do contrato, não a partir da implementação. O Contract.yaml define a API, o teste valida exatamente aquela API. Se o contrato mudar, o teste muda primeiro — comportamento TDD raiz, só que automatizado.
Nébula TUI: o próximo passo
Agora estamos avançando para criar a interface TUI (Terminal User Interface) do Nébula e reduzir drasticamente a carga manual do processo. Hoje o Spec Kit funciona, mas exige que você copie, cole e contextualize manualmente cada documento para o LLM. A TUI vem para eliminar esse atrito completamente.
Para entender o que está por vir, é essencial visualizar o fluxo de desenvolvimento em três fases:
As três fases do desenvolvimento no Nébula
Fase 1 — Spec Drive (Documentação)
Tudo começa no Brief.md — o documento mais personalizado do projeto e o único que merece crivo verdadeiramente imaginativo. Um brief bem definido resulta em documentação robusta.
É aqui que você contextualiza:
- O que o projeto é e o que não é
- Problemas que resolve
- Visão macro da stack
- Escolhas de banco de dados
- Restrições e premissas
Gaste tempo no brief. Invista no brief. Ele é a semente dos outros 14 documentos.
Os 15 documentos do Spec Drive:
| # | Documento | Responsabilidade |
|---|---|---|
| 01 | Brief.md | Visão livre — contexto, motivação, propósito |
| 02 | Project.md | Escopo formal, objetivos e limites do projeto |
| 03 | Stack.md | Tecnologias, linguagens, frameworks e ferramentas |
| 04 | UserStories.md | Histórias de usuário no formato padrão |
| 05 | Pages.md | Todas as telas, descrição e propósito de cada uma |
| 06 | Flow.md | Fluxos de navegação e interação do usuário |
| 07 | Design.md | Diretrizes visuais, componentes e padrões de UI/UX |
| 08 | Tokens.json | Design tokens: cores, tipografia, espaçamentos |
| 09 | Entities.md | Entidades de domínio e seus relacionamentos |
| 10 | Architecture.md | Arquitetura do sistema, padrões e decisões técnicas |
| 11 | Contract.yaml | Contratos de API (OpenAPI/Swagger) |
| 12 | Structure.md | Estrutura de pastas e organização do código-fonte |
| 13 | Deploy.md | Estratégia de deploy, ambientes e infraestrutura |
| 14 | Plan.md | Plano de execução por fases e marcos |
| 15 | Tasks.md | Tarefas atômicas derivadas do plano |
Praticamente todas as documentações são rastreáveis por ID, garantindo consistência entre si quando processadas pelo LLM.
O fluxo de criação segue um roteiro hierárquico com dependências explícitas:
graph TD
A[Brief.md] --> B[Project.md]
B --> C[Stack.md]
B --> D[Stories.md]
C --> E[Architecture.md]
D --> E
D --> F[Flow.md]
F --> G[Pages.md]
G --> H[Design.md]
H --> I[Tokens.json]
B --> J[Entities.md]
J --> E
E --> K[Contract.yaml]
C --> L[Structure.md]
E --> L
L --> M[Deploy.md]
A --> N[Plan.md]
B --> N
C --> N
D --> N
G --> N
F --> N
H --> N
I --> N
J --> N
E --> N
K --> N
L --> N
M --> N
N --> O[Tasks.md]
Cada aresta é uma dependência. Architecture.md não é gerado no vácuo — ele lê Stack.md, Entities.md e Flow.md antes. O comando /clarify valida essa consistência antes de qualquer avanço de fase. O agente não avança sem confirmação do estado correto.
Fase 2 — Prototipagem
Com o Spec Drive completo e validado, criamos protótipos de alta fidelidade baseados em cinco documentos:
| Documento | O que fornece ao protótipo |
|---|---|
Pages.md | Descrição com ID de cada tela, conteúdo e fluxo de uso |
Flow.md | Navegação entre páginas/telas: estado → ação → consequência |
Stories.md | Histórias de usuário por tipo: User, Admin, Dev |
Design.md | Design System completo do projeto |
Tokens.json | Tokens de design: cores, tipografia, espaçamentos |
graph LR
A[Pages.md] --> E[Prototype]
B[Flow.md] --> E
C[Stories.md] --> E
D[Design.md] --> E
F[Tokens.json] --> E
Os protótipos são HTML, CSS e JS puros — sem frameworks, sem dependências externas. São exatamente o que o usuário final verá e com o que interagirá. Nada de wireframe cinza: é interface real, fiel e navegável.
Fase 3 — Implementação
Na implementação, apenas dois documentos operam diretamente: Plan.md e Tasks.md. Eles contêm leituras guiadas para as outras documentações, acionadas sob demanda.
O fluxo de trabalho é direto:
"Implementar task-001" → Aguardar conclusão → "Implementar task-002" → ...
Estrutura de cada task:
TASK-001 — Descrição curta e objetiva
Local: /caminho/dos/arquivos
Page ID: PAGE-003
Flow ID: FLOW-007
Story ID: US-012
Contract ID: API-001
Entity ID: ENT-004
Architecture ID: ARCH-002
Token IDs: TOK-001, TOK-005
Design IDs: DS-003, DS-007
Subtasks:
- Validação de aderência documental
- Execução de testes
- Commit e push
Critérios de aceite:
- Implementação em aderência com a documentação
- Todos os testes passando
- Build sem erros
A próxima task só começa depois que a última foi concluída com sucesso. Sem exceções. Sem atalhos. Task que falha mais de duas vezes é marcada como blocked e exige intervenção humana — o agente não fica preso em loop de tentativa e erro.
Diferenciais estratégicos do Nébula
Backend como contrato
Começamos o desenvolvimento pela definição das integrações, contratos de API (internos e externos), entidades e estrutura de dados. O backend é a chave: se você o implementa com sucesso, o frontend apenas o obedece como contrato. Não há espaço para divergência entre o que o backend entrega e o que o frontend espera.
Estrutura antecipada
As primeiras tasks do Tasks.md são dedicadas à preparação do ambiente: criação da estrutura de diretórios e arquivos vazios. O Nébula cria antecipadamente todas as pastas e arquivos necessários. As tasks subsequentes não criam arquivos — elas os editam com base no Spec Drive. Isso mantém a integridade da estrutura do início ao fim e evita surpresas de arquivos fora do lugar.
Documentação de APIs externas
Para serviços de terceiros (ex: API do Asaas, Stripe, AWS), crie documentos separados ou utilize MCP servers dedicados. O Nébula trata APIs externas como contratos documentados, não como chamadas improvisadas no meio do código. Se a API externa tem documentação, ela vira parte do Spec Drive.
Sessões atômicas com memória persistente
O LLM não tem memória entre sessões por natureza. O Nébula resolve isso com estado persistente em SQLite (.nebula/control.db). A cada nova sessão, o agente lê esse estado e gera um briefing cirúrgico:
- Onde estava: última sessão no mesmo escopo
- Não repita: abordagens que já falharam
- Não quebre: invariantes e decisões já tomadas
- Incerto: decisões que podem ter sido invalidadas por mudanças externas
Isso mantém o custo de tokens estável independente da maturidade do projeto. Uma sessão de /stack no dia 1 e no dia 90 consome a mesma ordem de grandeza.
Minha abordagem: LLM como automação, não como desenvolvedor autônomo
Depois de mais de 7 anos programando, sendo 2 deles com uso intensivo de LLMs, minha conclusão é clara:
Não uso IA como "Self AI" autônoma. Uso IA como automação — para criar código mais rápido do que consigo digitar, dentro de contratos que eu defino.
O Nébula materializa essa filosofia. Ele retira o crivo imaginativo da IA e a transforma em executora automatizada de código. O desenvolvedor assume os papéis de:
- Engenheiro de projetos (Spec Drive)
- QA (validação documental e testes)
- Designer de produto (protótipos)
- Arquiteto (decisões técnicas registradas)
A IA executa. Você decide.
Roadmap do Nébula
Fase 1 (em desenvolvimento) — A TUI do Nébula
Onde estamos agora: construindo a interface de terminal (TUI) que transformará o Nébula de um framework manual em uma ferramenta interativa.
Hoje, o Spec Kit funciona — mas exige que você copie, cole e contextualize manualmente cada um dos 15 documentos para o LLM. Funciona, mas é artesanal. A TUI vem para eliminar esse atrito.
O que está sendo construído:
- REPL interativo: você digita
/brief,/stack,/clarifye o agente executa — sem abrir editor, sem copiar template, sem colar contexto - Sessões atômicas: cada comando abre e fecha uma sessão com escopo fechado, registro de estado e briefing cirúrgico gerado automaticamente
- Estado persistente: o
control.db(SQLite) lembra onde você parou, o que já foi decidido, o que falhou e o que não pode ser violado — mesmo entre sessões separadas por dias - Stack: TypeScript, Node.js LTS, Ink + React para a TUI, Vercel AI SDK para o agente, MCP Server para as tools internas
Tecnologias da TUI:
TypeScript + Node.js LTS
Ink + React (renderização no terminal)
CAC (parsing de comandos)
Zod (validação de entrada)
better-sqlite3 (estado persistente)
Vercel AI SDK (agent loop)
@modelcontextprotocol/sdk (tools do agente)
O que já funciona no código:
- Estrutura base do Core com sistema de comandos registráveis
- REPL que distingue comandos (
/comando) de mensagens livres para o agente - Sessões que abrem, executam e fecham com registro atômico
- Leitura e escrita de documentos com backup automático antes de sobrescrever
- Geração de briefing cirúrgico (contexto mínimo relevante — 300 a 600 tokens)
O que está em desenvolvimento ativo:
- Integração completa do agent loop com Vercel AI SDK
- Renderização da TUI com Ink (interface de terminal componentizada em React)
- Comandos de validação (
/clarify) com análise de aderência entre documentos - Orquestrador de tasks com dependências (fila
queued → ready → running → done)
Nesta fase, o foco é documentação. O Nébula cria e valida todo o Spec Drive — 15 documentos encadeados com dependências explícitas — mas ainda não executa implementação de código. É a fase de estabelecer o contrato completo e consistente antes de escrever uma linha.
Fase 2 — Prototipagem
Capacidade de gerar protótipos automaticamente a partir dos documentos validados. Interface real, navegável, HTML/CSS/JS puro — sem frameworks, sem dependências externas. Comando /prototype gera todas as telas ou uma tela específica.
Fase 3 — Execução
Implementação do código do projeto guiada pelo Spec Drive e pelos protótipos. O agente executa task por task, com escopo fechado, critério de sucesso objetivo e registro atômico de cada operação. Comandos /implement [fase] e /implement all controlam o fluxo completo.
Uma caminhada longa, mas necessária
Mesmo com mais de 7 anos de experiência em programação e 2 usando LLMs intensivamente, construir o Nébula não é simples. Estamos essencialmente criando um ambiente de desenvolvimento onde a documentação é o runtime — onde o contrato precede a execução e a imaginação da IA é substituída por rastreabilidade e previsibilidade.
É uma mudança de paradigma. E está só no começo.
Se você se interessa por Spec-Driven Development, automação com LLMs ou quer contribuir com a construção da TUI, fique à vontade para acompanhar o projeto e participar das discussões. Toda contribuição é bem-vinda — seja código, feedback sobre a abordagem ou ideias para os próximos passos.