Agrega un Logger donde sea difícil saber qué ocurrió

Este caso de uso se aplica a flujos de apps para Mac en los que saber que “pasó algo” es demasiado impreciso para depurar el problema con solo revisar el código. Pídele a Codex que agregue unas pocas entradas al registro unificado en puntos clave de un comportamiento específico, ejecute la app, reproduzca ese comportamiento y verifique en Consola o con log stream que se produjeron los eventos esperados.

Usa el complemento Build macOS Apps para este ciclo. Su habilidad de telemetría para macOS se limita a lo esencial: usa Logger de Apple, elige una combinación clara de subsistema y categoría, registra el inicio y el fin de las acciones y los cambios de estado, y evita incluir datos sensibles. Después de compilar y ejecutar la app localmente, verifica que el evento aparezca en el registro en vez de dar por hecho que la instrumentación funciona.

Por qué la telemetría es útil en la ingeniería con agentes

Con buenos registros, Codex puede repetir el mismo ciclo de verificación después de cada parche. En lugar de pedirte que revises manualmente cada ventana, acción de menú o cambio de estado de sincronización, el agente puede ejecutar la app, probar el flujo, revisar los registros filtrados y decidir qué cambiar en el código según lo que observe.

Esto resulta especialmente útil en tres ciclos de trabajo con agentes:

• Depuración sin intervención manual: Codex instrumenta un flujo en el que sospecha que hay un problema, inicia la app, hace clic en la barra lateral o ejecuta un comando y lee las entradas del registro en orden. Luego corrige el código que actualiza el estado y repite el mismo flujo hasta que los registros coincidan con el comportamiento de la interfaz.
• Recopilación de eventos de una sesión de la app: Codex agrega un evento para cada uno de estos casos: inicio de la app, apertura de una ventana, selección en la barra lateral, inicio de una importación, finalización de la importación y error de importación. Luego ejecuta una sesión local y resume los eventos en orden cronológico para que sea fácil detectar si falta alguna transición o si ocurrió fuera de orden.
• Captura guiada por el usuario: Codex inicia la app con el registro habilitado y mantiene activo un flujo de registros filtrados mientras pruebas manualmente un flujo difícil de depurar. Después revisa la sesión capturada y propone el siguiente parche a partir de esa traza.

Limita la instrumentación y facilita el filtrado de los registros

Pídele a Codex que use un registrador por área funcional y evite dejar una línea de registro permanente para cada cambio de estado. Con categorías por función como Windowing, Commands, MenuBar, Sidebar, Sync o Import, es mucho más fácil filtrar los registros en la siguiente ronda de depuración.

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
}

Usa info para registrar de forma concisa acciones y eventos del ciclo de vida que seguirán siendo útiles con el tiempo. Usa debug para los detalles del estado local que generen más ruido y que puedas eliminar o pasar a un nivel de registro inferior antes de terminar la tarea. Agrega marcadores de intervalo solo cuando necesites medir una duración.

Pídele a Codex que confirme el evento con los registros

Además de agregar llamadas a Logger, pídele a Codex que ejecute la app y reproduzca el flujo instrumentado. Pídele que te muestre el filtro exacto que usó en Consola o el predicado que usó con log stream, junto con una o dos líneas representativas del registro.

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

Si un evento esperado no aparece, pídele a Codex que acerque la llamada de registro al punto del flujo de control donde sospecha que está el problema, vuelva a ejecutar el mismo flujo y repita el proceso hasta que los registros expliquen lo ocurrido. Si necesitas analizar un cierre inesperado o una traza de la pila de llamadas, usa el flujo de depuración del complemento para compilar y ejecutar la app, y concentra la telemetría en el inicio y el fin de las acciones.

Guarda la traza de una sesión para que Codex la revise más adelante

Si un error tarda en manifestarse o aparece de forma intermitente, pídele a Codex que guarde un flujo de registros filtrados en un archivo de traza local pequeño, resuma los eventos en orden cronológico y deje el archivo en el espacio de trabajo. Así, en una ejecución posterior, Codex podrá revisar la misma evidencia sin tener que reconstruir toda la sesión de memoria. Esto facilita la depuración en varias etapas cuando quieres que el agente recopile una traza en una ejecución y compare el comportamiento antes y después de un parche en otra.

También puedes usar este método cuando necesites controlar parte de la sesión. Pídele a Codex que inicie la app en un ciclo de depuración que facilite el registro de eventos, comience una captura filtrada, espere mientras reproduces el problema manualmente y lea el archivo de traza guardado cuando termines.

Consejos prácticos

Instrumenta una función a la vez

Empieza con una sola barra lateral, ventana, comando o ruta de sincronización para que la secuencia de registros sea fácil de revisar. Cuando ese flujo funcione de forma confiable, Codex podrá aplicar el mismo patrón a otros flujos relacionados.

Incluye la privacidad en el prompt

Pídele a Codex que explique cada identificador que registre y evite escribir secretos, datos personales o contenido sin procesar en los registros unificados. Para la depuración local suele bastar con unos pocos tipos de eventos.

Incluye ejemplos de la salida en el resumen final

Unas líneas representativas del registro dan mucha más confianza en el cambio que la frase “se agregó telemetría”. Pídele a Codex que incluya el predicado del filtro y una breve cronología de las acciones para que el agente pueda repetir el mismo ciclo de verificación en la siguiente ejecución.