Spec Programming & Execution Logic Language · v3.0.0

Especificação que compila. Código que obedece.

Sua equipe está usando IA para gerar código sem especificação formal. A IA toma decisões arquiteturais que só você deveria tomar. O resultado chega em produção diferente do que foi aprovado.

SPELL resolve isso na raiz: uma linguagem estruturada que transforma a visão do arquiteto em contrato compilável — antes de qualquer linha de código ser escrita.

Baixar SPELL v3.0.0 Como funciona →

spell-package.zip · Grátis · Sem cadastro

agenda.spell

// o arquiteto declara o que o sistema faz
// a IA decide como implementar

Regras {

  rule HorarioDisponivel {
    contexto: Agendamento de consulta
    condicao: Médico já tem consulta no
               mesmo horário
    acao:     Recusar com mensagem de
               horário indisponível
    motivo:   Política da clínica
  }

  rule CancelamentoAntecedencia {
    contexto: Cancelamento de consulta
    condicao: Menos de 24h de antecedência
    acao:     Exibir aviso + pedir confirmação
    motivo:   Reduzir faltas de última hora
  }

}

// a IA nunca inventa regras de negócio
// o que não está aqui não será implementado
        

O custo real do vibe coding

Vibe coding funciona.
Mas só depois que
alguém faz o
Vibe Engineering.

— Marcos Fiore

Pedir código diretamente para uma IA sem especificação formal não é desenvolvimento — é uma aposta. A IA infere o que não foi dito, inventa regras de negócio que não existem e toma decisões arquiteturais sem autoridade para isso.

O problema não aparece no primeiro sprint. Aparece quando o sistema que chegou em produção é diferente do que foi aprovado. Quando o dev que escrevia os prompts sai da empresa e o conhecimento vai junto. Quando o retrabalho come o orçamento do próximo trimestre.

O SPELL não resolve o problema depois. Ele elimina a causa: ausência de uma especificação formal que a IA seja obrigada a seguir como contrato.

Decisões arquiteturais não autorizadas A IA escolheu padrões, estruturas e tecnologias que você nunca aprovou — e o código já está em produção.

Especificação que some com a equipe O conhecimento do sistema vive no histórico de chat. Quando o dev sai, a spec vai junto.

Entrega diferente do que foi aprovado Sem um contrato formal, não há como validar se o código gerado implementa o que o negócio precisa.

Débito técnico invisível até ser tarde Sessões diferentes de IA produzem convenções diferentes. A inconsistência se acumula silenciosamente.

O que é o SPELL

A spec não é
escrita.
Ela é provada.

SPELL é uma linguagem estruturada de especificação de software. Não é linguagem de programação. É o elo formal entre a visão do arquiteto e o trabalho de qualquer agente de IA gerador de código.

O arquiteto escreve o que o sistema deve fazer — entidades, regras de negócio, endpoints, telas, segurança. O compilador valida, audita e gera um conjunto de arquivos que o agente de IA segue como contrato. Sem inferências, sem ambiguidades, sem decisões arquiteturais delegadas à IA.

A spec fica no repositório, ao lado do código. Sobrevive à rotatividade de equipe. É compilável, versionável, auditável.

"O arquiteto nunca é obrigado a saber mais do que o negócio exige. A IA nunca pode saber mais do que o arquiteto declarou."

padroes.spell + modulo.spell → CLAUDE.md

// padroes.spell — decisões de engenharia

Tecnologia {
  Backend {
    linguagem: Node.js 22
    banco:     PostgreSQL
    agente:   claude-code
  }
}

ConvencoesD {
  chave-primaria:      id UUID
  soft-delete:         sim, via deleted_at
  campos-de-auditoria: created_at, updated_at
}

// modulo.spell — domínio do negócio

Dados {
  table consultas {
    id:        texto, chave-primaria
    medico_id: texto, obrigatorio
    status:    texto, padrao: "Agendada"
  }
}

          

Output gerado pelo spellcomp

            ✅ CLAUDE.md ← entrada do agente

            ✅ projeto-padroes.md

            ✅ projeto-dados.md

            ✅ projeto-regras.md

            ✅ projeto-endpoints.md

            ✅ projeto-telas.md

O diferencial real

O auditor semântico
detecta o que revisão
humana não captura.

Após construir o AST completo do projeto, o spellcomp audita a spec e produz um relatório de diagnóstico — antes de gerar qualquer arquivo. Nenhum agente começa a trabalhar enquanto houver inconsistências não resolvidas.

gaps lógicos

Entidade sem regra de transição

Campo status declarado na tabela sem nenhuma regra que governe suas transições. O agente não saberá quando mudar de "Pendente" para "Aprovado".

contradições

Regras conflitantes

Duas regras com comportamentos opostos para o mesmo contexto — o agente escolherá uma arbitrariamente. O compilador bloqueia antes de qualquer código ser gerado.

referências mortas

Endpoint aponta para regra inexistente

Um endpoint referencia regras: HorarioDisponivel mas essa regra nunca foi declarada no bloco Regras. Detectado na compilação, não no runtime.

entidades órfãs

Tabela declarada sem endpoint

Uma entidade foi especificada mas nenhum endpoint a escreve. Dado que nunca chegará ao banco. Arquiteto decide: é intencional ou esquecimento?

cobertura de erros

Endpoint sem resposta 404

Endpoint que busca por ID não declara resposta para "não encontrado". O agente deixará o comportamento indefinido — ou pior, escolherá um tratamento errado.

delegação crítica

Decisões de alto impacto delegadas

Muitos campos críticos marcados como recomendar em itens de alto impacto. O auditor avisa — o arquiteto decide se é intencional.

skills automáticas

Capacidades detectadas e injetadas

O compilador cruza o AST e detecta skills implícitas — integração com Stripe, upload de arquivos, envio de e-mail. O agente chega na sessão já avisado do que vai precisar dominar, sem que o arquiteto precise declarar manualmente.

integridade garantida

Spec protegida contra edições diretas

Cada .md gerado recebe um hash SHA-256. O spellcomp compile verifica automaticamente antes de gerar — se algum arquivo foi editado diretamente, a compilação é abortada. A rastreabilidade entre .spell e código é inquebrável.

Instalação

Pronto em
minutos.

O pacote inclui o compilador, o manual completo do arquiteto, a referência da linguagem e exemplos prontos para uso.

Baixe e extraia o pacote
Descompacte o spell-package.zip em uma pasta de sua escolha.

Copie o spell.md para a raiz do projeto
Este arquivo define o contexto da linguagem para o agente de IA.

Inicialize e escreva seu .spell
Use qualquer editor de texto. O manual está incluído no pacote.

Compile, valide e entregue ao agente

Baixar SPELL v3.0.0

# verificar instalação $ spellcomp --version SPELL Compiler v3.0.0 # validar sem gerar output $ spellcomp check . ✅ 4 tabelas │ 6 regras │ 9 endpoints ⚠ endpoint /consultas sem resposta 404 # compilar e gerar os .md $ spellcomp compile . ✅ CLAUDE.md gerado ✅ agenda-padroes.md ✅ agenda-dados.md ✅ agenda-regras.md ✅ agenda-endpoints.md ✅ agenda-telas.md

estrutura do projeto

meu-projeto/ ├── meu-projeto.spell ← índice + metadados ├── padroes.spell ← stack e convenções ├── fase-1/nucleo.spell← domínio do negócio ├── CLAUDE.md ← gerado · não editar ├── LEIAME.txt ← para o arquiteto └── wireframes/

Perguntas frequentes

FAQ

O que é o SPELL?

SPELL é uma linguagem estruturada de especificação de software. O arquiteto descreve o que o sistema deve fazer — entidades, regras de negócio, endpoints, telas — em arquivos .spell. O compilador spellcomp valida, audita e gera um conjunto de arquivos que qualquer agente de IA segue como contrato.

Não é linguagem de programação. É a camada formal que existe entre a visão do arquiteto e o trabalho da IA.

O que o SPELL faz que nenhuma outra ferramenta faz?

Compilar a especificação. Qualquer equipe pode escrever um documento descrevendo o sistema — o SPELL transforma essa descrição em um artefato verificável.

O spellcomp constrói o AST completo do projeto e detecta o que nenhuma revisão humana garante capturar: referências mortas, entidades declaradas sem nenhum endpoint que as escreva, regras de negócio conflitantes, campos status sem transições definidas, endpoints sem cobertura de erro.

A spec não é apenas escrita — ela é provada antes de qualquer código ser gerado. Essa camada de auditoria é o que separa o SPELL de um documento bem escrito.

Por que uma spec em Markdown não resolve o problema?

Um documento Markdown descreve intenções. Mas intenções não são verificadas — são interpretadas. Quando o agente de IA lê uma spec em linguagem natural, ele preenche os vazios com inferências. E cada sessão pode preencher de forma diferente. O resultado é um sistema que às vezes implementa o que foi descrito, às vezes implementa o que a IA achou mais razoável. Para um CTO, isso significa que a entrega é uma aposta — não um contrato.

Do ponto de vista técnico, o spellcomp constrói um AST completo da especificação e valida o grafo inteiro antes de gerar qualquer arquivo. Referências entre módulos são verificadas. Regras citadas em endpoints precisam existir. Entidades declaradas sem nenhum endpoint que as escreva geram aviso. Esse nível de validação estrutural é impossível em texto livre — não importa quão bem escrito esteja.

O SPELL é uma ferramenta exclusiva do Claude?

Não. O spellcomp gera o arquivo de entrada correto para o agente que seu time já usa: Claude Code, Cursor, Copilot, Aider. O campo agente no padroes.spell controla qual arquivo é gerado. Você não precisa trocar de ferramenta para adotar o SPELL.

Preciso especificar tudo antes de começar a desenvolver?

Não. O SPELL tem três níveis de detalhe: você pode especificar cada campo de cada tabela, ou pode escrever estrutura: recomendar e deixar a IA decidir. O arquiteto declara o que sabe. A IA completa o que não foi dito — e lista o que inferiu antes de gerar qualquer código.

Posso adotar o SPELL em projetos que já estão em andamento?

Sim. O SPELL é incremental. Você começa especificando apenas o próximo recurso — não precisa retrospecificar o que já existe. A cada nova feature, a spec cresce junto com o produto, sempre compilável e auditável.

O SPELL substitui o BMAD ou o OpenSpec?

Não compete. O BMAD organiza o processo de desenvolvimento — quem faz o quê e em que ordem. O OpenSpec estrutura histórias de usuário. O SPELL é a camada anterior: a especificação técnica formal que alimenta qualquer um desses fluxos como fonte da verdade imutável.

O que acontece com a spec quando um desenvolvedor sai da empresa?

Ela continua no repositório, versionada junto com o código. O conhecimento do sistema não vive no histórico de chat — vive no .spell. Qualquer novo membro do time, ou agente de IA, pode compilar a spec e entender exatamente o que foi especificado e por quê.

O spellcomp é gratuito?

A versão atual é gratuita e sem cadastro. Um modelo de licenciamento está planejado para versões futuras com recursos avançados, mas o compilador completo para uso individual permanece gratuito.

Especificação que compila. Código que obedece.

Vibe coding funciona.
Mas só depois que
alguém faz o
Vibe Engineering.

A spec não é
escrita.
Ela é provada.

O auditor semântico
detecta o que revisão
humana não captura.

A próxima abstração
já chegou.

Do contrato
ao código
em cinco passos.

Funciona com
qualquer
agente de IA.

Pronto em
minutos.

Pare de apostar.
Comece a contratar.

FAQ

Especificação que compila. Código que obedece.

Vibe coding funciona. Mas só depois que alguém faz o Vibe Engineering.

A spec não éescrita. Ela é provada.

O auditor semântico detecta o que revisão humana não captura.

A próxima abstraçãojá chegou.

Do contratoao códigoem cinco passos.

Funciona comqualqueragente de IA.

Pronto emminutos.

Pare de apostar. Comece a contratar.

FAQ

Vibe coding funciona.
Mas só depois que
alguém faz o
Vibe Engineering.

A spec não é
escrita.
Ela é provada.

O auditor semântico
detecta o que revisão
humana não captura.

A próxima abstração
já chegou.

Do contrato
ao código
em cinco passos.

Funciona com
qualquer
agente de IA.

Pronto em
minutos.

Pare de apostar.
Comece a contratar.