Como os erros estão guiando o Harness Design System

Read on Medium (English)

Uma conversa hoje com o Gustavo Navarro, nosso Engineering Manager, e o Diogenes Vanzela, nosso Group Product Manager, me fez enxergar algo que estava na frente desde o início. O mapa do que precisamos documentar no Projeto Harness Design System já existia. Estava nos erros que Claude Code havia cometido nos meses anteriores.

O que os testes já tinham mostrado

Antes de termos esse projeto formalizado, já havíamos feito experimentos usando Claude Code para construir interfaces direto em código. Alguns resultados foram surpreendentemente bons. Outros revelaram problemas que eu não esperava.

O que funcionou foi o tipo de componente com padrão global: tabelas, headers, menus. Claude Code já viu esses elementos em milhares de codebases diferentes. Ele consegue inferir o que uma tabela é, como um menu se comporta. Não precisa de muita instrução porque o padrão existe fora do nosso sistema.

O que falhou foi outro tipo de componente.

Num projeto que testamos sem prototipação em Figma, Claude Code tentou construir telas que incluíam drawers e componentes mais complexos. Num componente que representa um diagrama de pneus, ele acertou algumas partes e destruiu outras. Informações ficaram pequenas demais, espaçamentos estreitos demais para qualquer legibilidade.

Nas listagens, usou checkbox dentro de um formato que não existe no nosso sistema. Criou indicadores em grid, segregando informação em caixas quando uma lista simples teria funcionado melhor. Em outro caso, gerou uma listagem de cards totalmente genérica, com cores que não faziam sentido e caixas de informação empilhadas sem refinamento nenhum.

O caso mais emblemático: sem encontrar nossa forma específica de tratar status, ele inventou a própria. Criou cards com fundo amarelo, vermelho ou verde dependendo da situação. Essa lógica não existe no nosso design system. Ele construiu do zero porque não encontrou nada para se referenciar.

O padrão por trás das falhas

Olhando para o conjunto de erros, um padrão ficou claro: Claude Code inventa quando não encontra.

Quando há um componente disponível e documentado, ele usa. Quando não há, ele cria. E o que ele cria revela exatamente o que está faltando na documentação.

O checkbox em listagem aponta que o padrão de listagem precisa de uma regra explícita de quando usar e quando não usar. Os cards coloridos por status mostram que nosso sistema de status não está documentado de forma acessível. A caixinha de informação ocupando uma linha inteira indica que não existe nenhuma orientação sobre otimização de espaço disponível para consulta.

Componentes estruturais com padrão global funcionam porque Claude Code tem referência suficiente do mundo externo. Componentes contextuais específicos do produto falham porque a única referência possível é o nosso sistema, e se ele não documenta bem, a LLM adivinha.

Como isso muda a priorização

No artigo anterior descrevi a lógica de priorizar pelo padrão de tela mais repetido: menu, topbar, header e tabela. Essa ancoragem ainda faz sentido como ponto de partida. A conversa de hoje adicionou uma segunda camada que estava faltando.

A primeira parte continua sendo os componentes da tela âncora. Menu aparece em praticamente cem por cento das telas do sistema. Claude Code já consegue construí-lo razoavelmente, mas ainda comete erros. Refinar a documentação o suficiente para eliminar esses erros tem impacto imediato em escala total. É o componente com maior retorno proporcional.

A segunda parte vai diretamente para onde os erros estão concentrados. Drawers são o caso mais crítico: substituem modais no nosso sistema, são usados extensivamente e Claude Code tem construído de forma totalmente aleatória. Às vezes acerta um layout parecido, na maioria das vezes erra muito.

Antes de assumir que o problema está na documentação, vamos testar mais. Preciso entender se Claude Code falha porque não encontrou o componente, porque a documentação existente é insuficiente, ou porque as instruções que fornecemos estavam incorretas. Cada causa tem uma solução diferente.

Uma recomendação para quem está começando

Nem todo time tem duas semanas de dedicação exclusiva em design system, e nem todo design system tem o problema específico que o nosso tinha com tokens desatualizados.

O que esse processo está sugerindo como entrada mais prática: comece usando uma LLM para construir interfaces reais no código. LLMs que entregam código aproveitável para produção, com o desenvolvedor no loop. Ferramentas de prototipação rápida ficam fora do que estou recomendando aqui.

Nesse processo, os erros vão aparecer. Cada um aponta para um gap específico na documentação. Você não precisa planejar o que documentar: a LLM mostra onde está o buraco.

Se você já tem experimentos feitos e casos de falha mapeados, como é o nosso caso agora, pode ir diretamente ao que está falhando e priorizar a partir daí. Se ainda não tem, teste primeiro, deixe a LLM falhar, e use os erros como mapa.

Isso não substitui o trabalho de fundação quando ele for necessário. Tokens desatualizados precisam ser resolvidos antes de qualquer camada de IA. A ordem importa. Com a fundação razoavelmente sólida, priorizar pelo erro pode ser o caminho mais rápido para gerar valor real na operação.

O que vem pela frente

O Projeto Harness Design System já está em andamento. Desenvolvedores React e Flutter, eu e o Glauber Franco, com foco total nisso por duas semanas. O objetivo é sair desse período com tokens aplicados no código, componentes da tela âncora refinados e um entendimento claro de onde os drawers estão falhando e como corrigir.

Não sei os resultados que vamos atingir. Em breve trarei as novidades.