Bloco Regras

Por que regras são insubstituíveis

Regras de negócio são o ativo mais crítico de qualquer sistema — e o mais difícil de recuperar quando perdido. Ao contrário da estrutura de dados, que a IA pode inferir com razoável acerto ("uma tabela de usuários provavelmente tem email e senha"), as regras de negócio são específicas do seu domínio e não podem ser inventadas.

A IA não inventa regras não declaradas. Se a sua especificação não diz que um médico não pode ter duas consultas no mesmo horário, a IA vai implementar o agendamento sem essa validação. O sistema vai para produção com um bug que não é um bug técnico — é uma ausência de especificação.

O bloco Regras é a forma de tornar explícito o que seria implícito. Cada regra declarada é uma garantia de que o comportamento esperado vai estar no sistema.

Sintaxe básica

Cada regra é declarada com a keyword rule seguida do nome em PascalCase:

Regras {
  rule HorarioDisponivel {
    contexto: Agendamento de consulta médica
    condicao: Médico já tem consulta confirmada no mesmo horário
    acao: Recusar o agendamento com mensagem "Horário indisponível"
    motivo: Política da clínica para evitar conflitos de agenda
  }
}

Campos de uma regra

Campo	Obrigatório	Descrição
`contexto`	Recomendado	Em que situação esta regra se aplica
`condicao`	Recomendado	Quando a regra deve ser acionada
`acao`	Recomendado	O que acontece quando a condição é verdadeira
`excecao`	Não	Casos em que a regra não se aplica
`motivo`	Não	Justificativa de negócio para a regra existir
`tipo`	Não	Classificação semântica da regra (ver abaixo)

Campo tipo — classificação semântica

O campo tipo classifica a natureza da regra. Isso ajuda a IA a decidir onde e como implementar a verificação:

Tipo	Significado	Exemplo típico
`validacao`	Verifica dados antes de persistir	Formato de e-mail, senha forte
`autorizacao`	Verifica se o usuário pode executar a ação	Apenas admin pode excluir usuários
`rate-limit`	Limita frequência de ações	Máximo 3 tentativas de login por minuto
`negocio`	Regra do domínio de negócio	Médico não pode ter dois horários simultâneos
`auditoria`	Gera registro de auditoria da ação	Toda exclusão deve ser registrada com usuário e hora

Regra com tipo declarado

rule LimiteCadastro {
  tipo: rate-limit
  contexto: Cadastro de usuário
  condicao: IP realizou mais de 3 cadastros na última hora
  acao: Recusar com HTTP 429 — "Muitas tentativas. Aguarde."
}

Múltiplas ações com instruções livres

Quando uma regra precisa de mais de uma ação, ou quando o comportamento é complexo demais para caber num campo único, use instruções livres com hífen (-):

rule ContaBloqueadaAposErros {
  tipo: autorizacao
  contexto: Tentativa de login
  condicao: 5 falhas de senha nos últimos 10 minutos
  - Bloquear a conta por 30 minutos
  - Enviar e-mail de alerta de segurança ao usuário
  - Registrar evento de segurança no log de auditoria
  excecao: Contas de admin têm limite de 10 falhas antes do bloqueio
  /// O tempo de bloqueio pode ser configurado via variável de ambiente — não hardcodar 30 minutos
}

Referenciando regras em endpoints

O campo regras dentro de um endpoint vincula as regras que devem ser verificadas naquela operação. A IA sabe que precisa aplicar as validações antes de processar a requisição:

Regras {
  rule SenhaForte {
    tipo: validacao
    contexto: Cadastro de usuário
    condicao: Senha informada tem menos de 8 caracteres
    acao: Recusar o cadastro com mensagem de requisito mínimo
  }

  rule EmailUnico {
    tipo: validacao
    contexto: Cadastro de usuário
    condicao: Email já cadastrado no sistema
    acao: Recusar com mensagem genérica — não revelar que o email existe
    /// Não dizer "email já cadastrado" — evitar enumeração de usuários
  }
}

Endpoints {
  endpoint CadastrarUsuario {
    rota: POST /usuarios
    autenticacao: nao-requerida
    regras: SenhaForte, EmailUnico
    // ...
  }
}

Notas de contexto nas regras

As notas do arquiteto (///) são especialmente valiosas dentro de regras, pois adicionam contexto de negócio que não cabe nos campos estruturados:

Regras {
  /// O sistema opera em mercado regulado (setor financeiro).
  /// Qualquer dado pessoal deve seguir LGPD conforme declarado em Seguranca { }.

  rule AcessoDadosPessoais {
    tipo: autorizacao
    contexto: Consulta de dados pessoais de clientes
    condicao: Usuário não tem perfil de compliance ou admin
    acao: Retornar dados mascarados (CPF com dígitos centrais ocultos)
    /// Mascaramento deve ser consistente em toda a aplicação — não apenas na tela
  }
}