실행 경로가 불분명한 곳에 Logger 하나 추가하기

Mac 앱에서 “뭔가 일어났다”는 것만 알고 코드 리뷰만으로는 실제 동작을 파악하기 어려울 때 이 방법을 사용하세요. Codex에 특정 동작을 파악하는 데 필요한 통합 로그를 몇 개 추가하고, 앱을 실행해 해당 동작을 재현한 뒤, 콘솔 앱이나 log stream에서 예상한 이벤트가 발생했는지 확인해 달라고 요청하세요.

이 과정에는 Build macOS Apps 플러그인을 사용하세요. 이 플러그인의 macOS 텔레메트리 스킬은 간단한 절차에 집중합니다. Apple의 Logger를 사용하고, 어떤 기능의 로그인지 알아보기 쉽도록 서브시스템과 카테고리를 정하세요. 동작이 시작되거나 끝나는 지점과 상태 전환을 기록하되 민감한 데이터는 제외하세요. 앱을 로컬에서 빌드하고 실행한 뒤 실제 이벤트가 기록되는지 확인하세요.

에이전트 기반 개발에 텔레메트리가 유용한 이유

로그를 잘 남기면 Codex가 패치할 때마다 같은 절차로 결과를 확인할 수 있습니다. 사용자가 창과 메뉴 동작, 동기화 상태 전환을 일일이 확인할 필요 없이 에이전트가 앱을 실행해 해당 플로우를 재현하고, 필요한 로그만 추려 본 뒤 그 결과를 근거로 다음에 수정할 코드를 결정할 수 있습니다.

특히 다음 세 가지 방식으로 에이전트와 작업할 때 유용합니다.

• 자동 디버깅: Codex가 문제가 의심되는 플로우에 로그를 추가하고 앱을 실행해 사이드바를 클릭하거나 명령어를 실행합니다. 이어서 로그가 기록된 순서를 살펴보고 상태를 업데이트하는 코드 경로를 수정합니다. 로그와 UI 동작이 일치할 때까지 같은 플로우를 다시 실행합니다.
• 앱 세션 기록: Codex가 앱 실행, 창 열기, 사이드바 항목 선택, 가져오기 시작, 가져오기 완료, 가져오기 실패에 각각 이벤트를 하나씩 추가합니다. 그런 다음 앱을 로컬에서 실행하고 세션의 이벤트를 시간순으로 정리해 누락되거나 순서가 뒤바뀐 상태 전환을 쉽게 찾을 수 있게 합니다.
• 사용자가 직접 재현하는 세션 기록: Codex가 로깅을 켠 상태로 앱을 실행하고, 사용자가 까다로운 플로우를 직접 재현하는 동안 관련 로그만 계속 수집합니다. 세션이 끝나면 수집한 기록을 검토하고 이를 근거로 다음 패치를 제안합니다.

로그는 꼭 필요한 곳에 추가하고 쉽게 필터링할 수 있도록 구성하기

상태가 바뀔 때마다 로그를 남기는 코드를 영구적으로 두기보다는 Codex에 기능 영역별로 로거를 하나씩 추가해 달라고 요청하세요. Windowing, Commands, MenuBar, Sidebar, Sync, Import처럼 기능별로 카테고리를 나누면 다음에 디버깅할 때 필요한 로그만 훨씬 쉽게 골라낼 수 있습니다.

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
}

info는 나중에도 참고할 만한 동작이나 수명 주기 이벤트를 간결하게 기록할 때 사용하세요. debug는 로컬 상태를 자세히 살펴보기 위해 자주 남기는 로그에 사용하세요. 이런 로그는 작업을 마치기 전에 제거하거나 로그 수준을 낮춰도 됩니다. signpost는 특정 구간의 소요 시간을 측정할 때만 추가하세요.

Codex에 로그로 이벤트 발생을 확인해 달라고 요청하기

Logger 호출을 추가한 뒤에는 실제로 이벤트가 기록되는지 확인하세요. Codex에 앱을 실행해 로그를 추가한 플로우를 재현하고, 확인에 사용한 콘솔 앱의 필터나 log stream 조건식을 그대로 보여 달라고 요청하세요. 대표 로그 한두 줄도 함께 요청하세요.

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

예상한 이벤트가 나타나지 않으면 Codex에 로그를 남기는 위치를 문제가 의심되는 실행 경로에 더 가깝게 옮긴 뒤 같은 플로우를 다시 실행해 달라고 요청하세요. 로그로 실제 동작을 설명할 수 있을 때까지 이 과정을 반복하세요. 앱 충돌이나 백트레이스를 분석해야 한다면 플러그인의 빌드 및 실행 디버깅 워크플로우로 전환하고, 텔레메트리는 동작의 시작과 종료 지점에 집중하세요.

다음 Codex 실행에서 살펴볼 세션 추적 파일 저장하기

오래 추적해야 하거나 간헐적으로 발생하는 버그라면 Codex에 관련 로그만 골라 작은 로컬 추적 파일에 저장하고, 이벤트를 시간순으로 요약한 뒤 파일을 워크스페이스에 남겨 달라고 요청하세요. 다음에 Codex를 실행할 때 기억에 의존해 전체 세션을 재현할 필요 없이 같은 기록을 살펴볼 수 있습니다. 한 번은 에이전트를 실행해 추적 기록을 수집하고 다음번에는 패치 전후의 동작을 비교하는 식으로 디버깅하기가 쉬워집니다.

사용자가 세션의 일부를 직접 진행해야 할 때도 이 방법이 유용합니다. Codex에 로그를 수집할 수 있는 디버깅 환경에서 앱을 실행한 뒤 필요한 로그만 필터링해 기록하도록 요청하세요. 사용자가 문제를 직접 재현하는 동안에는 기다렸다가 재현이 끝나면 저장한 추적 파일을 읽어 달라고 하세요.

실무 팁

한 번에 한 기능에만 로그 추가하기

로그가 기록되는 순서를 쉽게 파악할 수 있도록 사이드바, 창, 명령어, 동기화 경로 중 하나부터 시작하세요. 해당 경로가 안정적으로 동작하면 Codex가 같은 방식을 관련 플로우에도 적용할 수 있습니다.

프롬프트에 개인정보 보호 지침 포함하기

Codex에 로그에 남기는 각 식별자가 무엇인지 설명하고, 비밀 정보나 개인정보, 원본 콘텐츠를 통합 로그에 기록하지 말라고 요청하세요. 로컬 디버깅에는 대개 몇 가지 이벤트만으로 충분합니다.

최종 요약에 출력 예시 포함하기

“텔레메트리를 추가했습니다”라는 설명만 있을 때보다 실제 로그 몇 줄을 보면 변경 사항이 의도대로 동작하는지 판단하기가 훨씬 쉽습니다. 다음에 에이전트를 실행할 때도 같은 절차로 검증할 수 있도록 Codex에 필터 조건식과 동작 순서를 간단히 정리해 넣어 달라고 요청하세요.