iOS-Apps mit KI-Agenten entwickeln: Der Praktiker-Leitfaden

TL;DR: Drei Agent-Runtimes liefern jetzt Code für iOS aus: Claude Code CLI mit MCP, Codex CLI mit MCP und die nativen Intelligence-Agenten von Xcode 26.3. Zwei MCP-Server (XcodeBuildMCP mit 59 Tools und Apples xcrun mcpbridge mit 20 Tools) verschaffen Agenten strukturierten Zugriff auf Builds, Tests, Simulatoren und Debugging. Dieser Leitfaden behandelt reale CLAUDE.md-Muster, Hook-Konfigurationen sowie ehrliche Einschätzungen dazu, was funktioniert und was bricht — gewonnen aus 8 produktiven iOS-Apps mit insgesamt 293 Swift-Dateien.¹⁷ Agenten glänzen bei SwiftUI-Views, SwiftData-Modellen, Refactoring und der Diagnose von Build-Fehlern. Sie scheitern an .pbxproj-Modifikationen, Code-Signierung und visuellem Debugging. Die Lücke zwischen „Agent schreibt Swift” und „Agent veröffentlicht eine iOS-App” wird durch Konfiguration überbrückt, nicht durch Prompting.

Ich habe 8 iOS-Apps mit KI-Coding-Agenten gebaut. Keine Prototypen — Apps im App Store, mit HealthKit-Integrationen, Metal-Shadern, SpriteKit-Physik, iCloud-Sync, Live Activities, Game Center-Bestenlisten und Multi-Plattform-Targets über iOS, watchOS und tvOS hinweg. Jede Zeile Swift in diesen Apps wurde entweder von einem Agenten geschrieben und von mir überprüft oder von mir geschrieben und von einem Agenten refaktoriert. Nach meiner Schätzung übernahmen Agenten den Großteil der zeilenweisen Autorenschaft; ich übernahm Review, Scope und die Teile, die menschliches Urteilsvermögen erfordern (visueller Feinschliff, Signierung, Performance-Tuning, App Store-Einreichung).

Dieser Leitfaden ist die Referenz, die ich mir bei meinem Einstieg gewünscht hätte. Er deckt den vollständigen Stack ab: welche Agent-Runtime man nutzen sollte, wie man MCP-Server für strukturierten Build-Zugriff konfiguriert, was in die CLAUDE.md gehört, welche Hooks verhindern, dass der Agent das Xcode-Projekt zerstört, und — entscheidend — wo Agenten scheitern und Sie selbst übernehmen müssen.

Zentrale Erkenntnisse

Für iOS-Entwickler, die neu bei KI-Agenten sind:

• Beginnen Sie mit Claude Code CLI + XcodeBuildMCP. Es ist die ausgereifteste Runtime mit der tiefsten MCP-Tool-Abdeckung. Installieren Sie zwei Befehle, fügen Sie Ihrem Projekt eine CLAUDE.md hinzu, und der Agent kann bauen, testen und debuggen, ohne dass Sie Fehlermeldungen kopieren müssen.
• Lassen Sie niemals einen Agenten .pbxproj modifizieren. Das ist die wichtigste Einzelregel. Ein PreToolUse-Hook, der Schreibvorgänge in .pbxproj und .xcodeproj/ blockiert, erspart Ihnen Stunden der Wiederherstellung.
• Ihre CLAUDE.md ist das Onboarding-Dokument des Agenten. Stunden, die darin investiert werden, zahlen sich in jeder Agent-Sitzung aus, die das Projekt berührt.

Für erfahrene Agent-Nutzer, die iOS in ihren Workflow aufnehmen:

• MCP verändert den iOS-Build-Loop grundlegend. Vor MCP schrieben Agenten Swift, konnten aber nicht überprüfen, ob es kompilierte. Mit XcodeBuildMCP schreibt der Agent Code, baut ihn, liest strukturierte Fehler, behebt sie und führt Tests aus — autonom.
• Drei Runtimes bedienen unterschiedliche Anforderungen. Claude Code CLI für tiefgreifende agentische Sitzungen, Codex CLI für Headless-Batch-Arbeit, native Xcode 26.3-Agenten für schnelle Inline-Korrekturen, ohne die IDE zu verlassen.
• Hook-Infrastruktur lässt sich übertragen. Ihre bestehenden PostToolUse-Formatter, PreToolUse-Blocker und Test-Runner-Hooks funktionieren mit geringfügigen Pfadanpassungen identisch für iOS-Projekte.

Für Team-Leads, die KI-gestützte iOS-Entwicklung evaluieren:

• Die Effektivität von Agenten skaliert mit der Projektdokumentation, nicht mit der Projektgröße. Eine 63-Dateien-App mit detaillierter CLAUDE.md liefert besseren Agent-Output als eine 14-Dateien-App ohne.
• Die .pbxproj-Grenze ist nicht verhandelbar. Agenten können Xcode-Projektdateien nicht zuverlässig bearbeiten. Ihr Workflow muss das manuelle Hinzufügen von Dateien zu Xcode-Targets berücksichtigen.
• Ehrliche ROI: Agenten übernehmen den Implementierungs-Großteil bei gut dokumentierten Projekten — sichtbar bei der 15-Dateien-TV-App, die in 3 Stunden agent-gestützter Arbeit ausgeliefert wurde (Fallstudie unten). Die verbleibende Arbeit — visueller Feinschliff, Signierung, Performance-Tuning, App Store-Einreichung — erfordert menschliches Urteilsvermögen.

Wählen Sie Ihren Pfad

So nutzen Sie diesen Leitfaden

Dies ist eine Referenz mit über 3.000 Zeilen. Beginnen Sie dort, wo Ihr Erfahrungsstand passt:

Inhaltsverzeichnis

1. Das Portfolio: 8 Apps, 293 Dateien
2. Voraussetzungen
3. Drei Agent-Runtimes für iOS
4. MCP Setup: Die vollständige Konfiguration
5. CLAUDE.md-Muster für iOS-Projekte
6. Ihre erste Agent-Sitzung
7. Was Agenten in iOS gut können
8. Was Agenten in iOS schlecht können
9. Hooks für die iOS-Entwicklung
10. Architekturmuster, die mit Agenten funktionieren
11. Framework-spezifischer Kontext
12. Multi-Plattform-Muster
13. Fortgeschrittene Workflows
14. Reale Fallstudien
15. Projekt-Lebenszyklus mit Agenten
16. Agent-Definitionen konfigurieren
17. Testmuster für agent-gestütztes iOS
18. Kontextfenster-Management für iOS-Projekte
19. Fehlerbehebung
20. Häufige Agent-Fehler in iOS
21. Die ehrliche Einschätzung
22. FAQ
23. Schnellreferenz-Karte
24. Referenzen

Verwandte Ressourcen

Das Portfolio: 8 Apps, 293 Dateien

Bevor wir uns der Konfiguration zuwenden, hier die Grundlage dieses Leitfadens. Es handelt sich nicht um Spielzeugprojekte — sie umfassen fünf Apple-Frameworks, drei Plattformen und die gesamte Bandbreite an iOS-Komplexität, vom 14-Dateien-Workout-Tracker bis zum 63-Dateien-Meditationstimer für mehrere Plattformen.

Warum die Dateianzahl zählt: Die Effektivität von Agents korreliert mit der Lesbarkeit eines Projekts, nicht mit dessen Größe. Return (63 Dateien) liefert bessere Agent-Ergebnisse als amp97 (41 Dateien), weil Return über eine detaillierte CLAUDE.md mit Datei-Annotationen, Architekturdiagrammen und expliziten Mustern verfügt. Die Metal-Shader von amp97 sind für Agents grundsätzlich schwerer zu erfassen — unabhängig von der Dokumentationsqualität.

Voraussetzungen

Bevor Sie eine Agent-Runtime für die iOS-Entwicklung einrichten:

Frist für App Store Connect: Ab dem 28.04.2026 müssen App-Uploads zu App Store Connect mit Xcode 26 oder neuer unter Verwendung von SDKs für iOS 26, iPadOS 26, tvOS 26, visionOS 26 oder watchOS 26 erstellt werden.¹² (macOS-Einreichungen sind von dieser Anforderung ausgenommen.) Falls Ihr Team noch Xcode 16.x verwendet, fungiert die agentengestützte Toolchain in diesem Leitfaden zugleich als Antrieb zum Wechsel — keiner der unten beschriebenen MCP Server funktioniert ohnehin ohne Xcode 26.3+.

Erforderlich: - macOS 15+ (Sequoia) oder macOS Tahoe - Xcode 26.3+ installiert und konfiguriert (die Mindestanforderung für xcrun mcpbridge); Xcode 26.4+ empfohlen für Bildanhänge in Swift Testing, Severity-Stufen für aufgezeichnete Issues, UI-Test-Crash-Warnungen mit Crashlogs sowie Verbesserungen am String-Catalog-Editor.¹³ Xcode 26.4.1 (16.04.2026, Build 17E202) ist die aktuelle stabile Version — reines Bugfix-Release.¹⁴ - Mindestens eine installierte iOS-Simulator-Runtime - Ein Anthropic API Konto (für Claude Code) oder OpenAI-Konto (für Codex)

Empfohlen: - SwiftFormat installiert (brew install swiftformat) — wird von Format-on-Save-Hooks verwendet - SwiftLint installiert (brew install swiftlint) — optional, aber nützlich für die Stildurchsetzung - Vertrautheit mit dem Terminal — alle drei Runtimes werden von der Kommandozeile aus bedient oder lassen sich darin integrieren

Überprüfen Sie Ihre Xcode-Installation:

# Check Xcode version
xcodebuild -version
# Expected: Xcode 26.3 or later (26.4+ recommended)

# 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")

Wenn xcrun mcpbridge „command not found” zurückgibt, benötigen Sie Xcode 26.3 oder neuer. Installieren oder aktualisieren Sie Xcode über den App Store oder developer.apple.com. Hinweis: xcode-select --install installiert lediglich die Command Line Tools, die mcpbridge nicht enthalten — Sie benötigen die vollständige Xcode.app.

Drei Agent-Runtimes für iOS

Drei verschiedene Runtimes können iOS-Code schreiben, kompilieren und testen. Sie sind nicht austauschbar — jede hat unterschiedliche Stärken, unterschiedliche MCP-Integrationsmuster und unterschiedliche ideale Anwendungsfälle.

1. Claude Code CLI

Was es ist: Der terminalbasierte agentische Coding-Assistent von Anthropic. Liest Ihre Codebasis, führt Befehle aus, modifiziert Dateien und verbindet sich über MCP mit externen Tools.

MCP-Integration: Vollständige Unterstützung sowohl für XcodeBuildMCP als auch für Apples Xcode MCP. Der Agent erkennt Tools über das MCP-Protokoll und ruft sie mit strukturierten Parametern auf. 59 + 20 Tools über beide Server hinweg.

Einrichtung:

# 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

Alternative — xcodebuildmcp init Auto-Installer (v2.1.0+, 23.02.2026):

Wenn Sie sich die manuelle MCP-Verdrahtung lieber ersparen möchten, liefert XcodeBuildMCP v2.1.0+ einen init-Unterbefehl mit, der Claude Code, Cursor oder Codex automatisch erkennt und die Agent-Skills + MCP-Konfiguration in einem Schritt installiert:

xcodebuildmcp init
# Or without a global install:
npx -y xcodebuildmcp@latest init

Flags: --print (Konfiguration für nicht unterstützte Clients an stdout schreiben), --uninstall (entfernen). Überspringen Sie dies, wenn Sie explizite Kontrolle darüber wünschen, welche MCP-Server in welchem Geltungsbereich eingebunden werden; die manuellen claude mcp add-Aufrufe oben geben Ihnen genau diese Kontrolle.¹⁵

Am besten geeignet für: Tiefgehende Implementierungssitzungen — Aufbau neuer Funktionen, Refactoring über mehrere Dateien hinweg, Debuggen komplexer Probleme, autonomes Ausführen von Build-Test-Fix-Schleifen. Das 1M-Kontextfenster von Claude Code (mit Opus 4.6) bedeutet, dass der Agent die meisten kleinen bis mittelgroßen iOS-Projekte im Arbeitsspeicher halten kann — meiner Erfahrung nach bis zu etwa 50 Dateien, abhängig von der Dateigröße.

Typische Sitzung:

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]

Der entscheidende Unterschied zum Workflow vor MCP: Der Agent fordert Sie nie auf, manuell zu kompilieren oder Fehlerausgaben einzufügen. Die Build-Error-Fix-Schleife läuft autonom ab.

2. Codex CLI

Was es ist: OpenAIs terminalbasierter Coding-Agent. Vom Konzept her ähnlich wie Claude Code, verwendet jedoch OpenAI-Modelle (GPT-4o, o3) und hat ein anderes Berechtigungsmodell.

MCP-Integration: Codex unterstützt MCP über den Befehl codex mcp add. Apples Xcode MCP funktioniert direkt:

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

XcodeBuildMCP funktioniert ebenfalls mit Codex über denselben npx-Befehl:

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

Am besten geeignet für: Headless-Batch-Operationen, CI/CD-Integration und Aufgaben, bei denen Sie eine zweite Meinung von einer anderen Modellfamilie wünschen. Der Sandbox-Modus von Codex führt Code in isolierten Umgebungen aus, was für destruktive Operationen wie Testsuite-Läufe nützlich ist, die den Zustand verändern.

Wesentliche Unterschiede zu Claude Code: - Verwendet OpenAI-Modelle anstelle von Claude-Modellen - Andere Kontextfenstergrößen und Token-Ökonomie - Sandbox-First-Berechtigungsmodell (standardmäßig restriktiver) - Kleineres MCP-Ökosystem (weniger getestete Community-Server) - Hook-System verfügbar (v0.119.0+), aber weniger ausgereift als das von Claude Code — weniger Event-Typen und kein bedingtes if-Feld

Wann Codex statt Claude Code für iOS verwenden:

Verwenden Sie Codex, wenn Sie Modellvielfalt wünschen — wenn ein zweiter Agent den vom ersten geschriebenen Code überprüft, werden andere Fehlerklassen erkannt. Der Collab-Workflow (Claude baut, Codex überprüft) ist für iOS effektiv, da SwiftUI-Muster, die für eine Modellfamilie korrekt aussehen, subtile Probleme aufweisen können, die eine andere erkennt. Metal-Shader und Concurrency-Muster profitieren besonders von einer Dual-Model-Review.

3. Xcode 26.3 Native Agents

Was es ist: Apple hat KI-Coding-Agents direkt in das Intelligence-Panel von Xcode integriert. Ab Xcode 26.3 können Sie Claude Agent und Codex als Intelligence-Provider in Xcode Einstellungen > Intelligence konfigurieren.

Einrichtung:

1. Öffnen Sie Xcode 26.3+
2. Navigieren Sie zu Einstellungen > Intelligence
3. Fügen Sie einen neuen Provider hinzu:
4. Für Claude: Wählen Sie „Claude Agent” und geben Sie Ihren Anthropic-API-Schlüssel ein
5. Für Codex: Wählen Sie „Codex” und geben Sie Ihren OpenAI-API-Schlüssel ein
6. Der Agent erscheint in der Intelligence-Seitenleiste und kann inline aufgerufen werden

Am besten geeignet für: Schnelle Inline-Bearbeitungen, Code-Vervollständigung mit Agent-Level-Reasoning sowie Entwickler, die Xcode nicht verlassen möchten. Die native Integration bedeutet, dass der Agent direkten Zugriff auf den Projektkontext von Xcode hat — geöffnete Dateien, Build-Targets, Scheme-Konfiguration — ohne MCP-Bridging.

Einschränkungen im Vergleich zu CLI-Agents: - Kein Hook-System — Sie können kein Format-on-Save erzwingen oder .pbxproj-Schreibvorgänge blockieren - Kein CLAUDE.md-Loading — der Agent liest Ihre projektbezogenen Konfigurationsdateien nicht - Eingeschränkte Autonomie — der Agent arbeitet an der aktuellen Datei oder Auswahl, nicht über das gesamte Projekt hinweg - Keine Subagent-Delegation — komplexe mehrstufige Aufgaben können nicht parallelisiert werden - Keine MCP-Server-Konfiguration — der Agent verwendet ausschließlich die in Xcode integrierten Tools

Wann Xcode-Native-Agents verwenden:

Für schnelle, eng umrissene Bearbeitungen, bei denen der Wechsel ins Terminal Overhead bedeutet. „Fügen Sie diesem Modell eine berechnete Eigenschaft hinzu.” „Schreiben Sie einen Unit-Test für diese Funktion.” „Refaktorieren Sie diese View, um @Observable zu verwenden.” Aufgaben, die ein oder zwei Dateien betreffen und keinen Build-Test-Zyklus erfordern.

Für alles, was Building, Testing, Multi-File-Refactoring oder autonome Fehlerkorrektur erfordert, verwenden Sie einen CLI-Agent mit MCP.

Runtime-Vergleichsmatrix

Die Empfehlung: Verwenden Sie Claude Code CLI als primäre Runtime. Verwenden Sie Xcode 26.3 Native Agents für schnelle Inline-Bearbeitungen. Verwenden Sie Codex CLI für Review-Durchläufe und Batch-Operationen. Die drei ergänzen sich, anstatt zu konkurrieren.

MCP Setup: Die vollständige Konfiguration

MCP (Model Context Protocol) verwandelt einen Agenten von „schreibt Swift und hofft, dass Sie es bauen” zu „schreibt Swift, baut es, liest strukturierte Fehler und behebt sie.” Dieser Abschnitt geht tiefer als der Blogbeitrag — er behandelt beide Server, alle Installationsmethoden, die Verifikation und die Agent-Konfiguration, die sicherstellt, dass die Tools tatsächlich verwendet werden.

XcodeBuildMCP: 59 Tools für Headless-iOS-Entwicklung

XcodeBuildMCP verpackt xcodebuild, xcrun simctl und LLDB in 59 strukturierte MCP-Tools. Es funktioniert, ohne dass Xcode läuft — der gesamte Build-Test-Debug-Zyklus läuft headless über Apples Befehlszeilen-Tools ab.

Installationsoptionen:

# 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

Das Flag -s user macht den Server global über alle Projekte hinweg verfügbar. Lassen Sie es weg für eine projektbezogene Installation (sinnvoll, wenn Sie MCP nur in iOS-Projekten und nicht in Web-Projekten benötigen).

Die Umgebungsvariable -e XCODEBUILDMCP_SENTRY_DISABLED=true deaktiviert die Crash-Report-Telemetrie. XcodeBuildMCP enthält standardmäßig Sentry, das Fehlerdaten einschließlich Dateipfaden sendet. Verzichten Sie darauf, es sei denn, Sie möchten Diagnosedaten zum Projekt beitragen.¹

Vollständige Tool-Übersicht (59 Tools in 8 Kategorien):

Die Tools, die für die tägliche Arbeit am wichtigsten sind:

1. build_sim — Sie werden dies hunderte Male aufrufen. Es liefert JSON mit Fehlern, kategorisiert nach Datei, Zeile und Schweregrad. Der Agent liest den Fehler, navigiert zur Datei und behebt ihn, ohne dass Sie etwas anrühren müssen.

2. test_sim — Liefert Ergebnisse pro Testmethode. Der Agent weiß genau, welcher Test fehlgeschlagen ist und warum — nicht nur „Tests fehlgeschlagen.”

3. list_sims + boot_sim — Simulatorverwaltung, ohne sich xcrun simctl-Flags merken zu müssen. Der Agent erkennt verfügbare Runtimes und wählt ein passendes Gerät.

4. discover_projs + list_schemes — Projekt-Introspektion. Der Agent muss Ihren Scheme-Namen oder die Workspace-Struktur nicht erraten.

5. debug_attach_sim + debug_stack + debug_variables — Remote-LLDB-Debugging. Der Agent kann Breakpoints setzen, Variablen inspizieren und durch den Code steppen, ohne dass Sie den Debugger öffnen müssen.

Apple Xcode MCP: 20 Tools als Brücke zu Xcode

Apples MCP-Server wird mit Xcode 26.3 über xcrun mcpbridge ausgeliefert. Er kommuniziert mit einem laufenden Xcode-Prozess über XPC (Apples Inter-Prozess-Kommunikations-Framework) und stellt internen Zustand bereit, auf den kein CLI-Tool zugreifen kann.

Installation:

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

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

Erfordert Xcode 26.3+ und einen laufenden Xcode-Prozess. Wenn Xcode nicht geöffnet ist, schlägt jeder MCP-Aufruf über diesen Server fehl oder hängt sich auf. XcodeBuildMCP hat diese Einschränkung nicht.

Tool-Übersicht (20 Tools in 5 Kategorien):

Tools, die einzigartig für Apple MCP sind (in XcodeBuildMCP nicht verfügbar):

1. DocumentationSearch — Durchsucht Apples Entwicklerdokumentation einschließlich WWDC-Sessions. Schneller und zuverlässiger als die Websuche bei Apple-API-Fragen. Fragen Sie „Ist HKQuantityType(.dietaryWater) gültig?” und Sie erhalten eine eindeutige Antwort direkt aus der Quelle.

2. ExecuteSnippet — Swift-REPL-Ausführung im Kontext des Projekts. Der Agent kann API-Verhalten verifizieren, Typkonvertierungen testen und Ausdrücke validieren, ohne die gesamte App zu bauen.

3. RenderPreview — Rendert SwiftUI-Previews headless. Der Agent kann prüfen, ob eine View ohne Fehler rendert, kann aber die visuelle Korrektheit nicht beurteilen (das Rendering wird als Daten zurückgegeben, nicht visuell inspiziert).

4. XcodeListNavigatorIssues — Liefert Echtzeit-Diagnosen von Xcodes Analyzer, nicht nur Build-Fehler. Erkennt Probleme wie unbenutzte Variablen, potenzielle Retain Cycles und Deprecation-Warnungen, die das Build-System nicht offenlegt.

Warum beide Server

Sie überschneiden sich bei Builds und Tests, unterscheiden sich aber fundamental:

┌─────────────────────────────────────────────────────────────────┐
│                     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        │         │                     │       │
│  └─────────────────────┘         └─────────────────────┘       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Verwenden Sie XcodeBuildMCP für: den Build-Test-Debug-Zyklus. Es funktioniert ohne geöffnetes Xcode, verbraucht weniger Systemspeicher und bietet eine umfangreichere Simulator- und Geräteverwaltung. Dies ist Ihr primäres Build-Tool.

Verwenden Sie Apple Xcode MCP für: Dokumentationssuchen, Swift-REPL-Verifikation, SwiftUI-Preview-Rendering und Echtzeitdiagnose. Halten Sie Xcode während Sessions, die diese Funktionen benötigen, geöffnet.

In der Praxis: Ich verwende XcodeBuildMCP für etwa 90 % aller MCP-Aufrufe und Apple Xcode MCP für Dokumentation und REPL-Verifikation. Der Agent greift bei Builds und Tests standardmäßig auf XcodeBuildMCP zurück, weil es schneller (kein Overhead durch den Xcode-Prozess) und zuverlässiger (keine XPC-Abhängigkeit) ist.

Verifikation

Nachdem Sie beide Server installiert haben, prüfen Sie, ob sie verbunden sind:

# List all configured MCP servers
claude mcp list

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

Wenn ein Server „Disconnected” anzeigt oder gar nicht erscheint:

1. XcodeBuildMCP verbindet sich nicht: Stellen Sie sicher, dass Node.js installiert ist (node --version). Der Befehl npx erfordert Node.js 18+.
2. Apple Xcode MCP verbindet sich nicht: Stellen Sie sicher, dass Xcode 26.3+ installiert ist und der Befehl xcrun mcpbridge in Ihrem Terminal funktioniert. Öffnen Sie Xcode mindestens einmal, um die Lizenzvereinbarung zu akzeptieren.
3. Beide erscheinen nicht: Starten Sie Claude Code neu (claude in einem neuen Terminal). MCP-Server, die mitten in der Session registriert wurden, erscheinen möglicherweise erst nach einem Neustart.

Dem Agenten beibringen, MCP zu verwenden

Die Installation der MCP-Server ist notwendig, aber nicht ausreichend. Ohne explizite Anleitung kann der Agent darauf zurückfallen, xcodebuild über Bash auszuführen (unstrukturierte Ausgabe, verschwendete Kontext-Tokens) oder die Websuche für die Apple-Dokumentation zu verwenden (langsamer, weniger zuverlässig).

Fügen Sie dies zu Ihrer CLAUDE.md oder Agent-Definition hinzu:

## Build & Test — Always Use MCP

Bevorzugen Sie MCP-Tools gegenüber rohen Shell-Befehlen für ALLE Build-Operationen:

- **Build**: `build_sim` / `build_device` (NICHT `xcodebuild` über Bash)
- **Test**: `test_sim` / `test_device` (NICHT `xcodebuild test` über Bash)
- **Simulators**: `list_sims`, `boot_sim`, `open_sim` (NICHT `xcrun simctl` über Bash)
- **Debug**: `debug_attach_sim`, `debug_stack`, `debug_variables`
- **Apple-Dokumentation**: `DocumentationSearch` (NICHT WebSearch für Apple APIs)
- **Swift-Verifizierung**: `ExecuteSnippet` (NICHT `swift` über Bash)
- **Vorschauen**: `RenderPreview` für Headless-SwiftUI-Verifizierung

MCP liefert strukturierte JSON zurück. Bash liefert unstrukturierten Text.
Strukturierte Daten bedeuten weniger verbrauchte Tokens und bessere Fehlerdiagnose.

Diese Anleitung sorgt dafür, dass der Agent zuerst zu MCP-Tools greift. Ohne sie werden Sie beobachten, wie der Agent lange xcodebuild-Befehle über Bash konstruiert, Tausende von Kontext-Tokens für das Parsen der Ausgabe verbraucht und manchmal den tatsächlichen Fehler falsch identifiziert.

CLAUDE.md-Patterns für iOS-Projekte

Ihre CLAUDE.md ist die wichtigste Datei im Projekt für agentengestützte Entwicklung. Sie ist das Onboarding-Dokument des Agenten — der Unterschied zwischen einem neuen Mitarbeiter, der die Architektur-Dokumentation gelesen hat, und einem, der rät.

Jedes iOS-Projekt, das ich pflege, hat eine CLAUDE.md. Hier sind die Patterns, die funktionieren, abgeleitet aus allen 8 Apps.

Die wesentlichen Abschnitte

Jede iOS CLAUDE.md benötigt diese sechs Abschnitte. Alles andere ist optional.

1. Projektidentität

# 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

Warum das wichtig ist: Der Agent muss das Deployment-Target kennen, bevor er Code schreibt. Ein Agent, der iOS 17 anvisiert, wird NavigationView und @ObservedObject verwenden. Ein Agent, der iOS 26 anvisiert, wird NavigationStack und @Observable verwenden. Die Bundle ID ist relevant für Entitlements und HealthKit-Konfiguration. Die Swift-Version bestimmt das Concurrency-Modell (async/await vs. Completion-Handler, Strict Concurrency vs. Lenient).

2. Dateistruktur mit Zweck-Annotationen

## File Structure

```
Return/
├── ReturnApp.swift              # App entry, dark mode enforcement
├── ContentView.swift            # Main timer view with theme backgrounds
├── TimerManager.swift           # Timer state, logic, and repeat handling
├── AudioManager.swift           # Sound playback with AVAudioPlayer
├── Settings.swift               # Centralized settings with validation
├── SettingsSheet.swift          # Settings UI
├── HealthKitManager.swift       # Mindful session logging + cross-device sync
├── LiveActivityManager.swift    # Lock Screen/Dynamic Island
├── Theme.swift                  # Theme definitions
├── ThemeManager.swift           # Theme state management
├── VideoBackgroundView.swift    # AVPlayer video backgrounds
├── GlassTextShape.swift         # Core Text glyph paths for glass effect
├── GlassTimerText.swift         # Timer text with glass material
└── Constants.swift              # App constants
```

Die Inline-Kommentare nach jedem Dateinamen sind keine Dekoration. Sie sind die wirkungsvollste Dokumentation, die Sie schreiben können. Wenn der Agent entscheidet, wo eine neue Funktion hinzugefügt werden soll, leiten ihn diese Annotationen beim ersten Versuch zur richtigen Datei, anstatt jede Datei zu lesen, um das Projektlayout zu verstehen.

Anti-Pattern: Dateien ohne Annotationen aufzulisten. TimerManager.swift sagt dem Agenten nichts darüber, ob die Datei State, UI oder beides verwaltet. TimerManager.swift # Timer state, logic, and repeat handling sagt ihm genau, was dort hineingehört und was nicht.

3. Build- und Test-Befehle

## Build & Test

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

Run tests:
```bash
xcodebuild -scheme Return -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test
```

Run tvOS tests:
```bash
xcodebuild -scheme ReturnTV -destination 'platform=tvOS Simulator,name=Apple TV' test
```

**Prefer MCP tools** (`build_sim`, `test_sim`) over these raw commands.
MCP returns structured JSON with categorized errors.

Geben Sie die rohen Befehle an, auch wenn der Agent MCP bevorzugen sollte. Die rohen Befehle dienen als Fallback-Dokumentation und machen die Schema-Namen und Destinations explizit.

4. Wichtige Patterns und Regeln

## 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

Diese Patterns verhindern, dass der Agent Inkonsistenzen einführt. Ohne explizite Pattern-Dokumentation wird der Agent gelegentlich ObservableObject in einer Datei und @Observable in einer anderen verwenden oder einen neuen Settings-Mechanismus erstellen, anstatt das vorhandene Settings.shared-Singleton zu nutzen.

5. Was der Agent niemals tun darf

## 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

Explizite Verbote sind wirksamer als implizite Erwartungen. Der Agent befolgt negative Einschränkungen zuverlässiger als positive Vorschläge, weil sie binär sind (tu es / tu es nicht), anstatt heuristisch (bevorzuge dies / verwende manchmal das).

6. Framework-spezifischer Kontext

Dieser Abschnitt variiert je nach App. Fügen Sie ihn für jedes Framework hinzu, das eine nicht offensichtliche Konfiguration aufweist:

Für HealthKit-Apps:

## 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)`

Für SwiftData-Apps:

## 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

Für SpriteKit-Apps:

## SpriteKit Scene Hierarchy

```
GameScene (SKScene)
├── backgroundLayer (SKNode, zPosition: -100)
│   └── StarfieldNode (custom, parallax scrolling)
├── gameLayer (SKNode, zPosition: 0)
│   ├── playerShip (PlayerNode, zPosition: 10)
│   ├── enemyContainer (SKNode, zPosition: 5)
│   └── bulletPool (SKNode, zPosition: 8)
├── effectsLayer (SKNode, zPosition: 50)
│   └── ParticleManager (manages explosion/trail emitters)
└── hudLayer (SKNode, zPosition: 100)
    ├── scoreLabel (SKLabelNode)
    └── healthBar (HealthBarNode)
```

- 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

Für Metal-Apps:

## 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.

Reale CLAUDE.md: Banana List (SwiftUI + SwiftData + iCloud + MCP-Server)

Hier ist ein annotiertes Beispiel, das zeigt, wie alle sechs Abschnitte für eine mäßig komplexe App zusammenwirken. Dies ist das CLAUDE.md-Pattern, das ich für Banana List verwende, eine Grocery-List-App mit 53 Dateien, iCloud-Sync und einem benutzerdefinierten MCP-Server, der die Daten der App für Claude Desktop bereitstellt:

# 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

## Dateistruktur

```
BananaList/
├── BananaListApp.swift           # App entry, model container setup
├── Models/
│   ├── GroceryList.swift         # @Model: list with name, items, color
│   ├── GroceryItem.swift         # @Model: item with name, quantity, category, isCompleted
│   ├── Category.swift            # @Model: user-defined categories
│   └── SampleData.swift          # Preview and test data
├── Views/
│   ├── ListsView.swift           # Main list of grocery lists
│   ├── ListDetailView.swift      # Items within a list
│   ├── ItemRow.swift             # Single item row with swipe actions
│   ├── AddItemSheet.swift        # New item form
│   ├── CategoryPicker.swift      # Category selection with create-new
│   └── SettingsView.swift        # App settings
├── Managers/
│   ├── CloudSyncManager.swift    # iCloud Drive sync status and conflict resolution
│   └── HapticManager.swift       # UIImpactFeedbackGenerator wrapper
├── MCP/
│   ├── MCPServer.swift           # MCP server for Claude Desktop integration
│   ├── ListTools.swift           # MCP tools: list CRUD operations
│   └── ItemTools.swift           # MCP tools: item CRUD operations
└── Extensions/
    ├── Color+Extensions.swift    # Custom color definitions
    └── View+Extensions.swift     # Reusable view modifiers
```

## SwiftData-Modelle

### Beziehungen
- `GroceryList` hat viele `GroceryItem` (kaskadierendes Löschen)
- `GroceryItem` gehört zu einer `GroceryList` (erforderlich)
- `GroceryItem` hat optionale `Category`
- `Category` hat viele `GroceryItem` (Nullify beim Löschen)

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

### Query-Muster
- Listen: `@Query(sort: \GroceryList.name) var lists: [GroceryList]`
- Aktive Einträge: `@Query(filter: #Predicate { !$0.isCompleted })`
- Nach Kategorie: Filterung im Speicher nach dem Abruf (Einschränkungen bei SwiftData-Prädikaten)

## Build & Test

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

Bevorzugen Sie MCP-Tools (`build_sim`, `test_sim`) gegenüber direkten Befehlen.

## Wichtige Muster

### Observable + SwiftData
- SwiftData-`@Model`-Klassen sind automatisch Observable
- Fügen Sie `@Observable` NICHT zu `@Model`-Klassen hinzu (redundant, verursacht Warnungen)
- Verwenden Sie `@Bindable` für bidirektionale Bindungen an Modelleigenschaften in Formularen
- Verwenden Sie `@Query` in Views, `modelContext.fetch()` in Code außerhalb von Views

### iCloud-Synchronisierung
- Automatisch über die SwiftData-CloudKit-Integration
- Konfliktauflösung: Last-Write-Wins (CloudKit-Standard)
- Sync-Status verfügbar über `CloudSyncManager.shared.syncState`
- Testen Sie die Synchronisierung, indem Sie zwei Simulatoren mit demselben iCloud-Konto verwenden

### MCP-Server-Architektur
- Läuft als lokaler WebSocket-Server auf Port 8765
- Stellt 6 Tools bereit: listAll, getList, createList, addItem, completeItem, deleteItem
- Claude Desktop verbindet sich über die MCP-Konfiguration in `~/.config/claude-desktop/config.json`

## Regeln

- Ändern Sie NIEMALS den Inhalt von .pbxproj oder .xcodeproj
- Ändern Sie NIEMALS das Modellschema, ohne SampleData.swift zu aktualisieren
- Verwenden Sie NIEMALS `ObservableObject` — SwiftData-Modelle sind bereits Observable
- Verwenden Sie NIEMALS `@StateObject` — verwenden Sie `@State` mit `@Observable`-Klassen
- Verwenden Sie NIEMALS `NavigationView` — immer `NavigationStack`
- Fügen Sie das `@Observable`-Macro NIEMALS zu `@Model`-Klassen hinzu
- Verwenden Sie IMMER `@Bindable` für Formularbindungen an Modelleigenschaften
- Testen Sie iCloud-Sync-Änderungen IMMER auf zwei Simulatorinstanzen

Reale CLAUDE.md: Reps (Minimale SwiftData-App — 14 Dateien)

Bei kleinen Projekten kann die CLAUDE.md kompakt ausfallen. Hier ist das Muster für Reps, einen Workout-Tracker mit 14 Dateien. Beachten Sie, dass selbst eine kurze CLAUDE.md alle sechs essenziellen Abschnitte abdeckt:

# Reps - Workout Tracking

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

## File Structure

```
Reps/
├── RepsApp.swift              # App entry, model container
├── Models/
│   ├── Workout.swift          # @Model: workout with exercises, date, duration
│   ├── Exercise.swift         # @Model: exercise with sets, reps, weight
│   └── ExerciseTemplate.swift # @Model: saved exercise definitions
├── Views/
│   ├── WorkoutListView.swift  # Main list of workouts
│   ├── WorkoutDetailView.swift # Exercises within a workout
│   ├── ExerciseRow.swift      # Single exercise with inline editing
│   ├── AddExerciseSheet.swift # Exercise selection from templates
│   ├── NewWorkoutView.swift   # Start new workout flow
│   └── StatsView.swift        # Progress charts and summaries
├── Managers/
│   └── WorkoutTimer.swift     # Active workout timer
└── Extensions/
    └── Date+Extensions.swift  # Formatting helpers
```

## 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
```

## SwiftData Relationships

- `Workout` has many `Exercise` (cascade delete)
- `Exercise` has optional `ExerciseTemplate`
- `ExerciseTemplate` standalone (nullify on exercise delete)

## Rules

- NEVER modify .pbxproj
- NEVER use ObservableObject — use @Observable
- NEVER use NavigationView — use NavigationStack
- @Model classes are already Observable — do not add @Observable macro
- Use @Bindable for form bindings to model properties

Das sind 40 Zeilen CLAUDE.md für ein Projekt mit 14 Dateien. Das Schreiben dauert 10 Minuten und erspart Stunden an Verwirrung beim Agenten.

Reale CLAUDE.md: Starfield Destroyer (SpriteKit + Metal — 32 Dateien)

Spieleprojekte erfordern mehr framework-spezifischen Kontext. Der Agent muss den Szenengraphen, die Physikkategorien und die Spielzustandsmaschine verstehen:

# 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

```
StarfieldDestroyer/
├── StarfieldDestroyerApp.swift    # App entry, Game Center auth
├── GameScene.swift                # Main game scene, update loop
├── MenuScene.swift                # Title screen, ship selection
├── Entities/
│   ├── PlayerShip.swift           # Player node with physics, weapons, shields
│   ├── EnemyShip.swift            # Enemy base class with AI behaviors
│   ├── Bullet.swift               # Bullet pool node
│   ├── PowerUp.swift              # Collectible power-ups
│   └── Boss.swift                 # Boss enemies (levels 33, 66, 99)
├── Systems/
│   ├── LevelManager.swift         # Level progression, wave spawning
│   ├── PhysicsCategory.swift      # UInt32 bitmask categories
│   ├── CollisionHandler.swift     # Contact delegate methods
│   ├── ScoreManager.swift         # Score tracking, multipliers
│   ├── ParticleManager.swift      # Explosion, trail, shield emitters
│   └── AudioManager.swift         # Sound effects, background music
├── UI/
│   ├── HUDNode.swift              # Score, health, level display
│   ├── ShipSelectView.swift       # SwiftUI ship selection (UIHostingController)
│   ├── GameOverView.swift         # Game over screen with score submission
│   └── PauseMenu.swift            # Pause overlay
├── Metal/
│   ├── MetalRenderer.swift        # Post-processing render pipeline
│   ├── BloomShader.metal          # Bloom post-process effect
│   └── ShaderTypes.h              # Shared uniforms (bridging header)
├── Data/
│   ├── ShipData.swift             # 8 ship definitions (speed, damage, shields)
│   ├── LevelData.swift            # 99 level configurations
│   └── AchievementData.swift      # Game Center achievement definitions
└── GameCenterManager.swift        # Leaderboard/achievement submission
```

## SpriteKit Scene Hierarchy

```
GameScene (SKScene)
├── backgroundLayer (zPosition: -100)
│   └── StarfieldNode (parallax scrolling, 3 layers)
├── gameLayer (zPosition: 0)
│   ├── playerShip (zPosition: 10)
│   ├── enemyContainer (zPosition: 5)
│   ├── bulletPool (zPosition: 8) — pre-allocated 50 bullets
│   └── powerUpContainer (zPosition: 3)
├── effectsLayer (zPosition: 50)
│   └── ParticleManager (explosion + trail emitters)
└── hudLayer (zPosition: 100)
    ├── scoreLabel (SKLabelNode)
    ├── healthBar (custom SKShapeNode)
    └── levelLabel (SKLabelNode)
```

## 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
```

## Game State Machine

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

## Metal Post-Processing

- Bloom shader: `BloomShader.metal` — multi-pass Gaussian blur + additive blend
- Uniforms: `PostProcessUniforms { float intensity; float threshold; float2 resolution; }`
- Applied after SpriteKit renders each frame via `SKView.presentScene(:transition:)`
- DO NOT modify Metal shaders without testing on device

## Build & Test

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

## Regeln

- NIEMALS .pbxproj modifizieren
- NIEMALS PhysicsCategory-Bitmasken modifizieren (bricht die gesamte Kollisionserkennung)
- NIEMALS die z-Order der Szenenhierarchie ändern, ohne die Render-Reihenfolge zu verstehen
- NIEMALS ShaderTypes.h modifizieren, ohne sowohl Swift- als auch Metal-Referenzen zu aktualisieren
- Neue Gegner durch Subclassing von EnemyShip hinzufügen, nicht durch dessen Modifikation
- Bullet-Pooling: über removeFromParent() + erneutes Hinzufügen recyceln, niemals neu allokieren
- Game Center: vor dem Übermitteln von Punktzahlen immer isAuthenticated prüfen

Echte CLAUDE.md: amp97 (Metal + Audio-Visualisierung — 41 Dateien)

Metal-Projekte benötigen den umfassendsten Framework-spezifischen Kontext, da Agenten die visuelle Ausgabe nicht verifizieren können:

# amp97 - Audio Visualizer

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

## Architektur

```
Audio Input (microphone/file)
    → AVAudioEngine tap
    → FFT (vDSP)
    → Frequency/amplitude buffers
    → Metal compute shader (analysis)
    → Metal render pipeline (visualization)
    → CADisplayLink (60fps)
    → MTKView
```

## Dateistruktur

```
amp97/
├── amp97App.swift               # App entry
├── Audio/
│   ├── AudioEngine.swift        # AVAudioEngine setup, tap installation
│   ├── FFTProcessor.swift       # vDSP FFT, frequency bin extraction
│   ├── AudioBuffer.swift        # Ring buffer for audio data
│   └── MicrophoneManager.swift  # Microphone permission, session config
├── Rendering/
│   ├── MetalView.swift          # MTKView wrapper for SwiftUI
│   ├── Renderer.swift           # Main render loop, pipeline state
│   ├── ShaderLibrary.swift      # Compiled shader management
│   ├── BufferManager.swift      # Triple-buffered uniform updates
│   └── TextureManager.swift     # Offscreen render targets
├── Shaders/
│   ├── Shaders.metal            # Vertex + fragment shaders
│   ├── AudioCompute.metal       # Audio analysis compute kernel
│   ├── PostProcess.metal        # Bloom, color grading
│   └── ShaderTypes.h            # Shared uniforms (bridging header)
├── Visualizations/
│   ├── WaveformViz.swift        # Oscilloscope-style waveform
│   ├── SpectrumViz.swift        # Frequency spectrum bars
│   ├── CircularViz.swift        # Radial visualization
│   └── VizSelector.swift        # Visualization switching
├── Views/
│   ├── MainView.swift           # Full-screen viz with overlays
│   ├── ControlsOverlay.swift    # Play/pause, viz selection, gain
│   └── SettingsView.swift       # Audio source, sensitivity
└── Extensions/
    ├── SIMD+Extensions.swift    # Vector math helpers
    └── Color+Metal.swift        # UIColor → float4 conversion
```

## 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;
```

### Render-Pipeline
1. Compute Pass: AudioCompute.metal verarbeitet FFT-Daten → Texture
2. Render Pass: Shaders.metal liest Texture + Uniforms → Visualisierung
3. Post-Process Pass: PostProcess.metal wendet Bloom an → finale Ausgabe

### Buffer-Verwaltung
- Triple Buffering mit DispatchSemaphore(value: 3)
- Uniforms werden pro Frame auf der CPU aktualisiert, von GPU 1-2 Frames später konsumiert
- Audio-Daten-Ringbuffer: 4096 Samples, lock-free Single Producer/Consumer

## Regeln

- NIEMALS ShaderTypes.h modifizieren, ohne BEIDE Swift- und Metal-Seiten zu aktualisieren
- NIEMALS 64 Frequenzbänder überschreiten (feste Buffer-Größe im Shader)
- NIEMALS visuelle Metal-Ausgabe im Simulator testen — nur auf dem Gerät
- NIEMALS das Format des Audio-Engine-Taps modifizieren (48kHz, mono, float32)
- Triple-Buffer-Disziplin: Semaphore immer im Completion Handler signalisieren
- Audio Session: .playAndRecord-Kategorie mit .defaultToSpeaker-Option

Skalierung von CLAUDE.md mit der Projektgröße

Der richtige Detailgrad hängt von der Dateianzahl und der Framework-Komplexität ab:

Die Kosten für Überdokumentation sind nahezu null (der Agent überspringt, was er nicht benötigt). Die Kosten für Unterdokumentation sind hoch (der Agent erfindet Patterns, die mit Ihrem Codebase im Widerspruch stehen).

CLAUDE.md-Checkliste

Verwenden Sie diese Checkliste beim Erstellen oder Auditieren einer CLAUDE.md für ein iOS-Projekt:

• [ ] Bundle ID und Deployment Target angegeben
• [ ] Swift-Version und Architekturmuster benannt
• [ ] Dateistruktur mit inline Zweckanmerkungen
• [ ] Build-Befehl mit korrektem Scheme und Destination
• [ ] Test-Befehl mit korrektem Scheme und Destination
• [ ] MCP-Präferenz vermerkt (“prefer build_sim over xcodebuild”)
• [ ] @Observable-Regel (niemals ObservableObject)
• [ ] NavigationStack-Regel (niemals NavigationView)
• [ ] .pbxproj-Verbot
• [ ] Framework-spezifischer Kontext (HealthKit-Berechtigungen, SwiftData-Beziehungen, SpriteKit-Hierarchie, Metal-Pipeline)
• [ ] Plattformverfügbarkeits-Guards dokumentiert (#if canImport, #if os)
• [ ] Wichtige Singletons und gemeinsame Patterns dokumentiert
• [ ] Bekannte Einschränkungen oder Stolperfallen vermerkt

Ihre erste Agent-Session

Mit konfiguriertem MCP und einer CLAUDE.md in Ihrem Projekt folgt hier eine Anleitung zu einer effektiven ersten Session. Diese verwendet Claude Code CLI, aber der Workflow gilt für jede Laufzeitumgebung.

Schritt 1: Verifizieren, dass der Agent Ihr Projekt sehen kann

Sie: Summarize this project. What scheme should I build with?

Claude: [reads CLAUDE.md]
        [calls discover_projs via MCP]
        [calls list_schemes via MCP]

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

Wenn der Agent nicht auf Ihren CLAUDE.md-Inhalt verweist, prüfen Sie, ob die Datei im Projekt-Stammverzeichnis liegt (im selben Verzeichnis wie .xcodeproj oder Package.swift).

Schritt 2: Health-Check-Build durchführen

Sie: Build the Return scheme for iOS simulator and report results.

Claude: [calls list_sims — finds iPhone 16 Pro on iOS 26.2]
        [calls boot_sim — boots the simulator]
        [calls build_sim — builds the project]

        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.

Schritt 3: Tests ausführen

Sie: Run all tests and report pass/fail.

Claude: [calls test_sim]

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

Schritt 4: Eine Funktion implementieren

Sie: Add a new "Rain" theme to the theme system. Follow the existing
     pattern in Theme.swift and ThemeManager.swift. Include a rain
     ambient sound. Build and test after implementation.

Claude: [reads Theme.swift — understands Theme struct pattern]
        [reads ThemeManager.swift — understands theme registration]
        [reads existing theme definitions]
        [adds Rain theme to Theme.swift following existing pattern]
        [registers Rain theme in ThemeManager.swift]
        [calls build_sim — build succeeds]
        [calls test_sim — all tests pass]

        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).

Der Hinweis des Agents, dass er .pbxproj nicht modifiziert hat, ist das Ergebnis der Regeln in CLAUDE.md. Ohne diese Regel würde der Agent versuchen, die Projektdatei zu modifizieren und sie wahrscheinlich beschädigen.

Was Agenten in iOS gut können

Dies sind die Aufgaben, bei denen Agenten konsequent korrekte, produktionsreife Ergebnisse mit minimalem menschlichen Review liefern.

SwiftUI Views und Modifier

Agenten verfügen über eine tiefe Mustererkennung für die deklarative SwiftUI-Syntax. View-Komposition, Modifier-Ketten, State-Bindings und Layout — all das lässt sich gut auf die Trainingsdaten des Agenten abbilden, weil die API-Oberfläche von SwiftUI gut dokumentiert ist und die Muster stark konsistent sind.

Wo Agenten brillieren: - Erstellen neuer Views aus einer Beschreibung („Erstelle ein Settings-Sheet mit Togglern für X, Y, Z”) - Anwenden von Modifier-Ketten (.glassEffect(), .sensoryFeedback(), .navigationTitle()) - Umwandeln zwischen Layout-Mustern (VStack zu LazyVGrid, List zu ScrollView) - Implementieren von @Bindable-Formular-Bindings an SwiftData-Modelle - Erstellen von Preview-Providern mit Beispieldaten

Beispiel-Prompt, der hervorragende Ergebnisse liefert:

Create a SettingsView that matches the existing pattern in SettingsSheet.swift.
Include toggles for:
- Enable haptic feedback (Settings.shared.hapticsEnabled)
- Enable HealthKit logging (Settings.shared.healthKitEnabled)
- Show session history (navigation link to SessionHistoryView)

Use Liquid Glass styling with .glassEffect() on section backgrounds.
Follow the @Observable pattern, not ObservableObject.

Auf die Spezifität kommt es an. „Erstelle eine Settings-View” liefert generische Ergebnisse. „Create a SettingsView that matches the existing pattern in SettingsSheet.swift” liefert dagegen Ergebnisse, die zu Ihrer Codebasis passen.

SwiftData-Modelle und Queries

Agenten gehen zuverlässig mit dem @Model-Makro, Beziehungen und @Query-Mustern von SwiftData um. Die deklarative Natur des Frameworks (ähnlich wie Django ORM oder SQLAlchemy) lässt sich gut auf Muster abbilden, die der Agent in vielen Codebasen gesehen hat.

Wo Agenten brillieren: - Definieren von @Model-Klassen mit Beziehungen - Schreiben von @Query mit Sort-Deskriptoren und Predicates - Implementieren von CRUD-Operationen über modelContext - Migrationspläne zwischen Schema-Versionen - Preview-Daten und Test-Fixtures

Wo Agenten Anleitung brauchen: - Komplexe #Predicate-Ausdrücke (die Predicate-DSL von SwiftData hat Einschränkungen, die der Agent nicht immer kennt — dokumentieren Sie bekannte Einschränkungen in CLAUDE.md) - CloudKit-Sync-Konfiguration (automatisch über SwiftData, aber der Agent versucht möglicherweise, manuelles Sync zu implementieren)

Unit-Tests

Vom Agenten geschriebene Unit-Tests sind für iOS-Projekte konsequent von hoher Qualität. Der Agent versteht XCTest-Muster, asynchrone Testmethoden und den Setup/Teardown-Lebenszyklus.

Write unit tests for TimerManager covering:
1. Initial state is .stopped
2. start() transitions to .running
3. pause() transitions to .paused
4. reset() returns to .stopped with original duration
5. Timer counts down correctly (test with 3-second duration)

Der Agent erzeugt gut strukturierte XCTest-Cases mit setUp() und tearDown(), passenden Assertions und asynchroner Behandlung für timerbasierte Tests.

Refactoring und Anwendung von Mustern

Agenten brillieren beim mechanischen Refactoring: Views in Komponenten extrahieren, ObservableObject zu @Observable konvertieren, von NavigationView zu NavigationStack migrieren und konsistente Muster über mehrere Dateien hinweg anwenden.

Refactor all views in the Views/ directory to use @Observable instead of
ObservableObject. Update @StateObject to @State, @ObservedObject to direct
property access, and @Published to plain properties.

Der Agent arbeitet methodisch jede Datei durch, wendet die Transformation korrekt an und erhält die bestehende Funktionalität. Das ist hochproduktive Arbeit — ein Refactoring, das eine Stunde manueller Bearbeitung erfordern würde, ist in Minuten mit nahezu perfekter Genauigkeit abgeschlossen.

Diagnose von Build-Fehlern via MCP

Mit strukturiertem MCP-Output diagnostizieren Agenten Build-Fehler schneller als die meisten Entwickler. Der Agent liest die Fehler-JSON, identifiziert die exakte Datei und Zeile, versteht die Fehlermeldung und wendet den Fix an — häufig in einem einzigen Zug.

Fehler, die Agenten autonom beheben: - Fehlende Imports - Typ-Inkompatibilitäten - Lücken in der Protokoll-Konformität - Verwendung veralteter API (mit Ersatz) - Fehlende erforderliche Initialisierer-Parameter - Verstöße gegen die Zugriffskontrolle

Fehler, bei denen Agenten Hilfe brauchen: - Mehrdeutige Typauflösung (mehrere Module definieren denselben Typ) - Komplexe Fehler bei generischen Constraints - Fehler bei der Makro-Expansion (der Agent kann den expandierten Makro-Output nicht sehen)

Simulator-Verwaltung

Agenten handhaben den Simulator-Lebenszyklus gut über MCP:

Boot an iPhone 16 Pro simulator on iOS 26, install the app, and take a screenshot.

Der Agent ruft list_sims auf, um verfügbare Runtimes zu finden, boot_sim, um den Simulator zu starten, build_sim, um zu bauen und zu installieren, und screenshot, um eine Aufnahme zu machen — alles über strukturierte MCP-Aufrufe.

Was Agents in iOS schlecht machen

Ehrliche Bestandsaufnahme, wo Agents versagen. Diese Grenzen zu kennen, verhindert Frustration und verschwendete Tokens.

Änderungen an .pbxproj-Dateien — NIEMALS

Dies ist die wichtigste einzelne Regel in der iOS-Agent-Entwicklung. Die .pbxproj-Datei ist die Projektkonfiguration von Xcode — eine strukturierte Textdatei mit UUID-Referenzen, Build-Phase-Listen und Target-Zugehörigkeiten. Sie ist nominell für Menschen lesbar, aber für AI-Agents praktisch nicht parsbar.

Warum Agents bei .pbxproj versagen: - Die Datei verwendet ein eigenes Format (nicht JSON, nicht YAML, nicht XML) mit positionsabhängiger Bedeutung - Jeder Eintrag wird per UUID querverwiesen — eine Datei hinzuzufügen erfordert konsistente Aktualisierungen in 3–5 verschiedenen Abschnitten - Ein einziges falsch platziertes Zeichen beschädigt die gesamte Projektdatei - Die Merge-Konflikt-Auflösung von Xcode für .pbxproj ist ohnehin schon fragil — Agent-Bearbeitungen verschlimmern das

Was passiert, wenn ein Agent .pbxproj bearbeitet: 1. Die Bearbeitung scheint zu gelingen (der Agent meldet „Datei aktualisiert”) 2. Xcode weigert sich, das Projekt zu öffnen („Die Projektdatei ist beschädigt”) 3. Sie verbringen 15–60 Minuten damit, sich aus dem Git-Verlauf zu retten 4. Sie lernen, den PreToolUse-Hook hinzuzufügen (siehe Hooks)

Der Workflow: Der Agent erstellt Swift-Dateien. Sie fügen sie manuell zum Xcode-Projekt hinzu (in Xcode hineinziehen oder File > Add Files). Das dauert 5 Sekunden pro Datei und erspart Ihnen Stunden der Wiederherstellung.

Für Swift-Package-Manager-Projekte: Diese Einschränkung ist weniger gravierend. Package.swift ist eine standardmäßige Swift-Datei, die Agents zuverlässig bearbeiten können. Wenn Ihr Projekt ausschließlich SPM verwendet (kein .xcodeproj), kann der Agent die gesamte Projektstruktur verwalten.

Komplexe Interface-Builder- / Storyboard-Bearbeitungen

Wenn Ihr Projekt Interface Builder (.xib-Dateien) oder Storyboards (.storyboard-Dateien) verwendet, können Agents diese nicht sinnvoll bearbeiten. Es handelt sich um XML-Dateien mit automatisch generierten UUIDs, Constraint-Referenzen und Outlet-Verbindungen, die für die visuelle Bearbeitung konzipiert sind, nicht für die Textbearbeitung.

Die Abhilfe: Verwenden Sie für neue Views ausschließlich SwiftUI. Wenn Ihr Projekt Legacy-Interface-Builder-Dateien hat, lassen Sie sie unangetastet und bauen Sie neue UI in SwiftUI.

Performance-Optimierung

Agents schreiben korrekten Code, aber nicht zwangsläufig performanten Code. Sie können Ihre App weder profilen noch Engpässe identifizieren oder Bildraten messen. Performance-Optimierung erfordert:

1. Instruments-Profiling (visuelles Werkzeug, für Agents nicht zugänglich)
2. Verständnis der spezifischen GPU/CPU-Eigenschaften des Geräts
3. Iterative, messungsgetriebene Änderungen

Wo sich das zeigt: - Metal-Shader-Optimierung (der Agent schreibt valides Metal, kann aber die GPU-Frame-Zeit nicht messen) - Komplexität von SwiftUI-View-Bodys (der Agent erzeugt tief verschachtelte Views, die Redraw-Overhead verursachen) - Core Data- / SwiftData-Fetch-Optimierung (der Agent schreibt korrekte Queries, die bei großen Datensätzen langsam sein können)

Die Abhilfe: Setzen Sie Agents für die Implementierung ein, profilen Sie manuell mit Instruments und bitten Sie den Agent dann, spezifische Optimierungen anzuwenden, die Sie identifiziert haben.

Code-Signing und Provisioning

Agents können Code-Signing-Probleme nicht über das Lesen der Fehlermeldung hinaus debuggen. Die Verwaltung von Provisioning-Profilen, das Erstellen von Zertifikaten, die Konfiguration von Entitlements und die App-Store-Einreichung sind grundsätzlich von Menschen bediente Workflows, die das Apple Developer Portal, Keychain Access und die Signing-UI von Xcode einbeziehen.

Was der Agent sieht: „Signing for ‘Return’ requires a development team.”

Was der Agent nicht sehen kann: Ob Ihr Zertifikat abgelaufen ist, ob das Provisioning-Profil das Gerät einschließt, ob die Bundle-ID mit der App-ID übereinstimmt oder ob Ihre Entitlements-Datei korrekt ist.

Die Abhilfe: Erledigen Sie das gesamte Signing im Tab „Signing & Capabilities” in Xcode. Bitten Sie Agents nicht, Signing-Fehler zu debuggen.

Komplexes Metal-Shader-Debugging

Agents schreiben syntaktisch korrekte Metal Shading Language (MSL), können jedoch weder visuelle Ausgaben überprüfen noch GPU-seitige Probleme debuggen. Metal-Shader laufen auf der GPU — der Agent hat keinen Rückkopplungsmechanismus, der ihm sagt, ob der Shader visuell korrekte Ergebnisse liefert.

Was Agents mit Metal können: - Vertex- und Fragment-Shader aus Beschreibungen schreiben - Die Metal-Render-Pipeline in Swift einrichten - Compute-Shader für datenparallele Operationen erstellen - Kompilierungsfehler in .metal-Dateien beheben

Was Agents mit Metal nicht können: - Visuelle Korrektheit der Shader-Ausgabe überprüfen - GPU-Performance debuggen (Frame-Zeit, Occupancy, Speicherbandbreite) - Visuelle Artefakte diagnostizieren (Banding, Präzisionsprobleme, falscher Farbraum) - Auf unterschiedlichen GPU-Architekturen testen (Verhaltensunterschiede zwischen A-Serie und M-Serie)

Die Abhilfe: Testen Sie Metal-Shader auf physischen Geräten. Die Metal-Implementierung des Simulators ist nicht repräsentativ für das GPU-Verhalten auf dem Gerät. Verwenden Sie Xcodes GPU Frame Capture für visuelles Debugging.

Visuelle Layout-Verifikation

Agents können die UI Ihrer App nicht sehen. Sie schreiben SwiftUI-Layout-Code und können verifizieren, dass er kompiliert, doch sie können nicht beurteilen, ob der resultierende Bildschirm korrekt aussieht. Eine View, die 10 Pixel außermittig gerendert wird, das falsche Font-Gewicht verwendet oder überlappende Elemente enthält, erzeugt keinen Build-Fehler und besteht alle Logik-Tests.

Die Abhilfe: Prüfen Sie UI-Änderungen visuell. Verwenden Sie SwiftUI Previews in Xcode (oder RenderPreview via Apple MCP für Headless-Rendering), um das Layout zu verifizieren. Erwägen Sie Snapshot-Tests mit Bibliotheken wie swift-snapshot-testing für automatisierte visuelle Regressionserkennung.

Hooks für die iOS-Entwicklung

Hooks sind Shell-Befehle, die deterministisch an bestimmten Punkten im Workflow des Agenten ausgeführt werden. Sie sind der Durchsetzungsmechanismus — der Unterschied zwischen „Bitte bearbeiten Sie .pbxproj nicht” (eine Empfehlung, die der Agent ignorieren kann) und „Sie können .pbxproj nicht bearbeiten” (eine harte Sperre).

Hintergrundinformationen zum Hook-System finden Sie im Claude Code Hooks Guide. Dieser Abschnitt behandelt iOS-spezifische Hook-Muster.

PreToolUse: .pbxproj-Schreibvorgänge blockieren

Der wichtigste Hook in jedem iOS-Projekt. Er hindert den Agenten daran, in .pbxproj-Dateien, .xcodeproj/-Verzeichnisse und andere von Xcode verwaltete Dateien zu schreiben:

{
  "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'"
      }
    ]
  }
}

Platzieren Sie dies in .claude/settings.json im Projekt-Stammverzeichnis oder in ~/.claude/settings.json für globalen Schutz.

Funktionsweise: Wenn der Agent versucht, das Edit- oder Write-Tool auf eine Datei anzuwenden, die dem Muster entspricht, wird der Hook ausgeführt, erkennt den Dateipfad, gibt eine Warnung an stderr aus und beendet sich mit Exit-Code 2 (was die Tool-Nutzung blockiert). Der Agent erhält die Fehlermeldung und passt sein Vorgehen an.

Was er abfängt: - Direkte .pbxproj-Bearbeitungen - Jede Datei innerhalb von .xcodeproj/- oder .xcworkspace/-Verzeichnissen - Interface-Builder-Dateien (.xib, .storyboard)

PostToolUse: Format-on-Save mit SwiftFormat

Swift-Dateien automatisch formatieren, sobald der Agent sie schreibt oder bearbeitet:

{
  "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'"
      }
    ]
  }
}

Voraussetzungen: SwiftFormat muss installiert sein (brew install swiftformat).

Warum das wichtig ist: Agenten erzeugen syntaktisch korrektes Swift, halten sich aber nicht konsequent an Formatierungskonventionen. SwiftFormat vereinheitlicht Einrückung, Klammerplatzierung und Import-Reihenfolge. Der Format-on-Save-Hook sorgt dafür, dass jede Swift-Datei, die der Agent berührt, automatisch formatiert wird, bevor Sie sie sehen.

Optional: Eine .swiftformat-Konfigurationsdatei im Projekt-Stammverzeichnis hinzufügen, um Formatierungsregeln anzupassen:

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

PostToolUse: SwiftLint automatisch ausführen

Wenn Sie SwiftLint verwenden, führen Sie es nach jeder Bearbeitung einer Swift-Datei aus:

{
  "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'"
      }
    ]
  }
}

Das || true verhindert, dass Lint-Warnungen den Agenten blockieren. Wenn Sie möchten, dass Lint-Verstöße blockieren, entfernen Sie es.

PostToolUse: Automatischer Build nach Änderungen

Für aggressive Feedback-Schleifen lösen Sie nach jeder Änderung einer Swift-Datei einen Build aus:

{
  "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'"
      }
    ]
  }
}

Warnung: Das ist teuer. Jede Dateibearbeitung löst einen Build aus. Verwenden Sie es sparsam — am nützlichsten ist es während Debugging-Sitzungen, in denen Sie sofortiges Build-Feedback wünschen. Lassen Sie den Agenten in der normalen Entwicklung Builds manuell über MCP auslösen, wenn er bereit ist.

PreToolUse: Änderungen an Entitlements blockieren

Schützen Sie Ihre Entitlements-Datei vor versehentlichen Änderungen durch den Agenten:

{
  "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'"
      }
    ]
  }
}

Kombinierte iOS-Hook-Konfiguration

Hier ist die vollständige .claude/settings.json, die ich in allen iOS-Projekten verwende:

{
  "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'"
      }
    ]
  }
}

Das gibt Ihnen zwei Garantien: 1. Der Agent kann Xcode-Projektdateien nicht beschädigen (PreToolUse-Sperre) 2. Jede Swift-Datei, die der Agent berührt, wird automatisch formatiert (PostToolUse-Formatierung)

Architekturmuster, die mit Agenten funktionieren

Nicht alle Swift-Architekturen sind gleichermaßen agentenfreundlich. Diese Muster liefern die besten Ergebnisse, weil sie explizit, konsistent und in Trainingsdaten gut vertreten sind.

@Observable (Niemals ObservableObject)

Projekte mit iOS 26+ als Ziel sollten ausschließlich @Observable verwenden. Das ist sowohl das moderne als auch das agentenfreundliche Muster:

// 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()
}

Warum @Observable agentenfreundlich ist: Das Muster ist einfacher (keine @Published-Annotationen erforderlich), das Besitzmodell ist klarer (@State statt @StateObject vs. @ObservedObject), und Agenten produzieren damit weniger Bugs, weil weniger bewegliche Teile vorhanden sind.

Dokumentieren Sie dies in CLAUDE.md: Selbst mit iOS 26 als Ziel greifen Agenten gelegentlich auf ObservableObject-Muster aus ihren Trainingsdaten zurück. Ein explizites Verbot verhindert das.

NavigationStack (Niemals NavigationView)

// 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)
        }
    }
}

NavigationStack ist iOS 16+ und das einzige Navigationsmuster, das Sie für neuen Code verwenden sollten. Das typsichere navigationDestination(for:)-Muster verhindert, dass der Agent fehlerhafte Navigationslinks erstellt.

SwiftData für Persistenz

SwiftData-Modelle sind das sauberste Persistenzmuster für agentengestützte Entwicklung:

@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
    }
}

Wichtige Regeln für Agenten, die mit SwiftData arbeiten: 1. @Model-Klassen sind automatisch Observable — fügen Sie kein @Observable hinzu 2. Verwenden Sie @Bindable für Formular-Bindings: @Bindable var item: GroceryItem 3. Verwenden Sie @Query in Views für reaktive Daten: @Query var items: [GroceryItem] 4. Verwenden Sie modelContext.fetch() in Code außerhalb von Views 5. Beziehungslöschungen benötigen explizite Regeln: .cascade, .nullify, .deny

Swift 6.2 Concurrency

Zielen Sie für neue Projekte auf Swift 6.2 strict concurrency ab:

// 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
}

Agentenleitfaden für Concurrency: - Markieren Sie alle View Models mit @MainActor (verhindert Data-Race-Warnungen) - Verwenden Sie async/await für jede asynchrone Arbeit (keine Completion-Handler) - Machen Sie Werttypen Sendable für Übertragungen zwischen Actors - Verwenden Sie Task { } in Views für asynchrone Initialisierung - Verwenden Sie nonisolated nur, wenn Sie einen messbaren Performance-Bedarf festgestellt haben

Liquid Glass Design System (iOS 26+)

iOS 26 hat das Liquid Glass Design System eingeführt. Agenten kommen damit gut zurecht, wenn sie explizit angeleitet werden:

// 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()

Nehmen Sie in CLAUDE.md auf: „Verwenden Sie .glassEffect() auf Section-Hintergründen und Card-Containern. Navigationsleisten übernehmen das Glasmaterial in iOS 26 automatisch. Bauen Sie Glaseffekte nicht manuell mit eigenen Materialien nach — nutzen Sie den Systemmodifier.”

Framework-spezifischer Kontext

Jedes Apple-Framework bringt agentenspezifische Besonderheiten mit. Dieser Abschnitt behandelt die Frameworks, die in den 8 Apps zum Einsatz kommen.

HealthKit

Apps, die es verwenden: Return, Water

HealthKit erfordert sorgfältige Berechtigungsbehandlung und Plattform-Guards:

// 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
        }
    }
}

Agentenregeln für HealthKit: - Sichern Sie immer mit HKHealthStore.isHealthDataAvailable() ab - Setzen Sie Berechtigungen niemals voraus — prüfen Sie diese bei jedem Schreibvorgang - Verwenden Sie #if canImport(HealthKit) für plattformübergreifenden Code (HealthKit ist auf tvOS nicht verfügbar) - Speichern Sie Gesundheitsdaten niemals lokal über das hinaus, was HealthKit bereitstellt - Nehmen Sie sowohl NSHealthShareUsageDescription als auch NSHealthUpdateUsageDescription in Info.plist auf

SpriteKit

Apps, die es verwenden: TappyColor, Starfield Destroyer

Das Scene-Graph-Modell von SpriteKit erfordert explizite Agentenanleitung:

## 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)

Stärken von Agenten bei SpriteKit: - Erstellen von SKAction-Sequenzen und -Gruppen - Einrichten von Physics Bodies und Kontakterkennung - Implementieren von Spielzustandsautomaten - Aufbau von HUD-Overlays

Schwächen von Agenten bei SpriteKit: - Performance-kritische Game Loops (der Agent fügt pro Frame unnötige Arbeit hinzu) - Komplexe Physiksimulationen (eigene Physik schlägt SKPhysicsBody bei der Präzision) - Tuning von Partikeleffekten (visuell, erfordert Iteration)

Metal

Apps, die es verwenden: amp97, Water, Starfield Destroyer

Metal ist das Framework, mit dem Agenten am meisten zu kämpfen haben. Das GPU Programmiermodell unterscheidet sich grundlegend von CPU-seitigem Swift, und Agenten können visuelle Ausgaben nicht überprüfen.

## 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

Was Sie für Metal-Projekte in CLAUDE.md aufnehmen sollten: - Die Definition des Uniforms-Structs (gemeinsam zwischen Swift und MSL) - Das Setup-Muster für den Render-Pipeline-State - Buffer-Indizes und ihre Zwecke - Welche Shader existieren und was jeder davon tut - Bekannte Präzisionsprobleme (half vs. float)

Live Activities

Apps, die es verwenden: Return

Live Activities erfordern eine spezifische Konfiguration, mit der Agenten gut zurechtkommen, sobald sie dokumentiert ist:

## 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

Apps, die es verwenden: Starfield Destroyer

## 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)

Multi-Plattform-Patterns

Return läuft auf iOS, watchOS und tvOS. Die Multi-Plattform-Entwicklung mit Agenten erfordert eine explizite Dokumentation der Plattformgrenzen.

Organisation des gemeinsamen Codes

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

Regel für Agenten: „Wenn eine Datei in Shared/ liegt, betreffen Änderungen alle Plattformen. Liegt eine Datei in einem Plattformverzeichnis, sind die Änderungen isoliert. Prüfen Sie immer, in welchem Verzeichnis sich eine Datei befindet, bevor Sie sie ändern.”

Plattform-Verfügbarkeitsschutz

// 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

Hinweis für Agenten: „Verwenden Sie immer #if canImport()- oder #if os()-Guards, wenn Sie plattformspezifische Frameworks einsetzen. Gehen Sie nicht davon aus, dass ein Framework auf allen Targets verfügbar ist.”

Plattformspezifische UI-Anpassung

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
    }
}

Fortgeschrittene Workflows

Autonome Build-Test-Fix-Schleifen

Das mächtigste Pattern: Geben Sie dem Agenten eine Feature-Spezifikation und lassen Sie ihn autonom durch Build-Test-Fix-Zyklen iterieren.

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.

Der Agent schreibt Code, baut über MCP, liest strukturierte Fehler, behebt sie und wiederholt den Vorgang. Eine Funktion, die 5–10 manuelle Build-Error-Fix-Zyklen erfordern würde, wird in einer einzigen autonomen Schleife abgeschlossen.

Wann das funktioniert: Klar definierte Funktionen mit eindeutigen Akzeptanzkriterien.

Wann das scheitert: Offene Funktionen („mach es schön”), performancekritischer Code oder alles, was visuelle Überprüfung erfordert.

Subagent-Delegation für iOS

Das Subagent-System von Claude Code funktioniert auch für iOS-Projekte:

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.

Der Subagent untersucht Dokumentation und Code-Patterns in einem separaten Kontextfenster, liefert eine Zusammenfassung zurück, und die Hauptsitzung setzt die Empfehlung um. So verhindern Sie, dass Recherche Ihren Primärkontext belegt.

App-übergreifende Pattern-Anwendung

Wenn Sie mehrere iOS-Apps mit konsistenten Patterns pflegen, können Agenten Patterns von einer App auf eine andere übertragen:

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.

Der Agent liest das Quell-Pattern, versteht die Struktur und erstellt eine konsistente Implementierung im Zielprojekt.

Dual-Agent-Review (Claude + Codex)

Setzen Sie für kritische Änderungen zwei Agenten aus unterschiedlichen Modellfamilien ein:

1. Claude Code schreibt die Implementierung
2. Codex CLI überprüft sie in einem separaten Durchgang

# 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."

Verschiedene Modellfamilien finden unterschiedliche Fehlerklassen. Besonders wertvoll ist das bei Metal-Shadern und Concurrency-Patterns, bei denen sich subtile Bugs leicht einschleichen.

Was Dual-Review findet, was ein Einzelreview übersieht:

Beim Dual-Review geht es nicht darum, mehr Bugs zu finden — es geht darum, andere Bugs zu finden. Jede Modellfamilie hat in ihrer Mustererkennung unterschiedliche Fehlermodi.

Batch-Operationen über mehrere Apps

Wenn eine Framework- oder Pattern-Änderung mehrere Apps betrifft:

# 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

Mit Vorsicht einsetzen. Das Flag --dangerously-skip-permissions ist für den nicht-interaktiven Modus erforderlich, umgeht jedoch alle Sicherheitsprüfungen. Stellen Sie sicher, dass Ihre PreToolUse-Hooks aktiv sind, um .pbxproj-Dateien zu schützen.

Apps, die Apples On-Device-LLM nutzen

Wenn Ihre App Apples Foundation-Models-Framework aufruft (z. B. für Offline-Zusammenfassung, Klassifizierung oder strukturierte Ausgabegenerierung), müssen Agenten das Prompt-Budget kennen. iOS 26.4 hat zwei APIs zu SystemLanguageModel hinzugefügt, die die bisherige Schätzung von 4096 Tokens ersetzen: contextSize (maximale Anzahl Tokens, die das Modell in einem Gespräch akzeptiert) und tokenCount(for:) (async throws, gibt zurück, wie viele Tokens ein bestimmter Prompt tatsächlich kostet).¹⁶ Beide sind @backDeployed(before: iOS 26.4), sodass sie in allen FM-fähigen OS-Versionen ohne #available-Leiter verfügbar sind.

Das Pattern, dem ein Agent beim Generieren von Prompt-Konstruktionscode folgen sollte:

import FoundationModels

func budgetFor(prompt: String, reservedReply: Int = 256) async throws -> Int {
    let model = SystemLanguageModel.default
    let promptCost = try await model.tokenCount(for: prompt)
    let budget = model.contextSize - promptCost - reservedReply
    guard budget > 0 else { throw ContextError.promptTooLong }
    return budget
}

Fügen Sie dieses Pattern zu Ihrer CLAUDE.md hinzu, wenn die App SystemLanguageModel verwendet. Ohne diesen Hinweis fallen Agenten auf den alten Hardcode von 4096 zurück und kürzen Prompts stillschweigend auf Geräten ab, die mit größeren Kontextfenstern ausgeliefert werden. Die async throws-Signatur von tokenCount(for:) ist tragend — Agenten, die eine synchrone Version einfügen, werden nicht kompilieren.

Praxisbeispiele

Abstrakte Ratschläge sind einfach. Hier sind konkrete Szenarien aus den 8 Apps, die zeigen, wie agentenunterstützte iOS-Entwicklung in der Praxis funktioniert — einschließlich der Fehlschläge.

Fallstudie 1: Hinzufügen einer TV-App zu Return (Erfolg)

Die Aufgabe: Hinzufügen eines tvOS-Targets zu Return, einem Meditationstimer, der bereits iOS- und watchOS-Versionen hatte. Die TV-App benötigte Siri Remote-Navigation, eine Großbildschirm-Benutzeroberfläche und eine Einstellungssynchronisation mit der iOS-App.

Was der Agent gut gemacht hat: - Hat den bestehenden iOS-TimerManager gelesen und einen TVTimerManager erstellt, der Live Activities und HealthKit (auf tvOS nicht verfügbar) wegließ - Hat benutzerdefinierte Button-Stile für die Siri Remote-Fokusnavigation erstellt (TVCapsuleButtonStyle, TVCircleButtonStyle) - Hat eine TVStepper-Komponente entwickelt, die Wheel-Picker (mit Siri Remote nicht nutzbar) durch +/- Schaltflächen ersetzt - Hat die Einstellungssynchronisation über App Groups (group.com.941apps.Return) implementiert - Hat #if os(tvOS)-Guards im gesamten gemeinsamen Code hinzugefügt - Hat über MCP mit platform=tvOS Simulator,name=Apple TV gebaut und getestet

Was ich manuell erledigen musste: - Das tvOS-Target in Xcode erstellen (File > New > Target > tvOS App) - Das neue Target zum Xcode-Projekt hinzufügen (.pbxproj-Änderungen) - Die App Groups-Berechtigung für das TV-Target konfigurieren - Das TV-Target zum bestehenden Schema hinzufügen oder ein neues erstellen - Alle vom Agent erstellten Swift-Dateien manuell zum TV-Target hinzufügen - Die Siri Remote-Navigation von Hand testen (der Agent kann das Fokusverhalten nicht beurteilen)

Ergebnis: 15 neue Swift-Dateien, eine voll funktionsfähige TV-App, in etwa 3 Stunden agentenunterstützter Arbeit. Nach meiner Einschätzung hat der Agent rund 80 % der Implementierungsarbeit übernommen; ich habe die Teile übernommen, die Interaktion mit der Xcode-Benutzeroberfläche erforderten (Berechtigungen, Target-Einrichtung, Capability-Flags) und das manuelle Fokustesten auf einem echten Apple TV. Eine vergleichbare Solo-Arbeit in dieser Codebasis — basierend auf ähnlichen Funktionen, die ich ohne Agenten ausgeliefert habe — wäre ein mehrtägiger Aufwand gewesen.

Fallstudie 2: Debugging eines Metal-Shaders in amp97 (Teilweiser Fehlschlag)

Die Aufgabe: Hinzufügen eines energiebasierten Intensitätssystems zum Oszilloskop-Shader. Die Visualisierung sollte mit der Audioenergie pulsieren.

Was passiert ist: 1. Der Agent hat eine gültige Metal-Shader-Modifikation geschrieben, die eine uEnergy-Uniform und HDR-Tonemapping hinzufügte 2. Der Code wurde fehlerfrei kompiliert 3. Auf dem Gerät war die Visualisierung vollständig weiß — der Intensitätskoeffizient war 10x zu hoch (3,5 statt 0,30) 4. Der Agent konnte den weißen Bildschirm nicht sehen, hatte also kein Feedbacksignal 5. Ich habe das Problem visuell erkannt und den Agent gebeten, den Koeffizienten zu reduzieren 6. Der Agent hat ihn reduziert, aber die gesamte Energiezustandsmaschine war zu komplex und hat den Visualizer auf andere Weise kaputt gemacht 7. Vollständig zurückgesetzt — zwei Commits (67959ed und cda4830) wurden in 869d914 revertiert

Die Lektion: Metal-Shader sind die schwierigste Domäne für agentenunterstützte Entwicklung, weil die Feedbackschleife unterbrochen ist. Der Agent kann Syntax (kompiliert) und Semantik (korrekte Typen) verifizieren, aber nicht die Ausgabe (sieht richtig aus). Jede Shader-Modifikation, die das visuelle Verhalten ändert, erfordert eine menschliche Verifikation auf dem Gerät.

Was ich danach zur CLAUDE.md hinzugefügt habe: „DO NOT attempt energy state modifications to the oscilloscope shader without extremely careful coefficient testing. Previous attempt broke the visualizer with coefficients 10x too high.”

Fallstudie 3: SwiftData-Migration in Banana List (Erfolg)

Die Aufgabe: Das Datenmodell von V1 zu V2 migrieren, ein quantity-Feld zu GroceryItem und ein neues Category-Modell mit Beziehungen hinzufügen.

Was der Agent gemacht hat: 1. Hat die bestehenden V1-Modelldefinitionen gelesen 2. Hat V2-Modelldefinitionen mit den neuen Feldern und Beziehungen erstellt 3. Hat einen GroceryMigrationPlan mit Konformität zum SchemaMigrationPlan-Protokoll geschrieben 4. Hat die V1toV2-Migrationsstufe implementiert: Standardwerte quantity: 1 und category: nil hinzugefügt 5. Hat alle Views aktualisiert, um die neuen Felder zu unterstützen 6. Hat SampleData.swift für Previews aktualisiert 7. Hat über MCP gebaut und Tests ausgeführt — alle bestanden 8. Hat migrationsspezifische Unit-Tests erstellt

Der Schlüssel: Der Agent war erfolgreich, weil SwiftData-Migrationen einem klar definierten Protokollmuster folgen, das in Apples Dokumentation und Trainingsdaten gründlich repräsentiert ist. Die CLAUDE.md hat das V1-Modell explizit dokumentiert, sodass der Agent verstanden hat, von welchem Stand er migriert.

Fallstudie 4: iCloud-Session-Synchronisation in Return (Erfolg mit Komplexität)

Die Aufgabe: Implementierung einer geräteübergreifenden Protokollierung von Meditationssitzungen. Auf Apple TV oder Mac abgeschlossene Sitzungen sollen mit dem iPhone für die HealthKit-Protokollierung synchronisiert werden.

Was der Agent produziert hat:

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

Der Agent: 1. Hat das Datenmodell MeditationSession mit UUID, Datumsangaben, Dauer, Quellgerät und HealthKit-Synchronisationsstatus erstellt 2. Hat ein SessionStore-Singleton gebaut, das NSUbiquitousKeyValueStore für die iCloud-Synchronisation verwaltet 3. Hat eine Auflösung von Merge-Konflikten implementiert (UUID-basierte Deduplizierung) 4. Hat eine SessionHistoryView mit plattformspezifischen Anpassungen hinzugefügt (Wischen zum Löschen auf iOS, fokusbasiert auf tvOS) 5. Hat die iPhone-seitige HealthKit-Synchronisation für Sitzungen von anderen Geräten verkabelt

Was Iteration erforderte: Die initiale Implementierung hat den Fall nicht behandelt, in dem die iPhone-App im Hintergrund startet (keine Vordergrundbenachrichtigung für die Synchronisation). Der Agent benötigte spezifische Anweisungen: „Verwenden Sie NSUbiquitousKeyValueStore.didChangeExternallyNotification, um die Synchronisation bei KV-Änderungen im Hintergrund auszulösen.” Nach diesem Hinweis war die Implementierung korrekt.

Die Lektion: Agenten gehen mit plattformübergreifenden Architekturmustern gut um, wenn die Architektur klar beschrieben ist. Das iCloud-Synchronisationsmuster ist nicht trivial, folgt aber einem dokumentierten Apple-Muster, das der Agent verstanden hat. Der Edge Case (Hintergrundsynchronisation) erforderte menschliches Fachwissen, weil er nicht gut dokumentiert ist.

Fallstudie 5: Game Center-Integration in Starfield Destroyer (Erfolg)

Die Aufgabe: Hinzufügen von Game Center-Bestenlisten und Errungenschaften zum Weltraum-Shooter.

Was der Agent gut gemacht hat: - Hat GKLocalPlayer.local.authenticateHandler im App-Einstiegspunkt implementiert - Hat einen GameCenterManager mit Methoden zur Punktübermittlung und zur Meldung von Errungenschaften erstellt - Hat eine Prüfung des Authentifizierungsstatus vor allen Game Center-Operationen hinzugefügt - Hat den Offline-Fall elegant gehandhabt (das Spiel läuft ohne Game Center, übermittelt bei erneuter Verbindung) - Hat Definitionen für Errungenschaften erstellt, die zum 8-Schiffe-Progressionssystem passen

Was manuelle Arbeit erforderte: - Erstellung der Bestenlisten und Errungenschaften in App Store Connect (Web-Portal, für den Agent nicht zugänglich) - Konfiguration der Game Center-Berechtigung in Xcode - Testen mit einem Sandbox-Game Center-Konto (erfordert manuelle Anmeldung auf dem Gerät)

Projektlebenszyklus mit Agenten

Ein neues iOS-Projekt starten

Der optimale Workflow für den Start eines neuen Projekts mit Agentenunterstützung:

Phase 1: Manuelle Einrichtung (15-30 Minuten) 1. Erstellen Sie das Xcode-Projekt (File > New > Project) 2. Konfigurieren Sie Signing und Capabilities 3. Legen Sie das Deployment Target und die unterstützten Destinations fest 4. Fügen Sie die erforderlichen Entitlements hinzu (HealthKit, Game Center usw.) 5. Erstellen Sie die initiale CLAUDE.md mit Projektidentität und Regeln

Phase 2: Agent-Implementierung (Stunden bis Tage) 1. Der Agent erstellt das Datenmodell (SwiftData, Core Data oder einfache Structs) 2. Der Agent baut Views nach Ihren dokumentierten Mustern 3. Der Agent implementiert Geschäftslogik in Manager-/Service-Klassen 4. Der Agent schreibt Unit Tests 5. Build-Test-Fix-Loop über MCP (autonom)

Phase 3: Manuelle Integration (30-60 Minuten) 1. Fügen Sie die vom Agent erstellten Dateien zu Xcode-Targets hinzu 2. Verifizieren Sie Signing und Entitlements 3. Testen Sie auf einem physischen Gerät 4. Überprüfen Sie das visuelle Layout und die UX 5. Reichen Sie die App bei App Store Connect ein

Ein bestehendes Projekt pflegen

Für die laufende Entwicklung etablierter Apps:

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]

Die Effektivität des Agenten skaliert damit, wie gut Ihre CLAUDE.md den aktuellen Zustand des Projekts widerspiegelt. Aktualisieren Sie Ihre CLAUDE.md, wenn Sie bedeutende neue Funktionen hinzufügen, architektonische Muster ändern oder neue Frameworks einführen.

Wann Sie den Agent einbeziehen sollten und wann nicht

Agentendefinitionen konfigurieren

Wenn Sie das Agentendefinitionssystem von Claude Code (.claude/agents/) verwenden, erstellen Sie einen iOS-spezifischen Agenten:

---
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

Referenzieren Sie diesen Agenten mit @ios-developer in Claude Code-Sitzungen.

Testmuster für agentenunterstützte iOS-Entwicklung

Agenten schreiben hervorragende Unit Tests, wenn sie klare Vorgaben erhalten. Hier sind die Muster, die die besten Ergebnisse liefern.

Organisation der Testdateien

# 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`

Prompts für Tests

Effektiver Test-Prompt:

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.

Warum das funktioniert: Nummerierte Akzeptanzkriterien geben dem Agenten eine Checkliste. Der Verweis auf eine bestehende Testdatei etabliert das Muster. Die Vorgabe der setUp()-Verwendung verhindert, dass der Agent verstrickten Test-State erzeugt.

Ineffektiver Test-Prompt:

Write tests for TimerManager.

Dieser produziert generische, oberflächliche Tests, die Edge Cases übersehen und möglicherweise nicht den Mustern Ihres Projekts folgen.

Async-Testmuster

Zum Testen von timerbasiertem und asynchronem Code:

// 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)
    }
}

Wichtige Muster, an die Agenten erinnert werden müssen: - @MainActor auf Testmethoden, die @MainActor-Klassen testen - async throws für Tests, die Task.sleep oder async-Operationen verwenden - Toleranz in zeitbasierten Assertions (1,1 Sekunden, nicht exakt 1,0) - Sauberes setUp() / tearDown() für Testisolierung

Snapshot-Testing

Zur Erkennung visueller Regressionen können Sie swift-snapshot-testing hinzufügen:

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.

Agenten richten Snapshot-Tests korrekt ein, können die Referenzbilder jedoch nicht überprüfen. Sie überprüfen die initialen Snapshots, danach erkennen die Tests des Agenten visuelle Regressionen bei zukünftigen Änderungen.

Kontextfenster-Verwaltung für iOS-Projekte

Das 1M-Kontextfenster (Opus 4.6) ist groß, aber nicht unbegrenzt. iOS-Projekte erfordern besondere Überlegungen zur Kontextverwaltung.

Token-Kosten von iOS-Dateien

Für ein Projekt mit 50 Dateien: Das Lesen aller Dateien verbraucht ungefähr 50.000-100.000 Tokens — deutlich innerhalb des 1M-Fensters. Der Agent kann das gesamte Projekt im Kontext halten.

Für ein Projekt mit 100+ Dateien: Selektives Lesen wird notwendig. Der Agent liest zunächst CLAUDE.md (für die Anmerkungen zur Dateistruktur) und dann gezielt bestimmte Dateien nach Bedarf. Aus diesem Grund sind Datei-Anmerkungen in CLAUDE.md entscheidend — sie führen den Agenten zu den richtigen Dateien, ohne dass alles gelesen werden muss.

Strategien für große Projekte

1. Detaillierte CLAUDE.md-Datei-Anmerkungen — Der Agent liest die Dateiübersicht und navigiert direkt zu den relevanten Dateien
2. Subagent-Delegation — Erkundung und Recherche an Subagenten weiterleiten (sauberer Kontext, gibt Zusammenfassungen zurück)
3. Fokussierte Prompts — „Modifizieren Sie SettingsView.swift, um einen neuen Toggle hinzuzufügen” ist besser als „aktualisieren Sie die Einstellungen”
4. Sitzungsgrenzen — Starten Sie neue Sitzungen für nicht zusammenhängende Funktionen, anstatt eine lange Sitzung zu verlängern
5. /compact verwenden — Der Compaction-Befehl von Claude Code fasst die Konversation zusammen und gibt Kontext frei

MCP Token-Effizienz

Eines der stärksten Argumente für MCP: Strukturierte JSON-Antworten verbrauchen weit weniger Tokens als rohe xcodebuild-Ausgaben.

Über eine typische Entwicklungssitzung mit 10-20 Build-Zyklen spart MCP 30.000-150.000 Tokens im Vergleich zu rohem xcodebuild — Tokens, die für die eigentliche Code-Analyse verfügbar bleiben.

Fehlerbehebung

„build_sim failed — scheme not found”

Der Agent rät den Schema-Namen. Lösung:

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

Oder fügen Sie den Schema-Namen explizit zu Ihrer CLAUDE.md hinzu:

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

„xcrun mcpbridge — command not found”

Sie benötigen Xcode 26.3 oder neuer. Prüfen Sie dies mit xcodebuild -version. Wenn Sie Xcode 26.3+ haben, der Befehl aber dennoch fehlschlägt:

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

# Verify
xcrun mcpbridge --help

„MCP-Tools erscheinen nicht in Claude Code”

Mitten in der Sitzung registrierte MCP-Tools erscheinen möglicherweise erst nach einem Neustart. Beenden Sie Claude Code und starten Sie eine neue Sitzung:

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

Dann verifizieren:

You: List all available MCP tools from XcodeBuildMCP.

„Agent verwendet weiterhin xcodebuild über Bash statt MCP”

Der Agent erkennt MCP-Tools nicht über die Tool-Suche. Zwei Lösungen:

1. Fügen Sie explizite Anweisungen zur CLAUDE.md hinzu (siehe Den Agenten zur Verwendung von MCP anleiten)
2. Direkt anweisen: „Verwenden Sie das build_sim MCP-Tool, nicht xcodebuild über Bash”

„Build erfolgreich, aber Agent meldet Fehlschlag”

XcodeBuildMCP parst die xcodebuild-Ausgabe. Wenn der Build Warnungen erzeugt, die wie Fehler aussehen (häufig bei Deprecation-Warnungen), kann der Agent das Ergebnis falsch interpretieren. Prüfen Sie das tatsächliche Status-Feld in der MCP-Antwort.

„Simulator hängt während des Bootvorgangs”

Beenden Sie alle Simulatoren und starten Sie neu:

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

Oder bitten Sie den Agenten:

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

„Agent hat versucht, .pbxproj zu modifizieren, trotz CLAUDE.md-Regeln”

CLAUDE.md-Regeln sind Vorschläge. Hooks sind Durchsetzung. Wenn Sie keinen PreToolUse-Hook haben, der .pbxproj-Schreibvorgänge blockiert, wird der Agent es irgendwann versuchen. Installieren Sie den Hook:

{
  "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'"
      }
    ]
  }
}

Regeln sagen „bitte nicht.” Hooks sagen „Sie können nicht.”

FAQ

Mit welcher Agent-Laufzeitumgebung sollte ich beginnen?

Claude Code CLI mit XcodeBuildMCP. Es bietet die tiefste MCP-Integration, das ausgereifteste Hook-System und das 1M-Kontextfenster (Opus 4.6), das ganze iOS-Projekte im Arbeitsspeicher halten kann. Beginnen Sie hier und ergänzen Sie mit zunehmender Reife Ihres Workflows Codex für Reviews und Xcode-native Agenten für schnelle Inline-Edits.

Benötige ich beide MCP-Server?

Für die meisten Entwickler deckt XcodeBuildMCP allein 90% der Anforderungen ab (Builds, Tests, Simulatoren, Debugging). Fügen Sie Apples Xcode-MCP hinzu, wenn Sie Dokumentationssuche, Swift-REPL-Verifikation oder SwiftUI-Preview-Rendering möchten. Sie können es jederzeit später hinzufügen — die beiden Server sind unabhängig voneinander.

Können Agenten ein neues Xcode-Projekt von Grund auf erstellen?

XcodeBuildMCP enthält ein create_project-Tool, das neue Xcode-Projekte erzeugt. Für produktive Apps empfehle ich jedoch, das Projekt in Xcode zu erstellen (um Signing, Capabilities und Target-Konfiguration korrekt einzurichten) und dann Agenten für die gesamte Code-Implementierung zu verwenden. Die 5 Minuten, die Sie im Xcode-Assistenten für neue Projekte verbringen, ersparen Ihnen Stunden an Konfigurationsproblemen mit agent-generierten Projekten.

Wie gehen Agenten mit Swift Package Manager-Abhängigkeiten um?

Gut. Package.swift ist eine Standard-Swift-Datei, die Agenten zuverlässig lesen und bearbeiten können. Abhängigkeiten hinzufügen, Versionsbereiche aktualisieren und Targets konfigurieren funktioniert alles. Die Einschränkung liegt bei der .xcodeproj-basierten Abhängigkeitsverwaltung (Xcode-Paketauflösungs-UI) — diese wird von Xcode verwaltet und sollte nicht von Agenten bearbeitet werden.

Können Agenten an den App Store übermitteln?

Nein. Die App-Store-Übermittlung umfasst Xcodes Organizer, Provisioning Profiles, Screenshots, Metadaten und das App-Store-Connect-Portal. Keines davon ist über MCP oder Befehlszeilentools so zugänglich, dass Agenten sinnvoll damit arbeiten könnten. Agenten erledigen alles bis zum Archive — Implementierung, Testing, Bugfixes und Dokumentation. Die letzte Meile der Übermittlung bleibt menschlich gesteuert.

Allerdings können Agenten bei App-Store-Metadaten helfen. Bitten Sie den Agenten, die App-Beschreibung, Keywords und „Was ist neu”-Texte basierend auf den letzten Änderungen zu schreiben. Dies ist Texterstellungsarbeit, in der Agenten exzellent sind.

Wie gehe ich mit Secrets und API-Keys in der agent-gestützten iOS-Entwicklung um?

Committen Sie niemals Secrets. Für iOS-Apps, die mit Backend-APIs verbunden sind:

1. Verwenden Sie .xcconfig-Dateien für umgebungsspezifische Konfigurationen
2. Fügen Sie .xcconfig-Dateien zu .gitignore hinzu
3. Referenzieren Sie Konfigurationswerte über Info.plist-Build-Einstellungen
4. Dokumentieren Sie die erforderlichen Secrets in CLAUDE.md, ohne die tatsächlichen Werte einzuschließen

## 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`.

Der Agent weiß, dass die Keys existieren und wo sie verwendet werden, sieht aber niemals die tatsächlichen Werte.

Was ist mit SwiftUI-Animationen — können Agenten diese schreiben?

Agenten schreiben Animationscode syntaktisch gut, können das Ergebnis jedoch nicht visuell überprüfen. Einfache Animationen (.animation(.spring()), .transition(.slide), withAnimation { }) liefern korrekte Ergebnisse. Komplexe, mehrstufige Animationen mit präzisem Timing erfordern visuelle Iteration, die Agenten nicht leisten können.

Effektiv: „Fügen Sie eine Spring-Animation hinzu, wenn der Timer zwischen Zuständen wechselt.”

Ineffektiv: „Lassen Sie die Timer-Animation befriedigend wirken.” (Subjektiv, erfordert visuelle Feinabstimmung.)

Wie gehen Agenten mit Error-Handling-Mustern um?

Sehr gut. Agenten verstehen Swifts do/catch-, Result- und async throws-Muster:

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

Agenten produzieren strukturiertes Error-Handling mit angemessenen benutzergerichteten Nachrichten. Manchmal behandeln sie Fehler über das nötige Maß hinaus (fangen Exceptions ab, die propagieren sollten), prüfen Sie daher die Catch-Blöcke.

Kann ich Agenten für die Implementierung von Barrierefreiheit nutzen?

Teilweise. Agenten fügen Accessibility-Labels, -Hints und -Traits korrekt hinzu:

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

Was Agenten nicht können: überprüfen, ob die VoiceOver-Navigationsreihenfolge korrekt ist, Dynamic Type-Skalierung testen oder Farbkontrastverhältnisse bewerten. Verwenden Sie zur Überprüfung den Accessibility Inspector von Xcode.

Wie gehen Agenten mit Core-Data-Migration um (wenn nicht SwiftData verwendet wird)?

Agenten schreiben Core-Data-Migration-Mappings und Modellversionen, aber die manuellen Xcode-Schritte (neue Modellversionen erstellen, die aktuelle Version auswählen) lassen sich nicht automatisieren. Wenn Sie noch Core Data statt SwiftData verwenden, dokumentieren Sie die Modellversionshistorie in CLAUDE.md:

## Core Data Modellversionen
- V1: Initial (GroceryList, GroceryItem)
- V2: Category-Modell hinzugefügt (aktuell)
- Migration: Lightweight automatisch für V1→V2

Wie gehen Agents mit SwiftUI Previews um?

Auf zwei Arten: 1. Apples Xcode MCP-Tool RenderPreview rendert Previews headless und gibt das Ergebnis zurück. Der Agent kann verifizieren, dass eine Preview kompiliert und ohne Fehler rendert, kann jedoch die visuelle Korrektheit nicht beurteilen. 2. Build-basierte Verifikation über build_sim bestätigt, dass Preview-Provider kompilieren. Wenn eine Preview zur Laufzeit abstürzt, ist der Build dennoch erfolgreich – der Absturz manifestiert sich erst, wenn Xcode versucht, die Preview zu rendern.

Für die visuelle Verifikation von Previews benötigen Sie weiterhin ein geöffnetes Xcode.

Was ist mit visionOS und Apple Vision Pro?

Es gelten dieselben Muster. XcodeBuildMCP unterstützt visionOS-Simulatoren, und die Architekturmuster (@Observable, NavigationStack, SwiftData) sind identisch. RealityKit-spezifischer Code (3D-Inhalte, immersive Spaces, Hand-Tracking) unterliegt denselben Einschränkungen wie Metal – Agents können korrekten Code schreiben, aber die räumliche Ausgabe nicht verifizieren.

Wie groß kann ein Projekt sein, bevor Agents an ihre Grenzen stoßen?

Die Größe des Kontextfensters ist der limitierende Faktor. Mit dem 1M-Token-Fenster von Opus 4.6 kann Claude Code etwa 50–70 Swift-Dateien gleichzeitig im aktiven Arbeitsspeicher halten. Bei größeren Projekten verwendet der Agent Dateisuche und selektives Lesen, um mit Teilmengen der Codebasis zu arbeiten. Projekte mit mehr als 100 Dateien funktionieren problemlos – der Agent liest die Dateien einfach bei Bedarf, anstatt alles im Kontext zu halten.

Die praktische Grenze ist nicht die Dateianzahl, sondern die Kohärenz der Codebasis. Ein gut dokumentiertes 200-Dateien-Projekt mit einer detaillierten CLAUDE.md liefert bessere Ergebnisse als ein undokumentiertes 30-Dateien-Projekt.

Muss ich Swift beherrschen, um Agents für die iOS-Entwicklung zu nutzen?

Sie müssen in der Lage sein, die Ausgabe des Agents zu überprüfen und Architekturentscheidungen zu treffen. Sie müssen nicht jede Zeile selbst schreiben, aber Sie müssen Swift gut genug verstehen, um zu erkennen, wenn der Agent falsche Entscheidungen trifft – insbesondere bei Concurrency, Speicherverwaltung und Framework-spezifischen Mustern. Ein Agent ist ein 10-facher Verstärker Ihrer vorhandenen Fähigkeiten, kein Ersatz dafür.

Wie gehen Agents mit Merge-Konflikten in Swift-Dateien um?

Agents lösen Merge-Konflikte in Swift-Quelldateien zuverlässig. Die Standard-Konfliktmarker (<<<<<<<, =======, >>>>>>>) werden von allen Agent-Runtimes gut verstanden. Merge-Konflikte in .pbxproj-Dateien bleiben jedoch eine manuelle Aufgabe – bitten Sie Agents nicht, .pbxproj-Konflikte zu lösen.

Was kosten Agents für die iOS-Entwicklung?

Mit dem Max-Plan von Anthropic (Opus 4.6, 1M Kontext) dauert eine typische iOS-Entwicklungssitzung 30–120 Minuten und verarbeitet 200K–800K Token. MCP-Tool-Aufrufe verursachen minimalen Overhead (strukturierte JSON-Antworten sind im Vergleich zur Roh-Build-Ausgabe Token-effizient). Die Kosten sind vergleichbar mit dem Einsatz von Claude Code für jede andere Codebasis – iOS-Entwicklung ist nicht nennenswert teurer oder günstiger als Web-Entwicklung.

Kann ich Agents mit UIKit-Projekten verwenden?

Ja, aber Agents sind mit SwiftUI effektiver. UIKit erfordert mehr Boilerplate, hat eine weniger deklarative Struktur und beinhaltet oft Interface-Builder-Dateien, die Agents nicht bearbeiten können. Wenn Sie ein UIKit-Projekt haben, sollten Sie Agents für die Modellschicht und Geschäftslogik einsetzen und die UI manuell bearbeiten – oder Views schrittweise zu SwiftUI migrieren.

Wie gehen Agents mit Lokalisierung um?

Agents erstellen und bearbeiten .xcstrings-Dateien (Xcode String Catalog) effektiv. Sie können neue Lokalisierungsschlüssel hinzufügen, Übersetzungen bereitstellen und die Konsistenz über Sprachen hinweg wahren. Das strukturierte JSON-Format der .xcstrings-Dateien ist agent-freundlich. Auch bei .strings-Dateien (Legacy-Format) leisten Agents gute Arbeit – das Schlüssel-Wert-Format ist unkompliziert.

Häufige Agent-Fehler bei iOS (und wie Sie sie vermeiden)

Dies sind die wiederkehrenden Fehler, die ich bei tausenden Agent-Interaktionen über 8 iOS-Projekte hinweg beobachtet habe. Für jeden gibt es eine Präventionsstrategie.

Fehler 1: Mischen von Observable-Mustern

Was passiert: Der Agent verwendet @Observable in einer Datei und ObservableObject in einer anderen, oder fügt @Observable zu einer @Model-Klasse hinzu (die bereits Observable ist).

Prävention: Explizite Regeln in CLAUDE.md:

- 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

Fehler 2: Erzeugen von Retain Cycles in Closures

Was passiert: Der Agent erstellt Closures, die self stark capturen, insbesondere bei Timer.publish, NotificationCenter und Completion-Handlern.

Prävention: Fügen Sie ein Closure-Muster in CLAUDE.md ein:

## 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

Fehler 3: Ignorieren von @MainActor-Anforderungen

Was passiert: Der Agent erstellt @Observable-Klassen ohne @MainActor-Isolation, was zu Swift 6.2 Concurrency-Warnungen oder Laufzeitabstürzen führt, wenn UI-Updates außerhalb des Main Threads erfolgen.

Prävention:

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

Fehler 4: Verwendung von NavigationLink mit Destination Closure

Was passiert: Der Agent verwendet das veraltete NavigationLink(destination:label:) anstelle des typsicheren Musters NavigationLink(value:) + .navigationDestination(for:).

Prävention:

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

Fehler 5: Hardcodieren von Simulator-Namen

Was passiert: Der Agent schreibt Build-Befehle mit spezifischen Simulator-Namen (“iPhone 16 Pro”), die auf Ihrem System möglicherweise nicht existieren.

Prävention: MCP erledigt das – list_sims ermittelt verfügbare Simulatoren. In CLAUDE.md:

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

Fehler 6: Erstellen von Dateien in falschen Verzeichnissen

Was passiert: Der Agent erstellt eine neue View-Datei im Projektroot anstatt im Unterverzeichnis Views/, oder legt ein Modell in der falschen Gruppe ab.

Prävention: Die Dateistruktur-Anmerkungen in CLAUDE.md leiten die Platzierung. Zusätzlich:

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

Fehler 7: Plattformverfügbarkeit nicht berücksichtigen

Was passiert: Der Agent verwendet HealthKit in geteiltem Code, der für tvOS kompiliert (wo HealthKit nicht verfügbar ist), oder verwendet ActivityKit in watchOS-Code.

Prävention:

## 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)

Fehler 8: Over-Engineering einfacher Features

Was passiert: Der Agent erstellt ein Protocol, eine Protocol Extension, eine konkrete Implementierung, eine Factory und einen Dependency-Injection-Container für das, was eigentlich eine 20-zeilige Utility-Funktion sein sollte.

Prävention: Fügen Sie ein Einfachheitsprinzip ein:

## 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

Die ehrliche Einschätzung

Nach der Auslieferung von 8 iOS-Apps mit KI-Agenten lautet die Zusammenfassung wie folgt:

Agenten haben verändert: Die Implementierungsgeschwindigkeit. Was früher Tage dauerte, dauert nun Stunden. SwiftUI-Views, SwiftData-Modelle, Unit-Tests, Refactoring — diese werden inzwischen überwiegend von Agenten produziert und von Menschen überprüft.

Agenten haben nicht verändert: Architekturentscheidungen, visuelles Design, Performance-Optimierung oder die App-Store-Einreichung. Diese bleiben menschengetrieben.

Der Multiplikator ist real, aber begrenzt. Meine subjektive Schätzung über das gesamte 8-App-Portfolio: eine 3- bis 5-fache Verbesserung der Time-to-Feature bei gut dokumentierten Projekten mit korrekter MCP- und Hook-Konfiguration. Dies ist nicht gegen eine Kontrollgruppe gemessen, sondern ein Vergleich der Wanduhrzeit zwischen agentengestützten Features und gleichwertiger Soloarbeit in denselben Codebasen. Undokumentierte Projekte ohne Hooks erreichen vielleicht eine 1,5- bis 2-fache Verbesserung — der Agent verbringt zu viel Zeit mit Raten statt mit Bauen.¹⁸

Die Investition, die sich auszahlt: Die Zeit, die Sie in CLAUDE.md, Hooks und MCP-Konfiguration stecken. Jede Stunde Einrichtung erspart viele Stunden, in denen Sie sonst Fehler des Agenten korrigieren müssten. Die Konfiguration ist das Produkt — der Agent ist die Ausführungsmaschine.

Was mich überrascht hat: Wie sehr die MCP-Server die Dynamik verändert haben. Vor MCP waren Agenten ausgefeilte Texteditoren, die zufällig Swift verstanden. Nach MCP sind sie Entwicklungspartner, die schreiben, bauen, testen, debuggen und iterieren. Die strukturierte Feedback-Schleife ist der Unterschied zwischen einem Agenten, der Code schreibt, und einem, der Code ausliefert.

Was ich meinem früheren Ich sagen würde: Beginnen Sie mit der kleinsten App (Reps, 14 Dateien), bringen Sie die MCP- und Hook-Einrichtung in Ordnung, schreiben Sie eine gründliche CLAUDE.md und übertragen Sie die Muster anschließend auf größere Projekte. Beginnen Sie nicht mit der 63-Datei-Multi-Plattform-App. Die Infrastrukturinvestition ist unabhängig von der Projektgröße gleich — erledigen Sie sie einmal in einem kleinen Projekt und kopieren Sie sie dann in alle anderen.

Die Zukunft: Xcodes 26.3 native Agentenintegration ist der Anfang, nicht das Ende. Dass Apple MCP-Unterstützung ausliefert, bedeutet, dass sich die Toolchain in Richtung agentenorientierte Entwicklung bewegt. Entwickler, die jetzt in agentenkompatible Projektstrukturen investieren — saubere CLAUDE.md-Dateien, testbare Architekturen, automatisierte Hooks — werden diese Investition mit der Verbesserung der Werkzeuge zunehmend amortisieren.

Schnellreferenz

Installation (einmalige Einrichtung)

# 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

Wesentliche CLAUDE.md-Abschnitte

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

Wesentliche Hooks

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

Architekturregeln

@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+)

MCP-Tool-Prioritäten

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)

Changelog

Referenzen