Treating a PRD as an executable spec for the agent

This whole site was built with Claude Code driving from a PRD. The PRD lives in docs/PRD.md. The strategic framing lives in docs/portfolio.md. The implementation plan was saved to a plan file before any code was written. These are the load-bearing artifacts; the others were mostly theater.

What I was testing

Can a tight PRD + a plan file + a CLAUDE.md carry the agent through ~3.7k lines of application code across 8 build steps without me having to course-correct more than a few times? Or does it inevitably devolve into "tell the agent what to do next" prompting?

What I tried

PRD-first methodology, executed as:

1. Wrote docs/PRD.md and docs/portfolio.md first. ~140 lines of plain Markdown.
2. Spawned the agent in plan mode with the question "what should I build?"
3. Reviewed the plan, edited it, approved it.
4. Walked through the build sequence step-by-step in a single long Claude Code conversation. No re-explaining at each step — the plan + the PRD + the CLAUDE.md were the context.

What worked, ranked by leverage

1. The Non-Goals section in the PRD. Single biggest scope-creep killer. "Phase 2 community features" got mentioned three times in the conversation and dismissed three times without me having to argue, because the PRD explicitly said they were out.
2. The plan file. A persistent artifact (not chat history) that I could re-reference, edit between steps, and treat as a contract. Chat context dilutes; files don't.
3. CLAUDE.md listing the stack pins. Next.js 16, AI SDK v6, Tailwind v4 — all post-training-cutoff versions. Without CLAUDE.md pinning them, the agent reached for the older API patterns it knew. With them pinned, it consulted the bundled node_modules/next/dist/docs/ instead.
4. Confirmed verification per step. Each step ended with pnpm build + pnpm lint clean before moving on. This caught two issues (the MDX blockJS: false requirement and the Vercel framework misdetection) at the earliest possible point.

What I thought would matter and didn't

• Detailed UI mockups. I had ASCII-style mocks in early drafts of the PRD. The agent didn't read them; what it actually used was the design principles ("calm, technical, minimally corporate") + the explicit "avoid AI-startup template aesthetic" line. The principles drove the output cleanly.
• Pre-specified component inventory. I listed every component I thought I needed in the plan. The agent built different ones, mostly better. The component list was busywork.
• Per-file estimates. I tried estimating lines-of-code per file. Pointless.

What surprised me

• The agent's wrong turns clustered around library version assumptions, not architecture decisions. Three of the four bugs we hit were "this API works differently in the new major version." The architecture itself never got challenged.
• The PRD's voice transferred to the code. I wrote the PRD in a terse, opinionated voice. The code comments and the lab system prompts came back in the same voice without me asking. The agent matched the project's tone consistently.
• The cached examples I wrote for the labs became the most useful prompt-engineering artifacts. Showing the model what good output looks like (in the system prompt as exemplars) outperformed describing what good output should look like.

What I'd do differently

• Write the plan file even tighter. Mine was ~250 lines; ~150 would have been enough. Long plans get skimmed.
• Pin the model in CLAUDE.md. I set claude-sonnet-4-5 for the labs in code but didn't put which Claude version Claude Code itself should use anywhere durable. Not an issue this session but a footgun.
• Add a "what's true in this repo today" section to the PRD. Half my time mid-build was reconciling what the PRD said with what was already shipped. A "Status" header in the PRD would close that loop.

Code/artifact links

• PRD — the original spec
• Portfolio strategy — the why
• CLAUDE.md — the running context
• The plan file is local to my Claude Code session, not in the repo. Same shape as the build sequence in the README.