Usando o Claude Code: a surpreendente eficiência do HTML

• No Claude Code, usar HTML como formato de saída em vez de Markdown permite criar resultados mais fáceis para humanos lerem e revisarem, com visualização, cores, diagramas e interatividade mais ricos
• O HTML expressa com eficiência a maior parte das informações que o Claude consegue ler, aproveitando tabelas, CSS, SVG, script, interatividade em JavaScript, imagens, canvas e posicionamento absoluto
• O Claude Code consegue ler contexto como sistema de arquivos, MCP, navegador e histórico do Git, e costurá-los em resultados em HTML; dá para começar apenas pedindo “crie um arquivo HTML”
• Os principais usos se dividem em especificações, planejamento e exploração, revisão e compreensão de código, design e prototipagem, relatórios, pesquisa e aprendizado, e interfaces personalizadas de edição pontual
• O HTML leva de 2 a 4 vezes mais tempo para ser gerado do que Markdown, e o diff é mais barulhento, o que dificulta o controle de versão, mas suas grandes vantagens são expressividade, compartilhamento e maior chance de realmente ser lido

---

Por que passei a preferir HTML em vez de Markdown

• Markdown se tornou o formato de arquivo dominante para agentes se comunicarem com pessoas: é simples, portátil, permite algum nível de formatação e é fácil para humanos editarem diretamente
• O Claude também cria bem diagramas ASCII dentro de Markdown, mas, à medida que os agentes ficam mais poderosos, Markdown passa a parecer um formato limitador
• Arquivos Markdown com mais de 100 linhas são difíceis de ler, e surge a vontade de compartilhar visualizações, cores e diagramas mais ricos com mais facilidade
• À medida que fica mais comum pedir ao Claude para editar arquivos em vez de editá-los manualmente, o valor da principal vantagem do Markdown — a facilidade de edição direta — diminui
• Até dentro da equipe do Claude Code, o uso de HTML como formato de saída está aumentando, e exemplos podem ser vistos em html-effectiveness

Expressividade e compartilhamento do HTML

• HTML pode representar não só a estrutura do documento, como títulos e formatação, mas também uma variedade de informações muito maior do que Markdown
• Entre as informações representáveis estão dados tabulares com tabelas, dados de design com CSS, ilustrações em SVG, trechos de código com a tag script e interatividade com JavaScript e CSS
• É possível representar fluxos de trabalho com SVG e HTML, dados espaciais com posicionamento absoluto e canvas, e incluir imagens com a tag img
• A maior parte do conjunto de informações que o Claude consegue ler pode ser expressa com bastante eficiência em HTML, tornando-o um formato eficiente tanto para o modelo transmitir informações profundas quanto para humanos revisarem
• Sem HTML, o Claude pode acabar recorrendo a formas ineficientes de expressão em Markdown, como criar diagramas ASCII ou estimar cores com caracteres Unicode
• À medida que o Claude passou a executar tarefas mais complexas, também passou a escrever especificações e planos maiores, e, na prática, arquivos Markdown com mais de 100 linhas não são bem lidos
• Documentos HTML podem organizar visualmente sua estrutura com abas, ilustrações e links, facilitando a navegação, e também podem ser responsivos para leitura diferente dependendo do tamanho da tela
• Arquivos Markdown não são bem renderizados por padrão no navegador e muitas vezes precisam ser anexados em e-mails ou mensagens, enquanto HTML pode ser enviado para um lugar como S3 e compartilhado facilmente por link
• Especificações, relatórios e descrições de PR em HTML têm muito mais chance de realmente serem lidos, porque colegas conseguem abrir e consultar com facilidade
• Documentos HTML podem oferecer interatividade bidirecional, com sliders e knobs para ajustar designs ou mudar opções de algoritmo e ver os resultados
• Também dá para criar uma função que copie o resultado ajustado de volta como prompt para colar no Claude Code; há um exemplo relacionado no playgrounds post

Por que usar Claude Code com HTML

• O Claude Code consegue ler contextos variados — como sistema de arquivos, MCP, navegador e histórico do Git — e reuni-los em resultados em HTML
• Por exemplo, ele pode encontrar todos os arquivos HTML gerados dentro de uma pasta de código, agrupá-los e classificá-los, e depois criar um arquivo HTML com diagramas que representem cada tipo
• Além do sistema de arquivos, ele também pode buscar contexto adicional em MCPs como Slack e Linear, no navegador via Claude in Chrome e no histórico do Git
• O processo de criar documentos HTML com o Claude é mais divertido e dá a sensação de maior envolvimento e investimento no resultado gerado
• Não é necessário criar uma skill /html separada; basta começar pedindo “crie um arquivo HTML” ou “crie um artifact HTML”
• A dica importante é saber o que o artifact deve fazer e como ele será usado; no começo, vale a pena escrever prompts do zero a cada vez para aprender diferentes usos

Principais formas de uso

• Especificações, planejamento e exploração

  • HTML pode servir como uma tela rica para o Claude investigar um problema, e o trabalho pode começar com um conjunto de vários arquivos HTML em vez de um único plano em Markdown
  • É possível primeiro fazer brainstorming de várias direções, depois expandir uma delas com mockups ou trechos de código e, por fim, escrever um plano de implementação
  • Quando o plano estiver satisfatório, dá para criar uma nova sessão e passar esses arquivos para implementação, e até um agente de validação pode ler os mesmos arquivos para obter o contexto necessário de forma mais ampla
  • É possível pedir uma grade HTML única com 6 abordagens para uma tela de onboarding, com layouts, tons e densidades diferentes, mostrando os trade-offs de cada escolha
  • Também é possível pedir um plano de implementação em HTML fácil de ler, incluindo mockups, fluxo de dados e trechos de código para revisão
  • Pode ser usado para explorar formas de implementar código e comparar diferentes designs visuais

• Revisão e compreensão de código

  • Código pode ser difícil de ler em arquivos Markdown, mas em HTML é possível renderizar diffs, comentários, fluxogramas e estruturas de módulo
  • Isso pode ser usado para entender código escrito por agentes, receber revisão de código ou explicar mudanças para quem estiver revisando um PR
  • Em alguns casos, funciona melhor do que a visualização padrão de diff do GitHub, e também é possível adotar um fluxo em que cada PR vem com um arquivo HTML explicando o código
  • É possível criar um artifact HTML para revisão de PR, focar em uma lógica de streaming/backpressure pouco familiar e pedir anotações laterais no diff real, com cores por severidade
  • Pode ser usado para escrever PRs, revisar PRs e entender tópicos de código

• Design e prototipagem

  • O Claude Design é baseado em HTML, e HTML oferece alta expressividade para design, mesmo quando a superfície final não é HTML
  • O Claude pode primeiro esboçar um design em HTML e depois escrevê-lo na linguagem desejada, como React, Swift etc.
  • Dá para prototipar interações como animações e ações, além de incluir sliders ou knobs para ajustar os valores desejados
  • É possível pedir um botão de checkout que, ao ser clicado, execute uma animação de reprodução e depois mude rapidamente para roxo, incluindo vários sliders, opções e um botão para copiar parâmetros que funcionaram bem
  • Pode ser usado para gerar artifacts de design system, ajustar componentes, visualizar bibliotecas de componentes e prototipar animações agradáveis

• Relatórios, pesquisa e aprendizado

  • O Claude Code é forte em sintetizar informações de várias fontes de dados e transformá-las em relatórios fáceis de ler
  • Você pode pedir que ele pesquise em Slack, codebase, histórico do Git, internet etc. e gere relatórios legíveis para você, sua liderança ou sua equipe
  • O resultado pode ser um documento HTML longo, uma explicação interativa ou um slide/deck
  • Pedir que ele crie diagramas usando SVG ajuda na visualização
  • Ao preparar um texto sobre prompt caching, foi usado um método em que o Claude lê o histórico do Git e cria um arquivo HTML de pesquisa aprofundada cobrindo todas as mudanças relacionadas a prompt caching
  • Também é possível pedir que ele leia o código relevante de um rate limiter e crie uma única página HTML explicativa com um diagrama do fluxo token-bucket, 3 ou 4 trechos principais de código anotados e uma seção final de gotchas
  • Pode ser usado para resumir o funcionamento de funcionalidades, explicar conceitos, gerar relatórios semanais de status, relatórios de incidentes e criar ilustrações SVG, fluxogramas e diagramas técnicos

• Interfaces personalizadas de edição

  • Quando é difícil explicar o que se quer apenas com uma caixa de texto, dá para criar um editor HTML descartável ajustado aos dados que você está trabalhando no momento
  • Não se trata de um produto ou ferramenta reutilizável, mas de um único arquivo HTML feito sob medida para um pedaço específico de dados
  • O ponto-chave é incluir no final uma exportação como “copy as JSON” ou “copy as prompt”, para que o resultado manipulado na UI possa ser colado no Claude Code
  • É possível transformar 30 tickets do Linear em cartões arrastáveis em colunas Now / Next / Later / Cut, e depois copiar a ordem final em Markdown com uma justificativa de uma linha para cada bucket
  • Também é possível criar um editor baseado em formulário para configurações de feature flags, agrupando por áreas, mostrando dependências, alertando quando alguém tenta ativar uma flag enquanto a flag prévia está desativada e copiando em diff apenas as chaves alteradas
  • Ao ajustar um prompt de sistema, pode haver à esquerda um prompt editável com slots de variáveis destacados e, à direita, a renderização em tempo real de três entradas de exemplo, além de contador de caracteres/tokens e botão de cópia
  • Pode ser usado para reorganizar tickets, casos de teste e feedback; editar configurações estruturadas; ajustar prompts, templates e textos; fazer curadoria de datasets; anotar documentos, transcrições e diffs; e escolher valores difíceis de expressar em texto, como cor, easing curve, região de crop, cron schedule e regex

Perguntas frequentes e limitações

• Markdown normalmente usa menos tokens, mas HTML oferece mais expressividade e maior chance de realmente ser lido, o que melhora o resultado final como um todo
• Na janela de contexto de 1MM do Opus 4.7, o aumento no uso de tokens quase não se destaca dentro da janela de contexto
• O uso descrito está próximo de abandonar Markdown em quase todos os casos, mas isso representa uma preferência máxima por HTML
• Arquivos HTML podem ser abertos no navegador local, você também pode pedir ao Claude para abri-los, e, se precisar de um link compartilhável, pode publicá-los no S3
• Gerar HTML leva mais tempo do que Markdown — pode levar de 2 a 4 vezes mais —, mas considera-se que o resultado vale esse custo
• Uma das maiores desvantagens é o controle de versão, porque o diff de HTML é mais barulhento e difícil de revisar do que o de Markdown
• Para fazer o Claude gerar HTML no estilo que você gosta, um frontend design plugin pode ajudar
• Para adequar o resultado ao estilo da empresa, você pode deixar o Claude analisar o codebase, criar um único arquivo HTML de design system e depois usá-lo como referência para outros arquivos HTML
• Usar HTML reduz o medo de deixar as escolhas nas mãos do Claude por não ler profundamente os planos que ele escreve, e ajuda você a permanecer mais no fluxo durante o trabalho com o Claude

[GN⁺]

Comentários no Hacker News

• Preocupa perder a capacidade de pessoas e LLMs escreverem e editarem documentos juntas quando se migra para HTML
  Para textos explicativos simples tudo bem, mas em especificações mais complexas a capacidade de entrar diretamente no resultado gerado e corrigir é muito importante. Em documentos HTML isso é bem mais difícil do que em Markdown, e até dá para pedir à LLM que edite o HTML de novo, mas quando você já tem bem claro na cabeça o que quer dizer isso por si só vira mais uma barreira. Se esse padrão se tornar comum, parece que a co-criação entre humano e LLM vai diminuir ainda mais, em direção a delegar à LLM até o estilo, o tom e a escolha do conteúdo. Surpreendeu que o FAQ do blog não mencionasse essa preocupação

  • Markdown suporta HTML inline para elementos interativos, então um documento Markdown com templates HTML conhecidos e um processo simples de build pode ser uma alternativa interessante
    Por exemplo, algo como um comando pandoc de uma linha
  • Acho que existe mais um passo além disso. Com HTML já dá para fazer bastante coisa, mas deixar a LLM definir a própria linguagem dela também foi estranhamente eficaz
    Estou fazendo agora um pequeno jogo mobile com visão isométrica e som, e pedi ao Codex para criar uma ferramenta que posicionasse blocos em uma documentação three.js preparada e tirasse screenshots com as ferramentas de desenvolvedor do Chromium; ele criou uma pequena estrutura JSON para definir blocos, cores e efeitos e gerou um tileset 2.5D. Depois também fiz ele definir sons e música com um script Python uv, e ele criou um formato YAML capaz de gerar ruído. Já passou muito de um teste bobo com pelicano em SVG, e o Codex acabou produzindo arte de protótipo suficiente para soldados, cavaleiros e sacerdotes, além de uma trilha sonora provisória
  • Nós escrevemos HTML manualmente com facilidade há décadas. Editores de texto são ótimos para escrever HTML, e há muitos comandos como quebra automática de linha e fechamento automático, então ler e escrever é simples
  • Isso parece valer só quando você se limita de propósito a um emulador cru de teletipo. Num ambiente de programação decente, editar HTML deveria ser muito simples, e se a tendência for em direção a saídas de modelo mais ricas, um editor WYSIWYG embutido também pode ser uma opção
  • Comecei a usar HTML em relatórios recentemente, mas sempre mantenho um arquivo Markdown como formato intermediário e peço à LLM que faça uma versão mais bonita com gráficos e figuras SVG com base nas tabelas do Markdown

• É irônico que isso seja um post no Twitter com uma imagem renderizada de HTML, e não uma página HTML interativa
  Defender HTML numa plataforma com estrutura semântica mais pobre do que Markdown acaba sendo bem engraçado

  • https://thariqs.github.io/html-effectiveness/
    Acho que é os dois
  • Nem vamos começar com a conversa sobre “templates” do Twitter Articles. Nem Markdown ele suporta

• Um prompt que uso com frequência ao explorar ideias ou ferramentas novas é o seguinte

  In a single index.html, no dependencies, sparse styling, create an app that  
  

  Eu já fazia pequenas ferramentas assim antes da IA, e gosto do fato de poder mandar uma ferramenta por e-mail para um amigo e dizer “se quiser mudar algo, joga na LLM”

  • É isso mesmo
    É impressionante o alcance de coisas que dá para fazer com um único arquivo HTML contendo estilo e JS quando você está criando dashboards, pequenos apps, ou utilitários que interagem com APIs ou puxam dados de algum lugar. Você pode jogar isso na pasta pessoal ~ do servidor compartilhado da empresa e todo mundo consegue ver e usar na hora
  • Quando estou iterando no design de um novo cliente, também faço isso num index.html simples com CSS inline, e quando gosto do resultado coloco esse arquivo ao lado dos arquivos de template do projeto e peço à LLM para incorporar o design do index.html ao template
  • Nunca tinha pensado de verdade nesse caso de uso antes, então me senti meio idiota. É obviamente útil demais
    Até agora, ao usar LLMs, o foco era o “app” em si, não as ferramentas auxiliares ao redor dele. Essas ferramentas auxiliares não precisam ser polidas nem cobrir todos os casos; basta funcionarem o suficiente para serem úteis. Quando terminar, você joga fora e faz outra amanhã
  • Descobri esse truque há um tempo e fiz um monte de calculadoras para circuitos eletrônicos analógicos: https://cofree.coffee/~solomon/calculators/
    É muito conveniente conseguir montar esse tipo de ferramenta rapidamente e publicar num site estático
  • No Claude web, quando você pede HTML, ele também faz isso. Como entrega em artifacts, é provável que o modelo tenha sido bem treinado nesse padrão

• As tecnologias web realmente acertaram muita coisa. Muita gente reclama, mas é impressionante
  No meu emprego anterior eu lidava com apps feitos por vibe coding e acabei saindo por causa disso, mas a arquitetura era um frontend de página única em Next.js com um backend de API separado, então as URLs voltadas para o usuário não batiam com os endpoints do backend. Como a IA usava React hooks para tudo, o estado ficava na memória, e roteamento baseado em URL simplesmente não existia a menos que fosse planejado conscientemente. Então links não surgiam de graça, e os usuários não tinham como linkar para nada além do ponto de entrada de nível superior. Links. Principalmente em ferramentas internas, tudo deveria ser linkável para facilitar colaboração e resolução de problemas. A ideia de projeto de ter localizadores uniformes de recursos e verbos foi realmente muito bem pensada, mesmo 30 ou 40 anos atrás

  • Quer dizer que a URL não era atualizada mesmo quando você navegava para outra página ou aba?

• Faltam aqui alguns pontos no meio-termo entre HTML e Markdown. HTML é muito menos eficiente em tokens, e dar feedback preciso sobre um plano em HTML é mais difícil do que em Markdown
  Esses dois trade-offs jogam a favor da Anthropic. Usar HTML como meio aumenta o consumo de tokens, e também é possível que eles estejam investindo em ferramentas para anotar ou marcar HTML como parte do Claude Design, o que pode fortalecer ainda mais o lock-in. Ou é coincidência, ou uma estratégia brilhante

  • É um pouco menos eficiente, mas se não houver muitos elementos estruturais ou visuais a diferença não é tão grande assim
    Também não entendo muito bem por que dar feedback preciso seria mais difícil do que em Markdown. Você pode colocar id em tags, seções etc.
  • HTML também amplia a superfície para vulnerabilidades de execução de código. Texto puro não faz mal

• Apesar de lidar com HTML há décadas, para documentos simples Markdown ainda é mais rápido. Seria bom ter um meio-termo, e na prática já existem opções mais completas, como o GitHub Markdown
  Você também pode embutir Mermaid, e usar algo como MDX, que mistura componentes quando necessário. Pelo que sei, o readme.com também usa MDX internamente. Se você precisa de cards ou layouts, pode colocar componentes baseados em algo como Bootstrap. Agora o que falta é só suporte de interface. Como HTML puro já pode ser renderizado, não parece tão difícil assim adicionar um Markdown mais poderoso

  • Acho que MDX é o meio-termo perfeito. Por causa deste comentário, estou pensando em começar a usar MDX em vez de Markdown comum

• Tanto a especificação original do Markdown [1] quanto o CommonMark [2] definem claramente suporte a HTML inline. Então, dependendo do uso, dá para ter um pouco das vantagens dos dois lados
  Na maior parte do tempo você usa cabeçalhos e parágrafos normais de Markdown, e ao inserir imagens e tabelas o texto continua legível na forma original sem precisar de tags HTML. Se quiser colocar algo como SVG, como no exemplo do autor, é só embutir o SVG diretamente, e quem for ler pode renderizar o Markdown no visualizador que preferir. No VS Code, se você estiver vendo o arquivo Markdown bruto e encontrar tags HTML, basta abrir a prévia com Cmd+Shift+V. Claro, se for uma página web completa com botões interativos e estilo totalmente personalizado, isso fica difícil de viabilizar, mas para casos focados principalmente em texto, imagens e tabelas, com alguns extras aqui e ali, dá para ir bem longe
  [1] https://daringfireball.net/projects/markdown/syntax#html
  [2] https://spec.commonmark.org/0.31.2/#html-blocks

  • Acho que um documento Markdown não deveria precisar de pré-visualização. Se for assim, então é melhor fazer logo um documento HTML

• Desde janeiro venho defendendo fortemente essa abordagem para usos não relacionados a programação. A propriedade importante é ser uma única fonte da verdade que pode ser editada, compreendida por LLMs e por humanos, renderizada e modificada de forma incremental
  Converso bastante com pessoas comuns sobre trabalho com IA e, quando encontro uma conversa sobre IA por acaso, acabo me intrometendo como um antropólogo. Artifacts em HTML são como a nova barra de endereços do navegador. É como quando alguns usuários entendem aquela barra como sendo, na verdade, o Google. Hoje muita gente fala de entregáveis como “planilha”, “apresentação”, “resumo de marketing de 1 página”, “slideshow”, “análise competitiva”, “diagrama de sistema HVAC”, e diz que trabalhar nisso no ChatGPT ou Claude web não era grande coisa, mas criar um documento novo com Claude Code ou OpenClaw parecia um milagre
  Quando pergunto qual era o documento real e qual era a diferença de experiência, normalmente preciso insistir bastante ou pedir para mostrarem, porque ainda falta vocabulário de computação para descrever isso, mas no fim a conclusão sempre aponta para o fato de que o artifact era HTML. A experiência agradável vem de iterar sobre arquivos HTML no sistema de arquivos (+CSS+imagens) com renderização imediata de alta qualidade, e com a possibilidade de salpicar um pouco de JavaScript quando necessário. Se houver um sistema git, a pessoa pode até acabar tendo versionamento sem perceber. Se não houver, eu recomendo criar checkpoints. Talvez controle de versão seja a próxima etapa de aprendizado para usuários comuns
  Já a experiência presa à web envolve cutucar várias vezes DOCX/PPTX/XLSX que ficam dentro de uma janela de contexto, lidando com uma noção nebulosa de armazenamento local. Na prática, mesmo quando renderiza em HTML na sidebar, é isso que acontece. O fluxo de trabalho em HTML também facilita muito integrar outros meios. No fim, esse tipo de produção de apresentações é vibe coding para as massas, e não é preciso conhecer todas as tartarugas que sustentam a base. Ainda assim, se quiser, você pode abrir, editar ou passar facilmente para outro agente. Um sistema criado para comunicação multimídia colaborativa acabou se tornando útil para inteligências de máquina ajudarem na nossa comunicação

• Antigamente, nós (https://www.definite.app/) fazíamos nosso agente escrever relatórios e dashboards numa especificação YAML renderizada por um framework frontend
  Por exemplo, se o usuário dissesse “quero um relatório que mostre receita e número de pedidos por mês, e exiba os 100 pedidos mais recentes”, o agente escrevia uma especificação que seria renderizada no frontend. Isso era rápido, mas ficamos soterrados por pedidos de recursos que o framework precisava renderizar. Coisas como “quero tirar o rótulo daqui”, “ali precisa de um rótulo”, “dá para transformar esse gráfico em mapa de calor?”. Há alguns meses passamos a fazer o agente simplesmente escrever HTML, e embora a geração demore mais, deixou de haver limites para customização. O novo modelo ainda tem vários problemas, como usuários não técnicos precisarem depurar os apps monstruosos que eles mesmos criaram, mas no geral os clientes gostam muito mais

  • Como vocês estão evitando prompt injection nesse caso?

• Leio saídas longas de agentes usando VIM e o Quick Look do macOS (com extensões de renderização de Markdown), ou colando no MarkEdit, que tem painel de pré-visualização
  No pior caso, basta pedir ao agente para criar uma página web local simples que interprete e renderize Markdown. Markdown foi inventado como uma forma abreviada da gramática da web [0], e é exatamente para esse tipo de uso. O número de tokens e o tempo gastos pedindo ao agente para transformar Markdown básico em HTML provavelmente seriam maiores do que nesses métodos
  0. https://daringfireball.net/projects/markdown/

  • É bem provável que gaste mais tokens, mas como o autor trabalha na Anthropic, imagino que ele nunca tenha pago diretamente pelo custo dos tokens
  • Se a ideia é ir no vibe até o fim, por que não pedir para o bot resumir também as saídas longas?
    O uso de bots está ficando realmente caótico e autorreferente
  • Fiquei curioso sobre qual extensão do Quick Look é essa. Eu estava procurando uma boa