앱의 기본 구조와 빌드·실행 루프 구성하기

새 Mac 앱을 만들 때는 먼저 Codex에 WindowGroup, Window, Settings, MenuBarExtra, DocumentGroup 중 앱에 맞는 씬 모델을 선택해 달라고 하세요. 그러면 iOS 스타일의 ContentView를 확장해 나가는 대신 처음부터 데스크톱에 맞는 구조로 앱을 만들 수 있습니다.

빌드와 실행은 셸에서 반복할 수 있도록 구성하세요. Xcode 프로젝트에는 xcodebuild를 사용하세요. 패키지 중심으로 구성한 앱에는 swift build와 프로젝트 내의 script/build_and_run.sh 래퍼 스크립트를 사용하세요. 이 스크립트는 기존 프로세스를 종료하고 앱을 빌드한 다음 새로 빌드한 앱을 실행합니다. 필요하면 로그나 텔레메트리도 확인할 수 있게 하세요.

SwiftPM만 사용하는 GUI 앱이라면 실행 파일을 직접 실행하는 대신 .app 번들로 패키징해 실행하세요. 이렇게 하면 로컬에서 검증할 때 앱이 Dock에 표시되지 않거나 앱 활성화 또는 번들 식별에 문제가 생기는 일을 피할 수 있습니다.

스킬 활용하기

데스크톱 고유의 기능을 다루기 시작하면 Build macOS Apps 플러그인을 추가하세요. 이 플러그인은 셸 중심의 빌드 및 디버깅 루프, SwiftPM 앱 패키징, SwiftUI의 네이티브 씬 및 윈도우 패턴, AppKit 연동, 통합 로깅, 테스트 실패 원인 분류, 서명 및 공증 워크플로우를 지원합니다.

플러그인과 스킬을 설치하고 사용하는 방법은 플러그인 문서와 스킬 문서를 참고하세요.

Mac에 맞는 네이티브 UI 만들기

iOS 탐색 패턴보다 Mac의 인터페이스 관례를 우선하세요. 사이드바와 상세 영역을 나란히 배치할 때는 NavigationSplitView를 사용하고, 환경설정에는 Settings 씬을 명시적으로 정의하세요. 사용자가 기능을 쉽게 찾을 수 있도록 도구 막대와 메뉴 명령을 활용하고, 언제든 사용할 수 있는 간단한 유틸리티는 메뉴 막대 항목으로 제공하세요.

시스템 머티리얼, 시맨틱 색상, 표준 컨트롤을 먼저 사용하세요. 제품에 고유한 데스크톱 UI가 필요할 때만 윈도우 스타일을 직접 지정하거나 드래그 영역 또는 Liquid Glass 표면을 추가하세요.

SwiftUI로 대부분 구현할 수 있지만 일부 동작이 부족하다면 필요한 부분에만 최소한의 AppKit 브리지를 추가하세요. 예를 들어 열기 및 저장 패널, 퍼스트 리스폰더 제어, 메뉴 항목의 활성화 여부 판단, 드래그 앤 드롭의 예외 처리에 활용할 수 있습니다. 특수한 컨트롤 하나를 구현하기 위해 NSView를 래핑하는 것도 좋은 예입니다.

디버깅, 테스트 및 배포 준비하기

실행 중 앱의 동작을 확인하려면 Codex에 윈도우 열기, 사이드바 항목 선택, 메뉴 명령 실행, 백그라운드 동기화 등의 시점에 Logger 이벤트를 몇 개 추가해 달라고 하세요. 앱을 실행한 다음 log stream으로 해당 이벤트를 확인하세요.

실패한 테스트가 있다면 Codex에 먼저 문제를 확인하는 데 필요한 최소 범위에서 xcodebuild test 또는 swift test를 실행해 달라고 하세요. 그런 다음 원인이 컴파일 오류, 어설션 실패, 크래시, 간헐적인 테스트 실패, 환경 또는 설정 문제 중 어디에 해당하는지 분류하도록 하세요.

로컬에서 수정과 검증을 반복하는 단계를 마치고 배포를 준비할 때는 Codex에 두 가지 절차를 마련해 달라고 하세요. 하나는 Xcode에서 수동으로 아카이브를 생성하는 절차이고, 다른 하나는 배포할 때마다 스크립트로 아카이브 생성과 공증을 수행하는 절차입니다. codesign과 plutil로 앱 번들, 인타이틀먼트, 강화된 런타임 설정을 점검하도록 하세요. 업로드까지 터미널에서 처리하려면 App Store Connect CLI를 사용하세요.

예시 프롬프트

실무 팁

씬을 명시적으로 정의하기

앱 전체를 하나의 거대한 뷰에 넣지 말고 기본 윈도우, 설정 윈도우, 유틸리티 윈도우, 메뉴 막대 항목을 각각 독립적인 씬 루트로 정의하세요.

시스템이 제공하는 UI 활용하기

사이드바, 도구 막대, 머티리얼을 직접 만들기 전에 표준 SwiftUI 씬 및 윈도우 API만으로 원하는 Mac 동작을 구현할 수 있는지 확인하세요.

AppKit 연동 범위 좁히기

SwiftUI에 없는 데스크톱 기능 하나를 구현할 때는 NSViewRepresentable, NSViewControllerRepresentable 또는 그 기능에 특화된 NSWindow 헬퍼를 사용하세요. 선택 상태와 앱 상태는 SwiftUI에서 일관되게 관리하세요.

서명과 공증은 로컬 빌드와 별도로 검증하기

앱이 로컬에서 정상적으로 실행되더라도 서명이 완료됐거나 공증을 받을 준비가 됐다고 볼 수는 없습니다. 개별 릴리스를 점검할 때 사용할 수 있도록 Xcode에서 수동으로 아카이브를 생성하는 절차를 유지하세요. 반복 배포를 위해 아카이브 생성과 공증을 스크립트로 자동화하고, 로컬 개발을 넘어 실제 배포를 준비할 때는 codesign과 plutil로 점검하세요.