Prisma Project

Scenario

You maintain a TypeScript API using Prisma as its database toolkit.

The repository contains:

• a Prisma schema;
• generated Prisma Client code;
• migrations;
• repository modules.

Coding agents need to understand that changing the database model is a workflow, not simply editing generated types.

Repository Structure

api/
├── prisma/
│   ├── schema.prisma
│   └── migrations/
├── src/
│   ├── db/
│   │   └── prisma.ts
│   ├── repositories/
│   └── services/
├── tests/
├── package.json
└── AGENTS.md

AGENTS.md

# Project Instructions

## Prisma

- Treat `prisma/schema.prisma` as the source of truth for Prisma models.
- Use the shared Prisma client from `src/db/prisma.ts`.
- Do not create new `PrismaClient` instances throughout application modules.
- Keep persistence logic in the existing repository/data-access layer.

## Generated Code

- Do not manually edit generated Prisma Client files.
- Regenerate the client using the repository's Prisma generation command when required.

## Schema Changes

- Update `prisma/schema.prisma` for intentional model changes.
- Create a new migration using the repository's established migration workflow.
- Review generated migration SQL before treating the migration as complete.
- Do not rewrite previously applied migrations to alter production schema history.

## Queries

- Select or include only the relations needed by the operation when practical.
- Follow existing transaction patterns for multi-step writes.
- Avoid introducing unbounded data loading where pagination or filtering is expected.

## Validation

For Prisma schema changes:

- validate the Prisma schema;
- generate the client;
- apply the migration in the development/test environment;
- run relevant database and application tests;
- run `pnpm typecheck`.

What This Does

This describes the relationship between:

schema.prisma
     ↓
migration
     ↓
database schema
     ↓
generated Prisma Client
     ↓
application repositories

An agent changing a field should understand that several artifacts may need to remain consistent.

For example, adding:

model User {
  id        String   @id
  email     String   @unique
  createdAt DateTime @default(now())
}

may require a migration and regenerated client before application code can use the model safely.

What This Does NOT Do

The instructions do not encourage editing generated Prisma Client code.

Generated output is derived from the schema and tooling.

A direct edit may disappear the next time generation runs.

The file also does not say that Prisma removes the need to think about SQL or database performance.

A query such as:

prisma.user.findMany({
  include: {
    orders: {
      include: {
        items: true,
      },
    },
  },
});

can still load much more data than required.

Abstractions do not remove database costs.

Why These Instructions Matter

A common mistake is to treat:

schema.prisma

as only a TypeScript-model definition.

It is connected to the actual database schema.

Changing:

email String

to something structurally different may require a safe database transition.

Likewise, automatically generated migration SQL should still be reviewed.

A generated migration may:

drop a column
recreate a table
remove data
change a constraint

depending on the schema change.

The fact that tooling generated it does not make the operation automatically safe.

Key Decisions

Use one shared client pattern

Creating Prisma clients throughout the application can lead to unnecessary connections and inconsistent lifecycle handling.

Generated files are outputs

Change their source, then regenerate.

Review migration SQL

ORM tooling makes schema changes convenient, but database effects still matter.

Query intentionally

Use select, include, filtering, and pagination according to actual data needs.

Keep persistence behind repository boundaries

Prisma is an implementation tool.

Business logic should not become unnecessarily coupled to database queries throughout the application.

When to Use This Pattern

Use this pattern when:

• Prisma manages database models;
• Prisma Client is generated from a schema;
• migrations are committed to the repository;
• repositories own persistence behavior;
• agents need guidance around schema and generation workflows.

The key lesson is that an ORM simplifies database work but does not remove database responsibility.