Prompt Requirements Document: The PRD's Successor for the AI Era

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 to 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: PasswordResetToken

Fields: 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), userId

Note: 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-password

Body: {"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-password

Body: {"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(), update User.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() in lib/email.ts, do not create a new email utility.

Password hashing: use hashPassword() and verifyPassword() in lib/auth.ts.

Token generation: use crypto.randomBytes(32).toString('hex') for the raw token; hash with crypto.createHash('sha256').update(rawToken).digest('hex') for storage.

Error responses: use the apiError() helper in lib/api.ts for 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 NULL before processing).

4. Rate limit: maximum 3 reset requests per email per hour (implement in route handler using Redis ratelimit key password-reset:{email}).

5. On successful reset, call invalidateAllSessions(userId) in lib/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

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 to 90 minutes for a developer who knows the codebase well.