A PRD for AI coding agents
is a list of pages, with the gaps closed.

An AI coding agent never asks the question your spec left open. It answers it. Write “users can swap between tokens” and the agent decides which pair, what the user sees before confirming and whether the fee shows in gas or in dollars, decides it in the schema, and you find out at review.

That line reads as finished. So do most lines in most PRDs. Five of them are taken apart on the visual PRD page, and each one hides a decision: which pair, what the user reads before confirming, whether the fee is in gwei or dollars, what a first-time buyer is told about the price moving. None of those are details. Each one is a table column, a page state, or a whole page.

A human developer reads the same line and walks over to ask. The agent has nobody to walk over to, so every gap becomes a decision made without you, and the cost of a wrong one is a rebuild. The job of a PRD for an agent is to leave no gap. That changes its shape.

A feature list is a translation the agent has to do itself. “Swap, rewards, a portfolio” tells it what exists. It still has to invent which page each one lives on, what is on that page, and what happens when it goes wrong. Agents build pages and tables, so give them pages and tables.

One section per page, in the order a user meets them. On each page, four things:

• Purpose. One line. What this page is for, and the one decision it carries.
• On it. The fields and the buttons. Every control, and what it does.
• States. Ready, pending, empty, error. The page when the user has no ETH.
• Data. What the page reads and what it writes, by table.

Written that way, the line about swapping tokens cannot survive. You reach “On it” and have to write The fee, in dollars, and the decision is made where the agent will read it. Below is what that looks like drawn, which is the same thing with less room to be vague.

Whatever the button says in the spec is what it says in production. Leave it as “CTA” and the agent writes “Submit”. Leave the empty state to the agent and a first-time user with no coins sees “No results found” on their wallet.

Write the button label, the empty state, the error, and the body of every message the product sends. The month-one email is the clearest case: Your ETH earned you money this month. +$41.20 is a spec line, because it decides the channel, the timing, the tone, and what is worth telling (money, not a percentage) in one sentence. “An email is sent” decides none of them.

This is also where a PRD stops being a document only the PM reads. A copywriter can write on it. A client can read it and know what their customers will see, before anything is built.

The agent writes the migration from whatever you gave it, and if you gave it nothing it invents the model. Ids, relations, which table owns the fee: every one of those is a guess unless the tables are in the spec.

List the tables and their columns, and put each page’s reads and writes next to the page. The decisions you made on the pages show up here as columns. “Show the fee in dollars” is a column on the swaps table, fee_usd, and the agent should find it named, next to the page that needs it.

An agent builds the path you described and nothing beside it. The declined card, the double booking, the ticket nobody is assigned to: if the spec does not name them, the product has no page for them, and the first real user finds the hole.

Ask, for every page: what does it look like when there is nothing here, and what does it look like when the thing the user tried failed. Each answer is a state on that page or a page of its own. On a wallet that is not enough ETH, the price moving mid-swap, and the first visit with nothing in it. Three lines in the spec; three pages that would otherwise be a stack trace.

Two boards you did not ask for: the refund the bank declines, and who is allowed to issue one.

what Nadia adds to a support tool drawn from one sentence, on /product-managers

Copy it, keep the headings, replace Kestrel. Four pages, four tables, three decisions written down, one question left open on purpose. It is short because Kestrel is small; a product with twenty pages gets twenty sections, and that is the right length.

# Kestrel, a crypto wallet
One sentence. What it is and who it is for.
A crypto wallet for people who find crypto confusing. Buy, hold and earn, in plain English.

## Pages, in the order a user meets them

### 1. Swap
Purpose   The page the product exists for. Nothing is sent until the button is tapped.
On it     You pay (amount, coin) · You get about · The fee, in dollars · Change 0.5 ETH to USDC
Words     Button: "Change 0.5 ETH to USDC". Price note: "The price can move by up to 0.5% before it goes through. If it moves more, nothing happens."
States    ready · not enough ETH · price moved, nothing happened · pending · done
Data      reads holdings, prices · writes swaps

### 2. Portfolio
Purpose   Where a returning user lands. The total, then every coin under it.
Words     "You earned $41.20 from staking this month"
States    holdings · empty (first visit) · earning
Data      reads holdings, rewards

### 3. Email, month one
Goes out  day 30, once earnings pass $1
Says      "Your ETH earned you money this month. +$41.20"
Data      reads rewards, users

### 4. Earn
Purpose   Put coins to work. Rates shown as money, then as % a year.
States    earning · not earning · unlocking (about two days)
Data      reads holdings, rewards · writes rewards

## Data
users        id · email · keys_on_device
holdings     user_id · coin · amount
swaps        user_id · from · to · amount · fee_usd · status
rewards      user_id · coin · per_day

## Decisions already made
Write these down or the agent makes them for you.
- Fees in dollars, never in gas.
- Earnings as money first, % a year second.
- Keys stay on the device.

## Still open
- Do rewards show on Portfolio as a % or in dollars? Ask Sam.

The “Decisions already made” section is the one people skip and the one the agent needs most. The “Still open” section is the honest one: a question you have not answered, written down, is a question the agent will ask you instead of answering itself.

Put the file where the agent starts. In a repo, that is PRD.md at the root, named in the agent’s instructions file so it is read before the first change. In Cursor, paste it into Plan Mode and the agent turns it into a Markdown plan of file paths; check that plan against the pages before you let it build, because that is the last cheap moment to catch a gap.

Or skip the typing. The reason a drawn spec builds better is that a board cannot leave a gap where a sentence can: a field is on the page or it is not, a button has words or it does not, a state is drawn or it is missing. On HuntingHydra, Nadia draws the boards from one sentence, with the data beside them and the unhappy states you did not ask for, you move them until they are right, and Devi builds exactly those. Your own Claude Code or Cursor can drive it over MCP; the setup is on /docs.