# Agentes e skills para depuração e diagnóstico de erros

Encontrar a causa raiz: stack traces, logs, incidentes e fugas de memória.

Um bug raramente chega com etiqueta. Chega como um teste que falha apenas na integração contínua, um pedido que devolve erro 500 uma vez em cada mil, ou a memória que cresce durante a noite até o processo morrer. A parte difícil não é escrever a correção. É provar qual das dez hipóteses plausíveis está certa antes de tocar no código.

Os componentes desta página dão ao Claude Code um método em vez de palpites: reproduzir primeiro, ler o stack trace de baixo para cima, correlacionar logs entre serviços, isolar a alteração com git bisect e só depois propor a correção. Alguns investigam várias hipóteses em paralelo e citam ficheiro e linha como prova. Outros ligam a sessão aos dados reais de produção, no Sentry, no Grafana ou no Datadog.

Comece pelo mais simples. Se o erro é local e reprodutível, uma skill de método mais um agente depurador chegam para a maioria dos casos. Se o problema só acontece em produção, precisa de acesso às provas, portanto, instale primeiro o conetor da ferramenta que já usa. Investigação em paralelo e comandos de incidente fazem sentido quando o custo de estar parado é alto.


## Método de investigação e causa raiz

Componentes que impõem uma ordem ao diagnóstico: reproduzir, formular hipóteses, recolher provas e só depois corrigir. É por aqui que se começa.

- **debugger** (Agentes): Pega no erro concreto, logs e stack trace incluídos, e trabalha até identificar a causa raiz em vez de sugerir uma correção baseada no sintoma visível. [ficha](https://doutorai.pt/componentes/agents__debugger)
- **systematic-debugging** (Skills): Funciona como travão: aplica-se assim que aparece um bug, uma falha de teste ou comportamento inesperado, e impõe-se antes de qualquer proposta de correção. [ficha](https://doutorai.pt/componentes/skills__systematic-debugging)
- **debug-error** (Comandos): Percorre a metodologia completa passo a passo, desde recolher a mensagem de erro e montar um caso mínimo reprodutível até ler o stack trace da base para o topo. [ficha](https://doutorai.pt/componentes/commands__debug-error)
- **parallel-debugging** (Skills): Indicado para bugs em que existem várias causas possíveis e nenhuma óbvia: levanta hipóteses concorrentes, investiga-as em paralelo e arbitra qual sobrevive às provas. [ficha](https://doutorai.pt/componentes/skills__wshobson-agents__parallel-debugging)
- **team-debugger** (Agentes): Cada instância investiga uma única hipótese e devolve provas com ficheiro e linha, mais um nível de confiança. Serve para separar factos de suposições dentro da equipa. [ficha](https://doutorai.pt/componentes/agents__wshobson-agents__agents-team-debugger)
- **gsd:debug** (Skills): Mantém o estado da investigação mesmo quando o contexto da sessão é reiniciado, o que conta em bugs que levam horas ou vários dias a fechar. [ficha](https://doutorai.pt/componentes/skills__davepoon-subagents__debug)

## Logs, stack traces e dados de produção

Para quando o erro só acontece no servidor e as únicas provas disponíveis são logs, métricas e traces. Aqui a limitação costuma ser o acesso aos dados, não o raciocínio.

- **error-detective** (Agentes): Correlaciona erros entre serviços em vez de olhar para um de cada vez, o que ajuda quando a falha visível num sítio tem origem noutro completamente diferente. [ficha](https://doutorai.pt/componentes/agents__error-detective)
- **devops-troubleshooter** (Agentes): Cobre o lado operacional, com análise de logs, falhas de deployment e configuração de monitorização, para quando a suspeita recai na infraestrutura e não na aplicação. [ficha](https://doutorai.pt/componentes/agents__devops-troubleshooter)
- **Context** (Comandos): Lê mensagens de erro, stack traces e padrões de falha para chegar à causa, e sugere além da correção os passos de observabilidade que estavam em falta. [ficha](https://doutorai.pt/componentes/commands__wshobson-agents__commands-smart-debug)
- **sentry** (Conetores): Conetor MCP do Sentry, pensado para fluxos de programação com supervisão humana. Dá à sessão acesso aos erros já registados, em vez de os ter de descrever à mão. [ficha](https://doutorai.pt/componentes/mcps__sentry)
- **grafana** (Conetores): Liga o Claude Code aos painéis e à monitorização do Grafana, em instância própria ou no Grafana Cloud, para consultar o estado do sistema durante a investigação. [ficha](https://doutorai.pt/componentes/mcps__grafana)
- **datadog-cli** (Skills): Pesquisa logs, consulta métricas e segue traces de pedidos pela linha de comandos do Datadog. Faz sentido para quem já tem a observabilidade concentrada nessa ferramenta. [ficha](https://doutorai.pt/componentes/skills__datadog-cli)

## Incidentes em produção e análise pós-incidente

Com o sistema em baixo, o problema deixa de ser apenas técnico: é preciso classificar a gravidade, coordenar a resposta e registar depois o que se aprendeu.

- **incident-responder** (Agentes): Feito para o momento em que a produção vai abaixo: coordena a depuração, aplica a correção e deixa o post-mortem documentado em vez de o adiar indefinidamente. [ficha](https://doutorai.pt/componentes/agents__incident-responder-2)
- **incident-commander** (Skills): Traz o enquadramento SRE completo, com classificação de severidade, reconstrução da linha temporal e revisão pós-incidente. Também serve para montar escalas de prevenção num serviço novo. [ficha](https://doutorai.pt/componentes/skills__alirezarezvani-claude-skills__incident-commander)
- **postmortem-writing** (Skills): Escreve post-mortems sem procurar culpados, com causa raiz, cronologia e ações concretas. É a peça que evita repetir o mesmo incidente dentro de três meses. [ficha](https://doutorai.pt/componentes/skills__wshobson-agents__postmortem-writing)
- **pagerduty-incident-responder** (Agentes): Para equipas que já recebem alertas via PagerDuty: cruza o contexto do incidente com as alterações recentes de código e propõe a correção em pull request no GitHub. [ficha](https://doutorai.pt/componentes/agents__pagerduty-incident-responder)

## Regressões, testes instáveis e fugas de memória

Três famílias de bugs com diagnóstico próprio, onde a pergunta não é o que está errado, mas desde quando, ou onde é que a memória fica presa.

- **git-bisect-helper** (Comandos): Conduz sessões de git bisect automatizadas com execução de testes em cada passo, para responder à pergunta de qual foi o commit que causou a falha. [ficha](https://doutorai.pt/componentes/commands__git-bisect-helper)
- **test-runner** (Agentes): Corre a suite, lê os resultados e diagnostica a causa das falhas, entregando correções concretas em vez de um relatório com testes a vermelho. [ficha](https://doutorai.pt/componentes/agents__test-runner)
- **Test Debugger Agent** (Agentes): Especializado em testes Playwright instáveis ou a falhar, com uma taxonomia sistemática que separa um teste mal escrito de um bug verdadeiro na aplicação. [ficha](https://doutorai.pt/componentes/agents__alirezarezvani-claude-skills__agents-test-debugger-09996b)
- **performance-profiler** (Agentes): Ataca estrangulamentos de desempenho e fugas de memória com testes de carga e monitorização, para quando a aplicação não rebenta, mas se vai degradando ao longo do dia. [ficha](https://doutorai.pt/componentes/agents__performance-profiler)
- **optimize-memory-usage** (Comandos): Deteção de fugas, afinação da recolha de memória (garbage collection) e análise de perfil de memória reunidos num só comando. Aplica-se quando o processo cresce até ter de ser reiniciado. [ficha](https://doutorai.pt/componentes/commands__optimize-memory-usage)

## Como instalar e onde cada peça encaixa

Agentes, skills e comandos são ficheiros Markdown que vivem no seu repositório, dentro de .claude/agents/, .claude/skills/ e .claude/commands/. Copie o ficheiro para a pasta certa e o Claude Code passa a reconhecê-lo na sessão seguinte: agentes e skills ativam-se pela descrição, os comandos invocam-se com barra. Os conetores MCP funcionam de outra maneira, exigem uma entrada no ficheiro de configuração e credenciais próprias, por exemplo o URL da instância e um token de conta de serviço no caso do Grafana. Comece por um agente depurador e uma skill de método. Acrescente conetores só quando precisar mesmo de dados de produção dentro da sessão.

## Uma ordem de trabalho que evita correções às cegas

A ordem importa mais do que a ferramenta escolhida. Primeiro reproduza: sem um caso mínimo que falhe de forma consistente, qualquer correção é um palpite. Depois recolha as provas: o stack trace completo, os logs de antes e depois do erro, o ambiente em que acontece. Só então formule hipóteses, e se houver mais do que uma plausível vale a pena investigá-las em paralelo em vez de as testar por ordem. Se o problema é recente e o código antigo funcionava, o bisect responde mais depressa do que a leitura do código. A correção fica para o fim, acompanhada de um teste que falhava antes e passa agora.

## Limites do que estes componentes conseguem ver

Nenhum destes componentes vê aquilo que não lhe for dado. Um agente depurador trabalha sobre o código, os logs e os testes a que tem acesso. Se o erro só se manifesta com dados reais ou sob carga, terá de ligar a sessão à sua ferramenta de observabilidade ou reproduzir o cenário localmente. Os conetores MCP levantam ainda a questão do acesso: um token do Sentry ou do Grafana dá leitura sobre informação sensível, portanto, utilize contas de serviço com permissões mínimas. E desconfie sempre de uma causa raiz apresentada sem prova, peça o ficheiro, a linha e o teste que a confirma.

## Perguntas frequentes

### Qual é a diferença entre um agente depurador e uma skill de depuração?

O agente é um executor com contexto próprio: recebe o problema, investiga e devolve um diagnóstico. A skill é conhecimento que altera a forma como o Claude Code aborda a tarefa, por exemplo, ao obrigar a reproduzir o erro antes de propor correções. Na prática usam-se em conjunto, a skill define o método e o agente faz o trabalho.

### Preciso mesmo de um conetor MCP para depurar?

Não, se o bug for reprodutível na sua máquina. Conetores como o Sentry, o Grafana ou o Datadog compensam quando a prova está fora do repositório, em erros registados, métricas ou traces de produção. Exigem credenciais e configuração, portanto, adicione-os quando a falta de dados for mesmo aquilo que o está a bloquear.

### Como devo tratar um teste que falha de forma intermitente?

Trate-o como um bug e não como ruído. Um agente dedicado a testes instáveis classifica a falha antes de a corrigir: pode ser uma espera mal feita, dependência entre testes, estado partilhado ou uma condição de corrida real na aplicação. Voltar a correr o teste até passar esconde o problema em vez de o resolver.

### Vale a pena investigar várias hipóteses ao mesmo tempo?

Vale quando o custo de estar parado é alto e existem causas plausíveis em áreas diferentes, por exemplo, base de dados, cache e rede. Cada investigação recolhe provas para confirmar ou eliminar a sua hipótese e no fim comparam-se os resultados. Para um bug pequeno e bem localizado é trabalho a mais.

### O que vale a pena guardar depois de resolver um incidente?

A cronologia, a causa raiz, o impacto real e as ações que ficam por fazer. Um post-mortem sem procura de culpados é o que transforma uma noite má em material reutilizável e serve de base ao runbook da próxima vez. Sem esse registo, a mesma falha volta e a investigação recomeça do zero.


Fonte: https://doutorai.pt/para/depuracao-de-erros - Doutor AI, selecao feita a mao da biblioteca tecnica.