AI 에이전트로 iOS 앱 만들기: 실무자 가이드

# Check Xcode version
xcodebuild -version
# Expected: Xcode 26.3 or later

# Check available simulators
xcrun simctl list devices available
# Expected: at least one iPhone simulator

# Verify xcrun mcpbridge is available
xcrun mcpbridge --help
# Expected: usage information (not "command not found")

# Install Claude Code (if not already installed)
claude --version  # verify installation

# Add XcodeBuildMCP (59 tools — builds, tests, simulators, debugging)
claude mcp add XcodeBuildMCP \
  -s user \
  -e XCODEBUILDMCP_SENTRY_DISABLED=true \
  -- npx -y xcodebuildmcp@latest mcp

# Add Apple Xcode MCP (20 tools — file ops, diagnostics, Swift REPL, previews)
claude mcp add --transport stdio xcode \
  -s user -- xcrun mcpbridge

You: Add a new SettingsView with toggles for notifications and haptic feedback.
     Use the existing Settings.swift pattern from TimerManager.
     Build for simulator after implementation and fix any errors.

Claude: [reads Settings.swift, TimerManager.swift, existing views]
        [creates SettingsView.swift]
        [calls build_sim via MCP]
        [reads structured error: missing import HealthKit]
        [fixes import]
        [calls build_sim again — success, 0 errors, 1 warning]
        [calls test_sim — all tests pass]

# Add Apple Xcode MCP to Codex
codex mcp add xcode -- xcrun mcpbridge

# Add XcodeBuildMCP to Codex
codex mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest mcp

# Option 1: Via npx (recommended — always uses latest version)
claude mcp add XcodeBuildMCP \
  -s user \
  -e XCODEBUILDMCP_SENTRY_DISABLED=true \
  -- npx -y xcodebuildmcp@latest mcp

# Option 2: Via Homebrew (pinned version, manual updates)
brew install xcodebuildmcp
claude mcp add XcodeBuildMCP \
  -s user \
  -e XCODEBUILDMCP_SENTRY_DISABLED=true \
  -- xcodebuildmcp mcp

# Option 3: Project-scoped (omit -s user)
claude mcp add XcodeBuildMCP \
  -e XCODEBUILDMCP_SENTRY_DISABLED=true \
  -- npx -y xcodebuildmcp@latest mcp

# Standard installation (global)
claude mcp add --transport stdio xcode \
  -s user -- xcrun mcpbridge

# For Codex CLI
codex mcp add xcode -- xcrun mcpbridge

┌─────────────────────────────────────────────────────────────────┐
│                     MCP TOOL COVERAGE                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  XcodeBuildMCP (59 tools)        Apple Xcode MCP (20 tools)    │
│  ┌─────────────────────┐         ┌─────────────────────┐       │
│  │ Standalone           │         │ Requires Xcode      │       │
│  │ (no Xcode process)  │         │ (XPC bridge)        │       │
│  │                     │         │                     │       │
│  │ ✓ Simulators        │  BOTH   │ ✓ Documentation     │       │
│  │ ✓ Real devices      │ ┌─────┐ │ ✓ Swift REPL        │       │
│  │ ✓ LLDB debugging    │ │Build│ │ ✓ SwiftUI previews  │       │
│  │ ✓ UI automation     │ │Test │ │ ✓ Live diagnostics  │       │
│  │ ✓ Project scaffold  │ └─────┘ │ ✓ Analyzer issues   │       │
│  │ ✓ Screenshot        │         │                     │       │
│  └─────────────────────┘         └─────────────────────┘       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

# List all configured MCP servers
claude mcp list

# Expected output includes:
# XcodeBuildMCP: npx -y xcodebuildmcp@latest mcp - Connected
# xcode: xcrun mcpbridge - Connected

## 빌드 및 테스트 — 항상 MCP 사용

모든 빌드 작업에서 쉘 명령어 대신 MCP 도구를 우선적으로 사용하세요:

- **빌드**: `build_sim` / `build_device` (Bash로 `xcodebuild` 사용 금지)
- **테스트**: `test_sim` / `test_device` (Bash로 `xcodebuild test` 사용 금지)
- **시뮬레이터**: `list_sims`, `boot_sim`, `open_sim` (Bash로 `xcrun simctl` 사용 금지)
- **디버그**: `debug_attach_sim`, `debug_stack`, `debug_variables`
- **Apple 문서**: `DocumentationSearch` (Apple API 검색 시 WebSearch 사용 금지)
- **Swift 검증**: `ExecuteSnippet` (Bash로 `swift` 사용 금지)
- **미리보기**: `RenderPreview`로 헤드리스 SwiftUI 검증

MCP는 구조화된 JSON를 반환합니다. Bash는 비구조화된 텍스트를 반환합니다.
구조화된 데이터는 토큰 소비가 적고 오류 진단이 더 정확합니다.

# Return - Zen Focus Timer

**Bundle ID:** `com.941apps.Return`
**Target:** iOS 26+ / macOS Tahoe / watchOS 26+ / tvOS 26+
**Architecture:** SwiftUI with @Observable pattern, companion Watch and TV apps
**Swift version:** 6.2
**Minimum deployment:** iOS 26.0

## File Structure

## Build & Test

Build for iOS simulator:
```bash
xcodebuild -scheme Return -destination 'platform=iOS Simulator,name=iPhone 16 Pro' build

xcodebuild -scheme Return -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test

xcodebuild -scheme ReturnTV -destination 'platform=tvOS Simulator,name=Apple TV' test

에이전트가 MCP를 우선 사용해야 하지만 원시 명령어도 포함하세요. 원시 명령어는 대체 문서 역할을 하며 스킴 이름과 대상을 명시적으로 보여줍니다.

#### 4. 핵심 패턴과 규칙

```markdown

## Key Patterns

### Observable Architecture
- ALL view models use `@Observable` (NEVER `ObservableObject`)
- ALL navigation uses `NavigationStack` (NEVER `NavigationView`)
- State management via `@Observable` classes with `@MainActor` isolation

### Settings Pattern
- Centralized `Settings.shared` singleton
- All settings bounded to valid ranges with validation
- Sound names validated against whitelist
- Thread-safe access via @MainActor

### Audio System
- `AVAudioPlayer` with `.playback` category (plays in silent mode)
- Silent audio loop for background execution
- Bell playback with completion callbacks and token-based staleness

## Rules

- **NEVER modify .pbxproj files** — create Swift files, then I will add them to Xcode manually
- **NEVER modify .xcodeproj/ contents directly**
- **NEVER add new package dependencies** without asking first
- **NEVER change the deployment target**
- **NEVER modify entitlements files** unless explicitly asked
- **NEVER use NavigationView** — always NavigationStack
- **NEVER use ObservableObject** — always @Observable
- **NEVER use @StateObject** — always @State with @Observable

## HealthKit Configuration

- Entitlement: `com.apple.developer.healthkit`
- Info.plist keys:
  - `NSHealthShareUsageDescription`: "Return reads your mindful minutes..."
  - `NSHealthUpdateUsageDescription`: "Return logs meditation sessions..."
- Category types: `HKCategoryType(.mindfulSession)`
- Authorization checked on every write (user can revoke at any time)
- HealthKit is unavailable on tvOS — guard with `#if canImport(HealthKit)`

## SwiftData Models

### Model Relationships
- `GroceryList` has many `GroceryItem` (cascade delete)
- `GroceryItem` belongs to one `GroceryList`
- `GroceryItem` has optional `Category`

### Model Container Setup
- Configured in App struct with `modelContainer(for:)`
- Schema versioning: currently V2
- Migration plan: `GroceryMigrationPlan` handles V1 → V2

### Queries
- `@Query(sort: \GroceryItem.name)` for sorted fetches
- `@Query(filter: #Predicate { !$0.isCompleted })` for active items
- Always use `@Query` in views, `modelContext.fetch()` in managers

## SpriteKit Scene Hierarchy

- Physics categories defined in `PhysicsCategory.swift` as bitmasks
- Contact detection via `didBegin(_ contact:)` on GameScene
- Bullet pooling: pre-allocate 50, recycle via `removeFromParent()` + re-add

## Metal Pipeline

- Render pipeline: `MetalView` → `Renderer` → `ShaderLibrary`
- Compute pipeline: `AudioAnalyzer` → compute shader → texture output
- Shared uniforms struct: `Uniforms` in `ShaderTypes.h` (bridged to Swift)
- Frame timing: `CADisplayLink` drives render loop
- Buffer triple-buffering: 3 in-flight frames with semaphore

### Shader Files
- `Shaders.metal` — Main render shaders (vertex + fragment)
- `Compute.metal` — Audio analysis compute kernel
- `PostProcess.metal` — Bloom and color grading

### DO NOT modify Metal shaders without testing on device.
Simulator Metal is not representative of device GPU behavior.

# Banana List - Grocery List App

**Bundle ID:** `com.941apps.BananaList`
**Target:** iOS 26+
**Architecture:** SwiftUI + SwiftData + iCloud Drive sync
**Swift version:** 6.2
**Minimum deployment:** iOS 26.0

## Core Features

- Grocery lists with items, categories, and quantities
- iCloud Drive sync via SwiftData CloudKit integration
- Custom MCP server exposing list data to Claude Desktop
- Liquid Glass design system
- Haptic feedback on interactions
- Share sheets for list sharing

## 파일 구조

## SwiftData 모델

### 관계

- `GroceryList`는 여러 `GroceryItem`을 가져요 (cascade delete)
- `GroceryItem`은 하나의 `GroceryList`에 속해요 (필수)
- `GroceryItem`은 선택적 `Category`를 가져요
- `Category`는 여러 `GroceryItem`을 가져요 (삭제 시 nullify)

### 컨테이너 설정

```swift
@main
struct BananaListApp: App {
    var body: some Scene {
        WindowGroup {
            ListsView()
        }
        .modelContainer(for: [GroceryList.self, GroceryItem.self, Category.self])
    }
}

xcodebuild -scheme BananaList -destination 'platform=iOS Simulator,name=iPhone 16 Pro' build
xcodebuild -scheme BananaList -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test

### 실제 CLAUDE.md: Reps (최소 SwiftData 앱 — 14개 파일)

소규모 프로젝트의 경우 CLAUDE.md를 간결하게 작성할 수 있어요. 다음은 14개 파일로 구성된 운동 추적 앱 Reps의 패턴이에요. 짧은 CLAUDE.md라도 6가지 필수 섹션을 모두 다루고 있다는 점에 주목하세요:

```markdown
# Reps - Workout Tracking

**Bundle ID:** `com.941apps.Reps`
**Target:** iOS 26+
**Architecture:** SwiftUI + SwiftData
**Swift version:** 6.2

## File Structure

## Build & Test

```bash
xcodebuild -scheme Reps -destination 'platform=iOS Simulator,name=iPhone 16 Pro' build
xcodebuild -scheme Reps -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test

40줄의 CLAUDE.md로 14개 파일 프로젝트를 커버할 수 있어요. 작성하는 데 10분이면 충분하고, 에이전트의 혼란을 줄여 수 시간을 절약할 수 있어요.

### 실제 CLAUDE.md: Starfield Destroyer (SpriteKit + Metal — 32개 파일)

게임 프로젝트는 프레임워크별 컨텍스트가 더 필요해요. 에이전트가 씬 그래프, 물리 카테고리, 게임 상태 머신을 이해해야 해요:

```markdown
# Starfield Destroyer - Space Shooter

**Bundle ID:** `com.941apps.StarfieldDestroyer`
**Target:** iOS 26+
**Architecture:** SpriteKit + Metal post-processing + Game Center
**Swift version:** 6.2

## Game Overview

99 levels across 3 galaxies. 8 unlockable ships with different stats.
Game Center leaderboards and achievements. Metal shader post-processing
for bloom and screen effects.

## File Structure

## SpriteKit 씬 계층 구조

## 물리 카테고리

```swift
struct PhysicsCategory {
    static let none:      UInt32 = 0
    static let player:    UInt32 = 0b1        // 1
    static let enemy:     UInt32 = 0b10       // 2
    static let bullet:    UInt32 = 0b100      // 4
    static let powerUp:   UInt32 = 0b1000     // 8
    static let shield:    UInt32 = 0b10000    // 16
    static let bossBullet:UInt32 = 0b100000   // 32
}

// Contact pairs:
// player + enemy → damage
// player + powerUp → collect
// bullet + enemy → destroy
// player + bossBullet → damage

.menu → .playing → .paused → .playing
                 → .gameOver → .menu
                 → .bossIntro → .playing
                 → .levelComplete → .playing (next level)

xcodebuild -scheme StarfieldDestroyer -destination 'platform=iOS Simulator,name=iPhone 16 Pro' build
xcodebuild -scheme StarfieldDestroyer -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test

## 규칙

- .pbxproj를 절대 수정하지 마세요
- PhysicsCategory 비트마스크를 절대 수정하지 마세요 (모든 충돌 감지가 깨집니다)
- 렌더 순서를 이해하지 않고 씬 계층 구조의 z 순서를 절대 변경하지 마세요
- Swift와 Metal 참조를 모두 업데이트하지 않고 ShaderTypes.h를 절대 수정하지 마세요
- 새로운 적을 추가할 때는 EnemyShip을 수정하지 말고 서브클래싱하세요
- 총알 풀링: removeFromParent() + 재추가로 재활용하고, 절대 새로 할당하지 마세요
- Game Center: 점수를 제출하기 전에 항상 isAuthenticated를 확인하세요

# amp97 - Audio Visualizer

**Bundle ID:** `com.941apps.amp97`
**Target:** iOS 26+
**Architecture:** Metal render pipeline + AVAudioEngine analysis
**Swift version:** 6.2

## Architecture

## File Structure

## Metal Pipeline

### Uniforms (ShaderTypes.h)
```c
typedef struct {
    float time;
    float2 resolution;
    float audioLevel;       // 0.0-1.0 RMS amplitude
    float frequencyBins[64]; // FFT output, normalized
    float4x4 transform;
} Uniforms;

### 프로젝트 규모에 따른 CLAUDE.md 확장

적절한 세부 수준은 파일 수와 프레임워크 복잡도에 따라 달라집니다:

| 프로젝트 규모 | CLAUDE.md 깊이 | 예시 |
|-------------|----------------|---------|
| **소규모 (< 20개 파일)** | 프로젝트 정보 + 파일 목록 + 규칙 | Reps (14개 파일): 기본 SwiftData 패턴, 빌드 명령어, 금지 사항 |
| **중규모 (20-40개 파일)** | + 프레임워크 컨텍스트 + 핵심 패턴 | TappyColor (30개 파일): SpriteKit 씬 계층 구조, 물리 카테고리, 게임 루프 |
| **대규모 (40개 이상 파일)** | + 아키텍처 다이어그램 + 관계 맵 + 멀티 타겟 정보 | Return (63개 파일): 크로스 플랫폼 아키텍처, 세션 동기화 다이어그램, 플랫폼별 차이점 |
| **특수 (Metal/GPU)** | + 파이프라인 다이어그램 + 공유 타입 정의 + 버퍼 레이아웃 | amp97 (41개 파일): 렌더 파이프라인 단계, uniform 구조체, 버퍼 관리 |

과도하게 문서화하는 비용은 거의 없습니다 (에이전트는 필요 없는 부분을 건너뜁니다). 반면 문서화가 부족하면 비용이 큽니다 (에이전트가 코드베이스와 충돌하는 패턴을 임의로 만들어냅니다).

### CLAUDE.md 체크리스트

iOS 프로젝트의 CLAUDE.md를 작성하거나 점검할 때 이 체크리스트를 활용하세요:

- [ ] Bundle ID와 배포 타겟이 명시되어 있는가
- [ ] Swift 버전과 아키텍처 패턴이 명시되어 있는가
- [ ] 인라인 용도 설명이 포함된 파일 구조가 있는가
- [ ] 올바른 scheme과 destination이 포함된 빌드 명령어가 있는가
- [ ] 올바른 scheme과 destination이 포함된 테스트 명령어가 있는가
- [ ] MCP 선호 사항이 명시되어 있는가 ("xcodebuild보다 build_sim 선호")
- [ ] @Observable 규칙이 있는가 (ObservableObject 사용 금지)
- [ ] NavigationStack 규칙이 있는가 (NavigationView 사용 금지)
- [ ] .pbxproj 수정 금지 규칙이 있는가
- [ ] 프레임워크별 컨텍스트가 있는가 (HealthKit 권한, SwiftData 관계, SpriteKit 계층 구조, Metal 파이프라인)
- [ ] 플랫폼 가용성 가드가 문서화되어 있는가 (#if canImport, #if os)
- [ ] 주요 싱글톤과 공유 패턴이 문서화되어 있는가
- [ ] 알려진 제한 사항이나 주의 사항이 명시되어 있는가

---

## 첫 번째 에이전트 세션

MCP가 설정되고 프로젝트에 CLAUDE.md가 있다면, 효과적인 첫 세션의 진행 과정을 살펴보겠습니다. 여기서는 Claude Code CLI를 사용하지만 워크플로우는 어떤 런타임에도 적용됩니다.

### 1단계: 에이전트가 프로젝트를 인식하는지 확인

    This is Return, a zen meditation timer for iOS 26+, watchOS, and tvOS.
    Available schemes: Return, ReturnWatch, ReturnTV, ReturnTests.
    Primary scheme for iOS: Return.

에이전트가 CLAUDE.md 내용을 참조하지 않는다면, 파일이 프로젝트 루트(`.xcodeproj` 또는 `Package.swift`와 같은 디렉토리)에 있는지 확인하세요.

### 2단계: 상태 점검 빌드 실행

    Build succeeded. 63 source files compiled.
    2 warnings:
    - HomeView.swift:132 — UIScreen.main deprecated in iOS 26.0
    - LogWaterIntent.swift:61 — Result of try? is unused
    0 errors.

### 3단계: 테스트 실행

    12 tests executed:
    ✓ TimerManagerTests (5/5 passed)
    ✓ SettingsTests (4/4 passed)
    ✓ ConstantsTests (3/3 passed)
    All tests passed.

### 4단계: 기능 구현

    Added Rain theme:
    - Theme.swift: new `static let rain` with video, cover, ambient
    - ThemeManager.swift: added to `allThemes` array
    - Build: success (0 errors, 2 existing warnings)
    - Tests: 12/12 passed

    Note: You'll need to add rain_ambient.wav to the project
    and add the new Theme.swift changes to the Xcode target manually
    (I did not modify .pbxproj).

에이전트가 .pbxproj를 수정하지 않았다는 메모는 CLAUDE.md의 규칙이 반영된 결과입니다. 해당 규칙이 없었다면 에이전트는 프로젝트 파일을 수정하려 시도했을 것이고, 파일이 손상될 가능성이 높았을 것입니다.

---

## iOS에서 에이전트가 잘하는 작업

에이전트가 일관되게 정확하고 프로덕션에 바로 사용할 수 있는 결과물을 만들어내며, 사람의 리뷰가 거의 필요 없는 작업들입니다.

### SwiftUI 뷰와 수정자

에이전트는 SwiftUI의 선언적 구문에 대한 패턴 인식 능력이 뛰어납니다. 뷰 구성, 수정자 체이닝, 상태 바인딩, 레이아웃 등은 SwiftUI의 API 영역이 잘 문서화되어 있고 패턴이 매우 일관적이기 때문에 에이전트의 학습 데이터와 잘 맞습니다.

**에이전트가 특히 잘하는 부분:**
- 설명을 바탕으로 새로운 뷰 구축 ("X, Y, Z 토글이 있는 설정 시트 만들기")
- 수정자 체이닝 적용 (`.glassEffect()`, `.sensoryFeedback()`, `.navigationTitle()`)
- 레이아웃 패턴 간 변환 (VStack에서 LazyVGrid로, List에서 ScrollView로)
- SwiftData 모델에 `@Bindable` 폼 바인딩 구현
- 샘플 데이터가 포함된 프리뷰 프로바이더 작성

**우수한 결과를 만들어내는 프롬프트 예시:**

구체적인 지시가 중요합니다. "설정 뷰를 만들어줘"라고 하면 범용적인 결과가 나옵니다. "SettingsSheet.swift의 기존 패턴에 맞는 SettingsView를 만들어줘"라고 하면 코드베이스와 일관된 결과가 나옵니다.

### SwiftData 모델과 쿼리

에이전트는 SwiftData의 `@Model` 매크로, 관계, `@Query` 패턴을 안정적으로 처리합니다. 이 프레임워크의 선언적 특성이 Django ORM이나 SQLAlchemy와 유사하여, 에이전트가 다양한 코드베이스에서 학습한 패턴과 잘 맞습니다.

**에이전트가 특히 잘하는 부분:**
- 관계가 포함된 `@Model` 클래스 정의
- 정렬 디스크립터와 프레디케이트를 활용한 `@Query` 작성
- `modelContext`를 통한 CRUD 작업 구현
- 스키마 버전 간 마이그레이션 계획
- 프리뷰 데이터 및 테스트 픽스처

**에이전트에게 가이드가 필요한 부분:**
- 복잡한 `#Predicate` 표현식 (SwiftData의 프레디케이트 DSL에는 에이전트가 항상 파악하지 못하는 제약사항이 있으므로, 알려진 제약사항을 CLAUDE.md에 문서화하세요)
- CloudKit 동기화 설정 (SwiftData를 통해 자동으로 처리되지만, 에이전트가 수동 동기화를 구현하려고 할 수 있습니다)

### 단위 테스트

에이전트가 작성하는 단위 테스트는 iOS 프로젝트에서 일관되게 높은 품질을 보여줍니다. 에이전트는 XCTest 패턴, 비동기 테스트 메서드, setup/teardown 라이프사이클을 잘 이해하고 있습니다.

에이전트는 `setUp()`과 `tearDown()`이 포함된 잘 구조화된 XCTest 케이스를 생성하며, 적절한 어서션과 타이머 기반 테스트를 위한 비동기 처리를 포함합니다.

### 리팩토링과 패턴 적용

에이전트는 기계적인 리팩토링에 탁월합니다. 뷰를 컴포넌트로 추출하거나, `ObservableObject`를 `@Observable`로 변환하거나, `NavigationView`에서 `NavigationStack`으로 마이그레이션하거나, 여러 파일에 걸쳐 일관된 패턴을 적용하는 작업이 대표적입니다.

에이전트는 각 파일을 체계적으로 처리하며, 변환을 정확하게 적용하고, 기존 기능을 유지합니다. 이는 활용도가 매우 높은 작업으로, 수동 편집으로 한 시간이 걸릴 리팩토링이 거의 완벽한 정확도로 몇 분 만에 완료됩니다.

### MCP를 통한 빌드 오류 진단

구조화된 MCP 출력이 있으면, 에이전트는 대부분의 개발자보다 빠르게 빌드 오류를 진단합니다. 에이전트는 오류 JSON를 읽고, 정확한 파일과 줄을 식별하고, 오류 메시지를 이해하고, 수정을 적용합니다 — 대부분 한 번의 턴으로 해결합니다.

**에이전트가 자율적으로 수정하는 오류:**
- 누락된 임포트
- 타입 불일치
- 프로토콜 준수 누락
- 사용 중단된 API 사용법 (대체 코드 포함)
- 필수 이니셜라이저 매개변수 누락
- 접근 제어 위반

**에이전트에게 도움이 필요한 오류:**
- 모호한 타입 해석 (여러 모듈이 동일한 타입을 정의하는 경우)
- 복잡한 제네릭 제약 조건 실패
- 매크로 확장 오류 (에이전트가 확장된 매크로 출력을 볼 수 없음)

### 시뮬레이터 관리

에이전트는 MCP를 통해 시뮬레이터 라이프사이클을 잘 처리합니다:

에이전트는 `list_sims`로 사용 가능한 런타임을 확인하고, `boot_sim`으로 시뮬레이터를 시작하고, `build_sim`으로 앱을 빌드 및 설치하고, `screenshot`으로 화면을 캡처합니다 — 모두 구조화된 MCP 호출을 통해 수행됩니다.

---

## iOS에서 에이전트가 잘 못하는 것들

에이전트가 실패하는 지점에 대한 솔직한 분석입니다. 이러한 한계를 알면 불필요한 좌절과 토큰 낭비를 방지할 수 있습니다.

### .pbxproj 파일 수정 — 절대 금지

이것은 iOS 에이전트 개발에서 가장 중요한 규칙입니다. `.pbxproj` 파일은 Xcode의 프로젝트 설정 파일로, UUID 참조, 빌드 단계 목록, 타겟 멤버십이 포함된 구조화된 텍스트 파일입니다. 명목상으로는 사람이 읽을 수 있지만, 실질적으로 AI 에이전트가 파싱하기는 불가능합니다.

**에이전트가 .pbxproj에서 실패하는 이유:**
- 이 파일은 위치 의존적인 커스텀 포맷을 사용합니다 (JSON, YAML, XML 어느 것도 아닙니다)
- 모든 항목이 UUID로 상호 참조되어 있어, 파일 하나를 추가하려면 3~5개의 서로 다른 섹션을 일관성 있게 업데이트해야 합니다
- 한 글자만 잘못 배치되어도 전체 프로젝트 파일이 손상됩니다
- Xcode의 .pbxproj 병합 충돌 해결은 이미 불안정한데, 에이전트의 편집은 상황을 더 악화시킵니다

**에이전트가 .pbxproj를 편집하면 발생하는 일:**
1. 편집이 성공한 것처럼 보입니다 (에이전트가 "파일이 업데이트되었습니다"라고 보고합니다)
2. Xcode가 프로젝트를 열지 못합니다 ("프로젝트 파일이 손상되었습니다")
3. git 히스토리에서 복구하는 데 15~60분을 소비합니다
4. PreToolUse 훅을 추가하는 법을 배우게 됩니다 ([훅](#hooks-for-ios-development) 참조)

**올바른 워크플로:** 에이전트가 Swift 파일을 생성하면, 여러분이 직접 Xcode 프로젝트에 추가합니다 (Xcode로 드래그하거나, File > Add Files 사용). 파일당 5초면 되고, 수 시간에 걸친 복구 작업을 방지할 수 있습니다.

**Swift Package Manager 프로젝트의 경우:** 이 제한은 덜 심각합니다. `Package.swift`는 에이전트가 안정적으로 편집할 수 있는 표준 Swift 파일입니다. 프로젝트가 SPM만 사용한다면 (.xcodeproj 없이), 에이전트가 전체 프로젝트 구조를 관리할 수 있습니다.

### 복잡한 Interface Builder / Storyboard 편집

프로젝트가 Interface Builder (`.xib` 파일) 또는 Storyboard (`.storyboard` 파일)를 사용하는 경우, 에이전트는 이를 의미 있게 편집할 수 없습니다. 이 파일들은 자동 생성된 UUID, 제약 조건 참조, 아울렛 연결이 포함된 XML 파일로, 텍스트 편집이 아닌 시각적 편집을 위해 설계되었습니다.

**대응 방법:** 새로운 뷰는 SwiftUI만 사용하세요. 프로젝트에 레거시 Interface Builder 파일이 있다면, 그대로 두고 새로운 UI는 SwiftUI로 구축하세요.

### 성능 최적화

에이전트는 올바른 코드를 작성하지만, 반드시 성능이 좋은 코드를 작성하는 것은 아닙니다. 앱을 프로파일링하거나, 병목 지점을 식별하거나, 프레임 레이트를 측정할 수 없습니다. 성능 최적화에는 다음이 필요합니다:

1. Instruments 프로파일링 (시각적 도구로, 에이전트가 접근할 수 없습니다)
2. 특정 기기의 GPU/CPU 특성에 대한 이해
3. 측정 기반의 반복적인 변경

**이런 상황에서 나타납니다:**
- Metal 셰이더 최적화 (에이전트가 유효한 Metal을 작성하지만 GPU 프레임 타임을 측정할 수 없습니다)
- SwiftUI 뷰 body 복잡도 (에이전트가 깊이 중첩된 뷰를 생성하여 리드로우 오버헤드를 유발합니다)
- Core Data / SwiftData 페치 최적화 (에이전트가 올바른 쿼리를 작성하지만 대규모 데이터셋에서는 느릴 수 있습니다)

**대응 방법:** 구현에는 에이전트를 활용하고, Instruments로 직접 프로파일링한 후, 식별한 특정 최적화를 에이전트에게 적용하도록 요청하세요.

### 코드 서명 및 프로비저닝

에이전트는 오류 메시지를 읽는 것 이상으로 코드 서명 문제를 디버깅할 수 없습니다. 프로비저닝 프로파일 관리, 인증서 생성, 엔타이틀먼트 설정, App Store 제출은 근본적으로 Apple Developer 포털, 키체인 접근, Xcode의 서명 UI를 통해 사람이 직접 수행하는 워크플로입니다.

**에이전트가 보는 것:** "Signing for 'Return' requires a development team."

**에이전트가 볼 수 없는 것:** 인증서가 만료되었는지, 프로비저닝 프로파일에 해당 기기가 포함되어 있는지, 번들 ID가 App ID와 일치하는지, 엔타이틀먼트 파일이 올바른지 여부.

**대응 방법:** 모든 서명 작업은 Xcode의 Signing & Capabilities 탭에서 처리하세요. 에이전트에게 서명 실패를 디버깅하도록 요청하지 마세요.

### 복잡한 Metal 셰이더 디버깅

에이전트는 문법적으로 올바른 Metal Shading Language (MSL)를 작성하지만, 시각적 출력을 검증하거나 GPU 측 문제를 디버깅할 수 없습니다. Metal 셰이더는 GPU에서 실행되기 때문에, 에이전트에게는 셰이더가 올바른 시각적 결과를 생성하는지 확인할 피드백 메커니즘이 없습니다.

**에이전트가 Metal로 할 수 있는 것:**
- 설명을 바탕으로 버텍스 및 프래그먼트 셰이더 작성
- Swift에서 Metal 렌더 파이프라인 설정
- 데이터 병렬 연산을 위한 컴퓨트 셰이더 생성
- `.metal` 파일의 컴파일 오류 수정

**에이전트가 Metal로 할 수 없는 것:**
- 셰이더 출력의 시각적 정확성 검증
- GPU 성능 디버깅 (프레임 타임, 점유율, 메모리 대역폭)
- 시각적 아티팩트 진단 (밴딩, 정밀도 문제, 잘못된 색 공간)
- 서로 다른 GPU 아키텍처에서의 테스트 (A 시리즈 vs. M 시리즈 동작 차이)

**대응 방법:** Metal 셰이더는 실제 기기에서 테스트하세요. 시뮬레이터의 Metal 구현은 기기 GPU 동작을 대표하지 않습니다. 시각적 디버깅에는 Xcode의 GPU Frame Capture를 사용하세요.

### 시각적 레이아웃 검증

에이전트는 앱의 UI를 볼 수 없습니다. SwiftUI 레이아웃 코드를 작성하고 컴파일이 되는지 확인할 수는 있지만, 결과 화면이 올바르게 보이는지는 판단할 수 없습니다. 10픽셀 중앙에서 벗어나거나, 잘못된 폰트 굵기를 사용하거나, 요소가 겹치는 뷰도 빌드 오류를 발생시키지 않고 모든 로직 테스트를 통과합니다.

**대응 방법:** UI 변경 사항은 시각적으로 검토하세요. Xcode의 SwiftUI Previews를 사용하거나 (헤드리스 렌더링을 위해 Apple MCP의 `RenderPreview` 사용), 자동화된 시각적 회귀 감지를 위해 swift-snapshot-testing과 같은 라이브러리로 스냅샷 테스트를 고려하세요.

---

## iOS 개발을 위한 Hooks

Hooks는 에이전트 워크플로우의 특정 시점에서 결정적으로 실행되는 셸 명령어입니다. 이것은 강제 메커니즘으로, ".pbxproj를 수정하지 마세요"(에이전트가 무시할 수 있는 제안)와 ".pbxproj를 수정할 수 없습니다"(하드 블록) 사이의 차이를 만들어 줍니다.

Hook 시스템에 대한 배경 지식은 [Claude Code hooks 가이드](/blog/claude-code-hooks-tutorial)를 참조하세요. 이 섹션에서는 iOS에 특화된 hook 패턴을 다룹니다.

### PreToolUse: .pbxproj 쓰기 차단

모든 iOS 프로젝트에서 가장 중요한 hook입니다. 에이전트가 `.pbxproj` 파일, `.xcodeproj/` 디렉토리 및 기타 Xcode 관리 파일에 쓰는 것을 차단합니다:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.(pbxproj|xcworkspace|xib|storyboard)$|xcodeproj/|xcworkspace/\"; then echo \"BLOCKED: Do not modify Xcode project files. Create Swift files and add to Xcode manually.\" >&2; exit 2; fi'"
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.swift$\"; then swiftformat \"$FP\" --quiet 2>/dev/null; fi'"
      }
    ]
  }
}

# .swiftformat
--indent 4
--allman false
--stripunusedargs closure-only
--importgrouping testable-bottom
--header strip

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.swift$\"; then swiftlint lint --path \"$FP\" --quiet 2>/dev/null || true; fi'"
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.swift$\"; then xcodebuild -scheme Return -destination \"platform=iOS Simulator,name=iPhone 16 Pro\" build 2>&1 | tail -5; fi'"
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.entitlements$\"; then echo \"BLOCKED: Do not modify entitlements files without explicit permission.\" >&2; exit 2; fi'"
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.(pbxproj|xcworkspace|xib|storyboard|entitlements)$|xcodeproj/|xcworkspace/\"; then echo \"BLOCKED: Do not modify Xcode-managed files. Create Swift files and add manually.\" >&2; exit 2; fi'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.swift$\"; then swiftformat \"$FP\" --quiet 2>/dev/null; fi'"
      }
    ]
  }
}

// CORRECT — @Observable
@Observable
@MainActor
final class TimerManager {
    var timeRemaining: TimeInterval = 0
    var state: TimerState = .stopped

    func start() {
        state = .running
        // ...
    }
}

// In a view:
struct TimerView: View {
    @State private var timer = TimerManager()

    var body: some View {
        Text(timer.timeRemaining, format: .number)
    }
}

// WRONG — ObservableObject (deprecated pattern)
class TimerManager: ObservableObject {
    @Published var timeRemaining: TimeInterval = 0
    @Published var state: TimerState = .stopped
}

// WRONG — @StateObject (deprecated pattern)
struct TimerView: View {
    @StateObject private var timer = TimerManager()
}

// CORRECT
NavigationStack {
    List(items) { item in
        NavigationLink(value: item) {
            ItemRow(item: item)
        }
    }
    .navigationDestination(for: Item.self) { item in
        ItemDetailView(item: item)
    }
}

// WRONG
NavigationView {
    List(items) { item in
        NavigationLink(destination: ItemDetailView(item: item)) {
            ItemRow(item: item)
        }
    }
}

@Model
final class GroceryItem {
    var name: String
    var quantity: Int
    var isCompleted: Bool
    var category: Category?
    var list: GroceryList?

    init(name: String, quantity: Int = 1) {
        self.name = name
        self.quantity = quantity
        self.isCompleted = false
    }
}

// Actor isolation for shared mutable state
@MainActor
@Observable
final class DataManager {
    var items: [Item] = []

    func loadItems() async throws {
        let fetched = try await api.fetchItems()
        items = fetched  // Safe: @MainActor isolated
    }
}

// Sendable conformance for cross-actor transfers
struct Item: Sendable, Identifiable {
    let id: UUID
    let name: String
    let createdAt: Date
}

// Glass effect on containers
VStack {
    // content
}
.glassEffect()

// Glass effect with tint
Button("Action") { }
    .glassEffect(.regular.tint(.blue))

// Glass effect on navigation bars (automatic in iOS 26)
NavigationStack {
    // content
}
// Navigation bar automatically uses glass material

// Custom glass shapes
RoundedRectangle(cornerRadius: 16)
    .fill(.ultraThinMaterial)
    .glassEffect()

// Always check availability and authorization
import HealthKit

@MainActor
@Observable
final class HealthKitManager {
    private let store = HKHealthStore()
    var isAuthorized = false

    func requestAuthorization() async {
        guard HKHealthStore.isHealthDataAvailable() else { return }

        let types: Set<HKSampleType> = [
            HKQuantityType(.dietaryWater),
            HKCategoryType(.mindfulSession)
        ]

        do {
            try await store.requestAuthorization(toShare: types, read: types)
            isAuthorized = true
        } catch {
            // User denied — do not retry automatically
        }
    }
}

## SpriteKit Rules

- Scene hierarchy is a tree of SKNodes with zPosition ordering
- Physics bodies use category bitmasks (UInt32) for collision detection
- Node pooling: pre-allocate reusable nodes (bullets, particles)
- Never add nodes directly to the scene — use layer nodes for organization
- Update loop: `update(_ currentTime:)` runs every frame — keep it fast
- Actions: use SKAction sequences for animations, not manual property updates
- Textures: use texture atlases for performance (.atlas directories)

## Metal Rules

- Shared types between Swift and Metal go in a bridging header (ShaderTypes.h)
- Triple buffer in-flight frames (semaphore with value 3)
- Test shaders on DEVICE, not simulator (Metal behavior differs)
- Compute shaders: threadgroup size must divide evenly into grid size
- Fragment shaders: output color must be in correct color space (sRGB or linear)
- DO NOT optimize shaders without Instruments GPU profiling data

## Live Activities

- ActivityAttributes defined in `TimerActivityAttributes.swift`
- ActivityKit framework: `import ActivityKit`
- Widget extension: `ReturnWidgets/ReturnLiveActivity.swift`
- Start: `Activity<TimerActivityAttributes>.request(attributes:content:)`
- Update: `activity.update(ActivityContent(state:staleDate:))`
- End: `activity.end(ActivityContent(state:staleDate:), dismissalPolicy:)`
- Push token: register for updates via `activity.pushTokenUpdates`

## Game Center

- Authentication: `GKLocalPlayer.local.authenticateHandler`
- Leaderboards: `GKLeaderboard.submitScore(_:context:player:leaderboardIDs:completionHandler:)`
- Achievements: `GKAchievement.report(_:withCompletionHandler:)` (takes `[GKAchievement]` array)
- Always check `GKLocalPlayer.local.isAuthenticated` before submitting
- Handle authentication failure gracefully (offline play must work)

Shared/
├── MeditationSession.swift    # Data model (all platforms)
├── SessionStore.swift         # iCloud sync (all platforms)
└── SessionHistoryView.swift   # UI (adapts per platform)

Return/                        # iOS-specific
ReturnWatch Watch App/         # watchOS-specific
ReturnTV/                      # tvOS-specific

// HealthKit: available on iOS and watchOS, not tvOS
#if canImport(HealthKit)
import HealthKit
// HealthKit code here
#endif

// ActivityKit: available on iOS only
#if canImport(ActivityKit)
import ActivityKit
// Live Activity code here
#endif

// WatchKit: available on watchOS only
#if os(watchOS)
import WatchKit
// Watch-specific code here
#endif

struct SessionHistoryView: View {
    @Query var sessions: [MeditationSession]

    var body: some View {
        List(sessions) { session in
            SessionRow(session: session)
        }
        #if os(tvOS)
        .focusable()
        #endif
        #if os(iOS)
        .swipeActions {
            Button("Delete", role: .destructive) {
                // delete
            }
        }
        #endif
    }
}

Implement a countdown timer that:
1. Starts from a user-selected duration (10, 20, or 30 minutes)
2. Shows remaining time with a circular progress indicator
3. Plays a bell sound on completion
4. Logs the session to HealthKit as mindful minutes

Build after each change. Fix all errors. Run tests when the build succeeds.
Continue until all tests pass and the build is clean.

Use a subagent to research the best approach for implementing
iCloud key-value store sync for meditation sessions across iOS,
watchOS, and tvOS. Report back with the recommended pattern.

Look at how Settings.swift works in the Return project
(centralized singleton with validation). Apply the same pattern
to create a Settings.swift for the Water project.

# After Claude implements the feature:
codex "Review the changes in the last commit. Focus on Swift 6.2
      concurrency correctness, SwiftData relationship integrity,
      and potential retain cycles. Report issues only — no praise."

# Update @Observable pattern across all projects
for project in BananaList Return Water Reps; do
  cd ~/Projects/$project
  claude -p "Audit all files for any remaining ObservableObject usage.
             Convert to @Observable following the pattern in CLAUDE.md.
             Build and test after changes." --dangerously-skip-permissions
done

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│    tvOS     │     │    Mac      │     │   Watch     │
│ TVTimerMgr  │     │ TimerMgr    │     │ WatchTimer  │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │
                           ▼
              ┌────────────────────────┐
              │     SessionStore       │
              │  (iCloud Key-Value)    │
              └───────────┬────────────┘
                          │
                          ▼
              ┌────────────────────────┐
              │  iPhone (on foreground)│
              │  → Write to HealthKit  │
              └────────────────────────┘

You: Here's the next feature for Return: add a "Focus Score" that
     calculates from session duration and consistency. Show it on
     the main timer view. Build and test.

Claude: [reads CLAUDE.md, understands patterns]
        [reads TimerManager.swift, Settings.swift]
        [creates FocusScore.swift — model with calculation logic]
        [creates FocusScoreView.swift — display component]
        [integrates into ContentView.swift]
        [calls build_sim — 1 error: missing import]
        [fixes import]
        [calls build_sim — success]
        [writes FocusScoreTests.swift]
        [calls test_sim — all pass]

---
name: ios-developer
description: iOS development agent with MCP build tools and SwiftUI expertise
tools:
  - XcodeBuildMCP
  - xcode
---

# iOS Developer Agent

You are an iOS development agent for apps targeting iOS 26+ with SwiftUI.

## Architecture Rules
- @Observable for all view models (NEVER ObservableObject)
- NavigationStack for all navigation (NEVER NavigationView)
- SwiftData for persistence
- Swift 6.2 strict concurrency
- @MainActor on all Observable classes

## Build & Test — Always Use MCP

Prefer MCP tools over raw shell commands for ALL build operations:

- **Build**: `build_sim` / `build_device` (NOT `xcodebuild` via Bash)
- **Test**: `test_sim` / `test_device` (NOT `xcodebuild test` via Bash)
- **Simulators**: `list_sims`, `boot_sim`, `open_sim`
- **Debug**: `debug_attach_sim`, `debug_stack`, `debug_variables`
- **Apple docs**: `DocumentationSearch` (NOT WebSearch for Apple APIs)
- **Swift verification**: `ExecuteSnippet` (NOT `swift` via Bash)

MCP returns structured JSON. Bash returns unstructured text.

## File Management Rules
- NEVER modify .pbxproj, .xcodeproj/, .xcworkspace/, .xib, .storyboard
- Create Swift files in the correct directory
- Report files that need manual addition to Xcode targets

## SwiftData Rules
- @Model classes are automatically Observable — do not add @Observable
- Use @Bindable for form bindings to model properties
- Use @Query in views, modelContext.fetch() elsewhere
- Document relationship delete rules

## When You Get Stuck
- Build errors: use `build_sim` via MCP for structured output
- API questions: use `DocumentationSearch` via Apple MCP
- Swift verification: use `ExecuteSnippet` via Apple MCP
- Never guess — verify with tools

# In CLAUDE.md:

## Test Structure

Tests mirror source structure:
- `ReturnTests/TimerManagerTests.swift` tests `TimerManager.swift`
- `ReturnTests/SettingsTests.swift` tests `Settings.swift`
- `ReturnTests/ConstantsTests.swift` tests `Constants.swift`

Test naming: `test_<what>_<condition>_<expected>`
Example: `test_start_whenStopped_transitionsToRunning`

Write unit tests for TimerManager covering:

1. Initial state is .stopped with timeRemaining == selectedDuration
2. start() transitions state to .running
3. pause() from .running transitions to .paused
4. reset() from any state returns to .stopped with original duration
5. start() from .paused resumes (state becomes .running)
6. Edge case: reset() when already stopped is a no-op
7. Edge case: pause() when already paused is a no-op

Follow the existing test pattern in SettingsTests.swift.
Use setUp() to create a fresh TimerManager for each test.

Write tests for TimerManager.

// Agent produces this pattern when guided correctly:
final class TimerManagerTests: XCTestCase {
    var sut: TimerManager!

    @MainActor
    override func setUp() {
        super.setUp()
        sut = TimerManager()
    }

    @MainActor
    func test_start_whenStopped_transitionsToRunning() {
        // Given
        XCTAssertEqual(sut.state, .stopped)

        // When
        sut.start()

        // Then
        XCTAssertEqual(sut.state, .running)
    }

    @MainActor
    func test_timerCountsDown_afterOneSecond() async throws {
        // Given
        sut.selectedDuration = 10
        sut.reset()
        sut.start()

        // When
        try await Task.sleep(for: .seconds(1.1))

        // Then
        XCTAssertLessThanOrEqual(sut.timeRemaining, 9.0)
    }
}