디버깅이 모호해지는 지점에 Logger 하나 추가하기

이 사용 사례는 코드 검토만으로는 ‘무언가 일어났다’는 설명이 너무 모호한 Mac 앱 플로우를 위한 것입니다. Codex에 특정 동작 주변에 핵심 정보가 담긴 통합 로그 몇 개를 추가하도록 요청한 뒤 앱을 실행하고 해당 동작을 트리거하세요. 그런 다음 예상 이벤트가 발생했는지 Console이나 log stream에서 확인합니다.

이 루프에는 Build macOS Apps 플러그인을 사용하세요. 이 플러그인의 macOS 텔레메트리 스킬은 의도적으로 가볍게 설계되었습니다. Apple이 제공하는 Logger를 사용하고, 명확한 서브시스템/카테고리 조합을 선택하고, 동작 경계와 상태 전환을 기록하고, 민감한 페이로드는 피하세요. 계측이 올바르게 연결되었다고 가정하지 말고 로컬 빌드/실행 후 이벤트를 확인하세요.

에이전트 기반 엔지니어링에 텔레메트리가 유용한 이유

잘 설계된 로그는 각 패치 후 Codex가 반복해서 활용할 수 있는 피드백 루프를 제공합니다. 모든 창, 메뉴 동작 또는 동기화 전환을 일일이 직접 확인할 필요 없이 에이전트가 앱을 실행하고 플로우를 수행해 필터링된 로그를 살핀 뒤, 근거를 바탕으로 다음 코드 변경을 결정할 수 있습니다.

특히 다음 세 가지 에이전트 기반 루프에 유용합니다:

• 자동 디버깅 루프: Codex가 의심스러운 플로우에 계측을 추가하고 앱을 실행한 다음, 사이드바 항목을 클릭하거나 명령을 실행합니다. 이어서 출력된 로그 순서를 읽고 상태 업데이트 경로를 패치한 뒤, 로그와 UI 동작이 일치할 때까지 같은 플로우를 다시 실행합니다.
• 앱 세션 수집 루프: Codex가 앱 실행, 창 열기, 사이드바 선택, 가져오기 시작, 가져오기 완료 및 가져오기 실패에 각각 이벤트 하나를 추가합니다. 그런 다음 로컬 세션을 실행하고 타임라인을 요약하여 누락되거나 순서가 어긋난 전환을 쉽게 파악할 수 있게 합니다.
• 사용자 주도 캡처 루프: Codex가 로깅을 활성화한 상태로 앱을 실행하고, 사용자가 까다로운 플로우를 직접 수행하는 동안 범위를 좰힌 로그 스트림을 계속 실행합니다. 이후 캡처한 세션을 살펴보고 해당 트레이스를 바탕으로 다음 패치를 제안합니다.

계측을 최소화하고 필터링하기 쉽게 유지하기

각 상태 변경마다 영구 로그 한 줄을 남기지 말고, 기능 영역마다 로거 하나를 두도록 Codex에 요청하세요. Windowing, Commands, MenuBar, Sidebar, Sync, Import 같은 기능 카테고리를 사용하면 다음 디버깅 과정에서 로그를 훨씬 쉽게 필터링할 수 있습니다.

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
}

오랫동안 유용해야 하는 간결한 동작 및 수명 주기 이벤트에는 info 수준을 사용하세요. 노이즈가 많은 로컬 상태 세부 정보에는 debug 수준을 사용하고, 작업이 끝나기 전에 필요에 따라 제거하거나 더 낮은 수준으로 조정하세요. 사인포스트는 타이밍 구간을 측정할 때만 추가하고 기본적으로는 추가하지 마세요.

로그로 이벤트 발생을 입증하도록 Codex에 요청하기

중요한 것은 단순히 Logger 호출을 추가하는 데 그치지 않는 것입니다. Codex에 앱을 실행하고 계측된 플로우를 트리거한 다음, 사용한 정확한 Console 필터나 log stream 조건식과 대표 로그 한두 줄을 제공하도록 요청하세요.

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

예상 이벤트가 나타나지 않으면 Codex에 로그를 의심되는 제어 경로에 더 가깝게 옮기고 같은 플로우를 다시 실행하도록 요청하세요. 로그로 실제 상황을 설명할 수 있을 때까지 이 과정을 반복합니다. 작업이 크래시 또는 백트레이스 분석으로 바뀌면 플러그인의 빌드/실행 디버깅 워크플로우로 전환하고 텔레메트리는 동작 경계에 집중하도록 유지하세요.

후속 Codex 실행을 위해 세션 트레이스 저장하기

오래 걸리거나 간헐적으로 발생하는 버그는 Codex에 범위를 좁힌 로그 스트림을 작은 로컬 트레이스 파일로 저장하고 타임라인을 요약한 뒤, 해당 결과물을 워크스페이스에 남기도록 요청하세요. 그러면 이후 Codex 실행에서 전체 세션을 다시 재현하지 않고도 같은 근거를 검토할 수 있습니다. 한 번의 에이전트 실행에서 트레이스를 수집하고 다른 실행에서 패치 전후 동작을 비교하려는 경우 여러 차례에 걸친 디버깅이 더 쉬워집니다.

사용자가 세션 일부를 직접 진행해야 할 때도 이 방식이 유용합니다. Codex에 로깅하기 좋은 디버그 루프에서 앱을 실행하고 필터링된 캡처를 시작한 다음, 사용자가 이슈를 직접 재현하는 동안 기다렸다가 완료되면 저장된 트레이스 파일을 읽도록 요청하세요.

실용적인 팁

기능을 한 번에 하나씩 계측하기

로그 순서를 쉽게 살펴볼 수 있도록 사이드바, 창, 명령 또는 동기화 경로 하나부터 시작하세요. 해당 경로가 안정적으로 동작하면 Codex가 같은 패턴을 관련 플로우로 확장할 수 있습니다.

프롬프트에 개인정보 보호 조건 포함하기

Codex에 기록하는 각 식별자의 필요성을 설명하고, 비밀 정보나 개인정보 또는 원문 콘텐츠를 통합 로그에 기록하지 않도록 요청하세요. 로컬 디버깅에는 소수의 이벤트 유형만으로도 충분한 경우가 많습니다.

최종 요약에 샘플 출력 포함하기

대표 로그 줄이 있으면 ‘텔레메트리를 추가했다’는 설명만 있을 때보다 변경 사항을 훨씬 더 신뢰하기 쉽습니다. 다음 에이전트 실행에서도 같은 검증 루프를 재사용할 수 있도록 Codex에 필터 조건식과 간단한 동작 타임라인을 포함하도록 요청하세요.