For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
기본 탐색 메뉴
Theme
Codex

Codex use case

Mac 앱의 기본 구조 만들기

Codex로 사이드바, 상세 패널, 인스펙터, 명령어, 설정을 갖춘 Mac 네이티브 SwiftUI 앱의 기본 구조를 만드세요.

Difficulty Advanced
Time horizon 1h

Codex와 Build macOS Apps 플러그인으로 앱 아이디어를 Mac에 맞는 NavigationSplitView 앱으로 구현하세요. 사이드바에서 선택한 항목이 그대로 유지되도록 하고 메뉴, 도구 막대, 키보드 단축키를 추가하세요. 환경설정은 전용 Settings 씬으로 옮기세요.

Best for

  • 항상 표시되는 탐색 영역과 메뉴, 도구 막대, 키보드 단축키 등 데스크톱 UI가 필요한 새 Mac 앱 아이디어나 iPad 또는 웹을 중심으로 구상한 앱
  • 사이드바에서 항목을 선택하면 상세 패널에 해당 내용이 표시되고, 인스펙터에서 부가 메타데이터를 확인하거나 추가 작업을 실행할 수 있는 편집기, 라이브러리 관리 도구, 관리자 도구 또는 검토 도구
  • 기본 콘텐츠 영역에서 설정 화면으로 이동하는 것보다 별도의 환경설정 윈도우를 여는 방식이 적합한 Mac 앱

Contents

    ← All use cases

    Mac 앱의 기본 구조 만들기

    Codex로 사이드바, 상세 패널, 인스펙터, 명령어, 설정을 갖춘 Mac 네이티브 SwiftUI 앱의 기본 구조를 만드세요.

    Codex와 Build macOS Apps 플러그인으로 앱 아이디어를 Mac에 맞는 NavigationSplitView 앱으로 구현하세요. 사이드바에서 선택한 항목이 그대로 유지되도록 하고 메뉴, 도구 막대, 키보드 단축키를 추가하세요. 환경설정은 전용 Settings 씬으로 옮기세요.

    Advanced
    1h

    Codex와 Build macOS Apps 플러그인으로 앱 아이디어를 Mac에 맞는 NavigationSplitView 앱으로 구현하세요. 사이드바에서 선택한 항목이 그대로 유지되도록 하고 메뉴, 도구 막대, 키보드 단축키를 추가하세요. 환경설정은 전용 Settings 씬으로 옮기세요.

    Advanced
    1h

    Best for

    • 항상 표시되는 탐색 영역과 메뉴, 도구 막대, 키보드 단축키 등 데스크톱 UI가 필요한 새 Mac 앱 아이디어나 iPad 또는 웹을 중심으로 구상한 앱
    • 사이드바에서 항목을 선택하면 상세 패널에 해당 내용이 표시되고, 인스펙터에서 부가 메타데이터를 확인하거나 추가 작업을 실행할 수 있는 편집기, 라이브러리 관리 도구, 관리자 도구 또는 검토 도구
    • 기본 콘텐츠 영역에서 설정 화면으로 이동하는 것보다 별도의 환경설정 윈도우를 여는 방식이 적합한 Mac 앱

    Skills & Plugins

    • macOS SwiftUI 패턴, 윈도우 관리, AppKit 연동, 빌드 및 실행 스킬을 활용하세요. 사이드바, 상세 패널, 인스펙터로 레이아웃을 구성하고 메뉴와 설정을 연결하세요. 앱의 기본 구조부터 빌드와 실행을 반복하며 동작을 확인하세요.
    Skill Why use it
    Build macOS Apps macOS SwiftUI 패턴, 윈도우 관리, AppKit 연동, 빌드 및 실행 스킬을 활용하세요. 사이드바, 상세 패널, 인스펙터로 레이아웃을 구성하고 메뉴와 설정을 연결하세요. 앱의 기본 구조부터 빌드와 실행을 반복하며 동작을 확인하세요.

    Starter prompt

    Build macOS Apps 플러그인을 사용해 다음 앱 아이디어를 Mac 네이티브 SwiftUI 앱으로 구현해 주세요. 앱 아이디어는 [describe your app idea]입니다. 앱의 기본 구조에 사이드바, 상세 패널, 인스펙터, 명령어, 설정을 포함해 주세요. 제약 조건: - 먼저 씬 모델을 선택해 주세요. 기본 윈도우에는 `WindowGroup`을 우선 사용하고, 환경설정에는 전용 `Settings` 씬을 추가해 주세요. - 기본 UI는 `NavigationSplitView`를 중심으로 구성해 주세요. 선택 상태를 명시적으로 관리하고 네이티브 `.sidebar` 목록과 상세 패널을 배치해 주세요. 부가 메타데이터나 컨트롤은 `inspector(isPresented:)` 패널에 넣어 주세요. - 사이드바 행은 기본 스타일을 살려 간결하게 구성해 주세요. 각 행에 아이콘 하나와 제목 한 줄을 넣고, 보조 텍스트가 필요하면 짧게 한 줄만 넣어 주세요. 제품 요구사항상 꼭 필요한 경우에만 모든 행을 큰 커스텀 카드로 감싸 주세요. - 중요한 작업은 씬 수준의 `commands`, `CommandMenu`, 도구 막대 버튼, 키보드 단축키로 실행할 수 있게 해 주세요. 핵심 작업에는 제스처 외의 실행 방법도 제공해 주세요. - 윈도우별 UI 상태에는 `@SceneStorage`를, 환경설정에는 `@AppStorage`를 사용해 주세요. 부모 뷰에서 선택 상태를 관리하고 바인딩을 명시적으로 전달해 사이드바에서 선택한 항목이 상세 패널에 표시되도록 해 주세요. - 시스템 머티리얼, 시맨틱 색상, 표준 사이드바 배경을 우선 사용해 주세요. 커스텀 스타일이 필요하면 상세 패널이나 인스펙터의 콘텐츠 카드에만 적용해 주세요. - SwiftUI로 자연스럽게 구현하기 어려운 특정 데스크톱 동작이 있을 때만 해당 동작에 한정해 AppKit 브리지를 사용해 주세요. - `script/build_and_run.sh`를 만들거나 업데이트하고, 앱이 빌드되고 실행되는지 확인하는 데 필요한 최소한의 검증을 수행해 주세요. 실제로 사용한 명령어도 그대로 알려 주세요. 결과물: - 씬 구조와 기본 UI를 구성하는 사이드바, 상세 패널, 인스펙터 뷰 - 메뉴, 도구 막대, 키보드 단축키를 각 작업에 연결한 코드 - 설정 씬과 환경설정 상태 모델 - AppKit 브리지를 추가했다면 해당 브리지와 브리지가 필요했던 이유 - 빌드 및 실행 검증 절차와 데스크톱 UX 개선을 위해 권장하는 후속 작업
    Build macOS Apps 플러그인을 사용해 다음 앱 아이디어를 Mac 네이티브 SwiftUI 앱으로 구현해 주세요. 앱 아이디어는 [describe your app idea]입니다. 앱의 기본 구조에 사이드바, 상세 패널, 인스펙터, 명령어, 설정을 포함해 주세요. 제약 조건: - 먼저 씬 모델을 선택해 주세요. 기본 윈도우에는 `WindowGroup`을 우선 사용하고, 환경설정에는 전용 `Settings` 씬을 추가해 주세요. - 기본 UI는 `NavigationSplitView`를 중심으로 구성해 주세요. 선택 상태를 명시적으로 관리하고 네이티브 `.sidebar` 목록과 상세 패널을 배치해 주세요. 부가 메타데이터나 컨트롤은 `inspector(isPresented:)` 패널에 넣어 주세요. - 사이드바 행은 기본 스타일을 살려 간결하게 구성해 주세요. 각 행에 아이콘 하나와 제목 한 줄을 넣고, 보조 텍스트가 필요하면 짧게 한 줄만 넣어 주세요. 제품 요구사항상 꼭 필요한 경우에만 모든 행을 큰 커스텀 카드로 감싸 주세요. - 중요한 작업은 씬 수준의 `commands`, `CommandMenu`, 도구 막대 버튼, 키보드 단축키로 실행할 수 있게 해 주세요. 핵심 작업에는 제스처 외의 실행 방법도 제공해 주세요. - 윈도우별 UI 상태에는 `@SceneStorage`를, 환경설정에는 `@AppStorage`를 사용해 주세요. 부모 뷰에서 선택 상태를 관리하고 바인딩을 명시적으로 전달해 사이드바에서 선택한 항목이 상세 패널에 표시되도록 해 주세요. - 시스템 머티리얼, 시맨틱 색상, 표준 사이드바 배경을 우선 사용해 주세요. 커스텀 스타일이 필요하면 상세 패널이나 인스펙터의 콘텐츠 카드에만 적용해 주세요. - SwiftUI로 자연스럽게 구현하기 어려운 특정 데스크톱 동작이 있을 때만 해당 동작에 한정해 AppKit 브리지를 사용해 주세요. - `script/build_and_run.sh`를 만들거나 업데이트하고, 앱이 빌드되고 실행되는지 확인하는 데 필요한 최소한의 검증을 수행해 주세요. 실제로 사용한 명령어도 그대로 알려 주세요. 결과물: - 씬 구조와 기본 UI를 구성하는 사이드바, 상세 패널, 인스펙터 뷰 - 메뉴, 도구 막대, 키보드 단축키를 각 작업에 연결한 코드 - 설정 씬과 환경설정 상태 모델 - AppKit 브리지를 추가했다면 해당 브리지와 브리지가 필요했던 이유 - 빌드 및 실행 검증 절차와 데스크톱 UX 개선을 위해 권장하는 후속 작업

    Mac의 씬 모델부터 선택하기

    터치 중심의 화면 구조를 데스크톱 크기로 늘리는 대신, 앱 아이디어를 Mac에 맞는 앱 셸로 구현하는 방법을 살펴봅니다. Codex에 먼저 씬 모델을 선택하도록 요청하세요. 그런 다음 선택 상태를 유지하는 사이드바, 선택한 항목을 보여 주는 세부 정보 패널, 보조 컨트롤이나 메타데이터를 담는 인스펙터를 중심으로 기본 윈도우를 설계하도록 하세요.

    사이드바에서 항목이 선택되어 있고 세부 정보 패널에 해당 콘텐츠가 표시된 Mac 네이티브 앱 셸

    Codex가 이 데스크톱 구조를 적용하고 셸에서 빌드와 실행을 반복하도록 하려면 Build macOS Apps 플러그인을 사용하세요. 플러그인에 포함된 macOS SwiftUI 패턴 스킬은 씬, 사이드바, 인스펙터, 명령어, 설정을 설계하는 데 적합합니다. SwiftUI만으로 구현하기 어려운 Mac 고유 동작을 위해 작은 AppKit 브리지를 추가할 때도 이 스킬을 활용할 수 있습니다.

    사이드바, 세부 정보 패널, 인스펙터 구성하기

    탐색 영역을 계속 표시하고 항목의 선택 상태를 유지하는 것이 유용한 기능이라면 NavigationSplitView를 우선 사용하세요. 사이드바의 각 행은 네이티브 요소로 간결하게 구성하고 배경은 시스템 기본값을 사용하세요. 사용자 지정 카드나 정보량이 많은 메타데이터는 세부 정보 패널이나 인스펙터에 배치하세요.

    import SwiftUI
    
    struct Item: Identifiable, Hashable {
      let id: String
      let title: String
      let systemImage: String
    }
    let items = [Item(id: "notes", title: "Notes", systemImage: "note.text"), Item(id: "photos", title: "Photos", systemImage: "photo")]
    
    struct ItemDetailView: View {
      let selection: String?
      var body: some View { Text(selection ?? "Select an item").frame(maxWidth: .infinity, maxHeight: .infinity) }
    }
    struct ItemInspectorView: View {
      let selection: String?
      var body: some View { Text("Metadata: \(selection ?? "No selection")").padding().frame(minWidth: 220) }
    }
    @MainActor final class LibraryStore: ObservableObject {
      @Published var entries = items
      @Published var selection: String?
      @Published var showInspector = true
      func addItem() {
        let item = Item(id: UUID().uuidString, title: "New Item", systemImage: "doc")
        entries.append(item)
        selection = item.id
      }
    }
    
    struct LibraryRootView: View {
      @StateObject private var store = LibraryStore()
      @SceneStorage("LibraryRootView.selection") private var savedSelection: Item.ID?
      @SceneStorage("LibraryRootView.showInspector") private var savedShowInspector = true
    
      var body: some View {
        NavigationSplitView {
          List(selection: $store.selection) {
            ForEach(store.entries) { item in
              Label(item.title, systemImage: item.systemImage)
                .tag(item.id)
            }
          }
          .listStyle(.sidebar)
          .navigationTitle("Library")
        } detail: {
          ItemDetailView(selection: store.selection)
            .inspector(isPresented: $store.showInspector) {
              ItemInspectorView(selection: store.selection)
            }
        }
        .focusedSceneObject(store)
        .onAppear {
          store.selection = savedSelection
          store.showInspector = savedShowInspector
        }
        .onChange(of: store.selection) { _, selection in
          savedSelection = selection
        }
        .onChange(of: store.showInspector) { _, showInspector in
          savedShowInspector = showInspector
        }
      }
    }

    분할 영역의 크기를 특수한 방식으로 조정하거나, 윈도우 간 동작을 저수준에서 조율하거나, 응답자 체인의 동작을 맞춤 설정해야 한다면 Codex에 SwiftUI 셸을 유지하면서 해당 동작에 꼭 필요한 만큼만 AppKit 브리지를 추가하도록 요청하세요.

    데스크톱에 맞게 명령어, 도구 막대, 키보드 단축키 구성하기

    Mac 사용자는 메뉴 막대와 도구 막대에서 주요 동작을 쉽게 찾고 해당 키보드 단축키도 확인할 수 있어야 합니다. Codex에 씬 수준의 commands, 상황에 따라 달라지는 메뉴 항목, 도구 막대 버튼을 동일한 앱 동작에 연결하도록 요청하세요. 이렇게 하면 데스크톱 사용자가 제스처로만 접근할 수 있는 컨트롤을 찾아 헤맬 필요가 없습니다.

    @main
    struct LibraryApp: App {
      @FocusedObject private var store: LibraryStore?
      var body: some Scene {
        WindowGroup {
          LibraryRootView()
        }
        .commands {
          CommandMenu("Library") {
            Button("New Item") {
              store?.addItem()
            }
            .keyboardShortcut("n")
            .disabled(store == nil)
    
            Button("Toggle Inspector") {
              store?.showInspector.toggle()
            }
            .keyboardShortcut("i", modifiers: [.command, .option])
            .disabled(store == nil)
          }
        }
    
        Settings {
          LibrarySettingsView()
        }
      }
    }

    명령어가 세부 정보 패널에 표시된 항목에 적용되어야 한다면 FocusedValue, 씬 상태 또는 명시적인 선택 상태를 사용하세요. 같은 단축키가 여러 곳에 등록될 수 있다면 Codex에 등록과 처리를 한곳에서 맡도록 요청해 명령어의 실행 경로를 하나로 정리하세요.

    Settings에서 환경설정 관리하기

    앱 환경설정에는 전용 Settings 씬을 사용하고, 앱을 다시 실행해도 유지해야 하는 사용자 설정은 @AppStorage로 저장하세요. Mac 앱에는 대개 기본 콘텐츠 윈도우의 탐색 스택에 설정 화면을 추가하는 것보다 이 방식이 더 잘 맞습니다.

    struct LibrarySettingsView: View {
      @AppStorage("showItemMetadata") private var showItemMetadata = true
    
      var body: some View {
        TabView {
          Form {
            Toggle("Show Item Metadata", isOn: $showItemMetadata)
          }
          .tabItem { Label("General", systemImage: "gearshape") }
        }
        .frame(width: 460, height: 260)
        .scenePadding()
      }
    }

    프롬프트로 앱 아이디어를 설명하고 셸 검증하기

    프롬프트에 어떤 앱을 만들려는지, 주로 다루는 콘텐츠 객체는 무엇인지, 사용자가 어떤 주요 동작을 수행하는지 명시하세요. 그런 다음 Codex에 그 워크플로우에 맞춰 데스크톱 셸부터 구현하도록 요청하세요. 에이전트가 앱을 빌드하고 실행해 간단히 확인한 뒤, 씬의 구성, 명령어가 연결된 동작, 상태를 관리하는 주체, AppKit 브리지가 필요했던 부분을 요약하도록 하세요.

    실용적인 팁

    사이드바에 네이티브 요소 사용하기

    사이드바의 각 행에는 아이콘 하나와 한 줄짜리 제목을 사용하고, 보조 텍스트는 짧게 한 줄까지만 넣으세요. 정보가 많은 카드, 개수를 나타내는 표시, 메타데이터는 세부 정보 패널이나 인스펙터로 옮겨 사이드바 목록을 한눈에 훑어볼 수 있도록 하세요.

    기본 탐색 스택에 설정 화면을 숨기지 않기

    앱 전체에 적용되는 사용자 설정이라면 Codex에 해당 컨트롤을 Settings에 배치하고 값을 @AppStorage로 저장하도록 요청하세요. 탐색 스택에 설정 화면을 하나 더 추가하는 대신 앱 메뉴에서 설정을 열 수 있도록 하세요.

    Mac 고유 동작에 필요한 부분만 AppKit으로 구현하기

    열기 및 저장 패널, 최초 응답자 제어 또는 사용자 지정 NSView가 필요한 경우에는 윈도우 전체를 AppKit으로 다시 작성하지 마세요. 상태 모델은 SwiftUI에서 계속 관리하고 해당 동작에 필요한 부분만 AppKit으로 연결하세요.

    Tech stack

    Need

    분할 뷰 기반 앱 구조

    Default options

    NavigationSplitView, .sidebar 목록, inspector(isPresented:)

    Why it's needed

    사이드바를 항상 표시하고 상세 패널과 인스펙터를 함께 배치하면 터치 중심으로 화면을 차례로 열어 가는 방식보다 일반적인 Mac 앱 레이아웃에 더 잘 맞습니다.

    Need

    데스크톱 작업과 설정

    Default options

    commands, CommandMenu, 키보드 단축키, Settings 씬

    Why it's needed

    iOS 화면을 데스크톱 크기로 늘리는 데 그치지 않고 메뉴 막대 명령어, 단축키, 전용 설정 윈도우를 제공하면 사용자가 Mac에 익숙한 방식으로 기능을 이용할 수 있습니다.

    Need

    상태 소유권

    Default options

    @State, @SceneStorage, @AppStorage, 명시적 선택 바인딩

    Why it's needed

    Codex는 뷰 모델을 매번 추가하지 않아도 사이드바 선택 상태, 인스펙터 표시 여부, 사용자 환경설정을 일관되게 관리할 수 있습니다.

    Need

    네이티브 API 연동

    Default options

    필요한 기능에 한정해 NSViewRepresentable 또는 NSWindow 브리지로 AppKit 연동

    Why it's needed

    SwiftUI로 자연스럽게 구현하기 어려운 플랫폼 동작에만 AppKit을 사용하세요. 씬 상태와 선택 상태는 SwiftUI에서 관리하고, AppKit에서도 이 값을 참조하세요.

    Need Default options Why it's needed
    분할 뷰 기반 앱 구조 NavigationSplitView , .sidebar 목록, inspector(isPresented:) 사이드바를 항상 표시하고 상세 패널과 인스펙터를 함께 배치하면 터치 중심으로 화면을 차례로 열어 가는 방식보다 일반적인 Mac 앱 레이아웃에 더 잘 맞습니다.
    데스크톱 작업과 설정 commands , CommandMenu , 키보드 단축키, Settings 씬 iOS 화면을 데스크톱 크기로 늘리는 데 그치지 않고 메뉴 막대 명령어, 단축키, 전용 설정 윈도우를 제공하면 사용자가 Mac에 익숙한 방식으로 기능을 이용할 수 있습니다.
    상태 소유권 @State , @SceneStorage , @AppStorage , 명시적 선택 바인딩 Codex는 뷰 모델을 매번 추가하지 않아도 사이드바 선택 상태, 인스펙터 표시 여부, 사용자 환경설정을 일관되게 관리할 수 있습니다.
    네이티브 API 연동 필요한 기능에 한정해 NSViewRepresentable 또는 NSWindow 브리지로 AppKit 연동 SwiftUI로 자연스럽게 구현하기 어려운 플랫폼 동작에만 AppKit을 사용하세요. 씬 상태와 선택 상태는 SwiftUI에서 관리하고, AppKit에서도 이 값을 참조하세요.

    Related use cases