Using Claude Code: The Unreasonable Effectiveness of HTML

À retenir

1. Auteur. Thariq Shihipar — Engineer & serial entrepreneur, équipe Claude Code chez Anthropic. X : @trq212. Site : thariqs.github.io/html-effectiveness (gallery d'exemples HTML générés par Claude Code, organisée par catégorie d'usage).
2. Date. ~2026-05-10 (article récent, mentionne Opus 4.7 avec 1MM context, ID snowflake X ~ mai 2026). URL : https://x.com/i/status/2052809885763747935.
3. Thèse en une ligne. "I've started preferring HTML as an output format instead of Markdown" — le format de sortie par défaut pour les artefacts agentiques doit basculer de Markdown vers HTML.
4. Pourquoi maintenant ?. trois facteurs convergents : 1. Les agents produisent des specs/plans plus longs et plus riches qu'avant. 2. L'auteur (et son entourage) n'édite plus manuellement ces fichiers — il prompte Claude pour les éditer → l'avantage "Markdown éditable à la main" disparaît. 3. Opus 4.7 + 1MM context absorbe sans douleur les tokens supplémentaires du HTML.
5. Les 6 raisons (why HTML). 1. Information density — tableaux, CSS, SVG, scripts, canvas, images, positions absolues, données spatiales. "Almost no set of information that Claude can read that you cannot fairly efficiently represent with HTML." 2. Visual clarity & ease of reading — tabs, illustrations, liens, mobile responsive. Au-delà de 100 lignes en Markdown, plus personne ne lit. 3. Ease of sharing — upload S3 → lien direct. "The chance of someone actually reading your spec is much much higher if it's in HTML." 4. Two-way interaction — sliders, knobs, boutons "copy as prompt" pour reboucler vers Claude Code. 5. Data ingestion — Claude Code agrège codebase + MCP (Slack, Linear) + git history + Chrome → contexte plus large que ClaudeAI ou Claude Design. 6. It's joyful — "makes me feel more involved and invested in the creation, and that by itself is enough".
6. Anti-pattern Markdown observé. le modèle, privé d'expressivité visuelle, fait des diagrammes ASCII ou estime des couleurs avec des caractères Unicode (l'article inclut un screenshot de Claude Code essayant de "montrer une couleur" en Unicode → signal absurde d'inadéquation du format).
7. Référence rhétorique. "The Unreasonable Effectiveness of HTML" est un clin d'œil à "The Unreasonable Effectiveness of Mathematics" (Wigner, 1960) et à la lignée de titres "unreasonable effectiveness of X" en ML (Karpathy 2015 sur les RNN).
8. 5 use cases canoniques détaillés. 1. Specs, Planning & Exploration — "a web of HTML files" : brainstorm 6 directions en grille comparative, expansion d'une option, mockups, code snippets, plan d'implémentation. Prompt-type : "Generate 6 distinctly different approaches — vary layout, tone, and density — and lay them out as a single HTML file in a grid so I can compare them side by side." 2. Code Review & Understanding — attacher un explainer HTML à chaque PR. Diff rendu inline avec annotations marginales, code-coloring par sévérité. Prompt-type : "Render the actual diff with inline margin annotations, color-code findings by severity." 3. Design & Prototypes — Claude Design est lui-même basé sur HTML. Prototyper animations avec sliders et bouton "copy parameters" pour exporter les valeurs réglées. 4. Reports, Research & Learning — l'auteur a fait générer son article sur prompt caching en lisant l'historique git. Format long HTML, explainer interactif, slideshow. 5. Custom Editing Interfaces (throwaway editors) — éditeur jetable single-file pour une donnée spécifique, finissant toujours par un export (copy as JSON/markdown/prompt) re-injectable dans Claude Code. Exemples : drag-and-drop de 30 tickets Linear en colonnes Now/Next/Later/Cut, éditeur de feature flags avec dépendances et warnings, prompt-tuner side-by-side avec compteur tokens. "Not a product, or a reusable tool, but a single HTML file, purpose-built for this one piece of data."
9. Anti-pattern majeur explicité. "I'm a little bit afraid that people will read this article and turn it into a /html skill or something. While there might be some value in that, I want to emphasize that you don't need to do much to get Claude to do this." → Anti-skill-ification : la pratique est trop contextuelle pour être figée en skill ; prompter "make a HTML file" suffit.
10. FAQ honnête. (concessions explicites) :
11. Token efficiency. HTML utilise plus de tokens mais le 1MM context d'Opus 4.7 absorbe.
12. Génération. 2-4× plus lente que Markdown — "but I've found the results are worth it".
13. Version control. "this is honestly one of the biggest downsides of HTML, HTML diffs are noisy and hard to review compared to Markdown" — downside non résolu, l'auteur l'assume.
14. Style / éviter le moche. utiliser le frontend design plugin ou créer un design system HTML unique en pointant Claude vers la codebase, puis le référencer pour les autres fichiers HTML générés.
15. Méta-thèse finale (in-the-loop). "I had begun to fear that because I had stopped reading plans in depth I would simply have to leave Claude to make its choices. But I am happy to say instead that I feel more in the loop than ever before when using HTML." → HTML comme antidote au cognitive surrender (Osmani) / comprehension debt : la lisibilité retrouvée permet de rester dans la boucle de décision.
16. Articulation avec la veille corpus.
17. Convergence directe avec Isenberg × Meng To design.md (2026-05-06) : Meng dit explicitement "HTML = finished dish, MD file = recipe, skills = ingredients". Shihipar valide la primauté HTML pour le plat fini livré à l'humain.
18. Réponse opérationnelle à Osmani — Cognitive Surrender / Comprehension Debt (2026-05-05) : Shihipar nomme exactement le même problème ("I had stopped reading plans in depth") et propose HTML comme solution de "rester dans la boucle".
19. Tension avec Lattice / Vincent / Karpathy "skills-maxi" : Shihipar adopte la posture inverse sur la skill-ification ("don't turn this into a /html skill"). Compromis : skills pour les patterns stables, prompt nu pour les pratiques émergentes.
20. Confirmation Opus 4.7 + 1MM context comme changement architectural qui rend économiquement supportables des formats plus verbeux (HTML, design system, brainstorms étendus).
21. Lignée Compounding engineering / Cherny : HTML comme nouvelle couche de l'output artefactuel entre l'agent et l'humain, au même titre que les PR descriptions, les release notes, les commits messages.
22. Exemple méta. pour rédiger cet article, l'auteur a demandé à Claude Code de lire son dossier de code, trouver tous les fichiers HTML générés, les grouper/catégoriser et produire un fichier HTML avec tous les diagrammes par type → les illustrations de l'article sont elles-mêmes le produit du pattern qu'il décrit.
23. Workflow découlant pour la pratique cabinet.
24. Toute spec, plan ou rapport > 100 lignes → bascule HTML.
25. PR critiques → attacher un explainer HTML.
26. Onboarding de fichiers, explorations de design, reorderings → throwaway editor HTML avec export structuré.
27. Garder Markdown pour : commits messages, notes de fiches courtes, fichiers .md de config (CLAUDE.md, agents.md, etc.).