# Regras do Claude Code para Projetos Prisma

> Regras do Claude Code para projetos com Prisma ORM, abordando segurança de migrações, padrões de consulta, carregamento de relações e prevenção de corrupção do schema por agentes.

**Type:** Rule  
**Tools:** Claude Code, Cursor, Codex  
**Stack:** Next.js, PostgreSQL, TypeScript  
**Updated:** 2026-06-08

---

Adicione isso como um arquivo `CLAUDE.md` na raiz do seu repositório. O Claude Code lê `CLAUDE.md` automaticamente (além de `AGENTS.md`) e o aplica como instruções de nível de projeto para cada sessão.

## Arquivo de Regras do Claude Code

```txt title="Claude Code Rules"
# Prisma Project Rules

## Schema rules — highest risk area
- NEVER edit `prisma/schema.prisma` without explicitly confirming the change with the
  developer first. Schema changes generate migrations that alter production data.
- When asked to add a field, propose the schema diff and the migration name, then
  STOP and wait for approval before running `prisma migrate dev`.
- New required fields MUST have a `@default(...)` value or be added as optional
  (`String?`). Adding a required field without a default breaks `migrate deploy` on
  a non-empty database.
- Do NOT add `@@map` or `@map` attributes to rename existing tables or columns without
  explicitly discussing the migration strategy — renames require data migration steps.
- Use `@db.Text` for long strings, `@db.VarChar(n)` for bounded strings. Never use
  bare `String` for fields that will store user-generated content longer than 255 chars.

## Migration rules
- Run `prisma migrate dev --name <descriptive-name>` to generate migrations locally.
  Never hand-edit files in `prisma/migrations/` — they are append-only.
- In CI/CD, run `prisma migrate deploy` (not `migrate dev`). Never run `migrate dev`
  against a production database.
- After adding or changing models, always regenerate the client: `prisma generate`.
  Never commit code that imports from `@prisma/client` without a matching `generate` run.

## Query patterns
- Import the Prisma client from `src/lib/prisma.ts` (the singleton). Never instantiate
  `new PrismaClient()` in application code — this leaks connections in serverless.
- Use `select` or `include` explicitly on every query. Never rely on Prisma's default
  select-all behaviour — it causes over-fetching and leaks sensitive fields.
- Paginate all list queries with `take` and `skip` (or cursor-based pagination with
  `cursor` + `take`). Never run a `findMany` without a limit on a user-facing endpoint.
- Wrap multi-step mutations in `prisma.$transaction([...])` or the interactive
  transaction callback. Never perform two sequential writes that must be atomic outside
  a transaction.
- Use `prisma.$queryRaw` and `Prisma.sql` template tag for raw SQL only. Never
  concatenate user input into a raw query string — this is a SQL injection vector.

## Relation loading
- Prefer `include` over N+1 patterns. If a resolver loads a relation in a loop,
  refactor to a single query with `include` or use a DataLoader.
- Do not `include` deeply nested relations more than 2 levels deep in a single query.
  Flatten with multiple targeted queries and join in application code if needed.

## Type safety
- All repository functions must return typed Prisma result types or mapped domain types.
  Never return `any` or plain `object` from a database function.
- Use `Prisma.validator()` to define reusable select/include shapes that keep return
  types precise.

## Definition of done
- `prisma validate` passes.
- `tsc --noEmit` passes.
- No `new PrismaClient()` outside `src/lib/prisma.ts`.
- No `findMany` calls without `take`.
- Migration files are committed alongside schema changes.
```

## Por que essas regras

- **Nunca editar o schema sem confirmação** é inegociável. As migrações do Prisma são irreversíveis em produção — uma coluna removida ou uma tabela renomeada sem um plano de migração de dados causa perda de dados. Agentes que são "prestativos" executarão alegremente `migrate dev` no momento em que tocarem no schema.
- **Importação singleton do cliente** evita um dos erros mais comuns em serverless: esgotamento do pool de conexões. Em funções serverless do Next.js, cada avaliação de módulo cria uma nova instância de `PrismaClient` (e um novo pool de conexões) a menos que o padrão singleton seja usado. Agentes que copiam exemplos da documentação do Prisma geralmente ignoram isso.

## Adequado para

- Aplicações Next.js ou Node.js que usam Prisma com PostgreSQL, onde o schema é maduro e a segurança de migrações é crítica.

## Não adequado para

- Projetos novos sem dados ainda, onde você deseja que o agente itere livremente no schema — afrouxe o requisito de aprovação de migração nessa fase.