|
| 1 | +# How to Create AI Prompts for Guide Pages |
| 2 | + |
| 3 | +This document explains how to add a "Copy prompt" banner to a Prisma docs guide page. The banner lets users copy a pre-built AI prompt so they can delegate setup to their IDE's AI assistant instead of reading the full guide. |
| 4 | + |
| 5 | +## How it works |
| 6 | + |
| 7 | +1. A prompt MDX file lives at `content/docs/ai/prompts/{slug}.mdx` |
| 8 | +2. The guide page's frontmatter references it via `aiPrompt: "{slug}"` |
| 9 | +3. The banner automatically appears on the guide page, extracting the prompt text from inside the ```` ````md ```` ```` code fence in the prompt MDX file |
| 10 | + |
| 11 | +## Step-by-step: Adding a prompt to a new guide |
| 12 | + |
| 13 | +### 1. Write the prompt MDX file |
| 14 | + |
| 15 | +Create `content/docs/ai/prompts/{slug}.mdx` where `{slug}` matches the framework/tool name (e.g., `remix`, `nuxt`, `sveltekit`). |
| 16 | + |
| 17 | +Use the following structure — copy this template and adapt it: |
| 18 | + |
| 19 | +````mdx |
| 20 | +--- |
| 21 | +title: "{Framework} + Prisma" |
| 22 | +description: "Step-by-step guide for integrating Prisma ORM and Prisma Postgres in a {Framework} project" |
| 23 | +url: /docs/ai/prompts/{slug} |
| 24 | +metaTitle: "How to Initialize a {Framework} App with Prisma ORM and Prisma Postgres" |
| 25 | +metaDescription: "Step-by-step guide for integrating Prisma ORM and Prisma Postgres in a {Framework} project." |
| 26 | +--- |
| 27 | + |
| 28 | +## Prerequisites |
| 29 | + |
| 30 | +Before using this prompt, you need to create a new {Framework} project: |
| 31 | + |
| 32 | +```bash |
| 33 | +# framework-specific create command |
| 34 | +``` |
| 35 | + |
| 36 | +Once your project is created, you can use the prompt below with your AI assistant to add Prisma and Prisma Postgres. |
| 37 | + |
| 38 | +## How to use |
| 39 | + |
| 40 | +Include this prompt in your AI assistant to guide consistent code generation for {Framework} + Prisma + Prisma Postgres projects. |
| 41 | + |
| 42 | +- **GitHub Copilot**: Type `#<filename>` to reference the prompt file. |
| 43 | +- **Cursor**: Use `@Files` and select your prompt file. |
| 44 | +- **Zed**: Use `/file` followed by your prompt's path. |
| 45 | +- **Windsurf**: Use `@Files` and choose your prompt file from the list. |
| 46 | + |
| 47 | +## Prompt |
| 48 | + |
| 49 | +````md |
| 50 | +(your full prompt content here — see "Writing the prompt" below) |
| 51 | +```` |
| 52 | +```` |
| 53 | + |
| 54 | +### 2. Write the prompt content |
| 55 | + |
| 56 | +The prompt inside the ```` ````md ```` ```` fence is what gets copied to the user's clipboard. Use the Next.js prompt (`content/docs/ai/prompts/nextjs.mdx`) as the reference. Here's what makes a good prompt: |
| 57 | + |
| 58 | +#### Structure to follow |
| 59 | + |
| 60 | +Use Clerk's pattern (proven to work well with AI assistants): |
| 61 | + |
| 62 | +1. **Project detection** — The AI must check whether a framework project already exists (e.g., look for `nuxt.config.ts`, `next.config.ts`, `remix.config.ts`, etc.). If the project exists, skip creation. If not, run the framework's create command before proceeding. This must be the **very first section** inside the prompt. |
| 63 | +2. **Overview** — What the prompt does, high-level steps |
| 64 | +3. **Critical instructions** — What the AI MUST always do (correct patterns, correct imports, correct config) |
| 65 | +4. **Never do this** — Deprecated/broken patterns the AI must avoid, with clear examples |
| 66 | +5. **Correct code samples** — Full, copy-pasteable code for every file the AI needs to generate |
| 67 | +6. **Setup workflow** — Numbered step-by-step sequence the AI should follow (step 1 should be the project detection) |
| 68 | +7. **Verification steps** — Checklist the AI should run through before responding (first item should verify the framework project exists) |
| 69 | + |
| 70 | +#### Key principles |
| 71 | + |
| 72 | +- **Always detect the project first**: The prompt content (inside the ```` ````md ```` ```` fence) is the only thing the AI sees — it never sees the Prerequisites section on the docs page. The prompt itself must check whether a framework project already exists (by looking for its config file) and create one if needed. This must be the first thing the AI does. |
| 73 | +- **Be explicit about correct patterns**: Don't assume the AI knows the latest API. Spell out exact import paths, exact config values, exact function signatures. |
| 74 | +- **Be explicit about broken patterns**: AI models are trained on outdated tutorials. List every deprecated pattern with a clear "DO NOT use this" marker. |
| 75 | +- **Include full code samples**: Every file the user needs should have a complete, working code block. Don't leave things to interpretation. |
| 76 | +- **Mark interactive commands**: If a CLI command requires user input (like `prisma init --db`), explicitly tell the AI to ask the user to run it manually. |
| 77 | +- **Version pin**: State exact version requirements (Node.js, TypeScript, framework version, Prisma version). |
| 78 | + |
| 79 | +#### AI prompt template |
| 80 | + |
| 81 | +Use this as a starting skeleton for the prompt content: |
| 82 | + |
| 83 | +``` |
| 84 | +# Bootstrap {Framework} app with Prisma Postgres (Prisma v7) |
| 85 | +
|
| 86 | +**Purpose:** Set up Prisma ORM with Prisma Postgres in a {Framework} project using the correct Prisma v7 patterns. |
| 87 | +
|
| 88 | +--- |
| 89 | +
|
| 90 | +## FIRST: Check for an existing {Framework} project |
| 91 | +
|
| 92 | +Before doing anything else, check whether the current directory already contains a {Framework} project by looking for its config file (e.g., `nuxt.config.ts`, `next.config.ts`, `remix.config.ts`). |
| 93 | +
|
| 94 | +- **If the config file exists** → A project is already set up. Skip to "Overview" below. |
| 95 | +- **If the directory does NOT contain the config file** → Create a new project first: |
| 96 | +
|
| 97 | +({framework-specific create command, e.g., npx nuxi@latest init hello-prisma}) |
| 98 | +
|
| 99 | +After the project is created, verify the config file exists before continuing. |
| 100 | +
|
| 101 | +## Overview of implementing Prisma with {Framework} |
| 102 | +
|
| 103 | +1. Ensure a {Framework} project exists (see above) |
| 104 | +2. Install Prisma and required dependencies |
| 105 | +3. Initialize Prisma and configure schema |
| 106 | +4. ...framework-specific steps... |
| 107 | +
|
| 108 | +## CRITICAL INSTRUCTIONS FOR AI LANGUAGE MODELS |
| 109 | +
|
| 110 | +As an AI language model, you MUST NOT generate any of the following code patterns, as they are DEPRECATED and will BREAK the application: |
| 111 | +
|
| 112 | +(list broken patterns with code examples) |
| 113 | +
|
| 114 | +Instead, you MUST ALWAYS generate ONLY this pattern: |
| 115 | +
|
| 116 | +(list correct patterns with code examples) |
| 117 | +
|
| 118 | +## ABSOLUTE REQUIREMENTS FOR AI CODE GENERATION |
| 119 | +
|
| 120 | +1. You MUST use `provider = "prisma-client"` (not "prisma-client-js") |
| 121 | +2. You MUST use custom output path |
| 122 | +3. ... |
| 123 | +
|
| 124 | +## VERSION REQUIREMENTS |
| 125 | +
|
| 126 | +- Node.js: 20.19 or higher |
| 127 | +- TypeScript: 5.4.0 or higher |
| 128 | +- Prisma: 7.0.0 or higher |
| 129 | +
|
| 130 | +## CORRECT INSTALLATION |
| 131 | +
|
| 132 | +(exact install commands) |
| 133 | +
|
| 134 | +## CORRECT PRISMA INITIALIZATION |
| 135 | +
|
| 136 | +(prisma init command — mark as interactive if needed) |
| 137 | +
|
| 138 | +## CORRECT CONFIG FILES |
| 139 | +
|
| 140 | +(prisma.config.ts, schema.prisma — full file contents) |
| 141 | +
|
| 142 | +## CORRECT CLIENT SETUP |
| 143 | +
|
| 144 | +(lib/prisma.ts or equivalent — full file contents) |
| 145 | +
|
| 146 | +## FRAMEWORK-SPECIFIC INTEGRATION |
| 147 | +
|
| 148 | +(API routes, server components, middleware — whatever is specific to this framework) |
| 149 | +
|
| 150 | +## COMPLETE SETUP WORKFLOW |
| 151 | +
|
| 152 | +1. Ensure a {Framework} project exists — check for config file, create if missing |
| 153 | +2. Install dependencies |
| 154 | +3. ...remaining steps from install to running dev server... |
| 155 | +
|
| 156 | +## AI MODEL VERIFICATION STEPS |
| 157 | +
|
| 158 | +Before generating any code, you MUST verify: |
| 159 | +1. Does the current directory contain the framework config file? If not, create the project first. |
| 160 | +2. Are you using the correct provider? |
| 161 | +3. Are you using the correct import paths? |
| 162 | +4. ... |
| 163 | +``` |
| 164 | + |
| 165 | +### 3. Add `aiPrompt` frontmatter to the guide |
| 166 | + |
| 167 | +Open the guide MDX file (e.g., `content/docs/guides/frameworks/remix.mdx`) and add `aiPrompt` to the frontmatter: |
| 168 | + |
| 169 | +```yaml |
| 170 | +--- |
| 171 | +title: Remix |
| 172 | +description: Learn how to use Prisma ORM in a Remix app |
| 173 | +url: /docs/guides/frameworks/remix |
| 174 | +metaTitle: ... |
| 175 | +metaDescription: ... |
| 176 | +aiPrompt: "remix" |
| 177 | +--- |
| 178 | +``` |
| 179 | + |
| 180 | +The value must match the slug of the prompt file (the filename without `.mdx`). |
| 181 | + |
| 182 | +### 4. Verify |
| 183 | + |
| 184 | +1. Run `pnpm dev` and navigate to the guide page |
| 185 | +2. The "Copy prompt" banner should appear below the description |
| 186 | +3. Click "Copy prompt" and paste into a text editor — verify the full prompt is there |
| 187 | +4. Navigate to a guide without `aiPrompt` — no banner should appear |
| 188 | +5. Run `pnpm build` — no build errors |
| 189 | + |
| 190 | +## Important notes |
| 191 | + |
| 192 | +- **Manual validation is required every time.** The prompt content is hand-written and must be tested with real AI assistants (Cursor, Copilot, Claude, etc.) to verify it produces working code. There is no automated way to validate prompt quality. |
| 193 | +- **Keep prompts up to date.** When Prisma APIs change, the prompts must be updated manually. Outdated prompts are worse than no prompt at all. |
| 194 | +- **The `content/docs/ai/prompts/nextjs.mdx` file is the reference implementation.** Always check it when writing a new prompt. |
0 commit comments