A prompt requirements document (PRD in the AI coding context) is a structured specification designed for AI coding agents — Cursor, Claude Code, Windsurf, and GitHub Copilot — rather than for human engineers. It contains the same information as a traditional PRD but formatted for machine consumption: explicit entity names, API contracts, state machines, and constraint lists that an AI agent can apply consistently across a coding session. This document is the bridge between a product idea and a coherent AI-generated implementation.
Why traditional PRDs don't work as AI coding context
A traditional PRD is written for human engineers. It uses narrative prose, explains context and rationale, and relies on the reader's domain knowledge to fill gaps. A human engineer reading "add a password reset flow" knows to use secure tokens, short expiry windows, and a "link already used" error state — they've built auth before.
An AI coding agent reading "add a password reset flow" makes decisions based on statistical patterns in its training data. It will produce code that looks reasonable but may not match your specific data model, authentication library choices, or error handling conventions. It doesn't know your User entity has a passwordHash field, not a password_hash field. It doesn't know you're using Resend for email, not SendGrid. It doesn't know your token table is called PasswordResetToken, not reset_tokens.
The prompt requirements document solves this by making the implicit explicit. Instead of "add a password reset flow," it says: "Add a password reset flow using the User.email field for lookup, creating a PasswordResetToken record with tokenHash, expiresAt (15 minutes), and usedAt fields. Send the reset email via Resend using the existing sendTransactionalEmail() helper in lib/email.ts. Return the same response for valid and invalid emails (prevents enumeration). Invalidate the token on first use."
The prompt requirements document format
Section 1: Feature context (2–3 sentences)
State what the feature does and why it exists. Keep this short — the AI coding agent needs context, not a business case.
This feature adds a password reset flow to allow users who have forgotten their password to regain access without contacting support. It is triggered from the login screen and delivered via email. Security requirements: token expiry (15 min), single-use, no account enumeration.
Section 2: Data model changes
Use your exact field names. This is the most important section — field name consistency prevents half the bugs in AI-generated code.
New table:
PasswordResetTokenFields:
id(cuid),tokenHash(string, SHA-256 of the raw token),userId(FK → User.id, cascade delete),expiresAt(DateTime),usedAt(DateTime, nullable),createdAt(DateTime, default now)Index:
tokenHash(unique),userIdNote: Store the hash, not the raw token. The raw token is sent in the email URL only.
Section 3: API contracts
Define each endpoint with exact paths, methods, request bodies, and response shapes. AI agents follow these contracts precisely.
POST /api/auth/forgot-passwordBody:
{"email": "string"}Response (always 200, regardless of whether email exists):
{"message": "If this email is registered, you'll receive a reset link."}Side effect: If email exists in User table, create PasswordResetToken record, send email via
sendTransactionalEmail()with the raw token in the URL (https://scriptonia.dev/reset-password?token={rawToken}).
POST /api/auth/reset-passwordBody:
{"token": "string", "newPassword": "string (min 8 chars)"}Response 200:
{"message": "Password updated successfully."}Response 400 (expired or used token):
{"error": "invalid_token", "message": "This link has expired or has already been used."}Side effect on success: set
PasswordResetToken.usedAt = now(), updateUser.passwordHash, invalidate all existing sessions for the user.
Section 4: Existing code to reuse
Point the AI to specific files and functions it should use. This prevents the AI from inventing duplicate utilities.
Email sending: use
sendTransactionalEmail()inlib/email.ts— do not create a new email utility.Password hashing: use
hashPassword()andverifyPassword()inlib/auth.ts.Token generation: use
crypto.randomBytes(32).toString('hex')for the raw token; hash withcrypto.createHash('sha256').update(rawToken).digest('hex')for storage.Error responses: use the
apiError()helper inlib/api.tsfor all error responses.
Section 5: Constraints and edge cases
1. Return 200 for both valid and invalid emails (no account enumeration).
2. Token expires 15 minutes after creation (check
expiresAt < now()).3. Token is single-use (check
usedAt IS NULLbefore processing).4. Rate limit: maximum 3 reset requests per email per hour (implement in route handler using Redis
ratelimitkeypassword-reset:{email}).5. On successful reset, call
invalidateAllSessions(userId)inlib/auth.ts.
Section 6: Success criteria
State what "done" looks like for the AI coding agent — the observable behaviors that must be true when the implementation is complete.
1. User submits valid email → receives reset email with a working link within 60 seconds.
2. User clicks link within 15 minutes → can set new password and is redirected to login.
3. User clicks expired or used link → sees expiry message; cannot set new password.
4. User submits invalid email → receives same response as valid email (no enumeration).
5. Existing sessions are invalidated after successful reset.
Prompt requirements document vs traditional PRD: what each is for
| Traditional PRD | Prompt requirements document | |
|---|---|---|
| Primary audience | Human engineers and stakeholders | AI coding agents |
| Length | 2–10 pages | 200–400 words |
| Field naming | Conceptual (e.g., "token expiry field") | Exact (e.g., PasswordResetToken.expiresAt) |
| Code references | None | Specific files and function names |
| Rationale | Included | Omitted (the AI doesn't need it) |
| When to write | Before sprint planning | Before each coding session |
| Generated by | PM (3–4 hours) or Scriptonia (30 seconds + review) | Scriptonia architecture blueprint section |
How Scriptonia generates prompt requirements documents
Scriptonia's architecture blueprint generation produces the core content of a prompt requirements document: data model with exact field names, API endpoint contracts, component relationships, and state machines. The PM adds Section 4 (existing code to reuse) — which requires knowledge of the specific codebase — and verifies Section 5 (constraints and edge cases) against the generated list.
Total time from rough idea to prompt requirements document: under 5 minutes. Total time writing one manually: 45–90 minutes for a developer who knows the codebase well.