5 PRD mistakes that make your AI coding agent rebuild the same feature twice
You hand a PRD to Cursor or Claude Code. It builds the feature. You review it, spot something wrong, and ask for a fix. It rebuilds — and breaks something that was working. Repeat twice more and your afternoon is gone, along with the credits.
Most of the time the agent is not the problem. The PRD left a decision open, and the agent guessed — differently each time. These are the five gaps I see most often, and what a complete spec does about each one.
1. Acceptance criteria that say "should work" instead of GIVEN-WHEN-THEN
"The sprint forecast should be accurate" is not a criterion. Accurate how? For which team? With what data?
A testable criterion names the setup, the trigger, and the expected result:
GIVEN a team with at least 3 completed sprints, WHEN the lead creates a new sprint, THEN calculate and display the recommended story-point capacity with a 95% confidence interval.
That sentence comes straight from the sample spec my generator produces for TaskPulse, a sprint-tracking app. With it, the agent has one thing to build and you have one thing to check. Without it, "accurate" means whatever the agent decides today — and something else tomorrow.
2. A feature with no owner in the database
A PRD can describe a feature beautifully and still never say where it lives. "Sprints belong to a workspace" is a sentence; the schema is the commitment:
CREATE TABLE public.sprints (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
workspace_id UUID NOT NULL REFERENCES public.workspaces(id) ON DELETE CASCADE,
name TEXT NOT NULL,
start_date TIMESTAMPTZ NOT NULL,
end_date TIMESTAMPTZ NOT NULL,
target_points INTEGER DEFAULT 0 CHECK (target_points >= 0),
created_at TIMESTAMPTZ DEFAULT now()
);
If the PRD never names the table, the agent invents one — and the next prompt invents a different one. The rebuild is not a bug. It is the PRD failing to pin the entity down the first time.
3. Security added "later"
Every PRD has a security section. Most of them say "add Row Level Security" and move on. The table ships, the policy never arrives, and the first real user can read another workspace's data.
The policy has to arrive with the table, in the same file:
ALTER TABLE public.sprints ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Tenant Workspace Isolation" ON public.sprints
FOR ALL USING (
workspace_id IN (
SELECT workspace_id FROM public.workspace_members
WHERE user_id = auth.uid()
)
);
"Add it in the hardening sprint" is how multi-tenant leaks are born. If the PRD does not contain the policy, the agent will not write it — it builds what the spec says, nothing more.
4. API limits that live only in someone's head
"Name must be reasonable" is not a rule. The API contract has to state the boundary in numbers, using the same names the table uses:
// POST /api/v1/sprints/create
export const CreateSprintSchema = z.object({
workspaceId: z.string().uuid(),
name: z.string().min(3).max(64),
startDate: z.string().datetime(),
endDate: z.string().datetime(),
targetPoints: z.number().int().positive().default(40),
});
3–64 characters, positive target, same field names as the database. When the limit is written down, the agent validates it. When it is not, the agent accepts anything — and the rebuild starts when a user types a 200-character name and the UI breaks.
5. No rules telling the agent what NOT to do
A PRD tells the agent what to build. It rarely tells it what to avoid. So the agent helpfully adds a dependency you never approved, invents a table the schema never mentioned, or leaves a // TODO where the real logic should be.
That is why the fourth file of the suite exists: deterministic rules for the agent itself. The ones that matter most:
- Never invent arbitrary dependencies or unapproved database tables.
- Every server action must validate input payloads using Zod schemas.
- Every database query must respect Supabase Row Level Security boundaries.
- Output complete, production-grade files. Do not use
// TODOor placeholder stubs.
Rules like these are not decoration. They are the difference between an agent that builds the spec and an agent that improvises a new one on every run.
The check before you hand it over
Before your PRD reaches an agent, check five things: every feature has a GIVEN-WHEN-THEN criterion, every entity has a table, every table has its access policy, every endpoint has typed limits, and the agent has written rules about what not to do. If one is missing, the rebuild is already scheduled — you just do not know it yet.
If you want the shape, the free template behind this format is on GitHub, no signup: https://github.com/web-dev-mehedi/ai-prd-template
And if you would rather generate the whole four-file suite from one paragraph — PRD, UI/UX spec, schema with RLS, and agent rules — the generator is here: https://webdevmehedi.com/ai-prd-generator — 50 free credits on signup, plans from ৳99/mo with bKash and Nagad.
A PRD is not a document. It is a set of decisions, written down before the agent has to guess them.
Top comments (0)