Writing PRDs for AI coding agents

Write a PRD an AI coding agent can execute by making it precise, file-scoped, and self-checkable: name the files to touch, give acceptance criteria the agent can test against, list the constraints it must respect, and define "done" as something it can verify without asking you. A regular PRD leaves room for human judgment. A spec for Claude Code, Cursor, or Codex has to close that room — because the agent runs on what you wrote, not what you meant.

This article is part of our AI PRDs guide. If you're new to PRDs, start with what a PRD is and the template. This page is about the version you hand to a machine.

Why an agent needs more than a human does

A person reading a PRD fills the gaps. They know your codebase, they've seen your style, and when something's unclear they walk over and ask. An AI coding agent does none of that reliably. It sees the words and the code you point it at, and it acts.

So the same instruction lands very differently. "Add validation to the signup form" is plenty for a teammate who knows the form. For an agent it's a coin flip — which file, which fields, what rules, what error copy, does it write a test? Every gap is a place the agent guesses. The whole craft here is removing the guesses.

The five things every agent spec needs

1. Scope it to files

Tell the agent where to work. "Edit src/auth/signup-form.tsx" beats "update the signup form." If you know the files, list them. If you don't, say how the agent should find them ("the form component under src/auth/") so it doesn't wander the repo. Scoping is also a safety rail — it keeps a change from sprawling into files you didn't mean to touch.

2. Give testable acceptance criteria

Write each criterion as a pass/fail check. Not "validate the email properly" but:

• Empty email shows "Email is required" below the field.
• An email without an @ shows "Enter a valid email."
• The submit button is disabled until every field is valid.

An agent can implement those and, more importantly, check its own work against them. "Properly" it cannot check.

3. Name the constraints

Say what not to do and what to match. Agents happily invent new patterns if you don't point at the old one. Quote the thing you want copied:

• Use the existing useForm hook, the same as login-form.tsx — don't add a new form library.
• Match the error-message style already in that file.
• No new dependencies.

Pointing at an existing file the agent can read is worth ten sentences of description.

4. Define done so the agent can prove it

"Done" should be something the agent runs, not something you eyeball. Give it the check:

• pnpm test src/auth/ passes.
• pnpm typecheck is clean.
• A new test covers the empty-email and invalid-email cases.

Now the agent has a finish line it can cross on its own, and you have a green build to review instead of a claim.

5. Keep each spec small

Hand an agent something it can finish in one focused pass — one feature, a few files, a clear done. If the work spans ten files and three subsystems, that's a human's PRD to break down; the pieces are what you give the agent. This is the same "standard unit of work" idea from the software factory model: a well-shaped unit an agent can pick up and clear the gates with.

A before-and-after

Here's a human PRD requirement turned into an agent-ready one.

Written for a human:

Add rate limiting to the API so people can't spam the export endpoint.

Written for an agent:

## Task: rate-limit the export endpoint

**Files:** `src/api/export/route.ts`, and a new `src/lib/rate-limit.ts`.

**Do:**
1. Add a rate limiter allowing 5 requests per minute per account ID.
2. Apply it to the export route only.
3. On limit exceeded, return HTTP 429 with body `{ error: "rate_limited" }`.

**Constraints:**
- Use the existing Redis client in `src/lib/redis.ts`. Don't add a new dependency.
- Match the error-response shape used in `src/api/auth/route.ts`.

**Done when:**
- `pnpm test src/api/export/` passes, including a new test that a 6th request
  in one minute returns 429.
- `pnpm typecheck` is clean.

The second version is longer, and that's the point. Every extra line is a guess the agent no longer has to make.

Where sfora fits

This is the part sfora is built for. In sfora, agents are equal members of your workspace — they read the same markdown, hold the same kind of permissions, and put their changes through the same review as a person. So a spec like the one above isn't a file you paste into a chat window and lose. It lives in the workspace as a task the agent picks up, works, and reports back on.

That closes the loop the whole AI PRDs guide has been building toward: a PRD is markdown, markdown is what your agents read, and a well-scoped requirement is a runnable instruction. Write the template with acceptance criteria this precise and you've written something a human can approve and an agent can execute — from the same document. For fully worked versions, see PRD examples.