10. PRD — what to build before any line of code

The first nine posts of this series were about what Alice is — persona, memory, skills, hooks, multi-agent, verification, token economy, session protocols. Things that live inside the system.

The next three posts are about the work that runs through Alice. The shape of intent before code starts, the gate that says when code is done, and the loop that runs both without the operator at the keyboard.

This is the first of those three. PRD.

0. The premise — code is the last thing to write

Most operators start with code. Open the editor, write a function, see if it works.

That pattern collapses the moment the work gets bigger than a single afternoon. Yesterday's code does not remember why it exists. Tomorrow's session does not know what counts as done. The team lead approves a slice and weeks later the slice no longer fits.

The problem is not the code. The problem is that intent never got written down anywhere durable. The operator carried it in their head, the AI carried fragments in the context window, and both surfaces evaporate.

PRD — Product Requirement Document — is the answer. Not a planning artifact. A surface where the operator's intent lives outside the session, where the next session and the next collaborator can read it without re-asking.

1. What breaks when there is no PRD

A few patterns I have watched collapse, in my own work and in handovers to me.

• Decision rot. A choice gets made in a chat session. Three weeks later no one — including the operator — remembers why. The code reverts, drifts, or gets re-litigated every session.
• Scope drift. "While we are at it" creeps in. By the time the slice ships, it has done four things instead of one, and none of the four are reviewed.
• Definition-of-done collapse. Someone reports "feature is in." The team lead asks "in what sense?" Built? Tested? Live? Reviewed? Every answer is partially yes and the conversation cycles.
• Onboarding collapse. A new collaborator — a different agent, a different teammate, future-Alice on a fresh context — has no entry point. They reverse-engineer intent from code, which is exactly the loop the operator paid to avoid.

The common thread is the same one Part 1 — Why Alice opened with. The operator's mind — the purpose behind the code — is not surviving the session boundary.

2. PRD is mind made durable

The job of a PRD is narrow and specific. It does not plan tasks, it does not assign owners, it does not track progress. Those belong elsewhere.

A PRD answers one question: what are we building, and what makes it count as built?

Notice what is not on this list. There is no task list, no daily log, no who-did-what. Those things change every session. A PRD changes when intent changes, which is much slower.

A PRD describes the destination. Everything else describes the route.

3. What to put in, and what to keep out

The rule I converged on, after writing PRDs that grew to forty pages and PRDs that fit on a postcard:

In the PRD if: changing the line changes what the system is. Examples — "i18n is required, six locales," "downloads must show SHA-256," "no operator real name appears anywhere."

Not in the PRD if: changing the line changes only how the system gets built. Examples — "use pnpm for builds," "use shadcn for UI primitives," "tag commits with [devAlice] prefix."

The second list lives in CLAUDE.md or a README or a tooling doc. Not the PRD.

The reason for this separation is not aesthetics. It is lifespan. PRD lines should outlive a year. Build-system lines might not survive two quarters. Keeping them in different documents lets each one rot at its own rate without dragging the other down.

4. The cumulative-gate pattern

The most useful pattern I have used in PRDs is a cumulative release gate section.

The shape:

Gate 0: M0 launch (temporary domain)
  - Build passes
  - Four category routes render
  - One seed guide per category
  - ESLint clean

Gate 1: Compliance (required before publication)
  - Privacy policy (ko + en)
  - Content license (CC BY)
  - Code license (MIT)
  - About page exists
  - ...

Gate 2: Infrastructure
  - Custom domain bound
  - SSL active (auto)
  - Production env vars set
  - ...

Gate 3: Security
  - No hardcoded secrets
  - .env.example has every key
  - RLS enabled on user tables
  - ...

... Gate 10

Each gate is a table. Each row is [item | status | note]. Status is one of ✅ pass / ⏳ in progress / 🔒 waiting on operator / ❌ not started / — N/A.

Three things make this pattern work.

Cumulative. Gate 2 assumes Gate 1 passed. Gate 9 assumes Gates 0–8. The shape of the road is built in. No one ever has to ask "in what order?" — the document answers.

Atomic rows. A row is either passing or not. "Mostly works" is not a status. This forces the operator to break vague items ("performance is fine") into rows that can be checked off ("Lighthouse Performance ≥ 90 on five reference pages").

Status visible at the row level. The operator does not need to read prose to know where the project stands. Glance the column — count the ✅ versus the 🔒 — and the picture is immediate.

This is the section the team lead reads first, every session. It is also the section that drives Part 11 — Release gates and Part 12 — Ralph loop.

5. PRD vs the one-off plan

Operators often confuse a PRD with the session-level plan. They are not the same. They live at different timescales.

A line of intent that bounces around between these — landing in HANDOFF one day, in PLAN the next, in a chat session the day after — never accretes. The same intent has to be expressible in one consistent place. PRD is that place.

When a session starts, Alice reads PRD.md first, then HANDOFF.md, then PLAN.md. The reads compound. PRD sets what counts; HANDOFF says where the operator left off; PLAN says what is happening this slice.

6. Keeping the PRD alive

A PRD that rots is worse than no PRD, because everyone keeps reading it and acting on stale intent. Three habits I keep in rotation.

Versioned in-place. Top of the file: v1.0 → v1.1 → v1.2. Each version has a one-line note on what changed. The current version is whatever the latest line says. There is no separate changelog file.

Open-questions section is mandatory. Every PRD I write has an "open questions" section that is never empty during active development. The day it goes empty, either the project is done or someone is hiding decisions in their head.

Status review every milestone. When a milestone closes, walk the entire gate table. Items that drifted to ✅ during the milestone are promoted; items that did not get touched migrate to the open-questions section. The PRD is the snapshot of current intent, not historical intent.

7. The traps

Patterns I have watched break PRDs in practice.

7.1 PRD-as-marketing

Lines like "delightful UX" and "world-class performance." Nothing in those lines is testable. Strip them. If "performance" matters, write "Lighthouse Performance ≥ 90 on mobile, five reference pages."

7.2 PRD-as-task-list

Every line starts with a verb. "Implement X. Build Y. Wire Z." That is a task board, not a PRD. PRD lines describe the system — what it is, what it must do — not the work to make it that way.

7.3 PRD that never updates

The PRD has v1.0 at the top and the milestone is M3. Either decisions are happening in chat sessions and not landing back here, or the project is coasting on stale intent. Both are warning signs.

7.4 Decisions in chat, not in PRD

The team lead approves something in a Slack message or a session reply. Two weeks later no one remembers why. If a decision changes the PRD, it goes in the PRD before the session ends. That is the cost of approving.

7.5 Two PRDs

Someone writes a "real PRD" and a "summary PRD" or a "Korean PRD" and an "English PRD" that drift. Pick one. Multilingual surfaces are for users; PRDs are for the team and live in one language and one file.

Download — PRD template

A copy-ready PRD template: working scope, global constraints, the verification command, a decision-authority matrix, and per-item completion criteria. The shape this post describes, as one file.

shasum -a 256 PRD-code.md
# expected: 1c41c0e61b3dd027fa261e10a8b1f06381e40ee3ce476c24a8df673acb310e7c

8. One principle

The whole shape of how I use PRDs collapses to one line.

"Anything the operator's mind would lose between sessions, write into the PRD. Anything that does not survive a quarter, keep out of it."

That is also the bridge to the next two posts. A PRD answers what is the destination. Part 11 — Release gates answers how do we know we arrived. Part 12 — Ralph loop answers how do we let the system walk most of the road without the operator holding its hand.

Together those three turn the operator's intent — the mind from Part 1 — into something the system can carry across sessions, days, and collaborators without losing.