{
  "id": "claude-code-rules-for-prisma-projects",
  "type": "rules",
  "category": "rules",
  "locale": "zh",
  "url": "/zh/rules/claude-code-rules-for-prisma-projects",
  "title": "Prisma 项目的 Claude Code 规则",
  "description": "适用于 Prisma ORM 项目的 Claude Code 规则，涵盖迁移安全性、查询模式、关联加载以及防止智能体破坏模式。",
  "tools": [
    "Claude Code",
    "Cursor",
    "Codex"
  ],
  "stack": [
    "Next.js",
    "PostgreSQL",
    "TypeScript"
  ],
  "tags": [
    "agents-md",
    "postgres",
    "typescript",
    "conventions",
    "security"
  ],
  "difficulty": null,
  "updated": "2026-06-08",
  "markdown": "将此文件作为 `CLAUDE.md` 添加到你的仓库根目录。Claude Code 会自动读取 `CLAUDE.md`（以及 `AGENTS.md`），并将其作为项目级别指令应用于每个会话。\n\n## Claude Code 规则文件\n\n```txt title=\"Claude Code Rules\"\n# Prisma Project Rules\n\n## Schema rules — highest risk area\n- NEVER edit `prisma/schema.prisma` without explicitly confirming the change with the\n  developer first. Schema changes generate migrations that alter production data.\n- When asked to add a field, propose the schema diff and the migration name, then\n  STOP and wait for approval before running `prisma migrate dev`.\n- New required fields MUST have a `@default(...)` value or be added as optional\n  (`String?`). Adding a required field without a default breaks `migrate deploy` on\n  a non-empty database.\n- Do NOT add `@@map` or `@map` attributes to rename existing tables or columns without\n  explicitly discussing the migration strategy — renames require data migration steps.\n- Use `@db.Text` for long strings, `@db.VarChar(n)` for bounded strings. Never use\n  bare `String` for fields that will store user-generated content longer than 255 chars.\n\n## Migration rules\n- Run `prisma migrate dev --name <descriptive-name>` to generate migrations locally.\n  Never hand-edit files in `prisma/migrations/` — they are append-only.\n- In CI/CD, run `prisma migrate deploy` (not `migrate dev`). Never run `migrate dev`\n  against a production database.\n- After adding or changing models, always regenerate the client: `prisma generate`.\n  Never commit code that imports from `@prisma/client` without a matching `generate` run.\n\n## Query patterns\n- Import the Prisma client from `src/lib/prisma.ts` (the singleton). Never instantiate\n  `new PrismaClient()` in application code — this leaks connections in serverless.\n- Use `select` or `include` explicitly on every query. Never rely on Prisma's default\n  select-all behaviour — it causes over-fetching and leaks sensitive fields.\n- Paginate all list queries with `take` and `skip` (or cursor-based pagination with\n  `cursor` + `take`). Never run a `findMany` without a limit on a user-facing endpoint.\n- Wrap multi-step mutations in `prisma.$transaction([...])` or the interactive\n  transaction callback. Never perform two sequential writes that must be atomic outside\n  a transaction.\n- Use `prisma.$queryRaw` and `Prisma.sql` template tag for raw SQL only. Never\n  concatenate user input into a raw query string — this is a SQL injection vector.\n\n## Relation loading\n- Prefer `include` over N+1 patterns. If a resolver loads a relation in a loop,\n  refactor to a single query with `include` or use a DataLoader.\n- Do not `include` deeply nested relations more than 2 levels deep in a single query.\n  Flatten with multiple targeted queries and join in application code if needed.\n\n## Type safety\n- All repository functions must return typed Prisma result types or mapped domain types.\n  Never return `any` or plain `object` from a database function.\n- Use `Prisma.validator()` to define reusable select/include shapes that keep return\n  types precise.\n\n## Definition of done\n- `prisma validate` passes.\n- `tsc --noEmit` passes.\n- No `new PrismaClient()` outside `src/lib/prisma.ts`.\n- No `findMany` calls without `take`.\n- Migration files are committed alongside schema changes.\n```\n\n## 为什么需要这些规则\n\n- **未经确认不得编辑模式** 是不可商量的。Prisma 迁移在生产环境中不可逆——在没有数据迁移计划的情况下删除列或重命名表会导致数据丢失。那些“乐于助人”的智能体一旦接触模式就会愉快地运行 `migrate dev`。\n- **单例客户端导入** 防止了最常见的无服务器陷阱之一：连接池耗尽。在 Next.js 无服务器函数中，除非使用单例模式，否则每次模块求值都会创建一个新的 `PrismaClient` 实例（以及新的连接池）。那些从 Prisma 文档复制示例的智能体通常会跳过这一点。\n\n## 适用场景\n\n- 使用 Prisma 与 PostgreSQL 的 Next.js 或 Node.js 应用，且模式成熟、迁移安全性至关重要。\n\n## 不适用场景\n\n- 尚无数据的全新项目，你希望智能体能自由迭代模式——在此阶段放宽迁移审批要求。"
}