Viniciustda/OiTenta / .agents/skills/backend-prisma-sync-module
backend-prisma-sync-module
UnverifiedSincronizar um módulo de domínio com o Prisma do backend. Usar quando o pedido envolver analisar entidades em `modules/<modulo>/src`, criar ou atualizar `apps/backend/prisma/models/<modulo>.model.prisma`, gerar migration incremental nomeada por módulo, aplicar a migration e manter o schema Prisma alinhado com as entidades que herdam de `Entity`.
Backend Sync Module Prisma
Objetivo
Sincronizar exclusivamente a estrutura de persistência Prisma de um módulo do monorepo com base nas entidades declaradas em modules/<modulo>.
Esta skill recebe um módulo, analisa classes que herdam de Entity<TState>, gera ou atualiza o arquivo Prisma correspondente em apps/backend/prisma/models/<modulo>.model.prisma, cria uma migration incremental com o nome do módulo, executa a migration e mantém o banco alinhado com o estado atual do módulo.
Esta skill só deve seguir com a execução quando o módulo alvo estiver explicitamente informado pelo usuário ou pelo contexto imediato da tarefa.
Não criar DTOs, adapters Prisma, repositories, seeds, controllers nem casos de uso, exceto se o pedido explicitar isso fora desta skill. As instruções da skill devem permanecer em português do Brasil. Os arquivos e códigos gerados devem seguir a língua, convenções e estilo já adotados no projeto.
Quando usar
- Quando o pedido for sincronizar entidades de um módulo com o Prisma.
- Quando houver criação ou alteração de entidades em
modules/<modulo>e isso precisar virar schema e migration. - Quando for necessário revisar se o schema Prisma de um módulo ficou desatualizado em relação ao domínio.
- Quando for preciso criar migrations incrementais focadas em um único módulo.
Escopo de leitura
- Ler o módulo informado em
modules/<modulo>. - Procurar entidades em arquivos
**/*.entity.ts. - Priorizar classes
class Xxx extends Entity<...>. - Ler o
Stateassociado a cada entidade para descobrir os campos persistidos pelo domínio. - Considerar os campos herdados de
EntityStateempackages/shared/src/model/entity.ts:id?: stringcreatedAt?: DateupdatedAt?: DatedeletedAt?: Date | null
Trava obrigatória
- Antes de qualquer leitura, edição de schema ou execução de migration, verificar se existe um módulo alvo claramente informado.
- São entradas válidas:
- nome do módulo, como
auth - path do módulo dentro de
modules/ - contexto inequívoco que aponte para um único módulo já citado na tarefa atual
- nome do módulo, como
- Se o módulo não tiver sido informado de forma clara, interromper a execução imediatamente.
- Nessa situação, a skill deve pedir ao usuário que informe qual módulo deseja sincronizar no Prisma do backend.
- Sem essa informação, não deve inferir módulo, não deve editar arquivos e não deve rodar comandos Prisma.
Workflow
- Resolver o módulo alvo.
- Verificar primeiro se o módulo foi informado de forma explícita ou inequívoca.
- Se o módulo não tiver sido informado, parar imediatamente e solicitar ao usuário o nome do módulo que deseja sincronizar.
- Aceitar nome do módulo, path dentro de
modules/ou contexto equivalente. - Normalizar para o nome real da pasta e para o nome do arquivo Prisma
<modulo>.model.prisma.
- Mapear o domínio persistível.
- Ler todas as entidades do módulo.
- Listar os campos declarados no
Statede cada entidade. - Incluir também os campos herdados de
EntityState. - Identificar relações apenas quando elas estiverem claras no código do módulo.
- Atualizar o schema Prisma do módulo.
- Criar ou editar somente
apps/backend/prisma/models/<modulo>.model.prisma. - Manter um model Prisma por entidade de domínio persistível.
- Preservar a organização modular do Prisma: cada módulo fica no próprio arquivo.
- Manter o nome do model Prisma coerente com a entidade de domínio, mas mapear a tabela física do banco para
snake_case, em letras minúsculas e preferencialmente no plural. - Sempre que necessário, usar
@@map("<nome_da_tabela>")para garantir esse padrão no banco. Exemplo: entidadeUser-> modelUsercom@@map("users"). - Remover
apps/backend/prisma/models/bootstrap.model.prismaquando o primeiro modelo real do domínio entrar no projeto e ele deixar de ser necessário.
- Criar ou editar somente
- Gerar migration incremental.
- Se for a primeira sincronização do módulo, usar migration com nome igual ao módulo em kebab-case.
- Se o módulo já existir no Prisma e houver diferenças, criar nova migration com
<modulo>-<sufixo-curto>. - O sufixo deve descrever a alteração de forma curta e objetiva, por exemplo:
auth-add-user-table,auth-add-user-deleted-at,transactions-rename-status.
- Aplicar e validar.
- Garantir que o banco esteja disponível antes da migration.
- Rodar
npm --workspace apps/backend run prisma:migrate:dev -- --name <migration-name>. - Rodar
npm --workspace apps/backend run prisma:generate. - Revisar o SQL gerado quando houver risco de alteração destrutiva.
- Reportar o resultado.
- Informar entidades analisadas, arquivo Prisma alterado, nome da migration criada e qualquer suposição feita.
- Se não houver diferença entre módulo e schema, dizer explicitamente que o módulo já estava sincronizado.
Regras de mapeamento
- Assumir que cada entidade persistível precisa refletir os campos do
State. - Sempre considerar os campos base herdados de
EntityState. - Para nomes de tabelas no banco, adotar como padrão
snake_case, em letras minúsculas e preferencialmente no plural. - Quando o nome da entidade/model estiver em singular ou em PascalCase, preservar o nome idiomático do model Prisma e mapear a tabela com
@@map. Exemplos:User->@@map("users")UserProfile->@@map("user_profiles")
- Mapear tipos primitivos de forma conservadora:
string->Stringboolean->BooleanDate->DateTimenumber-> escolherInt,BigIntouDecimalapenas quando o contexto deixar isso claro
- Em caso de ambiguidade de tipo numérico, cardinalidade, nulabilidade, enum ou relação, explicitar a dúvida antes de consolidar um schema destrutivo.
- Usar
@mape@@mapapenas quando houver necessidade real de compatibilidade com naming existente ou com banco já criado. - Evitar inferir estruturas que não aparecem no módulo. Se a relação não estiver clara no domínio, não inventar.
Guardrails
- Não prosseguir sem módulo alvo explicitamente informado.
- Não alterar outros módulos Prisma sem necessidade direta do schema global.
- Não mexer em seeds nem adapters de persistência como parte do fluxo padrão desta skill.
- Não sobrescrever migrations antigas.
- Ao detectar rename de campo, remoção de coluna, troca de tipo ou mudança de nulabilidade, tratar como alteração de risco e revisar com cuidado o SQL gerado.
- Se o módulo não tiver nenhuma entidade que herda de
Entity, informar que não há base suficiente para sincronização automática.
Comandos base
- Subir o banco, quando necessário:
npm --workspace apps/backend run db:start
- Gerar/aplicar migration do módulo:
npm --workspace apps/backend run prisma:migrate:dev -- --name <migration-name>
- Atualizar o client Prisma:
npm --workspace apps/backend run prisma:generate
Referencias
- Consultar
references/module-prisma-sync.mdpara checklist operacional e armadilhas comuns.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |