I want to go from "vague idea of something neat to build" to
"well-scoped project with definite value, acceptance criteria, and
no remaining uncertainty." The first step is a PRD agent that
interviews me before it writes anything.
<h1 id="why-a-prd-agent">Why a PRD agent</h1>
I ran three Deep Research reports on AI-augmented PRDs and
AI-native SDLCs
(<a href="/wiki/research/ai-augmented-prds.html">notes</a>). One finding
kept showing up across all three: AI agents don't ask clarifying
questions. They assume. Hand a coding agent a vague idea and
it'll produce something plausible, polished, and wrong in ways
you won't notice until later.
The traditional PRD solves a different version of this problem.
A human engineer reads a vague spec and asks "what happens
when the user does X?" or "does this need to work offline?" An
AI agent fills those gaps with assumptions. All three research
reports converged on this: the biggest risk isn't bad output,
it's convincingly mediocre output that looks complete enough to
skip the hard thinking.
So the fix is an agent that does the asking. One that
interviews me first, pushes back on vague answers, and refuses
to write until it has real clarity.
<h1 id="the-prd-writer">The PRD Writer</h1>
The <a href="/wiki/agent-team/prd-writer.html">PRD Writer</a> is a Claude
Code agent that turns vague ideas into scoped PRDs. It runs on
Opus because it needs to recognize when an answer is too vague,
when goals contradict constraints, and when I'm hand-waving
instead of thinking.
<img src="/images/agent-prd-writer.png" alt="PRD Writer, the Bowerbird">
<h2 id="phase-1-interview">Phase 1: Interview</h2>
The agent reads the project's
CLAUDE.md, the wiki, existing PRDs, and all agent definitions
for context. Then it asks me questions one at a time, covering
five categories: problem clarity, solution validation, success
criteria, constraints, and strategic fit.
One at a time matters. When questions come in batches, the
first two get real answers and the rest get skimmed. One
question, one answer,
then the agent decides what to ask next based on what I said.
It pushes back on contradictions, flags gaps, and won't accept
"make it better" as a success criterion.
The gate is explicit. When it has enough, it says "I have enough
to write a PRD. Proceeding to research." No ambiguity about
when the interview ends.
<h2 id="phase-2-research">Phase 2: Research</h2>
The agent delegates to a researcher subagent to gather facts on
the problem space. It also reads the wiki, codebase, and prior
PRDs to find existing patterns or infrastructure that could be
reused. The point is to ground the PRD in what actually exists,
not what the agent imagines.
<h2 id="phase-3-write">Phase 3: Write</h2>
It writes the PRD to the wiki using a standard <a href="/wiki/prds/template.html">template</a>. The
template has the sections that all three research reports agreed
on: problem, goal, success metrics, non-goals, user stories with
acceptance criteria, scope, open questions, and risks.
<ul>
<li>Non-goals come before scope. <a href="https://kevinyien.com/">Kevin Yien</a>'s
<a href="https://docs.google.com/document/d/1mEMDcHmtQ6twzNlpvF-9maNlAcezpWDtCnyIqWkODZs/edit">"perimeter of the solution space"</a> pattern. Draw
the boundary first, then fill it in. This
matters more for a solo dev than a team because there's no
one else to say "that's out of scope."</li>
<li>Acceptance criteria live on each user story, not in a
separate section. Keeps them co-located with the context
that makes them meaningful. 3-5 per story, not 20. Addy
Osmani's <a href="https://addyosmani.com/blog/good-spec/">guide on specs for AI agents</a>
describes the failure mode: pile on too many criteria and
agents start ignoring or contradicting them.</li>
</ul>
No implementation details in the PRD. That's the design doc's
job.
<h1 id="using-it">Using it</h1>
Start the agent directly:
<pre><code class="language-bash">claude --agent prd-writer
</code></pre>
Or describe a product idea to vanilla Claude and it'll
auto-delegate based on the agent's description field.
The output is a draft PRD at
<code>apps/blog/blog/markdown/wiki/prds/&#x3C;slug>.md</code>. Review it,
approve it, then hand it off to the Design Doc Writer.
<h1 id="the-design-doc-writer">The Design Doc Writer</h1>
The PRD answers "what and why." The next piece is a Design Doc
Writer agent that answers "how," and produces output a coding
agent can pick up without interpretation.
<pre><code class="language-bash">claude --agent design-doc-writer
</code></pre>
<h2 id="the-gap-between-prds-and-code">The gap between PRDs and code</h2>
A PRD says "the publisher pipeline should run autonomously in
K8s." A coding agent needs to know which files to create, what
interfaces to define, what depends on what, and in what order
to build it all.
Handing a PRD directly to a coding agent doesn't work. Agents
fill gaps with assumptions. The PRD says "use Claude Max
tokens" but doesn't say whether that means OAuth tokens, API
keys, or something else. A coding agent will pick one and keep
going. Three files later you realize it picked wrong.
The design doc takes the PRD's acceptance criteria and
translates them into architecture decisions, file change lists,
and ordered tasks through an interview, research, and
structured writing process.
<h2 id="five-phases">Five phases</h2>
The Design Doc Writer runs five gated phases:
<pre class="mermaid">
graph LR
 A["Phase 0 Discover PRD"] --> B["Phase 1 Interview"]
 B --> C["Phase 2 Research"]
 C --> D["Phase 3 Write"]
 D --> E["Phase 4 Validate"]
</pre>
Phase 0: Discover PRD. The agent finds and loads the target
PRD. If you don't specify one, it lists available PRDs from the
wiki and asks which one. It warns if the PRD's status is still
<code>draft</code> instead of <code>approved</code>.
Phase 1: Interview. Same pattern as the PRD Writer, one
question at a time, but focused on architecture instead of
product clarity. Five categories: architecture constraints,
component boundaries, data model and flow, integration points,
and operational concerns. Cap is 12 questions. Gaps go into
the Open Questions section.
Phase 2: Research. Delegates to a researcher subagent for
external context. Also reads the codebase, wiki, and prior
design docs for existing patterns to reuse.
Phase 3: Write. Writes the design doc to the wiki using a
structured template.
Phase 4: Validate. A separate subagent reads both the
design doc and the source PRD, checking that every acceptance
criterion maps to a task, no circular dependencies exist, and
no implementation code leaked in. Fixes issues before
finishing.
<h2 id="the-template">The template</h2>
The template has the sections all three Deep Research reports
agreed on as the minimum viable structure: context,
goals/non-goals, proposed design, alternatives considered, and
open questions. Two sections are specific to agent consumption.
File Change List. An explicit table of every file to
create, modify, or delete:
<pre><code class="language-markdown">| Action | File | Rationale |
|--------|------|-----------|
| CREATE | `path/to/new-file.ts` | Reason |
| MODIFY | `path/to/existing.ts` | Reason |
| DELETE | `path/to/old-file.ts` | Reason |
</code></pre>
Two of the three research reports I ran
(<a href="/wiki/research/design-docs-for-agents.html">notes</a>) found
that file-level change lists improve agent implementation
quality. Both
<a href="https://githubnext.com/projects/copilot-workspace">Copilot Workspace</a>
and
<a href="https://cursor.com/blog/plan-mode">Cursor's Plan Mode</a>
implement this pattern. The third report (Gemini) noted a
dissenting view: some practitioners argue file-level lists
make docs brittle when frameworks change. The template
includes them because for a solo dev with a known codebase,
brittleness matters less than precision.
Task Breakdown. Tasks are dependency-ordered, each with a
consistent structure:
<pre><code class="language-markdown">### TASK-001: Create OAuth token manager

- **Requirement:** PRD Story 2, AC 1 (authenticate against
 Max subscription)
- **Files:** `src/auth/token-manager.ts`,
 `src/auth/token-manager.test.ts`
- **Dependencies:** None
- **Acceptance criteria:**
 - [ ] Token manager reads CLAUDE_CODE_OAUTH_TOKEN from env
 - [ ] Validates token format before use
 - [ ] Returns clear error on invalid/expired token

### TASK-002: Add network policy for publisher pod [P]

- **Requirement:** PRD Story 4, AC 2 (restrict network egress)
- **Files:** `k8s/publisher-netpol.yaml`
- **Dependencies:** TASK-001
- **Acceptance criteria:**
 - [ ] Allows egress only to api.anthropic.com,
 github.com, registry.npmjs.org
 - [ ] Denies all other egress
 - [ ] Policy applies only to publisher pods
</code></pre>
Each task traces back to a PRD requirement. Files are listed
explicitly. Dependencies are declared so tasks can be executed
in order. The <code>[P]</code> marker means a task can run in parallel
with others at the same dependency level.
The acceptance criteria are checkboxes, not prose. A coding
agent (or a human) can verify each one independently.
<h2 id="why-this-structure-matters">Why this structure matters</h2>
Three findings from the
<a href="/wiki/research/design-docs-for-agents.html">research synthesis</a>
informed the template design.
Agents re-propose rejected approaches.
<a href="https://www.mahdiyusuf.com/why-your-coding-agent-keeps-undoing-your-architecture/">Mahdi Yusuf</a>
calls this the "amnesiac agent" problem: an agent consolidated
three microservices into one because the separation "added
unnecessary complexity," but the separation existed because
the services scaled differently under load. The Alternatives
Considered section addresses this directly.
Self-orchestrating agents fail on larger codebases.
<a href="https://medium.com/quantumblack/agentic-workflows-for-software-development-dc8e64f4a79d">McKinsey's QuantumBlack team</a>
published a two-layer architecture separating deterministic
orchestration from agent execution. Letting agents decide
their own sequencing led to "skipped steps, circular
dependencies, or analysis loops." The Task Breakdown's
explicit dependency ordering is the design doc's version of
that deterministic layer.
Task granularity has a sweet spot.
<a href="https://arxiv.org/pdf/2509.16941">SWE-bench Pro</a> measures
this: models scoring 70%+ on SWE-bench Verified dropped to
roughly 23% on Pro's more complex multi-file edits. The
template targets tasks that are each a single coherent
change, testable in isolation.
<a href="https://boristane.com/blog/how-i-use-claude-code/">Boris Tane</a>
puts it well: "I want implementation to be boring. The
creative work happened in the annotation cycles."
<h1 id="prd-to-design-doc-to-code">PRD to design doc to code</h1>
The PRD Writer and Design Doc Writer form two stages of a
three-stage pipeline:
<pre class="mermaid">
graph LR
 A["PRD Writer What & Why"] --> B["Design Doc Writer How"]
 B --> C["Claude Code Plan Mode Implementation"]
</pre>
<ol>
<li>PRD Writer interviews you, researches the problem
space, and writes a scoped PRD with acceptance criteria.</li>
<li>Design Doc Writer takes that PRD, interviews you on
architecture, researches technical approaches, and writes
a design doc with ordered tasks.</li>
<li>Claude Code reads the design doc's Task Breakdown and
executes each task in order, checking off acceptance
criteria as it goes.</li>
</ol>
The third stage isn't automated yet. Today you'd copy the
Task Breakdown into a Claude Code session or reference the
design doc file in your prompt.
Invoking either agent:
<pre><code class="language-bash">claude --agent prd-writer
claude --agent design-doc-writer
</code></pre>
Or describe what you want and Claude will auto-delegate based
on the agent's description field.
<h1 id="what-happened-when-the-design-doc-hit-reality">What happened when the design doc hit reality</h1>
The task breakdown held up for the known work. TASK-001 through
TASK-008 executed mostly as written. Dependency ordering meant
clear starting points: validate OAuth first, build the image
second, wire up the controller third. Each task had explicit
acceptance criteria with checkboxes. An agent could pick up
TASK-003 without reading the whole doc because its inputs,
outputs, and dependencies were declared.
For these eight tasks, implementation was boring. That's the
point.
TASK-009, the deployment and end-to-end test, broke the plan.
Ten issues surfaced that the design doc couldn't have predicted:
<ul>
<li>UID 1001 in the new runtime image vs UID 1000 on the workspace</li>
<li>Helm's field manager fighting kubectl patch over secret ownership</li>
<li>The QA subagent starting <code>next dev</code> in a pod with 1.5GB
available, hanging until OOMKill after 37 minutes</li>
<li>An import of <code>RemarkMermaid.js</code> that worked on macOS
(case-insensitive) and failed on Linux (case-sensitive)</li>
</ul>
These were integration bugs. The design doc told you what to
build, not what would go wrong when you plugged it all together.
The design doc became a living document during deployment. An
"Implementation Additions" section appeared, documenting changes
that weren't in the original plan.
Per-branch PVCs replaced the shared workspace after stale state
leaked between runs. GitHub App auth replaced the placeholder
PAT. The google-news MCP server got dropped because the
journalist agent worked fine with WebSearch. The design doc
stopped being a static spec and started being a changelog of
decisions made under pressure.
The three-stage pipeline didn't need a fourth stage. Child
documents under the design doc captured per-task completion
notes and a deploy runbook. When the OOMKill bug hit, the
TASK-001 completion note already had the memory limits I'd
tested, so the fix was a one-line edit instead of a fresh
investigation. The design doc earned its keep during
deployment, not before it.

Kyle Pericak

"It works in my environment"

Categories

Tags