HTML Over Markdown, Throwaway UIs, and the Compute Allocator Mindset: What Anthropic Engineers Know That You Don't

Two sources today. One from inside Anthropic's Claude Code team (Thariq Shihipar, via Lenny's newsletter), one from a practitioner running a full AI marketing stack with multi-agent toolchains (Riley Brown's Codex breakdown). On the surface, different domains. But read them together and a coherent picture emerges: the bottleneck in agent workflows is no longer capability — it's legibility and orchestration. The agents can do the work. The question is whether you can stay in sync with them and direct compute toward the right problems.

Here's what both sources reveal, and how to apply it to your Claude Code workflow starting tomorrow.

Section 1: HTML Is the New Spec Format — And This Isn't a Small Thing

This is Shihipar's central thesis, and it deserves careful unpacking because it changes how you should be writing specs, plans, and briefs for Claude Code.

The original reason Markdown won was simple: it's human-readable and machine-parseable. A PM can write it, an engineer can read it, and an LLM can ingest it without friction. That tradeoff made sense when context windows were small and plans were short.

That tradeoff no longer applies.

Per Shihipar, plans have grown to thousands of lines. At that scale, Markdown fails on the human side — nobody actually reads a 2,000-line .md file. You skim it, you scroll past it, you eventually ask Claude to just edit it directly. And when you stop reading your own plan, you stop being in the loop.

HTML restores the feedback loop. The same plan, rendered as HTML, becomes:

Scrollable with sticky headers
Filterable and interactive
Visually scannable with color, spacing, hierarchy
Embeddable with mockups, code excerpts, and diagrams inline

"Create an HTML file with a plan. Help me visualize. Include excerpts, mockups, code, whatever is needed to give me maximum context."
— Thariq Shihipar's actual planning prompt

Notice what's not in that prompt: elaborate instructions, formatting rules, section templates. The key phrase is "whatever is needed" — it grants Claude creative latitude to solve the legibility problem rather than constraining it into a format that's familiar but suboptimal.

Why this works mechanically: Claude's training has heavy exposure to HTML with visual intent. When you give it latitude to use HTML, it can choose information density strategies that Markdown simply can't express — collapsible sections, status badges, visual mockups embedded directly. You get a richer artifact from the same underlying information.

The Practical Switch: How to Start

Replace this pattern:

claude "Create a markdown plan for implementing X feature"

With this:

claude "Create an HTML file with a comprehensive plan for implementing X feature. 
Include visual mockups, architecture diagrams, file structure, key decision points, 
and whatever else gives me maximum context. Make it interactive and scannable."

Then open the file in a browser. Read it like a document, not a terminal output.

Gotcha: If you're working in Claude Code's terminal context, you'll need to explicitly instruct it to write to a .html file and open it. Claude won't automatically render HTML in the terminal. Build the habit of: claude [prompt] → write to plan.html → open in browser.

Section 2: The Compute Allocator Mindset

This is the reframe that matters most for where you are in your Claude Code journey.

Shihipar's framing: when Claude can run for eight hours on a single task, you are no longer a code author — you are a compute allocator. You're deciding how to spend $500 of inference. The critical skill shifts from implementation to:

Decision quality on what to build — Is this the right problem?
Spec fidelity — Does the plan encode enough context to produce the right output without constant correction?
Sync checkpoints — Are you staying in the loop or flying blind?

graph TD A[Task Identified] --> B{Worth building?} B -- No --> C[Kill it, reallocate] B -- Yes --> D[Write HTML Spec] D --> E[Review & critique spec interactively] E --> F{Spec faithful to intent?} F -- No --> D F -- Yes --> G[Launch Claude Code agent] G --> H[Checkpoint: sync on output] H --> I{Diverged from spec?} I -- Yes --> J[Correct + relaunch] I -- No --> K[Ship]

The planning phase is now the highest-leverage work you do. Not reviewing PRs. Not debugging. Planning. Because a bad spec at the top produces eight hours of wrong work at the bottom.

Per Shihipar: only about 1% of the tokens he generates go into production code. The other 99% go into dashboards, custom UIs, status reports, planning artifacts, and tooling for understanding what he wants to build. This isn't waste — it's the cost of staying in sync with agents doing the actual work.

For your workflow: treat every major Claude Code task as a two-phase operation:

Phase 1 (spec): Generate an HTML plan. Read it. Critique it. Use Claude to edit it until it accurately represents your intent. Budget 20-30% of your total time here.
Phase 2 (execution): Launch the agent against the spec. Set explicit checkpoints.

Section 3: Throwaway UIs for Editing Complex Plans

This is the technique that sounds like overkill until you use it once.

Shihipar's pattern: take a specific section of a complex plan — say, a data visualization rules table — and ask Claude to build a custom editing UI just for that section. Not a general-purpose editor. A purpose-built interface for this exact data, with exactly the controls you need.

The actual prompt pattern:

Here is [section of HTML plan]. 
Build me an ideal interface for editing just this section. 
Make it beautiful and optimized for this specific use case.

The result is what he calls "micro software on top of micro software" — disposable tooling that makes engaging with a specific piece of content genuinely enjoyable, then gets discarded when you're done.

Why this works: The cost of building a throwaway UI is now near zero. Ten minutes of Claude time. The benefit is that you actually engage with the content instead of avoiding it. Engagement = better decisions = better final output.

flowchart LR A[Complex HTML Plan] --> B[Identify painful-to-edit section] B --> C[Ask Claude: build ideal UI for this section] C --> D[Edit in custom UI] D --> E[Export edited content back to plan] E --> F[Discard UI] F --> G[Launch agent against updated plan]

Failure mode to avoid: Don't ask for a general-purpose plan editor. Be specific about the section and the exact interactions you need. The more constrained the request, the better the output.

Section 4: Living HTML Design Systems as Agent Context

Shihipar's second major pattern: instead of pointing Claude at Figma or a GitHub repo for design context, maintain a single HTML file that encodes your entire design system.

What goes in it:

Color palette with hex values
Typography scale
Spacing system
Component examples (buttons, cards, forms, states)
Animation conventions
Do/Don't examples

Why HTML instead of Figma link: A Figma link requires Claude to have API access and still doesn't give it the semantic understanding of why design decisions were made. An HTML file is directly ingestible, human-readable, and can include annotations and rationale alongside the visual output.

Practical workflow:

claude "Analyze the codebase in ./src and extract the design system. 
Encode it as a single self-contained HTML file with: 
color palette, typography, spacing, key components with code examples. 
Include annotations explaining the design intent for each element."

Then save this as design-system.html and include it as context in every future UI-related task:

claude --context design-system.html "Build the dashboard layout for..."

This is portable across projects. One file, passed as context, gives any Claude Code session the full visual and semantic understanding of your design language.

Section 5: Riley Brown's Multi-Agent Stack — What Transfers to Claude Code

Build Your Full AI Marketing Team (Agents + Skills)

Riley Brown's Codex breakdown covers a different surface area — marketing agents, not software engineering — but the orchestration patterns are directly applicable.

The key architectural insight from Brown's stack: each agent has a specific, bounded skill, and skills are composable. His seven skills:

YouTube Researcher (grounding) — external data ingestion
Readwise CLI — knowledge base access
Excalidraw Diagrams — visual output generation
Paper — long-form document creation
Remotion & Hyperframes — video/animation generation
Gen Media — image/media generation
Email Manager — outbound communication

Notice the architecture: each skill is a tool that a sub-agent can call. The orchestrator doesn't do any of the domain work itself — it routes to the right skill, passes context, and aggregates outputs.

What this tells you about Claude Code agent design:

The same logic applies to software engineering workflows. Your orchestrator agent shouldn't be trying to write code AND run tests AND deploy AND write docs. Each of those should be a bounded sub-agent with a specific skill. The orchestrator allocates work.

graph TD O[Orchestrator Agent] --> A[Sub-agent: Spec Writer] O --> B[Sub-agent: Code Generator] O --> C[Sub-agent: Test Writer] O --> D[Sub-agent: Docs Generator] O --> E[Sub-agent: Code Reviewer] A --> F[HTML Spec] B --> G[Implementation] C --> H[Test Suite] D --> I[README / Docs] E --> J[Review Report] F --> O G --> O H --> O I --> O J --> O

Brown's use of sub-agents (timestamp 19:29): He explicitly invokes sub-agents for tasks that require different context or capabilities than the main orchestrator. This isn't spawning parallel threads for speed — it's isolating context so each agent can focus without being polluted by irrelevant prior context.

The Claude Code equivalent:

claude "You are an orchestrator. Your job is to:
1. Read the spec at plan.html
2. Spawn a sub-agent to implement each module listed in the spec
3. Each sub-agent should work in an isolated context with only the relevant section of the spec
4. Aggregate results and report status

Do not write any code yourself. Coordinate only."

This enforces the compute allocator pattern at the agent level — the orchestrator stays strategic, sub-agents stay tactical.

Section 6: Where They Agree and Where They Diverge

Consensus:

Both sources converge on bounded, specialized agents over monolithic generalists. Shihipar's micro-apps for specific editing tasks and Brown's bounded skills are the same pattern at different scales. Specialization produces better output and stays manageable.

Both also converge on legibility as a first-class concern. Shihipar's HTML artifacts and Brown's Excalidraw/visual outputs both reflect the same principle: if you can't read and engage with what the agent produced, you can't direct it effectively. Visual output isn't a nice-to-have — it's infrastructure for human oversight.

Divergence:

The sources diverge on documentation philosophy. Shihipar advocates for just-in-time documentation in whatever format is most engaging — HTML status updates to his manager, throwaway UIs for editing, nothing standardized. Brown's stack implies more durational tooling — Readwise integration for knowledge management, Paper for long-form output — suggesting a more persistent documentation layer.

Which is right for you: Given your Formalist personality and preference for structure, Brown's durational approach probably deserves a place in your stack for reference documentation (design systems, architecture decisions, onboarding). Shihipar's just-in-time approach wins for process documentation (plans, specs, status updates). Use both, in their correct contexts.

Section 7: The Test Verification Reframe

Shihipar flags this briefly but it's important enough to unpack: test verification ≠ testing.

Traditional unit tests check that code does what the code says it does. In an agent workflow, the real question is whether the agent's understanding of the task matches the intended outcome. These are different problems.

His emerging patterns for verification:

Verification rubrics — explicit checklists that Claude checks its own output against
Managed agents checking outcomes — a separate agent reviews the output of the primary agent
Claude recording videos of what it did — visual verification of UI behavior

The practical implication for your Claude Code workflows:

Don't just ask Claude to "write tests." Ask it to also produce a verification rubric — a structured list of acceptance criteria that it (or a separate reviewing agent) can check the output against.

Prompt pattern:

claude "After implementing this feature:
1. Write unit tests for the implementation
2. Write a verification rubric: a checklist of 10-15 acceptance criteria that 
   capture the INTENT of this feature, not just the mechanics
3. Run through the rubric yourself and report which criteria pass/fail"

This is a different quality signal than green CI. A test can pass while the feature is wrong. A rubric checks intent.

Section 8: Practical Implementation Checklist

Based on today's sources, here's what you should have running by end of week:

HTML Spec Protocol (implement immediately)

[ ] Create a prompt template for HTML plan generation (use Shihipar's base prompt, extend for your domain)
[ ] Add to your Claude Code alias/shortcut: --output plan.html && open plan.html
[ ] Next task: generate spec as HTML before writing any code

Living Design System (this week)

[ ] Run design system extraction prompt against your primary codebase
[ ] Save as design-system.html in a shared location
[ ] Add to .claude context config for all UI-related tasks

Throwaway UI Pattern (first complex plan)

[ ] When you hit a section of a plan that's hard to edit (table, nested config, rule set), stop
[ ] Ask Claude to build a custom editing UI for just that section
[ ] Use it, export results, discard it

Orchestrator Architecture (next multi-step task)

[ ] Define your task's natural sub-domains (e.g., spec → implement → test → docs)
[ ] Write an orchestrator prompt that explicitly does NOT do domain work itself
[ ] Define sub-agent prompts for each domain with bounded context

Verification Rubric (add to all existing workflows)

[ ] Add rubric generation to your standard task completion prompt
[ ] Start collecting rubrics — they become training data for your own mental model of what "done" looks like

Section 9: The Prompts — Concrete and Ready to Use

HTML Project Plan:

Create a comprehensive HTML plan for [task]. The file should be self-contained, 
render in a browser without dependencies, and include: project overview, 
architecture decisions with rationale, file structure, key milestones with 
status indicators, open questions, and visual mockups where relevant. 
Use whatever formatting, interactivity, and visual elements give me 
maximum context. Make it genuinely enjoyable to read.

Design System Extraction:

Analyze the codebase. Extract the implicit design system. Encode it as a 
single self-contained HTML file with: color palette (with hex values and usage 
context), typography scale, spacing system, key UI components with working 
examples, and annotations explaining the intent behind each decision. 
The file should serve as a portable context file I can pass to future Claude sessions.

Throwaway Section Editor:

Here is this section of my plan: [paste section]. 
Build me a purpose-built HTML interface for editing exactly this content. 
Optimize for the specific interactions I'll need — don't build a general editor. 
Make it visually clear and genuinely pleasant to use. 
Include an export function that outputs the edited content in the same format 
as the input so I can paste it back into the main plan.

Orchestrator Agent:

You are an orchestrator. Your role is coordination only — you do not implement anything yourself.

Your task: [task description]
Spec: [link or paste HTML plan]

Steps:
1. Read the spec and identify discrete work units
2. For each work unit, spawn a sub-agent with: the relevant spec section, 
   clear acceptance criteria, and no irrelevant context
3. Collect outputs and verify against the verification rubric
4. Report status with a summary of what passed, what failed, and what needs human review

Begin with a plan of the work units you've identified and ask for approval before spawning sub-agents.

Verification Rubric Generator:

After completing [task], generate a verification rubric: 
10-15 acceptance criteria that capture the INTENT of this feature 
(not just mechanical correctness). 
Format as a checklist. 
Then run through the rubric and report pass/fail with specific evidence for each item.

Today's One Action

Convert your next task's spec from Markdown to HTML. Before writing a single line of code on your next Claude Code task, run the HTML Project Plan prompt above. Open it in a browser. Read the whole thing. Find one section that's hard to engage with, and ask Claude to build a throwaway editing UI for it.

This single workflow change — HTML spec + interactive editing — is the highest-leverage thing Shihipar's entire talk distills down to, and it takes 20 minutes to implement. Every future improvement (compute allocation, orchestration, verification rubrics) depends on you actually reading and staying in sync with what your agents are building. HTML is what makes that possible.