Adicione um Logger onde for difícil identificar o que aconteceu

Este caso de uso se aplica a fluxos de aplicativos para Mac em que saber que “algo aconteceu” é vago demais para diagnosticar o problema só pela revisão do código. Peça ao Codex que registre alguns eventos relevantes nos logs unificados para acompanhar um comportamento específico, execute o aplicativo, reproduza esse comportamento e confirme no Console ou com log stream que os eventos esperados ocorreram.

Use o plugin Build macOS Apps nesse ciclo. A habilidade de telemetria do macOS foi pensada para manter a instrumentação simples. Use o Logger da Apple, escolha nomes claros para o subsistema e a categoria, registre o início e o fim das ações e as transições de estado e evite incluir dados sensíveis. Depois de compilar e executar o aplicativo localmente, confirme que o evento foi registrado antes de concluir que a instrumentação funciona.

Por que a telemetria é útil na engenharia de software com agentes de IA

Com bons logs, o Codex pode repetir o mesmo ciclo de verificação após cada correção. Em vez de pedir que você inspecione manualmente cada janela, ação de menu ou transição de sincronização, o agente pode executar o aplicativo, percorrer o fluxo, examinar os logs filtrados e usar o que observou para decidir qual será a próxima alteração no código.

Isso é especialmente útil em três ciclos com agentes de IA:

• Depuração sem intervenção manual: o Codex instrumenta um fluxo em que pode haver uma falha, inicia o aplicativo, clica na barra lateral ou aciona um comando, lê a sequência de logs, corrige o trecho do código que atualiza o estado e repete o fluxo até que os logs correspondam ao comportamento da interface.
• Coleta de eventos de uma sessão do aplicativo: o Codex adiciona um evento para cada tipo de ocorrência: inicialização do aplicativo, abertura de janela, seleção na barra lateral, início da importação, conclusão da importação e falha na importação. Em seguida, executa uma sessão local e resume os eventos em ordem cronológica para que fique fácil identificar transições ausentes ou fora de ordem.
• Captura conduzida por você: o Codex inicia o aplicativo com os logs ativados e mantém um fluxo de logs filtrado enquanto você percorre manualmente um fluxo difícil de depurar. Depois, examina os registros da sessão e propõe a próxima correção com base neles.

Mantenha a instrumentação enxuta e os logs fáceis de filtrar

Peça ao Codex que use um logger por área funcional e evite adicionar uma linha de log permanente para cada alteração de estado. Categorias como Windowing, Commands, MenuBar, Sidebar, Sync ou Import facilitam a filtragem dos logs na próxima rodada de depuração.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import SwiftUI

struct SidebarItem { let id: String }
@MainActor private var selection: String?
import OSLog

private let logger = Logger(
  subsystem: Bundle.main.bundleIdentifier ?? "SampleApp",
  category: "Sidebar"
)

@MainActor
func selectItem(_ item: SidebarItem) {
  logger.info("Selected sidebar item: \(item.id, privacy: .public)")
  selection = item.id
}

Use info para registrar de forma concisa ações e eventos do ciclo de vida que continuarão úteis com o tempo. Use debug para detalhes do estado local que geram mais ruído e cujos registros podem ser removidos ou passar para um nível de log menos visível antes do fim da tarefa. Adicione marcadores de intervalo (signposts) somente quando precisar medir a duração de uma operação.

Peça ao Codex que confirme o evento nos logs

Adicionar chamadas a Logger é só o primeiro passo. Peça ao Codex que execute o aplicativo, acione o fluxo instrumentado e forneça o filtro exato do Console ou o predicado de log stream que usou, junto com uma ou duas linhas de log representativas.

log stream --style compact --predicate 'subsystem == "com.example.app" && category == "Sidebar"'

Se um evento esperado não aparecer, peça ao Codex que mova a chamada de log para mais perto do trecho do código onde pode estar o problema, execute o mesmo fluxo novamente e repita o processo até que os logs expliquem o que aconteceu. Se a investigação passar a exigir a análise de um encerramento inesperado ou de um rastreamento de pilha, use o fluxo de depuração do plugin para compilar e executar o aplicativo e mantenha a telemetria concentrada no início e no fim das ações.

Salve o rastreamento da sessão para uma execução posterior do Codex

Para bugs que levam mais tempo para investigar ou ocorrem de forma intermitente, peça ao Codex que salve um fluxo de logs filtrado em um pequeno arquivo de rastreamento local, resuma os eventos em ordem cronológica e deixe o arquivo no espaço de trabalho. Assim, em uma execução posterior, o Codex poderá examinar as mesmas evidências sem precisar reconstruir a sessão inteira de memória. Isso facilita a depuração em etapas quando você quer que o agente colete o rastreamento em uma execução e, em outra, compare o comportamento antes e depois de uma correção.

Essa abordagem também funciona bem quando você precisa conduzir parte da sessão. Peça ao Codex que inicie o aplicativo em um ciclo de depuração que facilite a coleta de logs, comece a captura com o filtro aplicado, aguarde enquanto você reproduz o problema manualmente e leia o arquivo de rastreamento salvo quando você terminar.

Dicas práticas

Instrumente uma funcionalidade por vez

Comece com uma única barra lateral, janela, comando ou rotina de sincronização para que a sequência de logs seja fácil de examinar. Se esse fluxo passar a funcionar de forma confiável, o Codex poderá aplicar o mesmo padrão a fluxos relacionados.

Inclua a privacidade no prompt

Peça ao Codex que explique cada identificador registrado e evite gravar segredos, dados pessoais ou conteúdo bruto nos logs unificados. Para depurar localmente, em geral bastam poucos tipos de evento.

Inclua exemplos de saída no resumo final

Linhas de log representativas dão mais confiança na alteração do que a simples afirmação de que “a telemetria foi adicionada”. Peça ao Codex que inclua o predicado usado no filtro e uma breve sequência cronológica das ações para que o agente possa repetir a mesma verificação na próxima execução.