How to write a PRD for a coding agent (and why the handoff is the moment that matters)

The moment you paste a prompt into Cursor or Claude Code, you've made a decision you can't take back. The agent doesn't pause to ask what you really meant. It reads your spec, fills the gaps with its best guess, and writes code with total confidence. Ten minutes later you have a working feature that may have nothing to do with what your customers actually asked for. That's why a PRD for a coding agent is a different artifact than the doc you used to write for an engineer who'd push back over Slack.

A human reviewer is a safety net. They catch the missing edge case, notice the auth requirement you forgot, ask why you're building this at all. An agent has no such instinct. It executes the spec you gave it, not the one in your head. So the quality of the handoff, the exact text that crosses from planning into building, becomes the single highest-leverage thing a product person controls. Get it right and you ship the right thing fast. Get it vague and you've automated the production of confidently wrong code.

Why a spec for AI coding is its own genre

Most PRDs are written to persuade. They have a narrative arc, a market-sizing slide, a paragraph of context that exists to get a skeptical stakeholder to nod. A spec for AI coding needs almost none of that. The agent isn't skeptical and it isn't going to be persuaded. It's going to be instructed. What it needs is the opposite of a pitch: unambiguous scope, explicit constraints, concrete acceptance criteria, and the file-level context to act without guessing.

The failure modes flip too. A human PRD fails when it's boring or unconvincing. An agent spec fails when it's underspecified. "Add a way for users to export their data" is fine for a human who'll ask which format and where the button goes. To an agent it's an invitation to invent CSV, drop it in a random menu, and skip the empty-state entirely. The job isn't to inspire. It's to remove every degree of freedom you don't want the agent to exercise.

What goes in a Build Pack

In Klyr the artifact that crosses the handoff is called a Build Pack, and it's deliberately three things stapled together because each does a job the others can't:

• ·A PRD. The problem, who has it, the proposed change, and what's explicitly out of scope. Tight, not narrative. Out-of-scope matters as much as scope, because an agent left to interpret will happily build the thing you didn't ask for.
• ·Acceptance criteria. Testable, binary statements of done. "When a user with no saved reports opens the export menu, the export button is disabled with a tooltip explaining why." Not "handle the empty state gracefully." If you can't write it as a pass/fail check, the agent can't build to it and you can't verify it.
• ·A coding-agent prompt. The actual paste-ready instruction for Cursor or Claude Code, with the file paths, conventions, and constraints the agent needs to start without inventing context. This is the part most teams skip, and it's the part that decides whether the build matches the spec.

The acceptance criteria are where most of the value sits. They're the contract. They tell the agent what done looks like, they tell you what to check before you trust the output, and and they survive the round trip: when the feature ships, the same criteria become the test of whether it worked.

The handoff is the moat moment

Here's the part that's easy to miss. Cited synthesis, turning interview notes into themes with source quotes, is table stakes now. NotebookLM does it. Your coding agent does a version of it for free. The thing that's genuinely hard, and genuinely valuable, is the irreversible handoff: the instant a ranked bet becomes a spec an agent will execute literally.

It's irreversible because the agent doesn't deliberate. Whatever assumptions are baked into the prompt become assumptions baked into your codebase. If the bet was ranked off a theme that only had one offhand mention, the agent doesn't know that. It builds with the same certainty it would for a theme backed by forty customers. The whole discipline is making sure the evidence behind the bet is strong before the handoff, because after it the cost of being wrong is real code, real review time, and a feature nobody needed.

This is why Klyr drops themes with fewer than two citations before they can ever become a bet, and why a Build Pack carries the evidence trail with it. The prompt you paste isn't floating free of its sources. It traces back to the verified quotes that justified the bet. You can see a live cited report to follow that chain end to end.

Writing the prompt so the agent can't drift

A few habits make the paste-ready prompt hold up. Name the files and the existing patterns to follow, so the agent matches your codebase instead of its training defaults. State the constraints as hard rules: "do not add a new dependency," "reuse the existing auth middleware", because anything you leave open, the agent will close on its own terms. Put the acceptance criteria directly in the prompt so the agent builds toward verification, not just toward something that compiles. And keep the bet to one shippable change; a prompt that tries to do five things produces five half-done things.

Be honest about the limit here: no prompt eliminates review. The agent will still make choices you didn't anticipate, and you still read the diff. What a good Build Pack does is shrink the gap between intent and output enough that review becomes confirmation rather than rescue. The acceptance criteria are your checklist; if the diff passes them, you're done, and if it doesn't, you know exactly where it drifted.

Closing the loop

The last thing a spec for AI coding should do is leave a trace. Your coding agent forgets everything the moment the session ends. It has no memory of why you built this or whether it worked. When the feature ships, the outcome should flow back to the bet, the bet to the theme, the theme to the quotes. That's the persistent evidence-to-outcome graph, and it's the part an agent can't give you, because forgetting is built into how it works.

So treat the Build Pack as the seam between two systems: the messy human work of deciding what's worth building, and the literal execution of an agent that will do exactly what you say. Write the PRD tight, make the acceptance criteria binary, ship the prompt paste-ready, and make sure the evidence behind the bet was real before you cross the line, because once it's in Cursor, the only thing left to do is read what it built. You can start free and turn your next ranked bet into one.