앱과 빌드 루프 스캐폴딩

새 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 상호 운용, 통합 로깅, 테스트 트리아지, 서명 및 공증 워크플로우를 다룹니다.

플러그인과 스킬을 설치하고 사용하는 방법을 자세히 알아보려면 플러그인 문서와 스킬 문서를 참조하세요.

데스크톱 네이티브 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를 사용하세요.

예시 프롬프트

실용적인 팁

씬을 명시적으로 구성

앱 전체를 하나의 거대한 뷰 안에 숨기지 말고 메인 윈도우, 설정 윈도우, 유틸리티 윈도우, 메뉴 막대 추가 항목을 각각 별도의 씬 루트로 모델링하세요.

시스템 크롬을 최대한 활용

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

AppKit은 필요한 부분에만 사용

누락된 데스크톱 기능 하나를 보완하려면 NSViewRepresentable, NSViewControllerRepresentable 또는 용도가 명확한 NSWindow 헬퍼를 사용하되, 선택 상태와 앱 상태의 기준은 SwiftUI로 유지하세요.

서명과 공증은 로컬 빌드 성공 여부와 별도로 검증

로컬에서 앱이 성공적으로 실행됐다고 해서 서명되었거나 공증할 준비가 되었다는 뜻은 아닙니다. 일회성 릴리스 확인을 위해 수동 Xcode 아카이브 플로우를 유지하고, 반복 가능한 배포를 위해 스크립트 기반 아카이브 및 공증 플로우를 추가하세요. 단순한 로컬 반복 개발이 아니라 배포를 위한 작업이라면 codesign 및 plutil 검사도 실행하세요.