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 <a href="/wiki/agent-team/design-doc-writer.html">Design Doc Writer</a>
answers "how," and produces output a coding agent can pick up
without interpretation.
<img src="/images/agent-design-doc-writer.png" alt="Design Doc Writer, the Nautilus">
<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.

I wanted research-backed guidance for my Claude Code agents. I had
Claude read everything Anthropic has published on agent design, then
ran deep research reports from ChatGPT, Gemini, and Claude on the
same topic. Notes are in the wiki
(<a href="/wiki/research/anthropic-guidance.html">Anthropic guidance</a>,
<a href="/wiki/research/coding-agent-best-practices.html">deep research synthesis</a>).
Here's what I applied.
Some key findings:
<ul>
<li>Most multi-agent failures are specification problems, not
infrastructure. Bad task descriptions, ambiguous instructions,
missing termination conditions. Berkeley's
<a href="https://arxiv.org/abs/2503.13657">MAST taxonomy</a> analyzed
150+ tasks across 5 frameworks and found specification and
system design issues were the dominant failure category.</li>
<li>Teach delegation. Give subagents an objective, output
format, tool/source guidance, and task boundaries. Without
all four, agents duplicate work or leave gaps.
(<a href="https://www.anthropic.com/engineering/multi-agent-research-system">Multi-Agent Research System</a>)</li>
<li>Evaluators need isolated context. If the evaluator shares
context with the producer, it becomes "another participant
in collective delusion."
(<a href="https://www.anthropic.com/research/building-effective-agents">Building Effective Agents</a>)</li>
<li>Start wide, then narrow. Agents default to overly specific
queries in unfamiliar territory. Begin with broad queries to
map what exists before drilling in.
(Gemini deep research,
<a href="/wiki/research/coding-agent-best-practices.html">wiki</a>)</li>
<li>Action-oriented descriptions improve auto-delegation.
Trigger phrases like "MUST BE USED when..." in agent
descriptions help Claude decide when to invoke subagents.
(Claude deep research,
<a href="/wiki/research/coding-agent-best-practices.html">wiki</a>)</li>
<li>Agents without browser tools ship half-working features.
Unit tests pass but the rendered page is broken. Playwright
catches what tests miss.
(<a href="https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents">Effective Harnesses</a>)</li>
<li>Route models by risk, not task complexity. Opus for
judgment calls that are hard to verify. Sonnet for mechanical
work that's easy to check. A complex summarization is
low-risk because you can read and discard it. A one-line
security review is high-risk because getting it wrong has
consequences.
(<a href="https://www.anthropic.com/research/building-effective-agents">Building Effective Agents</a>,
all three deep research reports)</li>
<li>Deny-by-default permissions. Start with no tool access
and progressively allowlist. The opposite of what most people
do (give the agent everything, restrict when something goes
wrong).
(<a href="https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents">Context Engineering</a>,
Claude deep research,
<a href="/wiki/research/coding-agent-best-practices.html">wiki</a>)</li>
<li>The harness enforces termination, not the agent. Don't
rely on the agent to know when to stop. Set max iterations,
token budgets, and repetition detection in the system that
runs the agent.
(<a href="https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents">Effective Harnesses</a>,
Claude deep research,
<a href="/wiki/research/coding-agent-best-practices.html">wiki</a>)</li>
<li>Write results to files, pass back references. Subagents
writing full output through the orchestrator bloats its
context window. Subagents should write to files and return
a summary and a path.
(<a href="https://www.anthropic.com/engineering/multi-agent-research-system">Multi-Agent Research System</a>)</li>
<li>Research, plan, then implement. Without explicit
instructions, Claude jumps straight to coding. Say "read X,
then make a plan, then implement." Three phases, stated
explicitly. Claude won't reliably do them on its own.
(<a href="https://code.claude.com/docs/en/best-practices">Claude Code Best Practices</a>)</li>
<li>One feature per prompt, commit after each piece. Agents
try to do everything and exhaust context mid-task. Commits
are rollback points. If the agent breaks something on step
3, you revert to step 2 instead of starting over.
(<a href="https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents">Effective Harnesses</a>)</li>
<li>Agents use ~4x more tokens than chat. Multi-agent uses
~15x. Don't pay that unless the task needs it. Multi-agent
is an economic decision, not an architectural one.
(<a href="https://www.anthropic.com/engineering/multi-agent-research-system">Multi-Agent Research System</a>)</li>
<li>Start simple, add layers only when measured outcomes
improve. The canonical agent loop is ~50 lines. Don't
build the full stack on day one.
(<a href="https://www.anthropic.com/research/building-effective-agents">Building Effective Agents</a>)</li>
</ul>
Security baseline: the
<a href="https://genai.owasp.org/llm-top-10/">OWASP Top 10 for LLM Applications</a>.
All three deep research reports recommended it. I use it as a
checklist for the Security Auditor agent.
<h1 id="2026-03-15s-agent-roster">2026-03-15's Agent Roster</h1>
The agents from the
<a href="/agent-org-chart.html">org-chart post</a> were made off-the-cuff.
16 agents, too ambitious, didn't have the infrastructure to support
them. I deleted most and got down to 7. This time: I had Claude
load the deep research synthesis, I extracted the best practices
that applied, and I updated the agent definitions with specific,
traceable changes.
<table>
<thead>
<tr>
<th>Agent</th>
<th>Model</th>
<th>Role &#x26; Applied Research</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/publisher.md">Publisher</a></td>
<td>Opus</td>
<td>Content pipeline orchestration, writing. <a href="https://www.anthropic.com/engineering/multi-agent-research-system">Delegation specs</a>, trigger phrase.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/analyst.md">Analyst</a></td>
<td>Opus</td>
<td>Research ingestion, system improvements. Trigger phrase.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/synthesizer.md">Synthesizer</a></td>
<td>Opus</td>
<td>Compare/contrast Deep Research reports. No changes needed.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/researcher.md">Researcher</a></td>
<td>Sonnet</td>
<td>Sourced facts, research briefs. <a href="/wiki/research/coding-agent-best-practices.html">Start wide, then narrow</a> search strategy, trigger phrase.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/reviewer.md">Reviewer</a></td>
<td>Opus</td>
<td>Style, substance, sourcing. <a href="https://www.anthropic.com/research/building-effective-agents">Context isolation</a> from producer.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/qa.md">QA</a></td>
<td>Sonnet</td>
<td>Build, render, links via <a href="https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents">Playwright</a>. Trigger phrase.</td>
</tr>
<tr>
<td><a href="https://github.com/kylep/multi/blob/main/.claude/agents/security-auditor.md">Security Auditor</a></td>
<td>Opus</td>
<td><a href="https://genai.owasp.org/llm-top-10/">OWASP LLM Top 10</a>, confidential data. Added LLM05 check.</td>
</tr>
</tbody>
</table>
<pre class="mermaid">
graph TD
 Claude["Vanilla Claude"]
 Publisher["Publisher (Opus)"]
 Analyst["Analyst (Opus)"]
 Synthesizer["Synthesizer (Opus)"]
 Researcher["Researcher (Sonnet)"]
 Reviewer["Reviewer (Opus)"]
 QA["QA (Sonnet)"]
 Security["Security Auditor (Opus)"]

 Claude --> Publisher
 Claude --> Analyst
 Claude --> Synthesizer
 Claude --> Researcher
 Claude --> Reviewer
 Claude --> QA
 Claude --> Security
 Publisher --> Researcher
 Publisher --> Reviewer
 Publisher --> QA
 Publisher --> Security
</pre>
Three report directly to me (Publisher, Analyst, Synthesizer).
Four are subagents under Publisher. Model routing follows the
research: Opus for judgment calls (review, security, editorial,
synthesis), Sonnet for mechanical work (research, QA).
<h2 id="calling-the-agents">Calling the agents</h2>
Three ways to use them:
Vanilla Claude auto-delegates. Each agent definition has a
<code>description</code> field that Claude reads when deciding whether to
spawn a subagent. The trigger phrases ("MUST BE USED when
writing blog posts", "MUST BE USED when gathering facts") tell
Claude when to invoke each one. If I ask vanilla Claude to
write a blog post, it sees the Publisher's description and
delegates. It can also run multiple subagents in parallel
when the tasks are independent.
CLAUDE.md tells Claude what's available. The project's
<code>CLAUDE.md</code> includes a section listing all 7 agents with their
roles and invocation commands. This gives vanilla Claude the
full picture of what agents exist without having to discover
them from the file system.
<code>claude --agent publisher</code> for the full pipeline. This
starts Claude with the Publisher's system prompt as the main
thread. Publisher then orchestrates the entire content
pipeline: research, substance gate, write, review, QA,
security audit. It spawns each subagent natively using Claude
Code's Agent tool, not CLI calls. Independent stages (QA and
security audit) run in parallel. This is the heavy path for
writing a full post from scratch.
Claude Code enforces a single-level subagent hierarchy.
Publisher can spawn subagents, but those subagents can't
spawn their own. If Reviewer needs research, it doesn't call
Researcher. It reports back to Publisher, which decides
what to do next.

Kyle Pericak

"It works in my environment"

Categories

Tags