Bloco Tecnologia

Visão geral

O bloco Tecnologia é um bloco de Padrões de Engenharia — pertence exclusivamente a arquivos declarados como [Padrões de Engenharia] (convencionalmente padroes.spell). Ele declara o stack tecnológico do projeto: linguagem, framework, banco de dados, hospedagem e provedores de serviços externos. A IA usa essas informações para escolher as bibliotecas, padrões de código e configurações corretas.

padroes.spell — Tecnologia completo

Tecnologia {
  Backend {
    linguagem: C# 12 / .NET 8
    framework: ASP.NET Core
    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
  }
  Comunicacao {
    email: Amazon SES
    sms: Twilio
    push: Firebase FCM
  }
  Integracao {
    storage: Amazon S3
    pagamento: Stripe
    mapas: Google Maps
  }
  Bibliotecas {
    pdf: QuestPDF
    planilha: EPPlus
    imagem: ImageSharp
  }
}

Sub-bloco Backend

Declara a tecnologia do servidor. Campos comuns:

Campo	Descrição
`tipo`	Obrigatório. Tipo da aplicação — `web`, `cli`, `desktop`, `biblioteca`
`linguagem`	Linguagem de programação e versão
`framework`	Framework web principal
`banco-principal`	Banco de dados primário
`banco-secundario`	Banco de dados secundário (cache, etc.)
`orm`	ORM ou biblioteca de acesso a dados
`hospedagem`	Plataforma de hospedagem/deploy
`agente`	Agente de IA que vai implementar (define o arquivo de saída)

Campo tipo — obrigatório

O campo tipo é obrigatório em todo bloco Backend { }. Remove a premissa implícita de que todo projeto SPELL é uma aplicação web com API REST. Omitir tipo gera ❌ ERRO no compilador.

Valor	Tipo de aplicação	Blocos habilitados	Blocos desabilitados
`web`	Aplicação web com API REST	`Endpoints`, `Telas`, `Seguranca`	—
`cli`	Executável de linha de comando	`Comandos`, `Dados`, `Regras`	`Endpoints`, `Telas`
`desktop`	Aplicação desktop nativa ou Electron	`Dados`, `Regras`	`Endpoints`
`biblioteca`	Biblioteca ou SDK sem interface própria	`Dados`, `Regras`	`Endpoints`, `Telas`

Para projetos cli, o bloco Endpoints { } é substituído pelo bloco Comandos { }. O auditor emite ⚠️ AVISO se Endpoints { } ou Telas { } forem declarados num projeto cli:

Tecnologia {
  Backend {
    tipo: cli
    linguagem: Go
    agente: claude-code
  }
}

Bloco Comandos — projetos CLI

Para projetos com tipo: cli, o bloco Comandos { } substitui Endpoints { }. Cada sub-bloco command descreve um comando do executável com seus argumentos, flags e contrato de saída.

Comandos {
  command compile {
    uso: spellcomp compile [arquivo]
    descricao: Compila o projeto e gera arquivos para o agente

    Args {
      arquivo: texto, opcional
      - Se omitido, descobre o arquivo-índice pela convenção de nome da pasta
    }

    Flags {
      --output: pasta de saída para os arquivos gerados
      --readable: gera output legível por humanos (padrão: compacto)
    }

    Saida {
      sucesso: lista de arquivos gerados com tamanho em bytes
      erro: mensagem com símbolo ❌ e número da linha do problema
    }

    - Roda auditoria completa antes de gerar qualquer arquivo
    - Aborta com código de saída 1 se houver ❌ ERRO
  }
}

Campos de command:

Campo / Sub-bloco	Descrição
`uso`	String de uso do comando — ex: `mycli build [arquivo]`
`descricao`	Descrição curta do que o comando faz
`Args { }`	Argumentos posicionais com tipo e modificadores
`Flags { }`	Flags nomeadas: `--nome: descrição`
`Saida { }`	Contrato de saída: campos `sucesso` e `erro`

O auditor emite ⚠️ AVISO para comandos sem Saida { } declarado.

Múltiplos Backend e Frontend nomeados

Projetos com mais de uma unidade deployável podem declarar múltiplos Backend e Frontend com nomes distintos. O nome após a keyword é livre:

Tecnologia {
  Backend Api {
    tipo: web
    linguagem: C# / .NET 10
    framework: ASP.NET Core 10
    banco-principal: PostgreSQL
    agente: claude-code
  }
  Backend Worker {
    tipo: web
    linguagem: C# / .NET 10
    framework: Generic Host
    /// Worker processa mensagens da fila SQS — deploy separado da API
  }
  Frontend App {
    framework: React
    design-system: shadcn/ui
  }
  Frontend Admin {
    framework: React
    design-system: Ant Design
  }
}

O campo agente é lido do primeiro Backend que o declarar. Para projetos com unidade única, a sintaxe sem nome (Backend { }) continua válida.

Sub-bloco Autenticacao

Declara o método de autenticação e, opcionalmente, os claims do token:

Autenticacao {
  metodo: JWT HS256
  Claims {
    id: inteiro
    apelido: texto
    perfil: texto
    ip: texto
    /// ip validado a cada requisição — mudança de IP invalida a sessão
  }
}

Sub-bloco Comunicacao (depreciado)

⚠️ Depreciado. Use o bloco nomeado Integracao Nome { } no nível raiz do arquivo de Padrões de Engenharia. O compilador emite aviso ao encontrar Comunicacao { }.

// ❌ Depreciado — emite ⚠️ AVISO
Comunicacao {
  email: Amazon SES
}

// ✅ Use no lugar:
Integracao SES {
  tipo:     email
  provedor: Amazon SES
  sdk:      AWSSDK.SimpleEmail
}

Sub-bloco Integracao (depreciado)

⚠️ Depreciado. Use o bloco nomeado Integracao Nome { } no nível raiz do arquivo de Padrões de Engenharia. O compilador emite aviso ao encontrar Integracao { } dentro de Tecnologia.

// ❌ Depreciado — emite ⚠️ AVISO
Integracao {
  pagamento: Stripe
}

// ✅ Use no lugar:
Integracao Stripe {
  tipo:     pagamento
  provedor: Stripe
  sdk:      Stripe.net
  Configuracoes {
    Stripe__SecretKey:     segredo
    Stripe__WebhookSecret: segredo
  }
}

Sub-bloco Bibliotecas

Declara bibliotecas específicas que o arquiteto quer prescrever para evitar que a IA escolha por conta própria. Qualquer chave é válida — o compilador passa os valores verbatim para o output:

Bibliotecas {
  qrcode: QRCoder
  pdf: QuestPDF
  planilha: EPPlus
  imagem: ImageSharp
  markdown: Markdig
}