CodeVetter · Repo Unpack · Contributor handoff
prisma/prisma
Agents should treat this as a layered contract compiler plus a runtime, not as a Next.js app. Start from Agents.md, the architecture overview, and architecture.config.json. Use pnpm on Node 24, rebuild before typecheck, and do not bypass lint:deps. Tests are written first and run with Vitest; name the Contract type at every JSON boundary; never use any, zod, or a bare cast. Skills and rules have one canonical directory each. The traps that waste a session are stale dist types, plane violations, fixture drift, warn-only marker checks, and editing a gitignored symlink tree.
- New packages must be registered in architecture.config.json with plane-specific globs, broad to specific, including a migration glob for src/core/migrations/** even if the directory is empty. pnpm lint:deps fails the PR if a migration file imports a runtime package.
- Every workspace package, including examples and the private root, carries the same version. docs/oss/versioning.md says internal packages are not published, extension authors must pin framework internals to an exact minor, and RC releases may break. Do not bump a single package.json by hand; pnpm bump-version is the maintainer path.
- Files to read before editing a query path: packages/3-extensions/postgres/src/runtime/postgres.ts, packages/2-sql/4-lanes/sql-builder/src/runtime/sql.ts, and packages/2-sql/5-runtime/src/sql-runtime.ts. Before editing emit or migrations: packages/1-framework/3-tooling/cli/src/control-api/operations/contract-emit.ts, emitter/src/emit.ts, and db-update.ts. Subsystem index pages live under docs/architecture docs/subsystems/.
- Known traps: verifyMarker logs and continues; loadContractFromTs allows relative imports; the CLI bin here is not the published prisma host; integration tests do not run in merge_group during the launch window; PGlite-heavy suites need the CI worker cap or they drop Postgres sockets; typecheck against a dirty dist lies.
- Do not start a dev server or a migration against a caller-supplied production URL from this repo without an explicit ask. docker-compose.yaml is a disposable local Postgres on 5433. db update can destroy data once consent or --confirm is provided. Telemetry posts to a production Compute URL unless disabled.