Separando padrões do domínio

As duas seções da linguagem

O SPELL divide o espaço de especificação em duas seções com responsabilidades distintas:

Padrões de Engenharia — padroes.spell

Os Padrões de Engenharia contêm as definições técnicas do projeto: linguagem, framework, banco de dados, convenções de código, arquitetura, qualidade. São preenchidos pelo arquiteto técnico ou engenheiro na inception do projeto e raramente precisam ser alterados depois.

Tecnologia {
  Backend {
    linguagem: C# 12 / .NET 8
    framework: ASP.NET Core
    tipo: web
    banco-principal: PostgreSQL
    banco-secundario: Redis
    orm: Entity Framework Core
    hospedagem: Railway
    agente: claude-code
  }
  Frontend {
    framework: React
    design-system: shadcn/ui + Tailwind
  }
  Autenticacao {
    metodo: JWT HS256
  }
}

Arquitetura {
  padrao: Clean Architecture
  organizacao-de-pastas: por feature
  tratamento-de-erros: exceções tipadas + middleware global
}

ConvencoesD {
  idioma-de-tabelas: inglês
  capitalizacao-de-tabelas: snake_case
  chave-primaria: id UUID
  soft-delete: sim, via deleted_at
}

ConvencoesC {
  idioma-do-codigo: inglês
  classes: PascalCase
  metodos: PascalCase
}

Domínio do Sistema — módulos de domínio

O Domínio do Sistema contém os módulos de negócio: dados, regras, endpoints, telas. É o espaço do arquiteto de negócio — ele não precisa conhecer o conteúdo do padroes.spell para trabalhar nos módulos.

Dados {
  table Consulta {
    medico_id: inteiro, obrigatorio -> Medico.id
    paciente_id: inteiro, obrigatorio -> Paciente.id
    data_hora: data-hora, obrigatorio
    status: texto(20), obrigatorio, padrao: agendada
    observacoes: texto(500), opcional
  }
}

Regras {
  rule HorarioDisponivel {
    contexto: Agendamento de consulta
    condicao: Médico já tem consulta confirmada no mesmo horário
    acao: Recusar o agendamento com mensagem de horário indisponível
  }
}

Endpoints {
  endpoint AgendarConsulta {
    rota: POST /consultas
    autenticacao: obrigatoria
    regras: HorarioDisponivel
    Entrada {
      medico_id: inteiro, obrigatorio
      data_hora: data-hora, obrigatorio
    }
    Respostas {
      201: Consulta agendada
      400: Horário indisponível
    }
  }
}

Regra de separação enforçada pelo compilador

O compilador não permite que blocos de Padrões de Engenharia apareçam em arquivos que não sejam o padroes.spell. Se você colocar um bloco Tecnologia ou ConvencoesD num módulo de negócio, o compilador emite ❌ ERRO e interrompe a compilação:

// modulo-usuarios.spell — ERRADO ❌
Tecnologia {
  // Bloco de Padrões de Engenharia fora do arquivo de padrões — vai gerar erro
  Backend {
    linguagem: Go
  }
}

O erro emitido é: ❌ ERRO: bloco 'Tecnologia' é de Padrões de Engenharia e só pode ser declarado em padroes.spell

Por que a separação existe

A motivação é organizacional, não técnica. Em projetos reais, quem preenche os Padrões de Engenharia (o arquiteto técnico) e quem preenche o Domínio do Sistema (o arquiteto de negócio) frequentemente são pessoas diferentes.

O arquiteto de negócio que está descrevendo o módulo de consultas médicas não precisa saber se o projeto usa PostgreSQL ou MySQL, Clean Architecture ou MVC, inglês ou português nas tabelas. Isso é decisão do time técnico, declarada uma vez no padroes.spell e aplicada automaticamente em toda a compilação.

Manter a separação garante que:

• Os módulos de negócio fiquem focados no domínio, sem ruído técnico
• Mudanças de padrão (ex: migrar o ORM) afetam apenas o padroes.spell
• O arquiteto de negócio pode trabalhar nos módulos sem conhecer decisões técnicas
• Padrões corporativos podem ser compartilhados entre projetos via caminho relativo