<p>This is the fourth rebuild of this blog.
This entire site exists as much for me to have something I
care about to work on as it does to actually do <em>blog stuff</em>.</p>
<p>The history of this site is kind of neat:</p>
<ol>
<li>v1: Started out as a pure <a href="/github-pages.html">github pages</a> theme and some markdown</li>
<li>v2: Rewrote into a <a href="/writing-pelican-content.html">pelican theme</a> I forked from someone and slightly modified</li>
<li>v3: Replaced Pelican and its theme with React, MUI and NextJs</li>
<li>v4: Basically v3 with a new custom front-end</li>
</ol>
<p>The v3 React rewrite used MUI purely because work used it too and I'd been just
slinging my own css and using bootstrap.js in Angular before that. I'd read
the developer docs and coded it by hand. It took a while, but it was pretty fun.
In the v3 design I had no opinions around design system use. I still didn't really need
one in v4 but decided to build it out anyways, again, for fun.</p>
<p>I spent most of my time in this rebuild selecting the libraries, tools, frameworks,
that sort of thing. I didn't care to actually learn the framework code: That feels low-leverage these days.
I can honestly say that for better or worse, I didn't write a single line of the code.
I did read some of the code, but mostly just to learn the frameworks better.</p>
<h1 id="the-new-blog-front-end-architecture">The new blog front-end architecture</h1>
<p>My goals were pretty straightforward:</p>
<ol>
<li>Learn something new</li>
<li>Make sure it works AI-first, human way out of the loop</li>
<li>Looks good and makes me happy</li>
</ol>
<p>The tools I landed on for this are kind of interesting.</p>
<h2 id="server-side-rendering-nextjs-15">Server-Side Rendering: Next.js 15</h2>
<p>I don't pay for a server to host this site. There's no dynamic content. Every time I
add a new post to it, I re-render the whole thing from markdown as static files and upload them to a
<a href="/google-cloud-storage-website.html">google storage bucket</a>. The site content is served just as a bunch of static assets from there.</p>
<p>It's dirt cheap and how it always worked. I didn't materially change this,
I'm just calling it out because I think it's really cool. While blost costs me like
$2/month.</p>
<h2 id="styling-tailwind-v4">Styling: Tailwind v4</h2>
<p>Tailwind has become the leader in CSS frameworks, <a href="https://2025.stateofcss.com/en-US/other-tools/">overtaking bootstrap</a>.
AI works great with popular tools and when I researched how to make a modern best-in-class
design system, it felt like a good fit.</p>
<p>Given how small the blog app realistically is, I'm able to get the design tokens
into a single <code>tokens.css</code> file. Pretty manageable.</p>
<p>The <a href="https://tailwindcss.com/docs/theme">Tailwind themes</a> feature also seemed worth using.
All the new sites seem to support dark mode, presumably for a11y, so I wanted that too.</p>
<h2 id="component-structure-shadcn-style-on-radix-primitives">Component structure: shadcn-style on Radix primitives</h2>
<p>I really like how modern web dev chunks things into components, but everyone rips on MUI
as being too same-y. I wanted something more modern, and something that might usually
have more ownership overhead but that AI mitigates.</p>
<p>AI can sling out component code on its own, so I really just want to be consistent.
Went with shadcn-style on Radix primitives for the components. They both seem to have good adoption
and when I reviewed how the style things it sat well with me.</p>
<ul>
<li><a href="https://ui.shadcn.com">shadcn</a>: components ship as source copied into the repo,
owned and edited directly, following a consistent convention for variants, class-merging, and config.</li>
<li><a href="https://www.radix-ui.com/primitives">Radix</a>: primitives that supply the interaction
and a11y, focus management, keyboard navigation, ARIA roles, that kind of thing.</li>
</ul>
<h2 id="workshop-storybook-10">Workshop: Storybook 10</h2>
<p>Every component builds and renders in isolation, off the live site. The agent
can stand one up and check it without touching a page.</p>
<p><img src="/images/storybook-foundations.webp" alt="The Storybook design-system view: the component tree in the sidebar, and the Terminal token palette and type scale rendered on the dark canvas."></p>
<p>The whole workshop ships with the site now. Poke around it at <a href="/storybook/">/storybook/</a>.</p>
<h2 id="content-markdown-to-static-html">Content: markdown to static HTML</h2>
<p>Posts stay plain markdown files in git with front-matter metadata,
rendered with Prism for code and <a href="/mermaid-markdown-support.html">Mermaid</a> for
diagrams. No change here, I just think it's neat.</p>
<hr>
<h1 id="the-development-flow">The development flow</h1>
<p>After the initial claude conversations and deep research report, I leveraged my
<a href="/ai-native-sdlc-first-try.html">PRD writing and Design Doc writing</a> claude skills to better scope the work. I really
didn't need to do much on my own. It asks clarifying questions then just kind of
<em>goes for it</em>. Works well. I share these in a Marketplace Plugin <a href="https://github.com/kylep/claude-plugins">here</a>.</p>
<p>Once the work is scoped, it ends up being chunked out into tasks that Claude is really
good at <a href="/using-agents-better.html">stepping through and verifying</a> one at a time.</p>
<p>I set up the backpressure mechanisms ahead of time. <a href="/playwright-mcp.html">Playwright MCP</a> is the biggest one,
and I had a solid test suite to get started. I recently read this article <a href="https://www.lucasfcosta.com/blog/backpressure-is-all-you-need">Backpressure is all you need</a>
that illustrates the approach well. You can work with Claude to set this up, don't do
it by hand. It's good at building its own guard-rails.</p>
<p>Next, I clean up my context and get my goal command.</p>
<pre><code class="language-text">Your context is getting full. Write me a /context prompt, less than 2000 chars, that will
clean up our work so far and leave us with what we need to know to execute on the plan.

Also provide a /goal command, less than 4000 chars, that I will paste back after
compaction. The goal should finish with a PR open and PW MCP rendering the changes. You
should have validated everything you can and be ready to ship pending my review.
</code></pre>
<p>That took it all the way from my old site to my new site. Night and day difference.
It took maybe 2 or 3 hours of claude cooking. I just use the auto mode classifier on my
Max plan, Opus 4.8 for this one, and walked away to hang out with my kids.</p>
<p>It wasn't perfect when it was done, but it was way further along than I'd have figured
it'd get. I clicked about, asked for some cosmetic changes, and then really spent the
rest of my time just getting it to teach me about what it did so I wasn't owning code
I didn't understand.</p>
<h2 id="ai-first-design">AI-First Design</h2>
<p>The experience of modifying the design was surreal. Entirely conversational. It built
the components, I talked to it, it changed them. I wanted some spacing, alignment, borders,
whatever - and I got them. This was a bit different from my usual flow in that it wasn't
just changing the code in the page I was poking, but it was operating like it would in a
more production style environment.</p>
<p>I'm pretty confident that this would work nicely with bigger teams and Design staff support.</p>
<hr>
<h1 id="qa-remains-critical">QA remains critical</h1>
<p>I see this all the time at work, too. AI churns out code at lightning pace, but it
still lands on humans for taste and UX. It also misses a lot of unhappy path scenarios.</p>
<p>Once it was done coding, I spent probably the majority of my actual at-laptop interaction
time just going through what it had built and tightening up the experience. Small UI bugs,
janky flows, weird alignment, that kind of thing.</p>
<p>As AI coding continues to evolve, this is an area I'm researching and watching closely:
Code QA processes are definitely changing and so far there's absolutely a big learning
curve.</p>
<p>Given how simple this blog site realistically is, I was surprised how much manual
review it needed.</p>


<p>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.</p>
<h1 id="why-a-prd-agent">Why a PRD agent</h1>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h1 id="the-prd-writer">The PRD Writer</h1>
<p>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.</p>
<p><img src="/images/agent-prd-writer.png" alt="PRD Writer, the Bowerbird"></p>
<h2 id="phase-1-interview">Phase 1: Interview</h2>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h2 id="phase-2-research">Phase 2: Research</h2>
<p>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.</p>
<h2 id="phase-3-write">Phase 3: Write</h2>
<p>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.</p>
<ul>
<li><strong>Non-goals come before scope.</strong> <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><strong>Acceptance criteria live on each user story, not in a
separate section.</strong> 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>
<p>No implementation details in the PRD. That's the design doc's
job.</p>
<h1 id="using-it">Using it</h1>
<p>Start the agent directly:</p>
<pre><code class="language-bash">claude --agent prd-writer
</code></pre>
<p>Or describe a product idea to vanilla Claude and it'll
auto-delegate based on the agent's description field.</p>
<p>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.</p>
<h1 id="the-design-doc-writer">The Design Doc Writer</h1>
<p>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.</p>
<p><img src="/images/agent-design-doc-writer.png" alt="Design Doc Writer, the Nautilus"></p>
<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>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<h2 id="five-phases">Five phases</h2>
<p>The Design Doc Writer runs five gated phases:</p>
<pre class="mermaid">
graph LR
    A["Phase 0<br/>Discover PRD"] --> B["Phase 1<br/>Interview"]
    B --> C["Phase 2<br/>Research"]
    C --> D["Phase 3<br/>Write"]
    D --> E["Phase 4<br/>Validate"]
</pre>
<p><strong>Phase 0: Discover PRD.</strong> 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>.</p>
<p><strong>Phase 1: Interview.</strong> 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.</p>
<p><strong>Phase 2: Research.</strong> Delegates to a researcher subagent for
external context. Also reads the codebase, wiki, and prior
design docs for existing patterns to reuse.</p>
<p><strong>Phase 3: Write.</strong> Writes the design doc to the wiki using a
structured template.</p>
<p><strong>Phase 4: Validate.</strong> 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.</p>
<h2 id="the-template">The template</h2>
<p>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.</p>
<p><strong>File Change List.</strong> An explicit table of every file to
create, modify, or delete:</p>
<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>
<p>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.</p>
<p><strong>Task Breakdown.</strong> Tasks are dependency-ordered, each with a
consistent structure:</p>
<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>
<p>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.</p>
<p>The acceptance criteria are checkboxes, not prose. A coding
agent (or a human) can verify each one independently.</p>
<h2 id="why-this-structure-matters">Why this structure matters</h2>
<p>Three findings from the
<a href="/wiki/research/design-docs-for-agents.html">research synthesis</a>
informed the template design.</p>
<p><strong>Agents re-propose rejected approaches.</strong>
<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.</p>
<p><strong>Self-orchestrating agents fail on larger codebases.</strong>
<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.</p>
<p><strong>Task granularity has a sweet spot.</strong>
<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."</p>
<h1 id="prd-to-design-doc-to-code">PRD to design doc to code</h1>
<p>The PRD Writer and Design Doc Writer form two stages of a
three-stage pipeline:</p>
<pre class="mermaid">
graph LR
    A["PRD Writer<br/><i>What & Why</i>"] --> B["Design Doc Writer<br/><i>How</i>"]
    B --> C["Claude Code Plan Mode<br/><i>Implementation</i>"]
</pre>
<ol>
<li><strong>PRD Writer</strong> interviews you, researches the problem
space, and writes a scoped PRD with acceptance criteria.</li>
<li><strong>Design Doc Writer</strong> takes that PRD, interviews you on
architecture, researches technical approaches, and writes
a design doc with ordered tasks.</li>
<li><strong>Claude Code</strong> reads the design doc's Task Breakdown and
executes each task in order, checking off acceptance
criteria as it goes.</li>
</ol>
<p>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.</p>
<p>Invoking either agent:</p>
<pre><code class="language-bash">claude --agent prd-writer
claude --agent design-doc-writer
</code></pre>
<p>Or describe what you want and Claude will auto-delegate based
on the agent's description field.</p>
<h1 id="what-happened-when-the-design-doc-hit-reality">What happened when the design doc hit reality</h1>
<p>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.</p>
<p>For these eight tasks, implementation was boring. That's the
point.</p>
<p>TASK-009, the deployment and end-to-end test, broke the plan.
Ten issues surfaced that the design doc couldn't have predicted:</p>
<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>
<p>These were integration bugs. The design doc told you what to
build, not what would go wrong when you plugged it all together.</p>
<p>The design doc became a living document during deployment. An
"Implementation Additions" section appeared, documenting changes
that weren't in the original plan.</p>
<p>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.</p>
<p>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.</p>
<p>The next time I used the PRD and design doc pipeline, I pointed it at laptop
security. An autonomous agent ran Lynis, rkhunter, and Ansible for a few days
while I was on vacation. That's in <a href="/secure-my-laptop.html">Ralph Secure My Laptop</a>.</p>


<p>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.</p>
<p>Some key findings:</p>
<ul>
<li><strong>Most multi-agent failures are specification problems</strong>, 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><strong>Teach delegation.</strong> 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><strong>Evaluators need isolated context.</strong> 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><strong>Start wide, then narrow.</strong> 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><strong>Action-oriented descriptions improve auto-delegation.</strong>
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><strong>Agents without browser tools ship half-working features.</strong>
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><strong>Route models by risk, not task complexity.</strong> 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><strong>Deny-by-default permissions.</strong> 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><strong>The harness enforces termination, not the agent.</strong> 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><strong>Write results to files, pass back references.</strong> 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><strong>Research, plan, then implement.</strong> 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><strong>One feature per prompt, commit after each piece.</strong> 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><strong>Agents use ~4x more tokens than chat. Multi-agent uses
~15x.</strong> 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><strong>Start simple, add layers only when measured outcomes
improve.</strong> 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>
<p>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.</p>
<h1 id="2026-03-15s-agent-roster">2026-03-15's Agent Roster</h1>
<p>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.</p>
<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>
<p>Delegation hierarchy (<a href="/mermaid-markdown-support.html">Mermaid flowchart</a>):</p>
<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>
<p>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).</p>
<h2 id="calling-the-agents">Calling the agents</h2>
<p>Three ways to use them:</p>
<p><strong>Vanilla Claude auto-delegates.</strong> 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.</p>
<p><strong>CLAUDE.md tells Claude what's available.</strong> 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.</p>
<p><strong><code>claude --agent publisher</code> for the full pipeline.</strong> 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.</p>
<p>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.</p>


Kyle Pericak

Blog Redesign 4 and an AI-First Design System

AI-Native SDLC: First Try

Applying Research to Claude Agents