Compilando o projeto

spellcomp compile .

O comando principal de compilação processa todos os arquivos .spell do projeto e gera os arquivos de instrução para o agente de IA:

spellcomp compile .

O ponto indica o diretório atual. O spellcomp descobre o arquivo-índice pela convenção de nome: ele procura um arquivo .spell com o mesmo nome do diretório. Por exemplo, dentro de um diretório chamado agendamedica/, o compilador encontra automaticamente agendamedica.spell.

Se você preferir um nome diferente para o arquivo-índice, passe-o explicitamente:

spellcomp compile meu-projeto.spell

Para compilar apenas um módulo específico:

spellcomp compile modulo-usuarios.spell

O que é gerado

A compilação produz um conjunto de arquivos .md consolidados por tipo de bloco. Para um projeto chamado agendamedica:

agendamedica/
├── CLAUDE.md                 ← entrada do agente (nome varia pelo campo agente)
├── LEIAME.txt                ← para o arquiteto humano
├── agendamedica-padroes.md   ← Padrões de Engenharia consolidados
├── agendamedica-dados.md     ← todos os Dados { } de todos os .spell
├── agendamedica-regras.md    ← todas as Regras { } de todos os .spell
├── agendamedica-endpoints.md ← todos os Endpoints { } de todos os .spell
├── agendamedica-telas.md     ← todas as Telas { } de todos os .spell
├── agendamedica-servicos.md  ← omitido se nenhum Servicos { } declarado
└── agendamedica-seguranca.md ← omitido se nenhum Seguranca { } declarado

O output é proporcional ao input: blocos ausentes não geram arquivos vazios. Se o projeto não tem nenhum bloco Servicos, o arquivo -servicos.md simplesmente não é criado.

Formato compacto vs readable

Por padrão, o spellcomp gera os arquivos no formato compacto — cerca de 40 a 63% menos tokens que o formato legível. Isso é importante quando o arquivo é passado como contexto para o agente: tokens economizados são custos reduzidos e janelas de contexto preservadas.

Para gerar no formato legível por humanos, use a flag --readable:

spellcomp compile . --readable

Use --readable para debug — quando você precisa inspecionar o output ou validar se a compilação está produzindo o resultado esperado. Em produção, o formato compacto é o recomendado.

Para especificar a pasta de saída:

spellcomp compile . --output dist/

spellcomp check — validar sem gerar

O comando check valida a spec sem gerar nenhum arquivo. Útil para integração em CI/CD — você pode verificar a integridade da spec antes de commitar:

spellcomp check .

O check também verifica a integridade dos arquivos .md já gerados: detecta se eles foram editados manualmente e emite ❌ ERRO.

Nota: o spellcomp compile também faz essa verificação automaticamente antes de gerar qualquer arquivo — não é preciso rodar check primeiro. Se algum .md foi editado diretamente, a compilação é abortada. Use --force para sobrescrever mesmo assim (as edições diretas serão perdidas).

O output usa os símbolos de diagnóstico do SPELL:

spellcomp info — mapa do projeto

O comando info exibe um mapa completo do projeto sem compilar nem validar:

spellcomp info

O output lista todas as fases, módulos, blocos declarados e status de compilação de cada arquivo. Útil para ter uma visão geral do projeto sem abrir cada arquivo individualmente.

O arquivo de entrada do agente

O arquivo gerado para o agente de IA varia de acordo com o campo agente no bloco Tecnologia:

O arquivo de entrada é sempre gerado em formato legível — independente da flag --readable — porque é o arquivo que o arquiteto humano também vai ler para entender o contrato de implementação.