使用 AI Agent 開發 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 工具，而非原始 shell 指令：

- **建置**：`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`（而非用 WebSearch 查詢 Apple API）
- **Swift 驗證**：`ExecuteSnippet`（而非透過 Bash 執行 `swift`）
- **預覽**：`RenderPreview` 可進行無介面的 SwiftUI 驗證

MCP 回傳結構化的 JSON。Bash 回傳的是非結構化文字。
結構化資料意味著消耗更少的 token，並能更精準地診斷錯誤。

# 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，仍應保留原始指令。這些原始指令可作為備用文件，並明確標示 scheme 名稱與目標裝置。

#### 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`（級聯刪除）
- `GroceryItem` 屬於一個 `GroceryList`（必填）
- `GroceryItem` 可選擇性關聯 `Category`
- `Category` 擁有多個 `GroceryItem`（刪除時設為 null）

### 容器設定
```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 可以簡潔扼要。以下是 Reps 的範例，一款僅含 14 個檔案的健身追蹤器。請注意即使是簡短的 CLAUDE.md，仍涵蓋了全部六個必要章節：

```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 分鐘，卻能省下數小時的 Agent 困惑。

### 實際範例 CLAUDE.md：Starfield Destroyer（SpriteKit + Metal——32 個檔案）

遊戲專案需要更多框架相關的上下文資訊。Agent 必須理解場景圖、物理類別與遊戲狀態機：

```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 Scene Hierarchy

## Physics Categories

```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-ordering
- 絕對不要在未同步更新 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 偏好（「優先使用 build_sim 而非 xcodebuild」）
- [ ] @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 中規則發揮作用的結果。若沒有該規則，代理程式會嘗試修改專案檔案，極可能導致檔案損毀。

---

## AI 代理在 iOS 開發中的優勢

以下是代理能穩定產出正確、可直接上線的成果，且僅需極少人工審查的任務類型。

### SwiftUI 視圖與修飾器

代理對 SwiftUI 宣告式語法具備深厚的模式識別能力。視圖組合、修飾器鏈、狀態綁定與佈局——這些都能良好對應代理的訓練資料，因為 SwiftUI 的 API 介面文件完善，模式高度一致。

**代理表現優異的領域：**
- 根據描述建構新視圖（「建立一個包含 X、Y、Z 開關的設定頁面」）
- 套用修飾器鏈（`.glassEffect()`、`.sensoryFeedback()`、`.navigationTitle()`）
- 轉換佈局模式（VStack 轉 LazyVGrid、List 轉 ScrollView）
- 實作 `@Bindable` 表單綁定至 SwiftData 模型
- 建立含範例資料的預覽提供者

**能產出優質結果的提示詞範例：**

具體程度至關重要。「建立一個設定視圖」只會產出通用結果；「建立一個符合 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 生命週期。

代理會產出結構良好的 XCTest 案例，包含 `setUp()` 與 `tearDown()`、適當的斷言，以及針對計時器測試的非同步處理。

### 重構與模式套用

代理擅長機械式重構：將視圖抽取為元件、將 `ObservableObject` 轉換為 `@Observable`、從 `NavigationView` 遷移至 `NavigationStack`，以及在多個檔案間套用一致的模式。

代理會有條不紊地逐一處理每個檔案，正確套用轉換並維持既有功能。這是高槓桿工作——原本需要一小時手動編輯的重構，幾分鐘內即可近乎完美地完成。

### 透過 MCP 診斷建置錯誤

藉由結構化的 MCP 輸出，代理診斷建置錯誤的速度往往超越多數開發者。代理讀取錯誤 JSON、精確定位檔案與行號、理解錯誤訊息並套用修復——通常一次互動即可完成。

**代理可自主修復的錯誤：**
- 缺少匯入
- 型別不匹配
- 協定遵循缺漏
- 已棄用的 API 用法（附替代方案）
- 缺少必要的初始化參數
- 存取控制違規

**代理需要協助的錯誤：**
- 模糊的型別解析（多個模組定義相同型別）
- 複雜的泛型約束失敗
- 巨集展開錯誤（代理無法檢視展開後的巨集輸出）

### 模擬器管理

代理透過 MCP 能妥善處理模擬器的生命週期：

代理會呼叫 `list_sims` 尋找可用的執行環境、`boot_sim` 啟動模擬器、`build_sim` 建置並安裝應用程式，以及 `screenshot` 擷取畫面——全部透過結構化的 MCP 呼叫完成。

---

## 代理工具在 iOS 開發中的不足之處

坦誠盤點代理工具力有未逮的領域。明確這些界限，能避免不必要的挫折與 token 浪費。

### .pbxproj 檔案修改——絕對禁止

這是 iOS 代理開發中最重要的一條規則。`.pbxproj` 檔案是 Xcode 的專案設定檔——一個包含 UUID 參照、建構階段列表及目標成員資訊的結構化文字檔。名義上可供人類閱讀，但實際上 AI 代理幾乎無法正確解析。

**代理工具為何無法處理 .pbxproj：**
- 該檔案採用自訂格式（非 JSON、非 YAML、非 XML），且位置具有語義意義
- 每筆項目皆透過 UUID 交叉參照——新增一個檔案需要同步更新 3 至 5 個不同區段
- 一個字元的錯位就會導致整個專案檔損毀
- Xcode 對 .pbxproj 的合併衝突解決機制本身已十分脆弱——代理的編輯只會雪上加霜

**當代理編輯 .pbxproj 時會發生什麼：**
1. 編輯看似成功（代理回報「檔案已更新」）
2. Xcode 拒絕開啟專案（「專案檔已損毀」）
3. 您花費 15 至 60 分鐘從 git 歷史記錄中復原
4. 您學會加上 PreToolUse hook（請參閱 [Hooks](#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、約束參照及 outlet 連接的 XML 檔案，設計上供視覺化編輯使用，並非為文字編輯而生。

**因應做法：** 新視圖一律使用 SwiftUI。若專案中有舊版 Interface Builder 檔案，維持原樣不動，新的 UI 全部以 SwiftUI 建構。

### 效能最佳化

代理能寫出正確的程式碼，但不一定是高效能的程式碼。代理無法對應用程式進行效能分析、找出瓶頸或量測影格率。效能最佳化需要：

1. 使用 Instruments 進行效能分析（視覺化工具，代理無法存取）
2. 了解特定裝置的 GPU/CPU 特性
3. 以量測數據驅動的迭代式調整

**常見問題情境：**
- Metal 著色器最佳化（代理能寫出有效的 Metal 程式碼，但無法量測 GPU 影格時間）
- SwiftUI 視圖本體複雜度（代理可能建立深層巢狀視圖，導致重繪開銷）
- Core Data / SwiftData 查詢最佳化（代理寫出的查詢語法正確，但在大型資料集上可能效能不佳）

**因應做法：** 讓代理負責實作，您使用 Instruments 手動分析效能，再請代理針對您已找出的具體問題進行最佳化。

### 程式碼簽署與佈建描述檔

代理除了讀取錯誤訊息之外，無法除錯程式碼簽署問題。佈建描述檔管理、憑證建立、權限設定及 App Store 提交，本質上都是需要人工操作的流程，涉及 Apple Developer 入口網站、鑰匙圈存取及 Xcode 的簽署介面。

**代理看到的是：**「Signing for 'Return' requires a development team.」

**代理看不到的是：** 您的憑證是否已過期、佈建描述檔是否包含該裝置、Bundle ID 是否與 App ID 相符、權限檔案是否正確。

**因應做法：** 所有簽署作業都在 Xcode 的 Signing & Capabilities 分頁中處理。不要要求代理除錯簽署問題。

### 複雜的 Metal 著色器除錯

代理能寫出語法正確的 Metal Shading Language（MSL），但無法驗證視覺輸出或除錯 GPU 端的問題。Metal 著色器在 GPU 上執行——代理沒有任何回饋機制來判斷著色器是否產生正確的視覺結果。

**代理在 Metal 方面能做到的：**
- 根據描述撰寫頂點與片段著色器
- 以 Swift 設定 Metal 渲染管線
- 建立用於資料平行運算的計算著色器
- 修正 `.metal` 檔案中的編譯錯誤

**代理在 Metal 方面做不到的：**
- 驗證著色器輸出的視覺正確性
- 除錯 GPU 效能（影格時間、佔用率、記憶體頻寬）
- 診斷視覺瑕疵（色帶、精度問題、色彩空間錯誤）
- 在不同 GPU 架構上測試（A 系列與 M 系列的行為差異）

**因應做法：** 在實體裝置上測試 Metal 著色器。模擬器的 Metal 實作無法代表裝置 GPU 的實際行為。請使用 Xcode 的 GPU Frame Capture 進行視覺化除錯。

### 視覺版面驗證

代理看不到您應用程式的 UI。代理能撰寫 SwiftUI 版面程式碼並驗證其可編譯，但無法判斷畫面呈現是否正確。偏移 10 像素的視圖、錯誤的字重、重疊的元素——這些都不會產生建構錯誤，也能通過所有邏輯測試。

**因應做法：** 以目視方式檢查 UI 變更。在 Xcode 中使用 SwiftUI Previews（或透過 Apple MCP 使用 `RenderPreview` 進行無頭渲染）來驗證版面。亦可考慮使用 swift-snapshot-testing 等函式庫進行快照測試，以自動偵測視覺回歸問題。

---

## iOS 開發的 Hooks 設定

Hooks 是在代理工作流程中特定時間點確定性執行的 shell 命令。它們是強制執行機制——區別在於「請不要編輯 .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)
    }
}

Add snapshot tests for the main timer view in three states:
1. Stopped (showing full duration)
2. Running (showing countdown)
3. Completed (showing 00:00 with completion state)

Use SnapshotTesting library. Create reference images on first run.

Use discover_projs and list_schemes to find the correct scheme name
for this project before building.

## 建置
Primary scheme: `Return` (iOS)
Watch scheme: `ReturnWatch` (watchOS)
TV scheme: `ReturnTV` (tvOS)

# Ensure Xcode command line tools are selected
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

# Verify
xcrun mcpbridge --help

# Exit current session (Ctrl+C or /exit)
# Start fresh
claude

You: List all available MCP tools from XcodeBuildMCP.

xcrun simctl shutdown all
xcrun simctl boot "iPhone 16 Pro"

Shut down all simulators, then boot a fresh iPhone 16 Pro.

{
  "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.\" >&2; exit 2; fi'"
      }
    ]
  }
}

## Configuration

API base URL and keys are in `Config.xcconfig` (not committed).
Required keys:
- `API_BASE_URL` — Backend server URL
- `API_KEY` — Authentication token

Create `Config.xcconfig` from `Config.xcconfig.template`.

Implement error handling for the HealthKit authorization flow:
1. Check HKHealthStore.isHealthDataAvailable() — show alert if not
2. Request authorization — handle denial gracefully
3. On write failure — retry once, then show error
4. All errors should be user-facing with localized descriptions

Add accessibility labels to all interactive elements in TimerView:
- Timer display: current time remaining
- Start/Pause button: current state and action
- Reset button: "Reset timer"
- Duration picker: selected duration

## Core Data Model 版本
- V1：初始版本（GroceryList、GroceryItem）
- V2：新增 Category 模型（目前版本）
- 遷移：V1→V2 採用輕量級自動遷移

- NEVER use ObservableObject — use @Observable
- NEVER add @Observable to @Model classes (already Observable)
- NEVER use @StateObject — use @State with @Observable
- NEVER use @ObservedObject — access @Observable properties directly

## Closure Pattern
- Timer callbacks: use `[weak self]` and guard
- NotificationCenter observers: store in `Set<AnyCancellable>` and use `[weak self]`
- Completion handlers: use `[weak self]` for any closure stored beyond the call site

## Concurrency Rule
ALL @Observable classes MUST be @MainActor:
```swift
@Observable
@MainActor
final class SomeManager { }

### 錯誤 4：使用含目標閉包的 NavigationLink

**現象：** Agent 使用已棄用的 `NavigationLink(destination:label:)` 而非型別安全的 `NavigationLink(value:)` + `.navigationDestination(for:)` 模式。

**預防方式：**
```markdown

## Navigation Pattern
ALWAYS use value-based navigation:
```swift
NavigationLink(value: item) { ItemRow(item: item) }
.navigationDestination(for: Item.self) { ItemDetailView(item: $0) }

### 錯誤 5：硬編碼模擬器名稱

**現象：** Agent 在建置指令中寫死特定模擬器名稱（如「iPhone 16 Pro」），而該模擬器可能不存在於您的系統上。

**預防方式：** MCP 可處理此問題——`list_sims` 會探索可用的模擬器。在 CLAUDE.md 中：
```markdown

## Simulators
Do NOT hardcode simulator names. Use `list_sims` MCP tool to discover
available devices, then `boot_sim` with the discovered device ID.

## File Placement Rules
- Views → `AppName/Views/`
- Models → `AppName/Models/`
- Managers → `AppName/Managers/`
- Extensions → `AppName/Extensions/`
- Tests → `AppNameTests/`

## Platform Guards
- HealthKit: `#if canImport(HealthKit)` (unavailable on tvOS)
- ActivityKit: `#if canImport(ActivityKit)` (iOS only)
- WatchKit: `#if os(watchOS)`
- UIKit haptics: `#if os(iOS)` (unavailable on tvOS, watchOS uses WKHaptic)

## Architecture Principle
Prefer the simplest solution that handles the requirements.
- Direct implementation over protocol abstraction (unless you have 2+ conforming types)
- Concrete types over generics (unless reuse is proven)
- Extensions on existing types over new wrapper types

# XcodeBuildMCP (59 tools)
claude mcp add XcodeBuildMCP -s user \
  -e XCODEBUILDMCP_SENTRY_DISABLED=true \
  -- npx -y xcodebuildmcp@latest mcp

# Apple Xcode MCP (20 tools)
claude mcp add --transport stdio xcode -s user -- xcrun mcpbridge

# Codex MCP setup
codex mcp add xcode -- xcrun mcpbridge

# Verify
claude mcp list

1. Project identity (bundle ID, target OS, architecture)
2. File structure with annotations
3. Build and test commands
4. Key patterns and rules
5. Prohibitions (NEVER touch .pbxproj)
6. Framework-specific context

{
  "PreToolUse": [{ "matcher": "Edit|Write", "command": "block .pbxproj" }],
  "PostToolUse": [{ "matcher": "Edit|Write", "command": "swiftformat" }]
}

@Observable         (not ObservableObject)
NavigationStack     (not NavigationView)
@State              (not @StateObject)
SwiftData @Model    (not Core Data)
async/await         (not completion handlers)
@MainActor          (on all Observable classes)
.glassEffect()      (Liquid Glass, iOS 26+)

Build:     build_sim          (not xcodebuild via Bash)
Test:      test_sim           (not xcodebuild test via Bash)
Sim:       list_sims/boot_sim (not xcrun simctl via Bash)
Docs:      DocumentationSearch (not WebSearch)
REPL:      ExecuteSnippet     (not swift via Bash)