Skills: Skill de Depuração
Última atualização: 2026-08-31
Depuração é a parte mais demorada do desenvolvimento — Skills solidificam a experiência de depuração para que cada solução de problema siga um método.
1. Tipos de Skills de depuração
(1) Diagnóstico de erros
Localizar a causa raiz a partir de mensagens de erro:
---
name: error-diagnoser
description: "Diagnosticar causa raiz a partir de mensagens de erro"
triggers:
- keyword: "error|bug|crash|exception|erro"
tools:
- Read
- Grep
- Glob
- Bash
---
(2) Análise de desempenho
Localizar gargalos de desempenho:
| Dimensão de análise | Ferramenta/Método | Saída |
|---|---|---|
| Hotspots de CPU | Saída do profiler | Ranking de tempo por função |
| Vazamentos de memória | Comparação de snapshot de memória | Localização de objetos vazados |
| Queries lentas | Análise de logs SQL | Lista de queries lentas |
| Tempo de inicialização | Marcadores de timestamp | Distribuição de tempo por fase |
(3) Análise de logs
Extrair pistas-chave dos logs:
## Fluxo de análise de logs
1. Leia o arquivo de log
2. Grep para palavras-chave ERROR/WARN
3. Extraia pilhas de exceção e linha do tempo
4. Correlacione entradas de log da mesma requisição
5. Exiba relatório de análise
2. Processo de depuração sistemático
(1) Método de depuração em quatro etapas
Quatro etapas da depuração
├── 1. Reproduzir
│ ├── Confirmar que o erro é reproduzível
│ ├── Registrar passos de reprodução
│ └── Restringir condições de reprodução
├── 2. Localizar
│ ├── Ler o stack trace do erro
│ ├── Buscar código relacionado
│ └── Confirmar a localização do problema
├── 3. Corrigir
│ ├── Analisar causa raiz
│ ├── Escrever código de correção
│ └── Adicionar verificações defensivas
└── 4. Verificar
├── Cenário de reprodução passa
├── Executar suíte completa de testes
└── Confirmar que não houve regressão
(2) Localização por busca binária
## Depuração por busca binária
1. Confirmar o intervalo de versões onde o problema existe
2. Bash: git bisect start
3. Restringir progressivamente ao commit específico
4. Read o diff daquele commit
5. Localizar a linha específica de código que introduziu o problema
(3) Depuração baseada em hipóteses
## Método de verificação de hipóteses
1. Listar possíveis hipóteses de causa (máximo 3)
2. Projetar método de verificação para cada hipótese
3. Verificar da mais provável para a menos provável
4. Verificação passa → Confirmar causa raiz
5. Verificação falha → Eliminar hipótese, reanalisar
3. Padrões de erro comuns
(1) Referência rápida de padrões de erro
| Tipo de erro | Assinatura típica | Direção de investigação |
|---|---|---|
| Ponteiro nulo | NoneType/null/undefined |
Verificar cadeia de atribuição de variáveis |
| Erro de tipo | TypeError/ClassCastException |
Verificar conversões e asserções de tipo |
| Problemas de concorrência | Falhas intermitentes | Verificar estado compartilhado e locks |
| Condições de contorno | Falha apenas com entrada específica | Verificar nulo, zero, valores extremos |
| Diferenças de ambiente | Funciona local, falha em produção | Verificar configuração, versões de dependências |
| Problemas de timing | Dependente de ordem | Verificar operações assíncronas e ordem de eventos |
(2) Leitura de mensagens de erro
Ordem de leitura do stack trace de erro:
1. Última linha: Tipo e mensagem do erro (mais crítica)
2. 2ª-3ª de baixo para cima: Pontos de chamada no seu código
3. Frames superiores: Cadeia de chamadas do framework/biblioteca
4. Primeira linha não-framework: O ponto de gatilho real
4. Skill de depuração na prática
▶ Exemplo: Skill de diagnóstico inteligente
Alice criou um Skill de diagnóstico automático de erros:
---
name: smart-debug
description: "Depuração sistemática: reproduzir→localizar→corrigir→verificar"
tools:
- Read
- Grep
- Glob
- Bash
- Edit
---
## Fluxo de depuração
1. Read a mensagem de erro e o stack trace
2. Grep para encontrar a localização da mensagem de erro no código
3. Read o código relacionado, analisar possíveis causas
4. Listar 3 hipóteses e verificar uma a uma
5. Após confirmar a causa raiz, use Edit para corrigir
6. Bash para executar testes de verificação
Bob disse: "O maior medo na depuração é 'tentar e ver' — você corrige algo sem saber por que funcionou, e o mesmo bug volta na próxima vez. Skills forçam você a passar pelo processo de hipótese→verificação, onde cada passo é baseado em evidências."
❓ Perguntas Frequentes
P: A depuração por IA é mais rápida que a manual? R: Muito mais rápida para erros padronizados (ponteiros nulos, erros de tipo, exceções comuns). Para problemas complexos de lógica de negócio, a IA pode restringir o escopo mas a localização final ainda precisa de julgamento humano. P: Como evitar que a IA dê direções erradas de depuração? R: Exija que a IA liste hipóteses e verifique uma a uma, em vez de pular direto para conclusões. Verifique cada passo da cadeia de raciocínio. P: Um Skill de depuração precisa de permissões de edição? R: A fase de diagnóstico precisa apenas de permissões somente leitura. A fase de correção requer Edit. Recomenda-se dividir em dois Skills: diagnóstico (somente leitura) + correção (leitura e escrita).
📖 Resumo
- Três tipos de Skills de depuração: diagnóstico de erros, análise de desempenho, análise de logs
- Processo de quatro etapas: reproduzir → localizar → corrigir → verificar
- Métodos de localização: análise de stack trace, busca binária, verificação de hipóteses
- Princípio central: entender antes de agir, baseado em hipóteses e não em tentativa e erro cega
📝 Exercícios
- Básico (dificuldade⭐): Crie um Skill de diagnóstico de erros que localize automaticamente posições de código a partir de stack traces de erro.
- Intermediário (dificuldade⭐⭐): Crie um Skill de depuração sistemática implementando o método de quatro etapas com verificação de hipóteses.
- Avançado (dificuldade⭐⭐⭐): Crie um Skill de análise de desempenho que localize gargalos a partir da saída do profiler, fornecendo sugestões de otimização com estimativa de impacto.
