Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions .claude/skills/prisma-docs-voice/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
name: prisma-docs-voice
description: Use when the operator wants Prisma docs, educational content, tutorials, guides, FAQs, or support-style responses reviewed, edited, or rewritten for accuracy, clarity, usefulness, calm tone, and product correctness without hype. Also use when writing or reviewing Prisma Next docs, where it fact-checks against the Prisma Next repo and follows the Prisma Next user-docs spec.
---

# Prisma Docs Voice

Use this skill for docs and educational writing, plus support-style communication that should sound clear and calm rather than promotional.

## Usage guide

Use this skill for prompts like:

- `Does this docs page talk about Accelerate correctly?`
- `Rewrite this guide intro so it is clearer and less hyped.`
- `Check this quickstart for vague claims and missing caveats.`
- `Turn this product note into a helpful support-style response.`
- `Review this docs PR for accuracy, tone, and usefulness.`
- `Write the Prisma Next data-modeling page.`
- `Review this Prisma Next docs PR for accuracy against the repo.`

## Foundation first

- If `prisma-product-messaging` is available, consult it first.
- Use that skill for product naming, messaging hierarchy, and uncertainty handling.
- Then read `references/docs-guidance.md`.
- For Prisma Next work (writing or reviewing anything under `/docs/orm/next` or `/docs/next`, or any page describing Prisma Next behavior), read `references/prisma-next.md` before writing. It is the branch that governs source of truth, information architecture, fact-checking, and redirect tracking.

## Workflow

1. Identify whether the draft is docs, educational content, FAQ, support-style communication, or Prisma Next docs.
2. Confirm the product references are accurate and specific.
3. Cut hype, vague value claims, and dramatic language.
4. Rewrite for usefulness first.
5. Add step-by-step structure when the reader needs to do something.

## Large docs review

When reviewing a docs PR or doc set, prioritize:

1. Overview and intro paragraphs.
2. Quickstart steps and prerequisites.
3. Command descriptions and examples.
4. Limitation and troubleshooting sections.
5. Any sentence that implies guarantees, defaults, or unsupported behavior.

## Docs and support rules

- Accuracy beats cleverness.
- Clarity beats persuasion.
- State limitations honestly.
- Do not use em dashes.
- If the source material is uncertain or incomplete, say so plainly and recommend verification.
74 changes: 74 additions & 0 deletions .claude/skills/prisma-docs-voice/references/docs-guidance.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Docs guidance

Use this for docs, tutorials, educational content, and support-style replies.

## Docs voice

Docs should:

- Explain what the product or feature is.
- Tell the reader when to use it.
- Show the next action clearly.
- Break workflows into steps when useful.
- Use precise names and precise constraints.

Docs should not:

- Sound like launch copy.
- Hide important limitations.
- Replace instructions with slogans.
- Assume the reader knows Prisma product boundaries.

For overview pages and quickstarts:

- Put the real setup requirement near the start.
- Put important limitations where readers will actually see them.
- Avoid operational absolutes unless the source docs explicitly support them.

## Educational content

Educational content should:

- Teach through concrete examples.
- Explain why the workflow matters.
- Keep jargon under control.
- Stay grounded in real product behavior.

Educational content should not:

- Turn every paragraph into a pitch.
- Inflate routine functionality into a grand narrative.

## Support-style responses

Support-style replies should:

- Start by addressing the question directly.
- Acknowledge limitations or uncertainty clearly.
- Give the next action or decision point.
- Stay calm and specific.

Support-style replies should not:

- Sound defensive.
- Borrow website or launch language.
- Promise capabilities that are not confirmed.

## High-risk docs patterns

Flag these carefully:

- Claims that a workflow is automatic without showing the trigger or setup.
- Claims that there are no limits, no timeouts, or no cold starts without explicit documentation.
- Claims that a product works for any workload unless the docs clearly support that scope.
- Claims that remove all configuration steps when the actual workflow still needs setup.

## Example shift

Weak:

Prisma Postgres gives you a powerful database experience for modern apps.

Better:

Prisma Postgres is the managed PostgreSQL offering in the Prisma platform. Use the pooled connection string for application traffic and the direct connection string for migrations or Prisma Studio.
142 changes: 142 additions & 0 deletions .claude/skills/prisma-docs-voice/references/prisma-next.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
# Prisma Next docs

Read this before writing or reviewing any Prisma Next docs. It governs the
source of truth, the information architecture, the fact-check discipline, the
writing voice, and redirect tracking.

Prisma Next is the next major version of Prisma ORM, available in Early Access.
Docs live in the `prisma/web` repo under `apps/docs/content/docs/`. The Prisma
Next ORM docs are authored at `/docs/orm/next` and become `/docs/orm` when
Prisma Next goes generally available; today's Prisma 7 ORM docs at `/docs/orm`
are then pinned to `/docs/orm/v7`. The Prisma Next getting-started pages live
separately at `/docs/next`. Prisma 7 stays the generally available release.

## Ground truth: fact-check before you write

Prisma Next is still shaping up, so its behavior changes faster than memory or
training data can track. Never write a Prisma Next behavioral claim (a command,
flag, API method, config key, default, or output) from memory. Trace every
claim to **ground truth**: the Prisma Next repo.

Repo: https://github.com/prisma/prisma-next

Clone or fork it locally when you need to check behavior:

```bash
git clone https://github.com/prisma/prisma-next
```

Check claims against these, in rough order of authority:

- `packages/` — the actual implementation. The final word on how an API,
runtime, or CLI command behaves.
- `examples/` — runnable example apps (per database and framework: Postgres,
MongoDB, SQLite, Cloudflare Workers, React Router, Supabase, and more). Copy
real, working code shapes from here instead of inventing them.
- `docs/` — the internal reference set: `docs/reference/` (capabilities,
MongoDB idioms, CLI patterns, extension packs), `docs/commands/`,
`docs/glossary.md`, `docs/architecture docs/`, and the topic guides
(Testing, Serverless Deployment, Error Handling).
- `AGENTS.md`, `CLAUDE.md`, `ARCHITECTURE.md`, `ROADMAP.md` — orientation and
the phased plan from Early Access to GA.
- The installed agent skills. `npx prisma-next@latest init` (or
`npm create prisma@next`) in a scratch project writes a `prisma-next.md`
primer and one `SKILL.md` per workflow under `.claude/skills/<name>/` and
`.agents/skills/<name>/`. These skills are the authoritative agent workflows;
use them to verify the exact commands, flags, and setup flow a page teaches.

Completion criterion: every behavioral claim on the page is backed by a
specific repo file, example, or generated command output. If you cannot find
it, you have not verified it.

### Call out deltas from Prisma 7

Readers arrive knowing Prisma 7. When Prisma Next changes a workflow (schema
authoring, the generated client, query API, migrations, CLI, project setup),
name the difference explicitly. A silent difference reads as a typo; a named
**delta** teaches. Point migrating readers at the Migration guide, not at a
buried aside.

### Do not guess

If Prisma Next behavior is unclear, unverifiable in the repo, or still in flux,
do not write a plausible-sounding guess. Flag it: leave a `TODO` with the
open question and the engineering owner, and say plainly that it needs
verification. An honest gap is fixable; a confident wrong claim ships and
misleads.

## Information architecture: follow the spec

The canonical structure for Prisma Next user docs is the user-docs spec:

https://github.com/prisma/prisma-orm-messaging/blob/main/docs-strategy/prisma-next-user-docs-spec.md

It is a private repo; fetch it with `gh`:

```bash
gh api repos/prisma/prisma-orm-messaging/contents/docs-strategy/prisma-next-user-docs-spec.md \
--jq '.content' | base64 -d
```

Before writing a page, read, in order: the section brief for its group, the
page template that brief names, the canonical example schema, and the style
section. The spec's own "Writers' quick start" lists these.

Load the full spec for detail; the rules that bite most often:

- **The tree** is canonical. Top-level groups (Introduction, Getting started,
Data modeling, Contract authoring, Fundamentals, Middleware, Extensions,
Migrations, CLI, Reference, Guides) are stable. Anything that does not fit
one of them needs a docs RFC, not a new top-level section.
- **One concept per page. Code first, prose second.** Open every page with one
sentence answering its title, then lead with a working example.
- **Pick one template** and follow it: Tutorial (step-by-step to a working
result), Concept-and-example (what a thing is and how it behaves), or
Reference (a scannable lookup for one symbol, flag, or error).
- **Reuse the canonical `User`/`Post` schema and the `db` import.** Do not
invent a new schema per page unless the topic forces it.
- **Multi-database is one canonical page per symbol**, layered by portability:
the portable core as the body, a `<DbSupport>` block near the top, and
per-database differences as `## On <Database>` **delta** sections. Reach for
`<Tabs>` only when the snippets are short, fully parallel, and have no shared
core (schema-shape blocks, the `aggregate` case), always Postgres then
MongoDB. Delta sections beat tabs because they stay crawlable for search and
cleanly chunkable for agents.
- Reuse existing MDX components (`<Cards>`, `<Tabs>`, admonitions). A new MDX
component needs an RFC in `prisma/web`.

## Writing voice: direct, assertive, useful

Write for a TypeScript developer, often working alongside a coding agent, who
wants to get something done. The docs read well for both humans and agents:
linear prose, exact product names, one canonical page per concept.

- **Write assertively.** State what to do and why. Imperative headings ("Filter
results", not "Filtering results").
- **Guide step by step** where the reader must do something; make the next
action and its reason explicit.
- **Keep explanations succinct.** No filler ("we will explore", "let us dive
in", "it is worth noting"). Respect the length budgets in the spec's briefs.
- **Avoid conceptual complexity the page does not need.** Teach the decision in
front of the reader, and link out for depth.
- **No vague hype**, no empty slogans, no dramatic fragments. No em dashes.
- **Exact product names.** Prisma Next is the next major version of Prisma ORM.
Do not reduce the platform to "just an ORM", and do not blur Prisma ORM (the
toolkit) and Prisma Postgres (the managed database).
- **Be honest about Early Access.** Do not imply GA or production readiness.
MongoDB support is still being validated. Avoid unsupported absolutes (`no`,
`all`, `any`, `automatic`, `instant`) and stacked superlatives (`powerful`,
`seamless`, `effortless`, `fast`) unless the page shows how or why.

The shift to make, every time:

- Weak (hype, no task): `Curious now? Go use this.`
- Strong (task, reason): `Use this to see how Prisma Next changes the way you
define models, write queries, and structure your Prisma ORM application.`

## Redirect tracking

Prisma Next docs will eventually become the latest ORM docs, so URLs will move.
For every new or moved Prisma Next section, record the migration decision in the
tracking file before the section merges. See `references/redirects-tracking.md`
for the format, the columns, and where the file lives.
68 changes: 68 additions & 0 deletions .claude/skills/prisma-docs-voice/references/redirects-tracking.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Redirect and URL migration tracking

Prisma Next ORM docs are authored at `/docs/orm/next`. Prisma 7 ORM docs are the
generally available docs at `/docs/orm`. When Prisma Next goes generally
available, `/docs/orm/next/*` becomes `/docs/orm/*` (Prisma Next is promoted to
the latest ORM docs) and the current Prisma 7 pages are pinned to a versioned
path, `/docs/orm/v7/*`. (The Prisma Next getting-started pages live separately
under `/docs/next` and are not part of that promotion.)

So sections move and URLs change. Track every decision before the routing
changes land, so redirects are deliberate rather than reconstructed after the
fact.

This tracking file **documents decisions only**. It does not implement
redirects. Redirects land later in `apps/docs/next.config.mjs` after the table
is reviewed.

## Where the file lives

One tracking file per migration effort, in the `prisma/web` repo:

```
apps/docs/prisma-next-redirects.md
```

It sits next to `next.config.mjs` (where redirects are implemented) and is a
plain working file, not a docs page (Fumadocs only renders `content/docs/`, so
a file at `apps/docs/` never becomes a route). Update it in the same PR that
adds or moves a Prisma Next section.

## What to record for each new or moved section

Maintain a table with one row per page. Columns:

| Column | Meaning |
| --- | --- |
| Current Prisma 7 URL | The live page today, e.g. `/docs/orm/prisma-schema/overview/generators`. Blank if the page is new to Prisma Next. |
| New Prisma Next URL | Where the page lives (or will live) under Prisma Next. |
| Redirect old → Prisma 7 versioned? | Whether the old URL should redirect to a pinned Prisma 7 page (e.g. `/docs/orm/v7/...`) so Prisma 7 readers keep the old behavior. Yes / No. |
| Redirect old → Prisma Next equivalent? | Whether the old URL should redirect to the Prisma Next page instead. Yes / No. |
| No one-to-one equivalent? | Yes when the page has no direct Prisma Next counterpart (removed, split, or merged concept). |
| Notes | Missing, merged, renamed, or deprecated pages; open questions; owner. |

Rules:

- A row's "redirect to Prisma 7 versioned" and "redirect to Prisma Next
equivalent" are usually mutually exclusive. If both look true, the page
probably splits into two, so add a note and a second row.
- When there is no one-to-one equivalent, still record the old URL and say in
Notes where its content went (merged into which page, or dropped and why).
- Do not delete rows as decisions settle. Mark them resolved so the history of
the migration stays legible.

## Template

Copy this into `apps/docs/prisma-next-redirects.md` to start (or extend) the
table.

```markdown
# Prisma Next redirect tracking

Temporary migration-decision log. Documents redirect intent only; redirects are
implemented later in `next.config.mjs` after review.

| Current Prisma 7 URL | New Prisma Next URL | Redirect old → Prisma 7 versioned? | Redirect old → Prisma Next equivalent? | No 1:1 equivalent? | Notes |
| --- | --- | --- | --- | --- | --- |
| /docs/orm/prisma-schema/overview/generators | /docs/orm/next/prisma-schema/overview/generators (if it exists) | Yes → /docs/orm/v7/prisma-schema/overview/generators | TBD | TBD | Confirm whether Prisma Next keeps a generators concept. If it does, the Prisma Next page owns /docs/orm/... at GA; if not, mark no 1:1 and note where the concept moved. |
```
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -40,3 +40,4 @@ next-env.d.ts
# opensrc - source code for packages
opensrc
.env
prisma-next/
Original file line number Diff line number Diff line change
Expand Up @@ -214,4 +214,4 @@ This command will set up Prisma Next in a new or existing project with a simple

Tell us what worked and what didn't on [Discord](https://pris.ly/discord) in the `#prisma-next` channel, and **star and watch [prisma/prisma-next](https://pris.ly/pn-gh) on GitHub** to follow development. We'd love to hear your feedback!

Be aware that Prisma Next is not production-ready yet. Prisma 7 is still the right choice for production today. When Prisma Next is ready for general use, it becomes Prisma 8.
Prisma Next is in Early Access. Prisma 7 is the current generally available release, so if you're using it, keep using it. When Prisma Next is ready for general use, it becomes Prisma 8.
Original file line number Diff line number Diff line change
Expand Up @@ -235,7 +235,7 @@ The ORM ecosystem has plenty of healthy competition, and we wanted to make sure

## Where we are, where we're going

Prisma Next is still in its early stages and isn't ready for production use yet. For production applications, Prisma 7 is still the recommended choice. Once Prisma Next is ready for general use, it will become Prisma 8, and upgrading will be a smooth process.
Prisma Next is in Early Access. Prisma 7 is the current generally available release, so if you're using it, keep using it. Once Prisma Next is ready for general use, it will become Prisma 8, and upgrading will be a smooth process.

**What works today**:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,6 @@ Build it, then tell us about it in [`#prisma-next`](https://pris.ly/discord) on

Prisma Next is early, and the SPI is stable enough that the existing extensions are real proof of what's possible, though we expect to iterate as more of you build against it.

Prisma 7 remains the right choice for production today, and Prisma Next will become Prisma 8 once it's ready for general use.
Prisma Next is in Early Access, and Prisma 7 is the current generally available release, so if you're using it, keep using it. Prisma Next will become Prisma 8 once it's ready for general use.

The most interesting extensions will be the ones you'll write.
Original file line number Diff line number Diff line change
Expand Up @@ -439,7 +439,7 @@ If you're shipping today while following this work, start with [Prisma ORM](http

## We’re working in the open

Today we’re publishing the Prisma Next repo so you can follow the work as it happens. Even though it's early and not yet production-ready, we’re sharing it now so the community can see where we’re headed and help shape the design.
Today we’re publishing the Prisma Next repo so you can follow the work as it happens. It’s in Early Access, and we’re sharing it now so the community can see where we’re headed and help shape the design.

If you want to stay close to the work, **star + watch** the repo.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -284,7 +284,7 @@ Most importantly, `migration.ts` combined with `ops.json` is _really_ easy to re

## Try it yourself

Prisma Next is not production-ready yet. Prisma 7 is still the right choice for production today. When Prisma Next is ready for general use, it becomes Prisma 8.
Prisma Next is in Early Access. Prisma 7 is the current generally available release, so if you're using it, keep using it. When Prisma Next is ready for general use, it becomes Prisma 8. Follow development by starring [`prisma/prisma-next`](https://pris.ly/pn-gh) on GitHub.

But you can try it now:

Expand Down
6 changes: 6 additions & 0 deletions apps/docs/content/docs/(index)/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,12 @@ npx prisma init
npx create-db
```

:::note

[Prisma Next](/next) is the next major version of Prisma ORM, available now in Early Access. We strongly recommend trying it out before it becomes generally available, so you can get familiar with the new developer experience and share feedback while it’s still actively shaping up.

:::


<Cards>
<Card href="/prisma-orm/quickstart/prisma-postgres" title="Use Prisma Postgres" icon={<div className="text-primary"><svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="159" height="195" viewBox="0 0 640 640" fill="none"><path d="M355.2 85C348.2 72.1 334.7 64 320 64C305.3 64 291.8 72.1 284.8 85L209.7 224L430.2 224L355.1 85zM123.3 384L516.6 384L456.1 272L183.7 272L123.2 384zM97.4 432L68.8 485C62.1 497.4 62.4 512.4 69.6 524.5C76.8 536.6 89.9 544 104 544L536 544C550.1 544 563.1 536.6 570.4 524.5C577.7 512.4 577.9 497.4 571.2 485L542.6 432L97.4 432z" fill="currentColor"/></svg></div>
Expand Down
Loading
Loading