Você inicia três agentes de codificação em três tarefas e, em seguida, passa os vinte minutos seguintes alternando entre abas de terminal tentando responder a uma pergunta: qual deles precisa de mim agora? Um ainda está em execução. Um está esperando por um y/n que você nunca viu. Um terminou com sucesso há uma hora e, silenciosamente, construiu a coisa errada. Nada lhe disse nada disso. Você teve que ir procurar.
Essa lacuna é o que a observabilidade de agentes de codificação deve preencher. Observabilidade, emprestada da engenharia de sistemas, é a capacidade de entender o que um processo em execução está fazendo a partir dos sinais que emite, sem se conectar diretamente a ele (O OpenTelemetry tem um bom guia introdutório). Para agentes de codificação, o padrão: você deve ser capaz de responder “o que cada agente está fazendo, o que falhou e o que precisa de um humano” a partir de uma visão compartilhada, não de acompanhar uma sessão. A maioria das configurações não consegue. Elas têm um status em algum lugar e um log em outro e chamam isso de observabilidade. Não é.
Este artigo percorre os três sinais que um agente de codificação realmente emite, quais sinais de falha valem a pena configurar um alerta e onde uma camada de tarefas compartilhada como o Sharkly transforma a saída bruta em algo acionável. O Sharkly fica acima dos agentes que você já executa; você já tem agentes de codificação, e o ponto aqui é tornar o trabalho deles legível quando há mais de um.
Status, logs e sinais de falha são três coisas diferentes
Essas três palavras são usadas de forma intercambiável, e a confusão é a raiz da maioria das configurações de monitoramento ruins. Elas respondem a perguntas diferentes.
Status é o estado resumido de uma execução. Em execução, aguardando entrada, concluído ou falhou. É um único campo, barato de ler, e informa onde uma execução está, não o que ela fez. Um status não é observabilidade; é o menor fato sobre uma execução.
Logs são o rastro bruto de execução. Cada chamada de ferramenta, edição de arquivo e resposta do modelo, em ordem. Os logs informam o que aconteceu depois que você já sabe que algo deu errado. São indispensáveis para uma análise post-mortem e inúteis como sinal ao vivo, porque ninguém observa cinco logs rolando ao mesmo tempo. Um log não é um sinal até que algo extraia significado dele.
Sinais de falha são alertas derivados. Eles são as condições específicas que valem a pena interromper você: um agente travado, uma execução que terminou com sucesso na direção errada, um orçamento que acabou no meio da tarefa. Um sinal de falha é o que você realmente quer, e é a camada que quase toda configuração feita manualmente pula, porque derivá-lo significa processar logs em eventos em vez de apenas armazená-los.
A armadilha é parar nas duas primeiras. Status mais logs parece observabilidade porque você tem um estado e um registro. Mas a única pergunta que escala, “qual dos meus agentes precisa de mim?”, vive inteiramente na terceira camada.
Os sinais de falha que realmente importam
A observabilidade de serviços web monitora travamentos e latência. Agentes de codificação falham de maneira diferente, e as falhas que custam uma tarde raramente são as que aparecem como um status vermelho. Estes são os sinais que vale a pena derivar.
| Sinal | O que significa | Por que status e logs não detectam |
|---|---|---|
| Parada silenciosa | O agente está esperando por um prompt ou um segredo ausente, sem produzir saída | O status ainda lê “em execução”; nada levanta a mão |
| Sucesso, mas errado | A execução terminou com sucesso e fez a coisa errada | O status é “concluído”; apenas ler o diff revela isso |
| Verificação ignorada | Reportou conclusão sem executar typecheck, testes ou a build | Os logs contêm a omissão, mas ninguém lê um log de sucesso |
| Esgotamento do orçamento | Cota do modelo ou limite de gastos atingido no meio de uma tarefa | A falha surge como uma resposta truncada, não como um alerta |
| Conflito latente | Dois agentes editaram os mesmos arquivos em worktrees separadas | Ambas as execuções estão “concluídas”; a colisão espera no merge |
| Edição em loop | O agente edita, reverte e edita novamente o mesmo arquivo em um loop | Cada passo individual parece bom no log |
O padrão nos seis: a falha é invisível na camada de status e está enterrada na camada de logs. “Sucesso, mas errado” é o que as pessoas mais subestimam. Um agente de codificação que termina confiantemente a tarefa errada parece idêntico a um que acertou em cheio, até que a revisão com evidências no nível da tarefa o detecte. A observabilidade que apenas relata códigos de saída reportará essa falha como um sucesso.
Dois deles são estruturais, não comportamentais. Conflitos latentes são a razão pela qual o trabalho paralelo no mesmo repositório precisa de worktrees isoladas por tarefa, para que sobreposições de arquivos apareçam antes do merge, e não durante. O esgotamento do orçamento é a razão pela qual acompanhar os gastos entre agentes pertence à mesma visão que o status; uma execução que parou silenciosamente porque ficou sem cota é um sinal de falha, não uma tarefa concluída.
Quanta observabilidade você precisa, por tamanho de equipe
Você não precisa dos seis sinais no primeiro dia. A quantidade certa de instrumentação escala com quantos agentes executam e quantas pessoas precisam vê-los.
| Configuração | O que instrumentar | Onde falha |
|---|---|---|
| Um agente, uma tarefa | Apenas status; leia o log se falhar | Nada, até você iniciar um segundo agente |
| Vários agentes individuais | Status por execução, mais sinais de parada e de sucesso, mas errado | Você infere o estado do silêncio e perde as paradas |
| Equipe pequena, repositórios compartilhados | Todos os seis sinais, mais estado de revisão, em uma visão compartilhada | Seu monitoramento vive em um laptop que ninguém mais pode ver |
| Equipe maior, muitos repositórios | O acima, mais propriedade por execução, orçamento e trilha de auditoria | Ninguém consegue responder “quem executou o quê” uma semana depois |
A leitura honesta: um desenvolvedor solo executando um agente em trabalho não relacionado tem toda a observabilidade de que precisa em um único terminal. A equação muda no momento em que os agentes superam suas telas, o trabalho é executado em máquinas onde você não está sentado, ou outra pessoa precisa ver o mesmo painel. Passada essa linha, um campo de status e um diretório de logs deixam de ser suficientes.
Quando logs brutos e um único runtime são suficientes
Dê às ferramentas integradas sua melhor versão, porque para muito trabalho elas vencem. Claude Code e Codex mantêm um rastro de sessão legível, e para um único agente em uma única tarefa, esse rastro é sua observabilidade. Você o iniciou, está observando, lerá o log se ele parar. Adicionar uma camada de gerenciamento aí é puro overhead.
Use a saída do próprio runtime quando você executa um ou dois agentes, em trabalho não relacionado, que nunca é repassado a mais ninguém. Recorra a uma camada de observabilidade compartilhada quando as execuções superarem sua atenção, quando elas executarem em algum lugar que você não pode acompanhar, ou quando a revisão tiver que se tornar uma atividade de equipe em vez de privada. Esse último caso é o assassino silencioso: cinco agentes terminando em paralelo não é uma vitória se a revisão de seus diffs serializar de volta em uma fila de uma pessoa. Os agentes ficaram mais rápidos; você ficou mais lento. Isso também é um problema de observabilidade, e nenhum runtime sozinho resolve, porque o sinal que importa, “esta execução terminou e está aguardando sua revisão”, vive entre agentes, não dentro de um.
Observabilidade quando os resultados retornam à Tarefa
Uma camada de tarefas muda a unidade de observabilidade de “um processo em um painel” para “uma Tarefa com um estado”. Essa é a mudança em torno da qual o Sharkly foi construído, e ela mapeia todos os três sinais de uma só vez.
Cada execução de agente se anexa a uma Tarefa. Status, progresso, bloqueios e resultados retornam à linha do tempo dessa Tarefa em vez de viverem em um log que só você pode ver. Os sinais de falha surgem em um só lugar: as execuções que precisam de um humano chegam à Caixa de entrada, então a pergunta deixa de ser “algo terminou?” e passa a ser “aqui está o que precisa da minha decisão”. Agentes pesquisam, executam, testam e relatam; pessoas definem a direção, concedem autoridade e aceitam o resultado. A automação para onde o julgamento da equipe é necessário.
A fronteira importa, porque é fácil presumir errado. O Sharkly não executa o agente nem escreve o código. Claude Code, Codex e os outros runtimes que você já usa ainda fazem a execução. O Sharkly adiciona a tarefa compartilhada, o Computador, o contexto e a camada de revisão ao redor deles, para que contexto, progresso, bloqueios, resultados e revisão humana permaneçam visíveis da solicitação à entrega. Para uma visão mais completa do que esse painel compartilhado deve mostrar, veja o que um dashboard de agente de codificação de IA realmente precisa, e para o ângulo de monitoramento ao vivo, como monitorar agentes de codificação em execução paralela.
Se você quer continuar usando múltiplos agentes de codificação em vez de se comprometer com um único ecossistema, essa visão compartilhada e focada em sinais é o problema em torno do qual o Sharkly foi projetado. Você pode executar seus agentes de codificação existentes através do Sharkly e manter todos os runtimes que já usa.
Perguntas frequentes
A observabilidade de agentes de codificação é o mesmo que logging? Não. O logging armazena o que aconteceu. A observabilidade é ser capaz de responder o que cada agente está fazendo, o que falhou e o que precisa de você, sem ler esses logs um por um. Os logs são uma entrada para a observabilidade, não o todo dela.
Qual é o sinal de falha mais importante para instrumentar primeiro? A parada silenciosa. Um agente que lê “em execução” enquanto espera para sempre por um prompt que você nunca viu é a maneira mais comum de o trabalho paralelo morrer silenciosamente. Faça com que execuções bloqueadas levantem a mão antes de perseguir qualquer coisa mais sofisticada.
Posso obter isso da saída integrada do meu agente de codificação? Para um agente, sim. O rastro de sessão do próprio runtime é suficiente. A saída integrada não tem uma visão entre agentes, então não pode dizer qual de cinco execuções precisa de você, que é exatamente a pergunta que aparece quando você escala além de um.
