The Unreasonable Effectiveness of Mini-App Specs

The Unreasonable Effectiveness of Mini-App Specs

HTML is the new Markdown. But mini apps are the new HTML.

The agent workflow today is simple: write a Markdown spec, ask an agent to build it, then manually inspect whether the result matches the original intent. Thariq from Anthropic made the point well: HTML improves information density and ease of reading. The deeper problem is reconciliation.

A mini-app spec is a small browser-native artifact that combines prose, structured data, prototype behavior, annotations, and checks.

The best spec format keeps intent closest to implementation. Markdown won because humans can read it, not because it is the strongest contract for agents. It is clean, portable, easy to edit, and efficient. Markdown is easier for future humans and agents to co-edit, diff, and reuse. But its structure is mostly implied: requirements, constraints, and edge cases collapse into prose and bullets.

The spec’s highest job is to preserve what you meant while the implementation changes underneath it.

That is why so many people prefer a fast prototype to a document. A prototype carries behavior that prose loses. But prototypes and specs usually live apart. The prototype shows what it feels like; the spec says what it means.

Mini-app specs collapse that split. The written intent and the prototype live in the same artifact. States, transitions, copy, layout, edge cases, and constraints become part of the contract instead of a separate reference that drifts.

Browser-native specs are more addressable than Markdown specs. Markdown gives you line numbers, headings, anchors, and links, but most references still point at text ranges. HTML and mini apps let the user reference a rendered subtree. Codex, Claude Code’s in-app browser, and Claude Design already support this pattern: comments on pages that give the agent precise instructions against a rendered target.

Mini apps add more structure. A requirement can link to a prototype state. A prototype state can link to a reconciliation check. A check can link back to implementation evidence. The agent is no longer reconciling loose prose against code; it is reconciling structured intent against code.

Mini-app specs can run reconciliation tests that normal tests miss. Traditional tests ask whether the implementation works. Reconciliation tests ask whether the implementation still matches the spec.

I’ve already used this for:

• Template reconciliation. Write templates as props to a React component so they cannot drift from the agreed-upon format. No missing sections, no fallbacks. Updates propagate to downstream consumers.

• File tree reconciliation. Do the packages and files in the spec exist? Are there extra ones?

• Test reconciliation. Mini-app specs do not replace unit tests or integration tests. They answer the meta question: do the tests in the spec exist, are they passing, and can you run them on demand?

• Configuration and secret reconciliation. Specs often include the configuration keys that apps need, though not their values. For example, Service A needs an OPENAI_API_KEY. The spec can report whether that secret exists and is bound to the right place.

The workflow becomes tighter.

• Markdown loop: write spec, build implementation, manually compare.

• HTML loop: write richer spec, build implementation, manually compare with better visuals.

• Mini-app loop: model intent, embed prototype, build implementation, run reconciliation checks.

Publishing workflows like “Claude Code to HTML to shareable URL” make HTML easy to distribute. The next step is making the artifact executable enough to participate in the build loop. Annotation closes another part of the loop: the human can point at a precise rendered subtree, attach feedback, and hand the agent structured context instead of prose directions.

Mini apps are not a silver bullet. Mini-app specs are overkill for notes, summaries, simple plans, and early sketches. HTML and React can be noisy if they become the only source of truth. I often embed OpenAPI YAML specs inside the apps so the spec and the code share the same source of truth.

Mini apps also require a runtime, where Markdown and self-contained HTML still win. But the runtime objection is weaker for agents than for humans: point an agent at the compiled browser output, and it can usually recover a minimal semantic summary from the rendered HTML.

That conversion is mostly one-way. HTML or a mini app can be reduced to Markdown, but Markdown cannot be expanded back into the richer structure, behavior, state, and affordances that were never captured.

So not every spec should become a mini app. But once the work has state, interaction, prototypes, edge cases, and verification needs, the spec should behave more like software.