Utiliser Claude Code : L'efficacité déraisonnable du HTML

Le Markdown est devenu le format de fichier dominant utilisé par les agents pour communiquer avec nous. Il est simple, portable, offre quelques capacités de texte enrichi et est facile à éditer. Claude est même devenu étonnamment bon pour utiliser l'ASCII afin de créer des diagrammes dans des fichiers Markdown.

Mais à mesure que les agents deviennent de plus en plus puissants, j'ai eu le sentiment que le Markdown devenait un format restrictif. Je trouve difficile de lire un fichier Markdown de plus d'une centaine de lignes. Je veux des visualisations plus riches, de la couleur et des diagrammes, et je veux pouvoir les partager facilement.

De plus, je n'édite plus ces fichiers moi-même, mais je les utilise comme spécifications, fichiers de référence, résultats de brainstorming, etc. Quand je fais des modifications, je demande généralement à Claude de les faire, ce qui supprime l'un des plus grands avantages du Markdown.

J'ai commencé à préférer le HTML comme format de sortie plutôt que le Markdown, et je vois de plus en plus d'autres membres de l'équipe Claude Code faire de même. Voici pourquoi.

(si vous voulez commencer par quelques exemples, vous pouvez en voir un tas ici : https://thariqs.github.io/html-effectiveness, mais revenez ensuite pour en savoir plus sur les raisons)

Pourquoi le HTML ?

Densité d'information

Le HTML peut transmettre des informations beaucoup plus riches que le Markdown. Il peut bien sûr gérer une structure de document simple comme les en-têtes et le formatage, mais il peut aussi représenter toutes sortes d'autres informations telles que :

• Des données tabulaires avec des tableaux
• Des données de conception avec CSS
• Des illustrations avec SVG
• Des extraits de code avec des balises script
• Des interactions avec des éléments HTML utilisant JavaScript + CSS
• Des workflows avec SVG et HTML
• Des données spatiales avec des positions absolues et des canvas
• Des images avec des balises image

J'irais même jusqu'à dire qu'il n'existe presque aucun ensemble d'informations que Claude peut lire que vous ne puissiez représenter assez efficacement avec du HTML. Cela en fait un moyen très efficace pour le modèle de vous communiquer des informations approfondies et pour vous de les examiner.

J'ai constaté qu'en l'absence de cette capacité, le modèle peut faire des choses plus inefficaces en Markdown, comme des diagrammes ASCII ou, mon préféré, estimer des couleurs avec des caractères Unicode, comme dans cette capture d'écran de Claude Code.

Claude Code essayant d'afficher des couleurs en Markdown

Clarté visuelle et facilité de lecture

À mesure que Claude est capable d'effectuer un travail plus complexe, il écrit également des spécifications et des plans de plus en plus longs. En pratique, j'ai constaté que je ne lis généralement pas plus d'un fichier Markdown de 100 lignes, et je suis certainement incapable de faire en sorte que quelqu'un d'autre dans mon organisation le lise.

Mais les documents HTML sont beaucoup plus faciles à lire. Claude peut organiser la structure visuellement de manière idéale pour naviguer avec des onglets, des illustrations, des liens, etc. Il peut même être responsive pour mobile, afin que vous puissiez le lire différemment selon votre facteur de forme.

Facilité de partage

Les fichiers Markdown sont assez difficiles à partager car la plupart des navigateurs ne les rendent pas bien nativement. Vous devez souvent les ajouter en pièces jointes à des e-mails ou des messages.

Avec le HTML, tant que vous téléchargez le fichier (par exemple sur S3), vous pouvez partager le lien facilement. Vos collègues peuvent l'ouvrir où ils veulent et le consulter facilement.

La probabilité que quelqu'un lise réellement votre spécification, votre rapport ou votre compte rendu de PR est beaucoup plus élevée si c'est en HTML.

Interaction bidirectionnelle

Le HTML vous permet d'interagir avec le document. Par exemple, vous pouvez lui demander d'ajouter des curseurs ou des boutons pour ajuster un design, ou vous permettre de modifier différentes options dans l'algorithme pour voir ce qui se passe. Vous pouvez également lui demander de vous permettre de copier ces modifications dans une invite à coller dans Claude Code.

Lisez la suite de mon article sur les playgrounds pour voir des exemples de cette interaction bidirectionnelle : https://x.com/trq212/status/2017024445244924382

Ingestion de données

Pourquoi utiliser Claude Code pour créer des fichiers HTML plutôt que ClaudeAI ou Claude Design par exemple ? L'une des principales raisons est tout le contexte que Claude Code peut ingérer.

Par exemple, en écrivant cet article, j'ai demandé à Claude Code de lire mon dossier de code, de trouver tous les fichiers HTML que j'avais générés, de les regrouper et de les catégoriser, puis de créer un fichier HTML avec tous les diagrammes représentant chaque type. Les diagrammes que vous voyez dans cet article sont le résultat direct de cela.

Outre le système de fichiers, Claude Code peut trouver un contexte supplémentaire en utilisant vos MCP (comme Slack, Linear, etc.), votre navigateur web (avec Claude dans Chrome), votre historique git, etc.

C'est joyeux

Créer des documents HTML avec Claude est tout simplement plus amusant et me donne l'impression d'être plus impliqué et investi dans la création, et cela suffit en soi.

Comment commencer

J'ai un peu peur que les gens lisent cet article et en fassent une compétence /html ou quelque chose du genre. Bien que cela puisse avoir une certaine valeur, je veux souligner que vous n'avez pas besoin de faire grand-chose pour que Claude fasse cela. Vous pouvez simplement lui demander de « créer un fichier HTML » ou « créer un artefact HTML ».

L'astuce est de savoir ce que vous voulez que l'artefact fasse et comment vous pourriez l'utiliser. Vous pourriez avec le temps créer une compétence, mais pour l'instant, je suggère de simplement lancer une invite à partir de zéro pour apprendre à l'utiliser dans différents cas.

Cas d'utilisation

Pour rendre cela plus concret, j'ai créé de nombreux fichiers HTML différents pour différents cas d'utilisation. Vous pouvez tous les voir ici : https://thariqs.github.io/html-effectiveness/ mais voici un aperçu.

Spécifications, planification et exploration

Le HTML est un canevas riche pour que Claude plonge dans un problème. Lorsque je commence à travailler sur un problème, au lieu d'un simple plan en Markdown, je m'attends à créer un réseau de fichiers HTML. Par exemple, je pourrais commencer par demander à Claude Code de brainstormer et de créer quelques explorations de différentes options. Je lui demanderais ensuite de développer davantage l'une d'elles, peut-être de faire des maquettes ou des extraits de code. Enfin, quand je me sens bien, je lui demande d'écrire un plan de mise en œuvre. Lorsque je suis satisfait du plan, je crée une nouvelle session et je lui passe tous ces fichiers pour qu'il les mette en œuvre.

Lors de la vérification, je demande également à l'agent de vérification de lire les fichiers et il aura un contexte beaucoup plus large sur ce qui est nécessaire.

Exemples d'invites :

• Je ne sais pas quelle direction prendre pour l'écran d'intégration. Génère 6 approches distinctement différentes — varie la mise en page, le ton et la densité — et dispose-les dans un seul fichier HTML en grille pour que je puisse les comparer côte à côte. Étiquette chacune avec le compromis qu'elle fait.
• Crée un plan de mise en œuvre approfondi dans un fichier HTML, assure-toi de faire quelques maquettes, de montrer le flux de données et d'ajouter des extraits de code importants que je pourrais vouloir examiner. Rends-le facile à lire et à digérer.

Cas d'utilisation :

• Explorer d'autres façons d'implémenter quelque chose en code
• Explorer plusieurs designs visuels

Révision et compréhension du code

Le code peut être difficile à lire dans un fichier Markdown. Mais avec le HTML, nous pouvons rendre les diffs, les annotations, les organigrammes, les modules, etc. Utilisez cela pour comprendre le code que l'agent a écrit, pour obtenir une révision de code ou pour expliquer une PR à quelqu'un qui révise votre code. Je trouve que cela fonctionne souvent mieux que la vue diff par défaut de Github, et j'attache maintenant un explicateur de code HTML à chaque PR que je fais.

Exemple d'invite :

Aide-moi à réviser cette PR en créant un artefact HTML qui la décrit. Je ne suis pas très familier avec la logique de streaming/backpressure, alors concentre-toi là-dessus. Affiche le diff réel avec des annotations dans la marge, code les résultats par couleur selon leur sévérité et tout ce qui pourrait être nécessaire pour bien transmettre le concept.

Cas d'utilisation :

• Créer une PR
• Réviser une PR
• Comprendre un sujet dans le code

Design et prototypes

Claude Design est basé sur le HTML car le HTML est incroyablement expressif pour le design, même si votre surface finale n'est pas du HTML. Claude peut esquisser un design en HTML puis l'écrire dans le langage de votre choix, que ce soit React, Swift, etc.

Vous pouvez également prototyper des interactions, comme des animations, des actions, etc. Pensez à demander à Claude de faire des curseurs, des boutons, etc. pour affiner exactement ce que vous recherchez.

Exemple d'invite :

Je veux prototyper un nouveau bouton de paiement. Quand on clique dessus, il fait une animation de jeu puis devient violet rapidement. Crée un fichier HTML avec plusieurs curseurs et options pour que je puisse essayer différentes options sur cette animation, donne-moi un bouton de copie pour copier les paramètres qui ont bien fonctionné.

Utilisez ceci pour :

• Créer des artefacts de système de design
• Ajuster des composants
• Visualiser des bibliothèques de composants
• Prototyper des animations joyeuses

Rapports, recherche et apprentissage

Claude Code est incroyablement doué pour synthétiser des informations provenant de multiples sources de données et les convertir en un rapport lisible. Vous pouvez demander à Claude de chercher dans votre Slack, votre codebase, votre historique git, internet, etc. et de l'utiliser pour générer des rapports extrêmement lisibles pour vous-même, pour la direction, pour votre équipe, etc.

Vous pouvez assembler cela sous la forme d'un long document HTML, d'un explicateur interactif ou même d'un diaporama/diapositives. Demandez à Claude d'utiliser SVG pour les diagrammes afin de les visualiser.

Par exemple, pour mes articles sur la mise en cache des invites, j'ai demandé à Claude de préparer un fichier de recherche approfondi en HTML pour que je puisse lire tous nos changements concernant la mise en cache des invites après avoir lu l'historique git.

Exemple d'invite :

Je ne comprends pas comment fonctionne réellement notre limiteur de débit. Lis le code pertinent et produis une seule page d'explication HTML : un diagramme du flux du seau à jetons, les 3-4 extraits de code clés annotés, et une section « pièges » en bas. Optimise-la pour quelqu'un qui la lit une fois.

Utilisez ceci pour :

• Résumer le fonctionnement d'une fonctionnalité
• M'expliquer un concept
• Rapports de statut hebdomadaires à votre patron
• Rapports d'incidents à votre direction
• Illustrations SVG, organigrammes, diagrammes techniques, etc.

Interfaces d'édition personnalisées

Parfois, il est difficile de décrire ce que vous voulez uniquement dans une zone de texte. Dans ce cas, je demande à Claude de me construire un éditeur jetable pour la chose exacte sur laquelle je travaille. Pas un produit, ni un outil réutilisable, mais un seul fichier HTML, conçu sur mesure pour cette seule donnée.

L'astuce est de toujours terminer par une exportation : un bouton « copier en JSON » ou « copier en invite » qui transforme ce que j'ai fait dans l'interface en quelque chose que je peux coller dans Claude Code.

Exemples d'invites :

• Je dois reprioriser ces 30 tickets Linear. Fais-moi un fichier HTML avec chaque ticket comme une carte déplaçable dans les colonnes Maintenant / Ensuite / Plus tard / Supprimé. Pré-classe-les selon ta meilleure estimation. Ajoute un bouton « copier en markdown » qui exporte l'ordre final avec une justification d'une ligne par groupe.
• Voici notre configuration de feature flags. Construis un éditeur basé sur un formulaire pour celle-ci, regroupe les flags par domaine, montre les dépendances entre eux, avertis-moi si j'active un flag dont le prérequis est désactivé. Ajoute un bouton « copier le diff » qui me donne uniquement les clés modifiées.
• Je suis en train d'ajuster cette invite système. Fais un éditeur côte à côte : invite modifiable à gauche avec les emplacements de variables en surbrillance, trois exemples d'entrée à droite qui réaffichent le modèle rempli en direct. Ajoute un compteur de caractères/tokens et un bouton de copie.

Utilisez ceci pour :

• Réorganiser, trier ou classer quoi que ce soit (tickets, cas de test, retours)
• Éditer une configuration structurée (feature flags, variables d'environnement, JSON/YAML avec contraintes)
• Ajuster des invites, des modèles ou du texte avec un aperçu en direct
• Curer des ensembles de données, approuver/rejeter des lignes, étiqueter des exemples, exporter la sélection
• Annoter un document, une transcription ou un diff et exporter les annotations
• Choisir des valeurs difficiles à exprimer en texte : couleurs, courbes d'assouplissement, zones de recadrage, plannings cron, expressions régulières.

Foire aux questions

J'ai parlé à beaucoup de gens de mon passage au HTML et j'ai vu quelques questions récurrentes.

N'est-ce pas moins efficace en termes de tokens ?

Bien que le Markdown utilise souvent moins de tokens, j'ai constaté que l'expressivité supplémentaire du HTML et la probabilité beaucoup plus élevée que je le lise me donnent globalement de meilleurs résultats. Avec la fenêtre de contexte de 1 million de tokens dans Opus 4.7, l'augmentation de l'utilisation des tokens n'est pas vraiment perceptible dans la fenêtre de contexte.

Quand utilisez-vous encore le Markdown ?

Honnêtement, j'ai complètement arrêté d'utiliser le Markdown pour presque tout, mais je suis probablement du côté maximaliste du HTML.

Comment visualiser le fichier HTML ?

J'ai tendance à simplement l'ouvrir dans un navigateur localement (vous pouvez demander à Claude de l'ouvrir), ou à le télécharger sur S3 si je veux un lien partageable.

Cela ne prend-il pas plus de temps à générer que le Markdown ?

Cela prend effectivement plus de temps ! Le HTML peut prendre 2 à 4 fois plus de temps que le Markdown, mais j'ai constaté que les résultats en valent la peine.

Qu'en est-il du contrôle de version ?

C'est honnêtement l'un des plus grands inconvénients du HTML. Les diffs HTML sont bruyants et difficiles à réviser par rapport au Markdown.

Comment faire pour que Claude corresponde à mes goûts / ne rende pas le résultat moche ?

Le plugin de design frontend aide Claude à créer de bons fichiers HTML. Mais pour correspondre au style de votre propre entreprise, vous pouvez créer un seul fichier HTML de système de design en pointant Claude vers votre codebase. Vous pouvez ensuite utiliser ce fichier de système de design comme référence pour d'autres fichiers HTML.

Restez dans la boucle

Tout ce qui précède pour dire que je pense que la vraie raison pour laquelle j'utilise le HTML est que je me sens beaucoup plus dans la boucle avec Claude. J'avais commencé à craindre que, parce que j'avais arrêté de lire les plans en profondeur, je devrais simplement laisser Claude faire ses choix.

Mais je suis heureux de dire qu'au contraire, je me sens plus dans la boucle que jamais en utilisant le HTML. J'espère qu'il en sera de même pour vous.