Usando o Claude Code: A Eficácia Irrazoável do HTML

Markdown se tornou o formato de arquivo dominante usado por agentes para se comunicar conosco. É simples, portátil, tem alguma capacidade de texto rico e é fácil de editar. O Claude ficou surpreendentemente bom em usar ASCII para fazer diagramas dentro de arquivos markdown.

Mas, à medida que os agentes se tornaram cada vez mais poderosos, senti que o markdown se tornou um formato restritivo. Acho difícil ler um arquivo markdown com mais de cem linhas. Quero visualizações mais ricas, cores e diagramas, e quero poder compartilhá-los facilmente.

Também estou cada vez mais deixando de editar esses arquivos eu mesmo, usando-os como especificações, arquivos de referência, resultados de brainstorming, etc. Quando faço edições, geralmente peço ao Claude para editá-los, o que remove um dos maiores benefícios do markdown.

Comecei a preferir HTML como formato de saída em vez de Markdown e vejo cada vez mais outras pessoas no time do Claude Code usando isso. Aqui está o porquê.

(se você quiser começar com alguns exemplos, pode ver vários aqui: https://thariqs.github.io/html-effectiveness, mas volte para ler mais sobre o motivo)

Por que HTML?

Densidade de Informação

O HTML pode transmitir informações muito mais ricas em comparação com o markdown. Ele pode, é claro, fazer estrutura simples de documentos como cabeçalhos e formatação, mas também pode representar todos os tipos de outras informações, como:

• Dados tabulares usando tabelas
• Dados de design com CSS
• Ilustrações com SVG
• Trechos de código com tags script
• Interações usando elementos HTML com javascript + CSS
• Fluxos de trabalho usando SVG e HTML
• Dados espaciais usando posições absolutas e canvases
• Imagens usando tags de imagem

Eu diria que quase não existe conjunto de informações que o Claude possa ler que você não consiga representar de forma bastante eficiente com HTML. Isso o torna uma maneira altamente eficiente para o modelo comunicar informações detalhadas para você e para você revisá-las.

Descobri que, na ausência de poder fazer isso, o modelo pode fazer coisas mais ineficientes em markdown, como diagramas ASCII ou, meu favorito, estimar cores com caracteres unicode, como nesta captura de tela do Claude Code.

Claude Code tentando mostrar cores em markdown

Clareza Visual e Facilidade de Leitura

À medida que o Claude é capaz de fazer trabalhos mais complexos, ele também escreve especificações e planos cada vez maiores. Na prática, percebi que geralmente não leio um arquivo markdown com mais de 100 linhas e, certamente, não consigo fazer com que ninguém mais na minha organização o leia.

Mas documentos HTML são muito mais fáceis de ler. O Claude pode organizar a estrutura visualmente para ser ideal para navegação com abas, ilustrações, links, etc. Ele pode até ser responsivo para dispositivos móveis, para que você possa lê-lo de forma diferente dependendo do seu dispositivo.

Facilidade de Compartilhamento

Arquivos Markdown são relativamente difíceis de compartilhar, pois a maioria dos navegadores não os renderiza nativamente bem. Muitas vezes você precisa adicioná-los como anexos em e-mails ou mensagens.

Com HTML, desde que você faça o upload do arquivo (por exemplo, para o S3), você pode compartilhar o link facilmente. Seus colegas podem abri-lo onde quiserem e consultá-lo facilmente.

A chance de alguém realmente ler sua especificação, relatório ou descrição de PR é muito maior se estiver em HTML.

Interação Bidirecional

O HTML pode permitir que você interaja com o documento. Por exemplo, você pode pedir para adicionar controles deslizantes ou botões para ajustar um design ou permitir que você ajuste diferentes opções no algoritmo para ver o que acontece. Você também pode pedir para copiar essas alterações em um prompt para colar de volta no Claude Code.

Leia mais sobre meu post sobre playgrounds para ver exemplos dessa interação bidirecional: https://x.com/trq212/status/2017024445244924382

Ingestão de Dados

Por que usar o Claude Code para fazer arquivos HTML em vez do ClaudeAI ou Claude Design, por exemplo? Uma das maiores razões é todo o contexto que o Claude Code pode ingerir.

Por exemplo, ao escrever este artigo, pedi ao Claude Code que lesse minha pasta de código e encontrasse todos os arquivos HTML que gerei, os agrupasse e categorizasse, e então fizesse um arquivo HTML com todos os diagramas representando cada tipo. Os diagramas que você vê neste artigo são um resultado direto disso.

Além do sistema de arquivos, o Claude Code pode encontrar contexto adicional usando seus MCPs (como Slack, Linear, etc.), seu navegador da web (com o Claude no Chrome), seu histórico do git, etc.

É Prazeroso

Fazer documentos HTML com o Claude é simplesmente mais divertido e me faz sentir mais envolvido e investido na criação, e isso por si só já é suficiente.

Como Começar

Tenho um pouco de medo de que as pessoas leiam este artigo e o transformem em uma skill /html ou algo assim. Embora possa haver algum valor nisso, quero enfatizar que você não precisa fazer muito para que o Claude faça isso. Você pode simplesmente pedir para "fazer um arquivo HTML" ou "fazer um artefato HTML".

O truque é saber o que você quer que o artefato faça e como você pode usá-lo. Com o tempo, você pode criar uma skill, mas por enquanto sugiro apenas criar prompts do zero para pegar o jeito de como usá-lo em diferentes casos.

Casos de Uso

Para tornar isso mais concreto, fiz muitos arquivos HTML diferentes para diferentes casos de uso. Você pode ver todos eles aqui: https://thariqs.github.io/html-effectiveness/ mas aqui está uma visão geral.

Especificações, Planejamento e Exploração

HTML é uma tela rica para o Claude mergulhar em um problema. Quando começo a trabalhar em um problema, em vez de um plano simples em markdown, espero criar uma teia de arquivos HTML. Por exemplo, posso começar pedindo ao Claude Code para fazer um brainstorming e criar algumas explorações de diferentes opções. Depois, peço para expandir mais em uma delas, talvez fazer mockups ou trechos de código. Finalmente, quando me sinto bem, peço para escrever um plano de implementação. Quando estou satisfeito com o plano, crio uma nova sessão e passo todos esses arquivos para ele implementar.

Ao verificar, também peço ao agente de verificação para ler os arquivos e ele terá um contexto muito mais amplo sobre o que é necessário.

Exemplos de Prompts:

• Não tenho certeza de qual direção seguir para a tela de integração. Gere 6 abordagens claramente diferentes — varie layout, tom e densidade — e organize-as em um único arquivo HTML em uma grade para que eu possa compará-las lado a lado. Rotule cada uma com a compensação que ela está fazendo.
• Crie um plano de implementação detalhado em um arquivo HTML, certifique-se de fazer alguns mockups, mostre o fluxo de dados e adicione trechos de código importantes que eu possa querer revisar. Torne-o fácil de ler e digerir.

Casos de Uso:

• Explorar outras maneiras de implementar algo em código
• Explorar múltiplos designs visuais

Revisão e Compreensão de Código

Código pode ser difícil de ler em um arquivo Markdown. Mas com HTML podemos renderizar diffs, anotações, fluxogramas, módulos, etc. Use isso para entender o código que o agente escreveu, para obter uma revisão de código ou para explicar um PR para alguém que está revisando seu código. Acho que isso geralmente funciona melhor do que a visualização padrão de diff do Github, e agora anexo um explicador de código HTML a cada PR que faço.

Exemplo de prompt:

Ajude-me a revisar este PR criando um artefato HTML que o descreva. Não estou muito familiarizado com a lógica de streaming/backpressure, então foque nisso. Renderize o diff real com anotações nas margens, codifique as descobertas por cores de acordo com a gravidade e tudo mais que for necessário para transmitir bem o conceito.

Casos de Uso:

• Criar um PR
• Revisar um PR
• Entender um tópico no Código

Design e Protótipos

O Claude Design é baseado em HTML porque o HTML é incrivelmente expressivo para design, mesmo que sua superfície final não seja HTML. O Claude pode esboçar um design em HTML e depois escrevê-lo na linguagem de sua escolha, seja React, Swift, etc.

Você também pode prototipar interações, como animações, ações, etc. Considere pedir ao Claude para fazer controles deslizantes, botões, etc. para ajustar exatamente o que você está procurando.

Exemplo de prompt:

Quero prototipar um novo botão de checkout. Quando clicado, ele faz uma animação de "play" e depois fica roxo rapidamente. Crie um arquivo HTML com vários controles deslizantes e opções para eu testar diferentes opções nesta animação. Dê-me um botão de copiar para copiar os parâmetros que funcionaram bem.

Use isso para:

• Criar artefatos de sistema de design
• Ajustar componentes
• Visualizar bibliotecas de componentes
• Prototipar Animações Prazerosas

Relatórios, Pesquisa e Aprendizado

O Claude Code é incrivelmente bom em sintetizar informações de múltiplas fontes de dados e convertê-las em um relatório legível. Você pode pedir ao Claude para pesquisar seu Slack, sua base de código, histórico do git, a internet, etc. e usá-lo para gerar relatórios extremamente legíveis para você, para a liderança, para sua equipe, etc.

Você pode montar isso na forma de um longo documento HTML, um explicador interativo ou até mesmo uma apresentação de slides/deck. Peça ao Claude para usar SVG para diagramas para ajudar a visualizar.

Por exemplo, para meus posts sobre prompt caching, pedi ao Claude que preparasse um arquivo de pesquisa aprofundado em HTML para eu ler sobre todas as nossas mudanças no prompt caching após ler o histórico do git.

Exemplo de prompt:

Não entendo como nosso limitador de taxa realmente funciona. Leia o código relevante e produza uma única página explicativa em HTML: um diagrama do fluxo do token-bucket, os 3-4 trechos de código principais anotados e uma seção de "pegadinhas" no final. Otimize para alguém que está lendo uma vez.

Use isso para:

• Resumir como um recurso funciona
• Explicar um conceito para mim
• Relatórios de status semanais para seu chefe
• Relatórios de incidentes para sua liderança
• Ilustrações SVG, fluxogramas, diagramas técnicos, etc.

Interfaces de Edição Personalizadas

Às vezes é difícil descrever o que você quer puramente em uma caixa de texto. Nesse caso, peço ao Claude para construir um editor descartável para exatamente aquilo em que estou trabalhando. Não um produto, ou uma ferramenta reutilizável, mas um único arquivo HTML, construído especificamente para aquela peça de dados.

O truque é sempre terminar com uma exportação: um botão "copiar como JSON" ou "copiar como prompt" que transforma o que fiz na interface de volta em algo que posso colar no Claude Code.

Exemplos de prompts:

• Preciso repriorizar estes 30 tickets do Linear. Faça-me um arquivo HTML com cada ticket como um cartão arrastável nas colunas Agora / Próximo / Depois / Cortar. Pré-classifique-os pelo seu melhor palpite. Adicione um botão "copiar como markdown" que exporta a ordenação final com uma justificativa de uma linha por balde.
• Aqui está nossa configuração de feature flag. Construa um editor baseado em formulário para ela, agrupe as flags por área, mostre dependências entre elas, avise-me se eu ativar uma flag cujo pré-requisito está desligado. Adicione um botão "copiar diff" que me dá apenas as chaves alteradas.
• Estou ajustando este prompt de sistema. Faça um editor lado a lado: prompt editável à esquerda com os slots de variáveis destacados, três entradas de amostra à direita que re-renderizam o template preenchido ao vivo. Adicione um contador de caracteres/tokens e um botão de copiar.

Use isso para:

• Reordenar, triar ou categorizar qualquer coisa (tickets, casos de teste, feedback)
• Editar configurações estruturadas (feature flags, variáveis de ambiente, JSON/YAML com restrições)
• Ajustar prompts, templates ou textos com pré-visualização ao vivo
• Curar conjuntos de dados, aprovar/rejeitar linhas, marcar exemplos, exportar a seleção
• Anotar um documento, transcrição ou diff e exportar as anotações
• Escolher valores que são difíceis de expressar em texto: cores, curvas de easing, regiões de corte, cron schedules, regexes.

Perguntas Frequentes

Tenho falado para muitas pessoas sobre como mudei para HTML e vi algumas perguntas repetidas.

Não é menos eficiente em termos de tokens?

Embora o markdown geralmente use menos tokens, descobri que a expressividade adicional do HTML e a probabilidade muito maior de eu lê-lo resultam em uma saída geral melhor. Com a janela de contexto de 1MM no Opus 4.7, o aumento no uso de tokens não é realmente perceptível na janela de contexto.

Quando você usa markdown agora?

Honestamente, parei de usar markdown completamente para quase tudo, mas provavelmente estou no extremo maximalista do HTML.

Como faço para visualizar o arquivo HTML?

Costumo apenas abri-lo em um navegador localmente (você pode pedir ao Claude para abri-lo) ou fazer upload para o S3 se quiser um link compartilhável.

Isso não leva mais tempo para gerar do que markdown?

Isso leva mais tempo, sim! O HTML pode levar de 2 a 4 vezes mais tempo que o Markdown, mas descobri que os resultados valem a pena.

E o controle de versão?

Esta é honestamente uma das maiores desvantagens do HTML. Diffs de HTML são ruidosos e difíceis de revisar em comparação com Markdown.

Como faço para o Claude combinar com meu gosto / não deixar feio?

O plugin de design de frontend ajuda o Claude a fazer bons arquivos HTML. Mas para combinar com o estilo da sua própria empresa, você pode criar um único arquivo HTML de sistema de design apontando o Claude para sua base de código. Você pode então usar esse arquivo de sistema de design como referência para outros arquivos HTML.

Fique por Dentro

Tudo o que foi dito acima é para dizer que acho que a verdadeira razão pela qual uso HTML é que me sinto muito mais envolvido com o Claude. Eu tinha começado a temer que, por ter parado de ler planos em profundidade, simplesmente teria que deixar o Claude tomar suas próprias decisões.

Mas fico feliz em dizer que, em vez disso, me sinto mais envolvido do que nunca ao usar HTML. Espero que você também se sinta.