Agent de Incidentes com Claude Code: investigar sem tocar em produção

English summary: A practical incident-commander workflow for using Claude Code to investigate production incidents without changing production: read-only access, explicit hypotheses, evidence packets, escalation gates, and postmortems that improve the next response.

Published: August 2026
Reading time: 20 min
Keywords: Claude Code, incident response, incident commander, read-only access, production safety, logs, diffs, evidence, escalation, postmortem

TL;DR

• Use o agent para investigar, não para alterar produção.
• Separe fatos, hipóteses, evidências e próximos gates.
• Escale qualquer side effect ou decisão irreversível.

Exemplo concreto: consultar logs de produção é investigação; reiniciar um serviço é um gate humano separado.

Às 02:17, a taxa de erro sobe, o dashboard fica vermelho e o canal do incidente começa a receber três explicações incompatíveis. Alguém sugere reiniciar os pods. Outra pessoa quer aumentar o timeout. Uma terceira encontra um deploy recente e conclui que ele é a causa. Nesse momento, um agent com acesso demais não reduz o risco: ele transforma uma hipótese apressada em ação real.

Um agent de incidentes útil tem outra função. Ele comprime a investigação, não a aprovação. Ele coleta sinais, separa fato de inferência, compara logs com diffs, registra hipóteses que podem ser derrubadas e prepara uma decisão que uma pessoa responsável consegue avaliar. Se a investigação aponta para produção, sua capacidade continua sendo leitura; a escrita permanece fora da sessão, em um executor humano ou pipeline com identidade controlada.

Minha tese é simples: Claude Code pode acelerar muito a resposta a incidentes quando é tratado como investigador read-only sob comando de um incident commander, e não como operador autônomo de produção. A maturidade não aparece quando o agent “resolveu” algo. Aparece quando todos conseguem reconstruir por que uma decisão foi tomada, qual evidência a sustentava, quem a aprovou e o que ainda não se sabia.

Esta é uma proposta de workflow, não uma promessa de que a ferramenta entende seu sistema. A sintaxe de permissões, hooks e opções de CLI pode mudar entre releases; as fontes oficiais ao fim foram verificadas para esta edição em agosto de 2026. Valide qualquer configuração na versão instalada antes de adotá-la durante um incidente real.

O que este agent é — e o que ele não é

Um agent de incidentes é um investigador que usa contexto e tools para reduzir incerteza numa situação aberta. A Anthropic define agentes como modelos que dirigem seu próprio processo e uso de tools para completar uma tarefa; isso é apropriado quando não dá para prever de antemão a sequência de consultas necessária (Trustworthy agents in practice). Um incidente é exatamente esse tipo de problema: o alerta raramente informa se a causa está no código, em uma dependência, no tráfego, numa configuração ou em dados.

Mas “agent” não significa “SRE de plantão sem supervisão”. O agent não é o incident commander (IC), não é dono do serviço, não recebe autoridade para declarar impacto de negócio e não executa mitigação. O IC continua coordenando pessoas, prioridade, comunicação e decisões. O dono do serviço continua aceitando risco técnico. A plataforma continua sendo dona de identidade, acesso e trilha de auditoria. O agent só torna a parte investigativa mais rápida e legível.

Há também situações em que um workflow simples é melhor. Se o alerta tem uma mitigação conhecida, reversível e já automatizada — por exemplo, trocar para uma réplica saudável por um runbook aprovado — use o workflow e a política existente. Não peça ao modelo para redescobrir uma sequência determinística sob pressão. Reserve o loop agentic para o que exige leitura, comparação e atualização de hipótese.

As quatro falhas que transformam investigação em risco

Antes de construir o harness, vale nomear os atalhos que parecem eficientes e falham no primeiro incidente confuso.

1. Dar credencial de operador “só para ajudar”

Uma credencial com escrita em produção faz qualquer regra local parecer frágil. CLAUDE.md pode dizer “não faça deploy”, mas isso ainda é texto. Uma regra do Claude Code pode bloquear um comando conhecido, mas não controla uma API chamada por uma tool externa, nem salva um token que já pode escrever em qualquer lugar.

O controle principal é identidade: use conta, role ou token separado, curto e read-only, limitado ao ambiente e aos recursos necessários. Quando possível, investigue uma réplica, um export sanitizado ou uma API de observabilidade que não exponha operações mutáveis. A documentação do Claude Code descreve permissões como uma camada para controlar tools; ela não substitui a autorização do sistema remoto (Identity and access management).

Pergunta de teste: se o agent interpretar tudo errado, qual é o pior efeito tecnicamente possível? Se a resposta for “ele pode mudar produção”, ainda não existe uma fronteira aceitável.

2. Confundir correlação temporal com causa

Um deploy às 02:10 e erros às 02:17 são uma pista, não um veredito. O mesmo intervalo pode conter tráfego anômalo, rotação de certificado, degradação de uma API externa, backlog de fila ou um alarme mal calibrado. O agent falha quando narra uma história plausível e o time a trata como evidência.

O antídoto é uma hipótese falsificável. Em vez de “o deploy quebrou checkout”, registre: “a versão abc123 adicionou uma chamada síncrona a risk-service; os erros 504 começaram no mesmo endpoint; se isso for causal, a latência de risk-service deve subir antes do aumento de 5xx, e requests sem esse caminho não devem piorar”. Agora existe uma consulta que pode enfraquecer ou fortalecer a explicação.

3. Logs sem janela, versão ou proveniência

Um trecho de log colado no chat parece concreto, mas pode ser de outro tenant, pod, região, release ou horário. Sem janela temporal, query, origem e filtro, ninguém consegue repetir a leitura. Pior: dados de log podem conter PII, segredos em mensagens de erro ou conteúdo controlado por usuário que tenta induzir o modelo.

Toda evidência precisa carregar proveniência mínima: fonte, intervalo em UTC, filtro, ambiente, release/commit quando aplicável e permalink ou identificador de consulta com acesso restrito. Não cole dumps intermináveis no contexto. Extraia contagens, amostras redigidas e linhas que testam a hipótese. Conteúdo externo é dado não confiável, não instrução para o agent.

4. Escalonamento depois da ação

“Pergunte antes de algo perigoso” é insuficiente às 03:00. Quem é o dono? O que ele precisa ver? O agent pode continuar consultando dados? Quem comunica o impacto? Sem uma condição objetiva de parada, a urgência empurra a ferramenta para a primeira ação disponível.

Defina stop conditions antes: qualquer escrita externa, alteração de tráfego, consulta que expõe dados sensíveis, suspeita de incidente de segurança, impacto financeiro, violação de SLO crítico ou ausência de evidência suficiente para escolher entre mitigação e espera. O agent monta o pacote de decisão e para. O IC escolhe o próximo passo com o dono apropriado.

O harness: contexto, tools, ambiente e observabilidade

O modelo não é o sistema inteiro. A Anthropic separa modelo, harness, tools e ambiente; uma configuração permissiva em qualquer uma dessas camadas pode anular a intenção das outras (Trustworthy agents in practice). Para resposta a incidentes, acrescente dois elementos explícitos: verificação e ownership.

Contexto: um contrato curto, não um prompt heroico

O contexto inicial deve incluir o identificador do incidente, serviço, ambiente, severidade, janela em UTC, sintomas conhecidos, links de dashboards e runbook, além de donos. Não inclua credenciais, tokens, dumps brutos, dados pessoais ou uma cópia de todos os documentos internos. Contexto demais dilui o sinal; contexto sensível aumenta o impacto de um erro.

O CLAUDE.md do workspace é o lugar para as invariantes reutilizáveis: produção é read-only, quais fontes são autorizadas, como rotular hipótese, quem é acionado por domínio e como encerrar uma investigação. Ele orienta o raciocínio; não deve ser a única barreira para comportamento crítico.

Tools: menor conjunto que responde às perguntas

Comece com leitura de repositório, git log, git show e git diff, mais ferramentas de observabilidade que só consultam dados. Evite uma tool genérica de shell com um perfil cloud de operador. Se um MCP expõe ação e leitura no mesmo servidor, prefira grants por tool, não pelo nome do servidor inteiro. A documentação do SDK/CLI permite restringir tools com --allowedTools e proibir ferramentas específicas com --disallowedTools; os nomes e a sintaxe devem ser conferidos contra a instalação atual (CLI reference).

Além da permissão do Claude Code, a API remota precisa aplicar o limite. Um token para logs deve não conseguir editar alertas. Uma role de banco deve não ter INSERT, UPDATE, DELETE, DDL ou acesso a tabelas fora do caso. Um token de GitHub de investigação não deve poder fazer push. Defesa em profundidade é o que torna a negativa relevante quando o modelo erra.

Ambiente: isole a investigação do caminho de execução

Use uma máquina, container ou workspace de investigação sem kubeconfig de escrita, sem chaves de deploy e sem diretórios de segredos montados. Faça o checkout do commit relevante ou clone espelhado read-only. Se houver dados de produção, use conta separada, auditoria do provedor e retenção curta. O objetivo não é “confiar mais no modelo em um container”; é reduzir as capacidades que simplesmente não precisam existir.

Claude Code oferece modo plan, que impede edição e execução de comandos, útil para raciocínio inicial; seu modo de permissões e comportamento exato devem ser verificados na documentação da release instalada (Identity and access management). Para investigação que precisa chamar apenas clientes read-only, prefira uma execução com allowlist pequena, credenciais incapazes de escrever e supervisão do IC. Não use --dangerously-skip-permissions como atalho em uma sessão conectada a produção; a referência da CLI o marca explicitamente como opção que pula prompts de permissão (CLI reference).

Verificação e observabilidade: o que fecha o loop

Cada ciclo deve produzir um fato novo, uma hipótese atualizada ou uma razão clara para escalar. “Li vários logs” não é resultado. Um registro útil diz: consulta, resultado agregado, o que a hipótese previa, se a previsão ocorreu e o próximo teste.

Para auditoria do agent, registre metadados suficientes para reconstruir o trabalho: ID do incidente, sessão, versão do contrato, tool chamada, fonte, intervalo, decisão, timestamp e IDs de links internos. Evite guardar prompt completo, output bruto, comando contendo segredo ou payload de cliente. Telemetria e logs do Claude Code podem ajudar a investigar uso, mas devem seguir política de privacidade e minimização; não são licença para copiar dados operacionais para uma nova base (Monitoring).