How to Write a PRD for AI-Assisted Development

What Makes a PRD "AI-Executable"

Most PRDs are written for people. They describe intent, sketch a few screens, and leave the details to the engineers who will fill in the blanks during implementation. That works when the implementer is a human who can ask questions, read the surrounding code, and apply judgement. It breaks down when the implementer is an AI coding agent: it will not ask, it cannot infer your conventions, and it will confidently invent whatever you left undefined.

An AI-executable PRD is not a wish list; it is a technical blueprint. Every product decision is already made, every field has a type, every page has a layout, every endpoint has a route, and the build order is explicit. The agent's job becomes translation, not invention.

The test is simple. If two competent developers read your PRD and produce two different schemas, it is not ready. If even one decision — a data type, an input control, a lookup route — is still open, the agent will close it with something plausible and wrong.

The Sections an AI Actually Needs

A PRD does not have to be long. It has to be complete on the points the builder actually touches. These are the sections that change the generated code.

Overview & Scope

State what the application is, who it is for, and — just as important — what is out of scope. The agent uses scope to decide which entities to create and which to ignore. The Asset Manager example, for instance, is a demonstration ASP.NET Core application used to prove the workflow; it is not the Indotalent webstore, and the PRD says so plainly.

Personas, Roles & Permissions

List the personas and map them to the authorization model. This workflow defines three: Admin (the existing Admin area, unchanged), Main (all new features, available to the Admin and Member roles), and Guest/Self Service (optional, and able to see only its own data). When a persona can see only its own rows, say so explicitly — that becomes a query filter, not a suggestion.

Business-to-Technical Traceability Matrix

This is the section most PRDs skip and the one an AI needs most. Every table and column from the business source of truth must map to exactly one technical decision, with no loss and no invention. If a business column has no technical home, the agent will drop it. If a technical field has no business source, the agent will invent one.

Data Dictionary

Field by field: name, business meaning, type, nullability, and constraints. The type must come from an allowed list, not whatever the agent prefers. This is where you forbid the types that break the pattern and state which control renders each field.

Feature Backlog

Order the work in a buildable sequence: Master Pure first, then Master with Lookup, then Master-Detail. The order matters because lookups depend on the masters they reference and details depend on their parents. An unordered backlog forces the agent to guess dependencies.

Feature Specifications

For each feature: its data dictionary slice, page layouts, endpoints, business rules, and seed plan. This is the per-feature contract the generator reads when it creates the controller, CQRS handlers, Minimal API endpoints, validators, Razor views, and collocated JavaScript.

API Contract Summary

Every route, verb, request shape, and response shape in one place. In this standard, the last segment of an endpoint names the entity being fetched, and lookup endpoints follow the form /api/{entitylower}/{lookupentitylower}-lookup.

Traceability: Business Requirement to Technical Decision

Traceability is easier to show than to describe. Take a single business column and follow it all the way to the screen. Nothing is added, nothing is lost.

Now every reader — human or AI — can answer "where did this field go?" without ambiguity. If a business column has no row in the matrix, the PRD is incomplete.

Keep Ambiguity Out

The fastest way to make a PRD executable is to constrain the vocabulary. In this workflow the data dictionary accepts a fixed allow-list of types, and each type maps to one canonical UI control:

• string — text input
• string? — long text, rendered as a textarea
• decimal — numeric input, rendered as a range slider
• bool — a form-switch
• DateTimeOffset? — a flatpickr date
• TimeSpan? — a time input
• enum — the first enum uses Tom Select, later enums use radio cards
• lookup — string {X}Id plus a navigation property
• master-detail — ICollection<T>? Items
• string? AutoNumber — a generated document number

Four types are forbidden outright: long, Guid, DateTime, and int. They either leak storage concerns into the model or lose the offset that auditing needs. Derived totals — an amount with tax, a remaining quantity — are computed display values, not columns. Write that down, or the agent will add a column for them.

Enum controls get the same treatment. Because the reader must choose a control, the PRD states which enum is the primary one (Tom Select) and which are secondary (radio cards). AutoNumber is mandatory for every entity and is implemented through IHasAutoNumber in the format {ToShortNameConsonant(3)}/{Year}/{4-digit}, producing values such as PRD/2026/0001 or AST/2026/0001.

A Worked Example: the Asset Manager PRD

The whole workflow runs from one command, start the development. Its Phase 1 driver is PROMPT.md: it reads the engineering skill and FEATURE.md read-only and produces exactly one deliverable, PRD.md. FEATURE.md is the business source of truth generated in Phase 0 from the developer-written DATA-DICTIONARY.md; the PRD is the technical blueprint generated from it.

For the Asset Manager example the entities are Branch, Department, Manufacture, Vendor, Depreciation, AssetModelGroup, AssetModelSubGroup, AssetModel, Asset, and Employee. The AssetStage lifecycle runs ReadyToAssigned -> Assigned -> Repair -> Quarantine -> Missing, and AutoNumber prefixes include Branch BRN, Manufacture MNF, Vendor VND, AssetModel AST, and Asset ASS.

The PRD turns that raw business list into a buildable plan by classifying every entity by shape:

public class Asset : BaseEntity, IHasAutoNumber
{
    public string? AutoNumber { get; set; }        // string? AutoNumber
    public string Name { get; set; }               // string
    public string AssetModelId { get; set; }       // lookup FK
    public AssetModel? AssetModel { get; set; }    // lookup navigation
    public AssetStage Stage { get; set; }          // enum
    public ICollection<AssetDetail>? Items { get; set; } // master-detail
}

Entity type detection is part of the spec, not a discovery step. A Pure Master has no foreign key and no collection. A Master with Lookup declares string {X}Id plus a nullable {X}? navigation. A Master-Detail declares ICollection<T>? Items. When the PRD states the shape explicitly, the generator can produce the full file set — controller, CQRS handlers, Minimal API endpoints, validators, Razor views, and collocated JavaScript — without second-guessing.

The PRD also carries the rules that never change: soft delete only, with a global query filter (never a hand-written IsDeleted check and never .Remove()), and a CancellationToken on every CQRS handler and every Minimal API endpoint. Phase 2 then builds the app feature by feature, running dotnet build and fixing every error until it reports zero — the workflow's verification ceiling. Beyond that, a human tests the running application, because the build only proves it compiles.

Key Takeaways

• An AI-executable PRD is a technical blueprint; every open decision becomes a likely hallucination.
• Traceability is the core: every business column maps to exactly one technical decision, with no loss and no invention.
• Constrain types with an allow-list and forbid long, Guid, DateTime, and int.
• Order the backlog Pure Master, then Master with Lookup, then Master-Detail.
• The PRD is generated by Phase 1 of start the development, and dotnet build with 0 errors is the finish line before human review.