Como se comunicar 5x melhor com o Claude Code usando arquivos HTML

Se você usa Claude Code, Codex ou outro agente de codificação, já deve ter sentido o problema: o agente despeja um volume grande de informação em texto puro no terminal, espalhada ao longo da conversa, e fica difícil extrair o que realmente importa. A solução proposta neste tutorial é simples e eficaz — fazer o agente apresentar os resultados em arquivos HTML e diagramas, não em texto corrido.

Por que a comunicação com agentes é difícil

Há dois problemas centrais. O primeiro é a dispersão: o agente pode colocar informações importantes no meio da conversa e mais informações no final, sem que você consiga juntar tudo. O segundo é a formatação: texto puro sem quebras visuais cansa o cérebro humano, que processa muito melhor informação visual (títulos, negrito, imagens, diagramas) do que blocos contínuos de texto.

O autor relata usar essa técnica até 100 vezes por dia — pedindo aos agentes que apresentem achados em HTML em cerca de 90-95% dos casos.

A técnica: fazer o agente responder em HTML

Em vez de ler o resultado no terminal, peça ao agente para gerar um arquivo HTML. Ele pode incluir títulos, texto em negrito para o que é crítico, destaques, capturas de tela e diagramas. A informação fica muito mais rápida de absorver.

Para isso, o autor atualizou o arquivo Markdown de nível de usuário que é carregado em todos os seus agentes (funciona tanto no Claude Code quanto no Codex). A instrução é algo como:

Quando apresentar informações, sempre coloque no final da conversa.
Se for algo significativo (não uma tarefa simples), apresente em um
arquivo HTML e abra no meu navegador.

Ele também criou “skills” de HTML para cenários específicos — por exemplo, um test report que orienta o agente a listar cada tarefa separadamente, com link para a página de teste, passo a passo de verificação e o pedido original citado na íntegra.

Bônus: diagramas com Archify

Para entender o funcionamento de partes do sistema, o autor recomenda o pacote Archify (disponível no GitHub), que gera diagramas densos de informação. Um exemplo: entender o pipeline de processamento de documentos — classificação, OCR e extração de informações — fica muito mais claro em um diagrama do que em parágrafos de texto.

Prós e contras

✅ O que você ganha:

• Absorção mais rápida das informações do agente;
• Menos esforço cognitivo — você não precisa ler tudo;
• Revisão de implementações mais eficiente (aprovar/reprovar visualmente);
• Funciona com qualquer agente que aceite instruções via Markdown de usuário;
• Diagramas tornam arquiteturas e fluxos muito mais compreensíveis.

⚠️ O que você não ganha:

• Para tarefas muito simples, o overhead de gerar HTML pode ser desnecessário;
• Exige configurar o Markdown de usuário e, opcionalmente, criar skills;
• Não resolve agentes que omitem informação — só melhora a apresentação do que é dito.

Como aplicar no seu fluxo

1. Adicione a instrução ao seu arquivo de configuração de usuário do Claude Code/Codex.
2. Peça ao agente para apresentar resultados significativos em HTML e abrir no navegador.
3. Crie skills de HTML para relatórios recorrentes (test report, análise, revisão).
4. Use Archify para diagramas quando precisar entender fluxos e arquitetura.

Por que isso importa agora

À medida que o papel do desenvolvedor migra de escrever código para orquestrar uma frota de agentes, a comunicação eficaz com esses agentes vira a habilidade crítica. Quem domina a leitura rápida do que os agentes produzem toma decisões melhores e mais rápidas — e a apresentação visual da informação é o caminho mais curto para isso.