HTML 不可思议的有效性：用独立文件替代 Markdown 的实践

The unreasonable effectiveness of HTML — examples

Companion to the blog post Twenty self-contained .html files an agent produced instead of a wall of markdown. Each one trades a document you'd skim for one you'd actually read — open any of them directly in a browser. Grouped by the kind of work they replace. Exploration & Planning 3 Code Review 3 Design 2 Prototyping 2 Diagrams 2 Decks 1 Research 2 Reports 2 Custom Editors 3

01Exploration & Planning3 demos When you're not sure what you want yet. Ask the agent to fan out across several directions and lay them next to each other so you can point at one — instead of reading three sequential walls of text and trying to hold them all in your head. And once you've picked, turn the pick into a plan the implementer can actually read.

02Code Review & Understanding3 demos Diffs and call-graphs are spatial information; markdown flattens them. Let the agent render the change as an annotated diff, draw the module as boxes and arrows, or write the PR description your reviewers actually want — so the shape of the code is visible at a glance.

03Design2 demos HTML is the medium your design system ships in, so it's the natural format for talking about it. Tokens become swatches, components become contact sheets, and the artifact can be fed straight back into the next prompt.

04Prototyping2 demos Motion and interaction can't be described, only felt. A throwaway page with the real easing curve or the real click-through tells you in five seconds what a paragraph of prose never could.

05Illustrations & Diagrams2 demos Inline SVG gives the agent a real pen. Ask for the figures for a post or a flowchart of a process and get vector art you can tweak by hand or paste straight into the final document.

06Decks1 demo A handful of <section> tags and twenty lines of JS is a slide deck. Point the agent at a Slack thread or a design doc and get something you can arrow-key through in a meeting — no Keynote, no export step.

07Research & Learning2 demos An explainer with collapsible sections, tabbed code samples and a glossary in the margin reads very differently from the same words dumped linearly. The agent can build the scaffolding that makes a new topic navigable.

08Reports2 demos Recurring documents — status updates, post-mortems — benefit most from a bit of structure and color. A small chart and a colored timeline turn something people skim into something they actually read.

09Custom Editing Interfaces3 demos Sometimes it's hard to describe what you want in a text box. Ask for a throwaway editor for the exact thing you're working on — and always end with an export button that turns whatever you did in the UI back into something you can paste into the agent or commit. You stay in the loop; the loop gets tighter.