使用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 工具，而非原始 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`（删除时置空）

### 容器配置
```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 分钟，却能节省数小时的代理调试时间。

### 真实 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 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 排序
- 绝对不要在未同步更新 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 中规则生效的体现。如果没有该规则，代理会尝试修改项目文件，很可能导致文件损坏。

## 智能体在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调用完成。

---

## AI 智能体在 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 钩子（参见[钩子](#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 视图 body 复杂度（智能体创建的深层嵌套视图会导致重绘开销）
- 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 模型版本
- 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

**表现：**代理使用已弃用的 `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：硬编码模拟器名称

**表现：**代理在构建命令中写入特定的模拟器名称（如 "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)