Depurando um BadUSB Pi Zero 2W com Claude Code: Corrigindo um Bug 'Impossível'

Cerca de 10 meses atrás, um desenvolvedor montou um kit BadUSB com Pi Zero 2W, mas um recurso — "reset completo entre ataques" — nunca funcionou. Marcado como WIP, foi abandonado. Esta semana, eles reconstruíram o projeto do zero com Claude Code como programador-par. O resultado: o recurso "impossível" agora funciona, e a sessão revelou vários bugs sutis.

O que Claude Code fez

• Diagnosticou a causa raiz em uma leitura: O listener monitorava a existência de /dev/hidg0 — verdadeira desde a inicialização — então disparava payloads ao ligar, independentemente da conexão do host. O sinal correto é /sys/class/udc/<udc>/state == "configured".
• Confirmou empiricamente limitação de hardware: Quando a primeira correção não funcionou completamente, Claude acessou via SSH, pediu ao desenvolvedor para conectar/desconectar enquanto ele consultava sysfs e o registro regdump do dwc2 debugfs. Descobriu que o registro GOTGCTL congela em 0x000d0000 independentemente do estado do cabo — o Pi Zero 2W não tem VBUS sense ligado ao bloco OTG do SoC. Mudou para uma solução de desvinculação ativa com cooldown e proteção de taxa.
• Pegou um bug silencioso em Python: open(udc_path, "w").write("") não invoca write(2) com zero bytes — o TextIOWrapper do CPython omite a chamada. A desvinculação era um no-op por uma hora de testes. Corrigido para os.write(fd, b"\n") para forçar uma syscall.
• Corrigiu desmontagem proibida no configfs: rm -rf falhava porque o configfs proíbe desvincular arquivos de atributo gerenciados pelo kernel. A sequência correta é apenas rmdir, da folha para a raiz.
• Escreveu um conjunto de testes pytest com 34 testes contra um mecanismo HID simulado, permitindo testar o parser em qualquer host sem um Pi.
• Atualizou a memória da IA: O desenvolvedor usa Postgres como memória de longo prazo para Claude — essas entradas de bug agora são referenciadas em projetos similares de configfs/gadget USB.

Toda a sessão de trabalho levou cerca de 4 horas, principalmente esperando por conexões/desconexões físicas. O PR teve seis commits bem es-copados com tags de co-autor e um plano de teste. O projeto (Pi-Zero-2W-Bad-USB) é licenciado sob MIT, com linguagem de payload estilo Ducky-Script, variáveis, IF/WHILE, HOLD/RELEASE, INJECT MOD, RANDOM *, mapas de teclado US/UK, gadget de armazenamento em massa RO opcional, integração com systemd e instalador idempotente.

Para desenvolvedores que fazem workflows com hardware-in-the-loop com Claude Code, este é um estudo de caso convincente em depuração assistida por IA no nível de sysfs e registros.