Depurador Interativo

Quando Usar

Use esta habilidade quando precisar depurar código-fonte interativamente — definir pontos de interrupção, percorrer a execução linha por linha, inspecionar o estado de variáveis em tempo real, avaliar expressões contra o programa em execução e navegar pela pilha de chamadas para rastrear as causas raiz. Use quando um programa travar, gerar exceções inesperadas, produzir...

Use quando um programa travar, produzir saída incorreta ou você precisar entender exatamente como a execução chegou a um determinado estado — e executá-lo novamente com mais instruções print não fornecer a resposta rápido o suficiente.

Você pode pausar um programa em execução a qualquer momento, ler os valores das variáveis em tempo real e a pilha de chamadas naquele exato momento, avançar linha por linha ou pular para o próximo ponto de interrupção, e avaliar expressões arbitrárias contra o processo em tempo real — tudo sem reiniciar.

Configuração

Esta habilidade usa dap, uma ferramenta CLI que atua como um daemon em segundo plano para interagir com o depurador via Protocolo DAP, mantendo o estado do depurador, para que você possa simplesmente interagir com ele com várias chamadas.

Se dap não estiver instalado (verifique: command -v dap), instale-o AGORA. Pergunte/notifique o usuário antes de prosseguir com a instalação.

Via Homebrew (macOS)

brew install AlmogBaku/tap/dap

Script instalador:

bash scripts/install-dap.sh

Instalar a partir das fontes:

go install github.com/AlmogBaku/debug-skill/cmd/dap@latest

Esta ferramenta é de código aberto e está disponível no GitHub, mantida e segue as melhores práticas.

Suporta nativamente Python, Go, Node.js/TypeScript, Rust, C/C++, e qualquer outra linguagem que suporte DAP.

Se um backend de depurador estiver faltando ou falhar ao iniciar, consulte references/installing-debuggers.md

Para todos os comandos e flags: dap --help ou dap <cmd> --help.

Iniciando uma Sessão

dap debug <file> inicia o programa sob o depurador. O backend é detectado automaticamente pela extensão do arquivo.

Escolha sua estratégia de início com base no que você sabe:

• Tem uma hipótese — defina um ponto de interrupção onde você espera o bug: dap debug script.py --break script.py:42
• Ponto de interrupção condicional — pare apenas quando uma condição for atendida: dap debug script.py --break "script.py:42:x > 5" ( sempre coloque as especificações com condições entre aspas)
• Aplicativo com múltiplos arquivos — pontos de interrupção entre módulos: --break src/api/routes.py:55 --break src/models/user.py:30
• Sem hipótese, programa pequeno — percorra desde a entrada: dap debug script.py --stop-on-entry (evite para projetos grandes — o código de inicialização é barulhento; use bissecção com pontos de interrupção em vez disso)
• Exceção, localização desconhecida — dap debug script.py --break-on-exception raised (Python) / all (Go/JS)
• Processo remoto — dap debug --attach host:port --backend <name>
• Processo já em execução (servidor travado, problema ativo) — anexe sem reiniciar: dap debug --pid <PID> --backend <name>

  Observação sobre macOS + Go: dlv --pid requer SIP desativado (csrutil disable). Prefira iniciar o programa sob o depurador em vez disso ou anexe a um depurador remoto!

Isolamento de sessão: --session <name> impede que agentes concorrentes interfiram. Dica: Você pode querer usar o ID da sua sessão (${CLAUDE_SESSION_ID}) se disponível.

Execute dap debug --help para ver todas as flags, backends e exemplos.

A Mentalidade de Depuração

Recorra a um depurador quando a leitura do código-fonte sozinha não puder validar a causa raiz. Um depurador permite que você observe o que acontece: valores reais, caminho real, estado real. Quando isso diverge do que deveria acontecer, você encontrou seu bug.

Duas tentativas falhas, repense. Se duas hipóteses falharem no mesmo local, seu modelo mental está errado. Releia o código, forme uma teoria completamente diferente com pontos de interrupção diferentes.

Escalone gradualmente. Comece com dap eval para testar uma hipótese rápida. Use pontos de interrupção condicionais para filtrar o ruído. Volte para pontos de interrupção completos + percorrer apenas quando precisar de controle interativo.

Imite a jornada do usuário. Se você estiver depurando um fluxo de usuário, defina pontos de interrupção ao longo do caminho que você espera que o código siga. Se você esperava que compute() fosse chamado, mas ele nunca é, então o bug está no chamador — não em compute(), mas no que quer que fosse suposto chamá-lo.

Defina pontos de interrupção em vez de prints. Quando sentir a vontade de imprimir algo, defina um ponto de interrupção em vez disso.

Conheça Seu Estado

Cada comando de execução dap retorna o contexto completo automaticamente: localização atual, código-fonte, variáveis locais, pilha de chamadas e saída. A cada parada, pergunte:

• As variáveis locais têm os valores que eu esperava?

…