AI coding agents don't fail on code — they fail on vague specs. A PRD for an AI coding agent needs four parts: the requirements, the database schema, the API contracts, and a rules file the agent must obey. A normal PRD has only the first. That's why agent-built apps drift: the agent isn't being careless — it's being forced to guess table names, payload shapes and security rules, and it guesses differently every session.
Why agents drift (the 3 failure modes)
- Invented data. No schema in the spec → the agent invents tables and columns mid-build, and invents different ones tomorrow.
- Shape-shifting APIs. No contracts → the same endpoint returns different payloads in different files.
- Security amnesia. Nothing pins the rules → Row Level Security, tenancy checks and permission limits silently disappear between sessions.
Each failure has the same cure: decide it once, in writing, before code exists.
The 4-part format
Part 1 — Requirements the agent can check
Number every requirement (FR-1, FR-2…) and give each an acceptance check — an observable test ("create product X with stock 20 → list shows stock 20"). An agent can verify a check; it cannot verify a wish.
Part 2 — The schema, as law
Real table names, foreign keys, constraints — and for Supabase/PostgreSQL, the RLS policies in the same document. Tell the agent: use these names exactly; never invent a column. (Free template: https://webdevmehedi.com/prd-template)
Part 3 — Contracts before code
For every endpoint or Server Action: method, path, who may call it, exact request shape (Zod), exact success shape, and the error cases. When the contract and the code disagree, the contract wins — say that in writing.
Part 4 — The rules file
Paste-ready for .cursor/rules or CLAUDE.md:
1. Build only what the PRD requires. If a requirement is unclear, stop and ask — do not invent behaviour.
2. Use the schema's table and column names exactly. Never invent a column, table, or relationship.
3. Use the API contracts exactly. Never change a payload without updating the contract first.
4. Never bypass Row Level Security. Never use the service-role key in a user-facing endpoint.
5. After each requirement, run its acceptance check and report the result.
6. If the PRD, schema and contracts disagree, report the conflict instead of choosing silently.
Worked example (fictional, 2 minutes)
ShopStock, a stock app for small shops: FR-2 says "recording a sale decreases stock; stock never goes negative" — the schema enforces it with a check (stock >= 0) constraint, the sales contract returns a 409 when quantity exceeds stock, and rule 5 makes the agent prove it with the acceptance check. Four short documents, zero guessing. Full example: https://github.com/web-dev-mehedi/ai-prd-template
Doing this by hand vs generating it
By hand: an evening with the free template, and the discipline to keep four documents consistent as the product changes. Generated: Web Dev Mehedi produces all four parts from one idea description in under 60 seconds, consistent with each other, with 50 free credits to start — https://webdevmehedi.com/ai-prd-generator
FAQ
Does this work with Windsurf or other agents?
Yes — the format is agent-neutral. Any tool that reads a rules file or a project document can follow it.
My PRD is in Notion/Docs. Can I add Parts 2–4?
Yes. Most teams only need to add the schema and the rules file to see drift drop sharply.
How long should the PRD be?
As short as possible while still answering: what, for whom, what data, what shapes, what rules. For a small app, 2–4 pages total across all four parts is normal.
What do you hand your coding agent before a build — a paragraph, a PRD, or the full four-part spec? Genuinely curious what other people's specs look like.
Top comments (0)