Convenções

ConvencoesD — banco de dados

O bloco ConvencoesD (Convenções de Dados) define as regras de nomenclatura e comportamento para o banco de dados. É um bloco de Padrões de Engenharia (padroes.spell):

ConvencoesD {
  idioma-de-tabelas: inglês
  capitalizacao-de-tabelas: snake_case
  tabelas: plural
  chave-primaria: id UUID
  campos-de-auditoria: created_at, updated_at, created_by
  soft-delete: sim, via deleted_at
  soft-delete-filtro-global: sim
  /// Filtro global de soft delete via HasQueryFilter no DbContext (EF Core)
}

Campo	Descrição	Exemplos de valor
`idioma-de-tabelas`	Idioma usado nos nomes de tabelas e colunas	`português`, `inglês`
`capitalizacao-de-tabelas`	Convenção de capitalização	`snake_case`, `PascalCase`, `camelCase`
`tabelas`	Singular ou plural no nome da tabela	`singular`, `plural`
`chave-primaria`	Tipo e convenção da chave primária	`id UUID`, `id inteiro auto-incremento`
`campos-de-auditoria`	Campos de auditoria automáticos em toda tabela	`created_at, updated_at`
`soft-delete`	Estratégia de soft delete	`sim, via deleted_at`, `nao`
`soft-delete-filtro-global`	ORM aplica filtro automaticamente em todas as queries	`sim`, `nao`

ConvencoesC — código

O bloco ConvencoesC define as convenções de escrita do código. A IA usa essas definições para nomear classes, métodos, variáveis e outros elementos:

ConvencoesC {
  idioma-do-codigo: inglês
  classes: PascalCase
  metodos: PascalCase
  variaveis: camelCase
  constantes: UPPER_SNAKE_CASE
  interfaces: prefixo I — IRepository, IService
  sufixo-service: Service — UserService, OrderService
  sufixo-repository: Repository — UserRepository
}

Bloco API

O bloco API define os padrões da interface HTTP do sistema:

API {
  estilo: REST
  urls: kebab-case, plural — /api/v1/pedidos-ativos
  versionamento: prefixo de URL — /api/v1/
  envelope: sim — {data: ..., meta: ...}
  paginacao: skip/take
  datas: ISO 8601 UTC
  cors: meusite.com.br, app.meusite.com.br
}

Interface e Qualidade

Os blocos Interface e Qualidade definem padrões de UI e testes respectivamente:

Interface {
  design-system: shadcn/ui
  tema: escuro por padrão, com toggle
  formularios: validação inline com mensagens amigáveis
  feedback: toast para ações de sucesso e erro
  - Todas as ações destrutivas pedem confirmação
  - Loading states em todos os botões de ação
}

Qualidade {
  tipos-de-teste: unitário, integração, e2e
  cobertura-minima: 80% nas regras de negócio
  nomenclatura-de-testes: Dado_Quando_Entao
  - Testes de integração usam banco em memória
  - E2E rodando em pipeline de CI/CD
}

Bloco Engenharia e Configuracoes

O bloco Engenharia define práticas de desenvolvimento e o sub-bloco Configuracoes declara as variáveis de ambiente esperadas:

Engenharia {
  branching: trunk-based — branch por feature, merge via PR
  commits: conventional commits — feat, fix, chore, docs
  documentacao: README atualizado a cada feature, Swagger gerado automaticamente

  Configuracoes {
    DATABASE_URL: segredo
    JWT_SECRET: segredo
    AWS_ACCESS_KEY_ID: segredo
    AWS_SECRET_ACCESS_KEY: segredo
    STRIPE_SECRET_KEY: segredo
    CORS_ORIGINS: https://meusite.com.br
    NODE_ENV: production
  }
}

Campos com valor segredo são marcados no output gerado com uma coluna "Segredo: sim" — a IA sabe que não deve incluir esses valores em código ou logs. O output gerado é uma tabela Chave | Valor | Segredo.