Claude Code et l'efficacité déraisonnable des artefacts HTML

Markdown a gagné la première phase de la collaboration avec les agents parce qu'il est simple.

Il est facile à générer, facile à comparer en diff, facile à coller dans une pull request et suffisant pour la plupart des notes. Il est donc devenu le format par défaut naturel des coding agents : plans, résumés, specs, notes de review, postmortems et checklists d'implémentation finissent tous en Markdown.

Le dernier article d'Anthropic sur Claude Code explique que ce défaut commence à montrer ses limites.

L'argument n'est pas que Markdown est mauvais. C'est que Claude Code peut désormais faire plus qu'écrire un long fichier texte, et HTML offre au modèle une meilleure surface de travail : plus forte densité d'information, structure visuelle plus claire, artefacts plus faciles à partager et interactivité légère.

Pour les développeurs, c'est un changement très concret. Il modifie ce que nous devrions demander à Claude Code de produire.

L'idée centrale

Dans l'article officiel, Thariq Shihipar, de l'équipe Claude Code, explique pourquoi il préfère désormais les fichiers HTML à Markdown pour de nombreuses sorties de Claude Code.

La raison est simple : à mesure que Claude Code prend en charge des tâches plus grandes, les sorties deviennent elles aussi plus grandes.

Une checklist Markdown de 30 lignes convient très bien. Un plan d'implémentation, rapport de recherche, code review, explicatif d'architecture ou exploration UI de 300 lignes n'est pas satisfaisant simplement parce qu'il se rend techniquement.

HTML donne à Claude Code plus d'espace pour organiser la même information :

• tableaux pour les comparaisons denses
• CSS pour la hiérarchie visuelle
• SVG pour les diagrammes
• images pour les références
• JavaScript pour les interactions locales
• onglets et sections pour la navigation
• boutons pour copier les prompts, JSON, diffs ou réglages générés

Cela fait de HTML moins un format documentaire qu'un établi ponctuel.

Pour les workflows d'agents, cette distinction compte.

Pourquoi cela compte pour les utilisateurs de Claude Code

Claude Code est différent d'une interface de chat classique parce qu'il peut lire le projet local, inspecter l'historique git, travailler avec les fichiers, utiliser des serveurs MCP et générer des artefacts dans le même workspace que le vrai travail d'ingénierie.

Il est donc particulièrement bien placé pour créer des artefacts HTML utiles à partir d'un vrai contexte.

Par exemple, au lieu de demander :

Write a plan for refactoring the billing module.

vous pouvez demander :

Create an HTML artifact that explains the billing refactor.
Include a module map, the key file changes, risks by severity,
a staged migration plan, and a copyable implementation prompt.

Ces deux prompts peuvent contenir la même demande sous-jacente, mais le second demande un format plus facile à inspecter, plus facile à partager et plus facile à réutiliser comme référence dans une future session Claude Code.

C'est le vrai avantage : HTML peut devenir un contexte de projet durable, pas seulement une réponse ponctuelle.

Les quatre cas où HTML dépasse Markdown

1. Specs et planification

La planification est le premier endroit où Markdown commence à peiner.

Les longs plans d'implémentation combinent souvent architecture, extraits de code, dépendances, diagrammes, compromis, captures d'écran et questions ouvertes. Markdown peut contenir tout cela, mais il n'aide pas le lecteur à naviguer.

HTML permet à Claude Code de diviser le plan en une surface plus facile à reviewer :

• vue d'ensemble en haut
• diagramme de flux du système
• carte des changements fichier par fichier
• tableau des risques
• plan de déploiement par étapes
• questions non résolues
• prompts de suivi copiables

C'est particulièrement utile quand un plan doit survivre entre plusieurs sessions. Un agent futur peut lire le fichier HTML comme contexte, tandis qu'un humain peut le parcourir sans lire un mur de texte.

2. Code review et compréhension

Une code review n'est pas seulement du texte. C'est une structure.

Une bonne review a souvent besoin d'un diff, de niveaux de sévérité, de modules affectés, de chemins d'appel, de flux de données et d'explications courtes sur l'importance du problème. Markdown peut l'approximer, mais HTML peut le rendre directement.

Pour Claude Code, cela suggère un meilleur workflow :

Review this PR by creating an HTML artifact.
Show the diff with inline annotations, group findings by severity,
and include a small diagram of the streaming/backpressure path.

La sortie de review devient ainsi plus proche d'un dossier de review interactif. Elle peut rester temporaire, mais elle est plus facile à transmettre à un autre ingénieur.

3. Design et prototypes

HTML est une cible naturelle pour Claude Code quand la sortie a une composante visuelle ou interactive.

Même si l'application de production est en React, Swift, Kotlin ou autre, HTML reste un moyen rapide d'esquisser des layouts, comparer des directions, tester du motion et ajuster des paramètres UI.

L'article original cite les sliders, knobs et boutons de copie comme primitives utiles. C'est le bon modèle mental. Claude Code peut créer une interface jetable pour choisir des valeurs difficiles à décrire en prose :

• palettes de couleurs
• courbes d'easing
• densité de composants
• zones de recadrage
• variantes de prompt
• combinaisons de feature flags
• priorités de tickets

La partie importante est l'export. Un bon artefact HTML doit aboutir à quelque chose d'utile : copier en JSON, copier en Markdown, copier en prompt ou copier un diff.

Si l'artefact ne peut pas renvoyer sa sortie dans le workflow d'ingénierie, ce n'est qu'une démo.

4. Rapports, recherche et apprentissage

Claude Code peut synthétiser un codebase, l'historique git, les docs, Slack via MCP, Linear via MCP et des sources web. Markdown peut résumer ce contexte, mais HTML peut le rendre lisible.

Pour les explications internes, incident reviews, points hebdomadaires, audits de dépendances et guides d'onboarding, HTML donne au modèle assez d'espace visuel pour montrer les relations au lieu de seulement les décrire.

C'est là que HTML devient un format d'apprentissage :

• extraits de code annotés
• diagrammes système
• encarts de glossaire
• vues chronologiques
• matrices de risque
• tableaux de décision

Le résultat n'a pas besoin de devenir un produit poli. Il doit seulement être assez lisible pour que quelqu'un l'utilise vraiment.

Le point caché : HTML garde les humains dans la boucle

La partie la plus forte de l'article d'Anthropic n'est pas l'argument de format. C'est l'argument de workflow.

À mesure que Claude Code traite de plus grandes tâches, les développeurs risquent de lire moins ce que l'agent produit. Les longs plans Markdown sont faciles à approuver sans review approfondie. C'est dangereux, car le plan peut contenir des hypothèses faibles, des cas limites oubliés ou des changements que le développeur n'aurait pas choisis.

HTML peut réduire ce mode d'échec parce qu'il donne de meilleurs points d'appui à l'humain :

• parcourir la vue d'ensemble
• inspecter le diagramme
• comparer les options côte à côte
• sauter aux risques
• ajuster un slider
• recopier la sortie sélectionnée dans Claude Code

Cela ne supprime pas le besoin de review. Cela rend la review plus probable.

Pour des workflows d'agents sérieux, ce n'est pas cosmétique. C'est une partie du contrôle.

Quand Markdown reste le meilleur choix

HTML ne doit pas remplacer Markdown partout.

Markdown reste meilleur quand l'artefact doit être :

• petit
• facile à comparer en diff
• souvent édité manuellement
• intégré dans un README
• collé dans une issue ou une description de PR
• consommé par des outils qui attendent du Markdown

La règle pratique est simple :

Utilisez Markdown quand la sortie est surtout du texte et sera éditée par des humains.

Utilisez HTML quand la sortie a besoin de layout, diagrammes, comparaison dense, interactivité ou meilleure expérience de lecture.

Cela évite que HTML devienne un nouveau défaut trop utilisé.

Un pattern de prompt simple

Si vous voulez essayer dans Claude Code, commencez par un prompt direct :

Create a single HTML artifact for this task.
It should be readable in a browser, self-contained, and optimized for review.
Use tables, diagrams, and sections where useful.
Add copy buttons for any output I may want to paste back into Claude Code.
Keep all source references visible.

Puis rendez l'objectif spécifique :

For this refactor, include:
- a dependency map
- the proposed file changes
- migration steps
- risks by severity
- test plan
- open questions

Avec le temps, les patterns récurrents devraient devenir des skills ou des templates. Mais la première étape ne demande pas d'infrastructure. Elle demande seulement l'habitude de demander à Claude Code un meilleur artefact.

Ce que les équipes devraient faire ensuite

L'opportunité à court terme n'est pas de reconstruire tout le système documentaire interne autour de HTML.

Le geste utile est plus ciblé :

1. Identifiez les sorties Claude Code que votre équipe ne lit pas vraiment.
2. Transformez l'une de ces sorties en artefact HTML.
3. Exigez que l'artefact exporte quelque chose d'utile vers le workflow.
4. Gardez l'artefact dans le repo quand il aide les sessions futures.
5. Supprimez-le quand il n'a servi qu'à une seule décision.

Ce dernier point compte. Beaucoup d'artefacts HTML devraient être jetables. Leur valeur est d'aider un humain à prendre une meilleure décision maintenant.

Conclusion

L'efficacité déraisonnable de HTML ne vient pas du fait que ce serait un meilleur langage de balisage que Markdown.

Elle vient du fait que HTML donne à Claude Code une surface de collaboration plus riche.

Pour les petites notes, Markdown reste le bon outil. Mais pour les specs, code reviews, explications d'architecture, explorations design, rapports de recherche et interfaces d'édition sur mesure, HTML peut rendre la sortie d'un agent plus lisible, plus partageable et plus actionnable.

À mesure que Claude Code devient capable de prendre en charge de plus grands blocs de travail, le format de sortie devient une partie du design du workflow. Les équipes qui traitent les artefacts comme des surfaces de review de premier ordre garderont plus de contrôle que celles qui continuent d'approuver des murs de Markdown.

Source

• Claude blog: Using Claude Code: The unreasonable effectiveness of HTML
  https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html