Seu primeiro arquivo .spell

O arquivo mínimo válido

O compilador nunca rejeita uma spec por estar incompleta. O arquivo mais simples possível que o spellcomp aceita contém apenas um bloco Projeto e um bloco Dados:

meusistema.spell

Projeto {
  nome: MeuSistema
  versao: 1.0
}

Dados {
  table Usuario {
    nome: texto(100), obrigatorio
    email: texto(200), unico, obrigatorio
  }
}

Esse arquivo é suficiente para o compilador gerar um CLAUDE.md e um arquivo meusistema-dados.md com as instruções para a IA. Nenhum erro. Nenhum aviso sobre blocos ausentes.

O bloco Projeto

O bloco Projeto identifica a spec. Ele é declarado no arquivo-índice do projeto — o arquivo que tem o mesmo nome do diretório. Os campos disponíveis são:

Campo	Obrigatório	Descrição
`nome`	Sim	Nome do projeto, sem espaços. Usado como prefixo nos arquivos gerados.
`versao`	Sim	Versão da spec. String livre — use semver ou qualquer convenção.
`descricao`	Não	Descrição curta do sistema. Aparece no cabeçalho dos arquivos gerados.
`padroes`	Não	Caminho para o arquivo de Padrões de Engenharia. Padrão: `padroes.spell`.

agendamedica.spell

Projeto {
  nome: AgendaMedica
  versao: 1.0
  descricao: Sistema de agendamento de consultas médicas
  padroes: padroes.spell
}

Bloco singleton O bloco Projeto pode aparecer apenas uma vez em todo o projeto. Se declarado em mais de um arquivo, o compilador emite ❌ ERRO: bloco Projeto é singleton e interrompe a compilação.

Seu primeiro bloco Dados

O bloco Dados contém as tabelas do seu sistema. Cada tabela é declarada com a keyword table seguida do nome da entidade:

modulo-usuarios.spell

Dados {
  table Usuario {
    nome: texto(100), obrigatorio
    email: texto(200), unico, obrigatorio
    senha_hash: texto(200), obrigatorio, privado
    ativo: booleano, padrao: sim
    criado_em: data-hora, obrigatorio
  }
}

Cada campo tem um tipo e, opcionalmente, modificadores separados por vírgula. O tipo define a estrutura; os modificadores definem as restrições e comportamentos.

Tipos de campo básicos

Os tipos disponíveis para campos de tabela são:

Tipo	Descrição	Exemplo
`inteiro`	Número inteiro	`idade: inteiro`
`decimal`	Número com decimais	`preco: decimal`
`texto(N)`	String com tamanho máximo N	`nome: texto(100)`
`booleano`	Verdadeiro ou falso	`ativo: booleano`
`data`	Data sem hora	`nascimento: data`
`data-hora`	Data com hora	`criado_em: data-hora`
`arquivo`	Referência a arquivo/blob	`foto: arquivo`
`json`	Objeto JSON sem esquema fixo	`configuracoes: json`

Ausência é silêncio — o compilador infere

Um princípio fundamental do SPELL: blocos ausentes não geram erros. Eles são silêncio — o arquiteto não tinha nada a declarar naquele momento.

Quando a spec está incompleta, a IA infere defaults razoáveis e lista o que inferiu antes de gerar qualquer código. Isso permite começar com o mínimo e ir detalhando conforme o projeto evolui. Você pode escrever:

Dados {
  table Produto {
    // Recomendar estrutura completa à IA
    estrutura: recomendar
  }
}

E a IA vai propor campos razoáveis para um produto antes de implementar. Isso é delegação intencional — o arquiteto sabe que existe uma entidade Produto, mas delega a estrutura detalhada à IA.

Comentários e notas do arquiteto

O SPELL tem dois tipos de comentário com comportamentos diferentes:

Dados {
  // Este comentário é ignorado pelo compilador
  /// Esta nota do arquiteto vai para o markdown gerado
  /// como contexto adicional para a IA — equivale a um prompt complementar

  table Pedido {
    status: texto(20), obrigatorio
    /// Os status válidos são: rascunho, pendente, aprovado, cancelado
    valor_total: decimal, obrigatorio
  }
}

Use // para comentários de rascunho que não devem influenciar a IA. Use /// para informações de contexto que a IA precisa saber para implementar corretamente.