Explicações interativas – Padrões de Engenharia Agentetica

Quando perdemos a noção de como funciona o código escrito por nossos agentes, assumimos dívida cognitiva.

Para muitas coisas isso não importa: se o código busca alguns dados de um banco de dados e os gera como JSON, os detalhes da implementação são provavelmente simples o suficiente para que não precisemos nos preocupar. Podemos experimentar o novo recurso e adivinhar como ele funciona e, em seguida, dar uma olhada no código para ter certeza.

Muitas vezes, embora os detalhes realmente importem. Se o núcleo do nosso aplicativo se tornar uma caixa preta que não entendemos completamente, não poderemos mais raciocinar com segurança sobre isso, o que dificulta o planejamento de novos recursos e eventualmente retarda nosso progresso da mesma forma que a dívida técnica acumulada.

Como pagamos a dívida cognitiva? Melhorando nossa compreensão de como o código funciona.

Uma das minhas maneiras favoritas de fazer isso é construindo explicações interativas.

Compreendendo as nuvens de palavras

Em Um cético de codificação de agente de IA tenta a codificação de agente de IA, com detalhes excessivos, Max Woolf mencionou testar as habilidades Rust dos LLMs com o prompt Create a Rust app that can create "word cloud" data visualizations given a long input text.

Isso capturou minha imaginação: sempre quis saber como funcionam as nuvens de palavras, então iniciei um projeto de pesquisa assíncrono – prompt inicial aqui, código e relatório aqui – para explorar a ideia.

Isso funcionou muito bem: Claude Code para web criou para mim uma ferramenta Rust CLI que poderia produzir imagens como esta:

Mas como isso realmente funciona?

O relatório de Claude disse que usa “Colocação da espiral de Arquimediana com deslocamento angular aleatório por palavra para layouts de aparência natural”. Isso não me ajudou muito!

Solicitei um passo a passo linear da base de código que me ajudou a entender o código Rust com mais detalhes – aqui está o passo a passo (e o prompt). Isso me ajudou a entender a estrutura do código Rust, mas eu ainda não tinha uma compreensão intuitiva de como a parte do “posicionamento da espiral de Arquimedes” realmente funcionava.

Então eu pedi um explicação animada. Eu fiz isso colando um link para aquele existente walkthrough.md documento em uma sessão do Claude Code junto com o seguinte:

Busque https://raw.githubusercontent.com/simonw/research/refs/heads/main/rust-wordcloud/walkthrough.md para /tmp usando curl para que você possa ler tudo Inspirado nisso, crie uma palavra animada-cloud.html – uma página que aceita texto colado (que persiste no `#fragment` do URL de forma que uma página carregada com aquele `#` preenchido usará esse texto como entrada e o enviará automaticamente) de modo que, quando você envia o texto, ele cria uma nuvem de palavras usando o algoritmo descrito naquele documento, mas é animado, para tornar o algoritmo o mais claro possível. Inclua um controle deslizante para a animação que pode ser pausado e a velocidade ajustada ou até mesmo percorrida quadro a quadro durante a pausa. A qualquer momento, a nuvem de palavras visível em andamento pode ser baixada como PNG.

Você pode brincar com o resultado aqui. Aqui está uma demonstração de GIF animado:

Isso foi usando Claude Opus 4.6, que acaba tendo bastante bom gosto na hora de construir animações explicativas.

Se você observar a animação com atenção, poderá ver que, para cada palavra, ela tenta colocá-la em algum lugar da página, mostrando uma caixa e verifica se essa caixa cruza uma palavra existente. Nesse caso, ele continua tentando encontrar um bom ponto, movendo-se em espiral a partir do centro.

Descobri que essa animação realmente ajudou a fazer com que o algoritmo funcionasse para mim.

Há muito tempo sou fã de animações e interfaces interativas para ajudar a explicar diferentes conceitos. Um bom agente de codificação pode produzi-los sob demanda para ajudar a explicar o código – seu próprio código ou código escrito por terceiros.