How to Write a PRD for an AI Feature: The Spec Forward Deployed Engineers Own

A PRD, a product requirements document, is the page that says why a feature exists, who it is for, what success will look like, how the thing works, what you will measure and what you are deliberately not trying to do. Learning how to write a PRD is usually taught as a product manager's skill. For a forward deployed engineer it is the moment the job changes shape: discovery is over, the client has agreed what the problem is, and someone now has to turn that agreement into a document an engineering team can build from without a meeting for every question. That someone is you.

I have written about the scope contract that records what you agreed to build and why architecture stays out of it. This post starts where that one stops. It draws on the product-management track of my cohort, taught by a product leader who has written specs from two pages to sixteen, and on a spec I wrote for a feature in my own project, because a template is only convincing once you have seen it filled in.

#Do the homework before the first line

A spec written cold is a feature list with a heading. The teacher's sequence before writing anything was industry research, then competitive analysis, then a gap that is unserved or underserved, then a solution for that gap, then the number you expect to move. Industry research tells you the shape of the market: is it supply-constrained or demand-constrained, is it local by nature, is it regulated. Competitive analysis tells you what each player has chosen to be good at. The gap falls out of the two.

Then a warning I keep coming back to: there is usually a good reason a gap is unserved. Sometimes it is regulation, sometimes a structural constraint nobody can move, sometimes an incumbent's sunk investment. Only the last one is an opportunity. The others are a trap that looks like one.

In an FDE engagement most of this homework is already done by the time you reach the spec. The discovery call and the root cause work produced the problem; the go/no-go decided it was worth solving. What the PRD homework adds is the check that the gap is real and reachable, and a sharper answer to the one question the whole document hangs on.

#Define the customer before you define a single feature

The teacher's case for this was the Delhi Metro, and I will tell it the way it was told in class, as a product-thinking parable rather than documented history. The dates are real: the Delhi Metro Rail Corporation was set up in 1995, construction began in 1998 and the first line opened in December 2002, with E. Sreedharan running the corporation for its first seventeen years. The conversation is the class's reconstruction.

The mandate reads like every mandate: decongest Delhi by building affordable public transport for people who cannot afford cars. Do the research and the mandate falls apart. Congestion is not caused by buses; a bus carries thirty or forty people in a fraction of the road those people would take in cars. Congestion is caused by single-occupant cars. Move bus passengers into a metro and the roads look exactly the same. The only system that decongests the city is one the car commuter chooses over the car.

Reframe the customer and the whole design changes. Routing has to run through the neighbourhoods and business districts where car owners live and work, not only where the political story is easiest. Pricing can be a fifty-rupee fare that a commuter spending two hundred on petrol will happily pay, instead of a twenty-rupee fare that competes with the bus and never recovers the capital. By the same logic the metric stops being "riders carried" and becomes "cars that stayed home." Two conditions closed the story: the engineer reports directly to the person who can make decisions, because layers in between will only relay the original brief, and the sponsor carries the politics of spending public money on a system built for the well-off. If that pairing sounds familiar, it is the same split I described in stakeholder alignment: you fight the problem, the sponsor fights the room.

The line that stayed with me was about what happened next. Other cities saw the artifact, tracks and trains, and copied it, without the reframing that made it work. Product teams do the same thing every quarter when they open a competitor's release notes and build the same list. The customer and the problem come first; the features are downstream of them, every time.

#How to write a PRD: the seven sections

The spec structure the class taught is short enough to hold in your head and strict enough to catch a bad idea. Every section answers one question, and the order matters because each answer constrains the next.

• Justification. One line on why this exists, in the language of a business outcome. "Loss of context during texting leads to annoyance" was the justification for WhatsApp's Reply feature. If you cannot write it in one line, you do not yet know why you are building it.
• Target customer. Precise enough to exclude people. Vertical tabs in a browser are for the person with twenty tabs open, not the person who keeps five and closes the window. "Anyone who uses the product" is not a target, it is an evasion.
• Goals and non-goals. Goals restate the justification as something measurable in a period. Non-goals are the things the feature is not expected to do, written down so that nobody asks six months later why it did not do them. Reply's non-goal was "not to increase usage": the target customer was already a heavy user.
• Design. How it works, not what it looks like. A login page is not three buttons; it is what happens to a new user, a returning user who forgot the password, a guest who filled a cart and closed the browser. The corner cases are the design.
• Metrics. Two kinds, always separated. Funnel metrics tell you whether the feature was built as designed: how many entered, how many completed each step, where they dropped. Impact metrics tell you whether the goal moved. A six-page insurance form can have a beautiful funnel and still fail if branch walk-ins do not fall, because people complete the form online and then go to the branch anyway.
• Constraints. The things that must hold whatever the design becomes: platforms, size limits, languages, compliance, cost ceilings.
• Version history. Every decision with the alternatives you rejected and the constraint that made you reject them. Someone will inherit this document and ask why a strange call was made. The answer "we had a week before the launch and no budget" is only useful if it was written down at the time, and it lets them check whether the constraint still applies.

#A worked example: the PRD for a self-healing test agent

Templates are easy to nod along to and hard to fill in, so here is the spec for one feature of FlowTrace, a project I built where you write end-to-end tests in plain English and a LangGraph agent drives a real browser through them. The feature is self-healing: the agent adapts when the UI changes underneath a test. The repository has the implementation; this is the document that should have existed before it.

• Justification. End-to-end tests break far more often because a designer renamed a class or moved a button than because the product actually broke. Each false failure costs a developer time and erodes trust until the team stops running the suite.
• Target customer. A small product team that already maintains a selector-based browser test suite and spends more time repairing it than it saves. Not a team with no end-to-end tests, and not a QA organisation with dedicated automation engineers who would rather own the selectors themselves.
• Goals and non-goals. Goal: a test written in plain English keeps passing through a renamed button or a relocated field without anyone editing the test. Non-goals: it does not catch visual regressions, it does not replace unit tests, and it is not trying to make test runs faster. If anything, it makes them slower, and the document should say so.
• Design. A ReAct-style agent observes the page, decides the next action, executes it through Playwright, and re-observes, on every step. A renamed button is a new observation, not a failure. Three healing layers handle recovery, every heal is written to the run's reasoning trace, and the critical corner case is that healing must never mask a real failure: an assertion about product behaviour still fails when the behaviour is wrong.
• Metrics. Funnel: tests created, runs completed, steps where a heal fired, heals that led to a passing step. Impact: the share of failures that were UI churn rather than real bugs, hours spent editing tests, and whether the team is still running the suite a month later. I will be honest that I can read the funnel out of the run history and the reasoning trace, and I have not measured the impact at all, which is itself a finding the spec forces out of you.
• Constraints. Works with OpenAI, Anthropic, Gemini, Ollama and OpenRouter so a team can bring its own key and its own cost profile; runs in a real browser; every step spends tokens, so a long test has a price the spec has to acknowledge; persistence is SQLite, which caps the deployment story for now.
• Version history. The design re-reads the page on every step rather than caching selectors between runs. That is what makes healing possible, and it is also why runs cost more. The entry to write is the reason: the obvious alternative, a cached selector, is exactly the brittleness the feature exists to remove. If token prices or page sizes change that calculus, this is where a future maintainer finds the trade-off and can revisit it.

Writing that out did something the code had not: it separated what I could measure from what I had assumed. The funnel was real. The impact was a belief. A spec that ends with "we believe" in the metrics section is not finished, and it is far cheaper to learn that on paper than after the launch.

#Outcomes, not outputs

The distinction underneath the metrics section is one the class spent real time on. Outputs are the things you control: a campaign sent, a homepage refreshed, a middleware shipped. Outcomes are the market's reaction: retention, revenue, the client's on-time delivery number. A business only wants outcomes, and it hires you for them, but you can only directly produce outputs. The whole craft of a spec is choosing outputs that plausibly cause the outcome, then measuring both, so that when the funnel is fine and the impact is flat you know it is the hypothesis that failed, not the build.

This is also the difference between project thinking and product thinking. A project has an end and is judged on efficiency: did the right materials arrive at the right time with the least waste. A product does not end and is judged on effectiveness: did the number move. A forward deployed engineer carries both, and the failure mode is reporting the project when the client asked about the product. "The pipeline shipped on schedule" is an output. "On-time delivery moved from 78 to 84 percent" is the outcome the sponsor is going to repeat to the board.

#Ship it behind a gate, not a switch

The one document the class called an anti-explosive device is the rollout plan, and it earns the name. There will always be pressure to release to the whole customer base at once, because the thing is built and waiting looks like caution. Release to two percent. Write down, before you start, the metrics that have to hold before you open the next gate: failure rate under a threshold, funnel completion above one, no regression in the impact metric. Only then go to ten percent, then fifty. The plan exists so that the decision to widen is made against numbers you chose in advance, not against how confident the room feels on the day.

For an agentic feature the gate is not optional. Self-healing that quietly masks a real failure would look like a success at two percent and a disaster at a hundred. The metric that catches it, healed steps whose assertions later fail, has to be on the dashboard before the first customer sees the feature.

#Where the PRD sits in an FDE engagement

The teacher's estimate was that product management is about sixty percent of the forward deployed engineer's job: the part where you consult with the client to make product decisions, and the part where you fold what one client needed back into the product every client gets. I would not defend the number, but the shape is right. Discovery finds the problem. The go/no-go decides whether to solve it. Alignment gets the humans to agree on the same version of reality. The scope contract fixes what is in and out. Then, and only then, the PRD: one per workstream, so the data pipeline, the model and the dashboard each get their own justification, customer and metrics rather than sharing one vague document. Sprint planning breaks the PRD into work an engineer can finish in a week.

Every one of those steps exists to protect the sentence at the top of the spec, the one-line justification, from being written by whoever asked loudest. That protection is what separates a forward deployed engineer from a developer with a client. The developer builds what the document says. The FDE makes sure the document is about the right customer before anyone builds anything.