iOS-Apps mit AI Agents entwickeln: Der Praxisleitfaden

TL;DR: Drei Agent-Runtimes können inzwischen Code für iOS liefern: 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) geben Agenten strukturierten Zugriff auf Builds, Tests, Simulatoren und Debugging. Dieser Leitfaden behandelt echte CLAUDE.md-Muster, Hook-Konfigurationen und ehrliche Einschätzungen dazu, was funktioniert und was bricht — abgeleitet aus 8 produktiven iOS-Apps mit insgesamt 293 Swift-Dateien.¹⁸ Agenten sind stark bei SwiftUI-Views, SwiftData-Modellen, Refactoring und der Diagnose von Build-Fehlern. Sie scheitern bei .pbxproj-Änderungen, Code-Signing und visuellem Debugging. Die Lücke zwischen „Agent schreibt Swift” und „Agent veröffentlicht eine iOS-App” wird durch Konfiguration geschlossen, nicht durch Prompting.

Ich habe 8 iOS-Apps mit AI-Coding-Agenten gebaut. Keine Prototypen — Apps im App Store, mit HealthKit-Integrationen, Metal-Shadern, SpriteKit-Physik, iCloud-Synchronisierung, Live Activities, Game Center-Bestenlisten und Multi-Plattform-Targets für iOS, watchOS und tvOS. Jede Zeile Swift in diesen Apps wurde entweder von einem Agenten geschrieben und von mir geprüft oder von mir geschrieben und von einem Agenten refaktoriert. Nach meiner Einschätzung haben Agenten den Großteil der Autorenschaft auf Zeilenebene übernommen; ich habe Review, Scope und die Teile verantwortet, die menschliches Urteil erfordern (visueller Feinschliff, Signing, Performance-Tuning, App-Store-Einreichung).

Dieser Leitfaden ist die Referenz, die ich mir zu Beginn gewünscht hätte. Er deckt den gesamten Stack ab: welche Agent-Runtime Sie verwenden sollten, wie Sie MCP-Server für strukturierten Build-Zugriff konfigurieren, was in Ihre CLAUDE.md gehört, welche Hooks verhindern, dass der Agent Ihr Xcode-Projekt zerstört, und — entscheidend — wo Agenten scheitern und Sie selbst das Steuer übernehmen müssen.

Zentrale Erkenntnisse

Für iOS-Entwickler, die neu mit AI-Agenten arbeiten:

• Beginnen Sie mit Claude Code CLI + XcodeBuildMCP. Das 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 einen Agenten niemals .pbxproj ändern. Das ist die wichtigste Regel überhaupt. Ein PreToolUse-Hook, der Schreibzugriffe auf .pbxproj und .xcodeproj/ blockiert, erspart Ihnen Stunden an Wiederherstellungsarbeit.
• Ihre CLAUDE.md ist das Onboarding-Dokument des Agenten. Die Stunden, die Sie dort investieren, zahlen sich in jeder Agentensitzung aus, die das Projekt berührt.

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

• MCP verändert den iOS-Build-Loop. Vor MCP schrieben Agenten Swift, konnten aber nicht prüfen, ob es kompiliert. 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 tiefe agentische Sitzungen, Codex CLI für Headless-Batch-Arbeit, native Agenten in Xcode 26.3 für schnelle Inline-Korrekturen, ohne die IDE zu verlassen.
• Hook-Infrastruktur lässt sich übernehmen. Ihre vorhandenen PostToolUse-Formatter, PreToolUse-Blocker und Test-Runner-Hooks funktionieren mit kleinen Pfadanpassungen identisch für iOS-Projekte.

Für Teamleads, die AI-gestützte iOS-Entwicklung bewerten:

• Die Wirksamkeit von Agenten skaliert mit der Projektdokumentation, nicht mit der Projektgröße. Eine App mit 63 Dateien und detaillierter CLAUDE.md liefert bessere Agentenergebnisse als eine App mit 14 Dateien ohne Dokumentation.
• Die .pbxproj-Grenze ist nicht verhandelbar. Agenten können Xcode-Projektdateien nicht zuverlässig bearbeiten. Ihr Workflow muss berücksichtigen, dass Dateien manuell zu Xcode-Targets hinzugefügt werden.
• Ehrliche ROI: Agenten übernehmen bei gut dokumentierten Projekten den Großteil der Implementierung — sichtbar an der TV-App mit 15 Dateien, die in 3 Stunden agentengestützter Arbeit veröffentlicht wurde (Fallstudie unten). Die verbleibende Arbeit — visueller Feinschliff, Signing, Performance-Tuning, App-Store-Einreichung — erfordert menschliches Urteil.

Wählen Sie Ihren Pfad

So nutzen Sie diesen Leitfaden

Dies ist eine Referenz mit mehr als 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 Agentensitzung
7. Was Agenten in iOS gut können
8. Was Agenten in iOS schlecht können
9. Hooks für iOS-Entwicklung
10. Architekturmuster, die mit Agenten funktionieren
11. Framework-spezifischer Kontext
12. Multi-Plattform-Muster
13. Fortgeschrittene Workflows
14. Praxisfallstudien
15. Projektlebenszyklus mit Agenten
16. Agent-Definitionen konfigurieren
17. Testmuster für agentengestütztes iOS
18. Kontextfenster-Management für iOS-Projekte
19. Fehlerbehebung
20. Häufige Agentenfehler in iOS
21. Die ehrliche Einschätzung
22. FAQ
23. Kurzreferenzkarte
24. Referenzen

Verwandte Ressourcen

Apple-Ecosystem-Serie. 21 produktive Beiträge zu SwiftUI-Apps, die Apple Intelligence, MCP, Foundation Models, Vision, Core ML und den iOS-26-Framework-Stack integrieren. Abgeleitet aus Water, Get Bananas, Return und dem restlichen 941-Portfolio:

Serien-Hub: Apple Ecosystem Series

Agentic Apple (E4):

Frameworks (E2/E3):

Shipped-Code (E1):

Synthese (E5):

Das Portfolio: 8 Apps, 293 Dateien

Bevor es in die Konfiguration geht, sehen Sie hier, worauf dieser Leitfaden basiert. Das sind keine Spielzeugprojekte – sie erstrecken sich über 5 Apple-Frameworks, 3 Plattformen und die gesamte Bandbreite der iOS-Komplexität, vom Workout-Tracker mit 14 Dateien bis zum plattformübergreifenden Meditationstimer mit 63 Dateien.

Warum die Dateianzahl wichtig ist: Die Effektivität von Agents korreliert mit der Lesbarkeit des Projekts, nicht mit seiner Größe. Return (63 Dateien) erzeugt bessere Agent-Ausgaben als amp97 (41 Dateien), weil Return eine detaillierte CLAUDE.md mit Dateianmerkungen, Architekturdiagrammen und expliziten Mustern hat. Die Metal-Shader von amp97 sind für Agents unabhängig von der Dokumentationsqualität grundsätzlich schwerer zu durchdenken.

Voraussetzungen

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

App Store Connect-Frist: Ab dem 28.04.2026 müssen App-Uploads zu App Store Connect mit Xcode 26 oder neuer erstellt werden und SDKs für iOS 26, iPadOS 26, tvOS 26, visionOS 26 oder watchOS 26 verwenden.¹² (macOS-Einreichungen fallen nicht unter diese Anforderung.) Wenn Ihr Team noch Xcode 16.x nutzt, dient die agentengestützte Toolchain in diesem Leitfaden zugleich als zwingender Umstiegsgrund – keiner der untenstehenden MCP-Server funktioniert ohnehin ohne Xcode 26.3+.

Erforderlich: - macOS 15+ (Sequoia) oder macOS Tahoe - Xcode 26.3+ installiert und konfiguriert (die Mindestversion für xcrun mcpbridge); Xcode 26.5+ empfohlen für die Verbesserungen am Agent-Workflow – Nachrichtenwarteschlange im Coding Assistant und Unterstützung für Rückfragen – plus Swift Testing-Bildanhänge, Schweregrade für aufgezeichnete Issues, UI-Test-Absturzwarnungen mit Crashlogs und Verbesserungen am String Catalog-Editor, die zuerst in 26.4 hinzugefügt wurden.¹³¹⁴ Xcode 26.5 (11.05.2026, Build 17F42) ist die neueste stabile Version; 26.4.1 (16.04.2026, Build 17E202) war das letzte Bugfix-Release der 26.4-Reihe.¹⁵ - Mindestens eine installierte iOS Simulator-Laufzeitumgebung - Ein Anthropic-API-Konto (für Claude Code) oder ein 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 Durchsetzung von Stilregeln - Vertrautheit mit dem Terminal – alle 3 Laufzeitumgebungen arbeiten über die Kommandozeile oder integrieren sich darin

Überprüfen Sie Ihre Xcode-Installation:

# Check Xcode version
xcodebuild -version
# Expected: Xcode 26.3 or later (26.5+ 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 nur 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” in „schreibt Swift, baut es, liest strukturierte Fehler und behebt sie.” Dieser Abschnitt geht tiefer als der Blogbeitrag — er behandelt beide Server, alle Installationsmethoden, die Verifizierung und die Agentenkonfiguration, die sicherstellt, dass Tools tatsächlich genutzt 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 Befehlszeilentools.

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 projektübergreifend global verfügbar. Lassen Sie es für eine projektbezogene Installation weg (sinnvoll, wenn Sie MCP nur in iOS-Projekten nutzen möchten, nicht in Webprojekten).

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

Vollständiger Tool-Bestand (59 Tools in 8 Kategorien):

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

1. build_sim — Dieses Tool werden Sie Hunderte Male aufrufen. Es gibt JSON zurück, wobei Fehler nach Datei, Zeile und Schweregrad kategorisiert sind. Der Agent liest den Fehler, navigiert zur Datei und behebt ihn, ohne dass Sie etwas anfassen müssen.

2. test_sim — Gibt Ergebnisse pro Testmethode zurück. 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 — Projektintrospektion. Der Agent muss Ihren Scheme-Namen oder Ihre Workspace-Struktur nicht erraten.

5. debug_attach_sim + debug_stack + debug_variables — Remote-LLDB-Debugging. Der Agent kann Breakpoints setzen, Variablen prüfen und Code schrittweise ausführen, ohne dass Sie den Debugger öffnen.

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

Apples MCP-Server wird mit Xcode 26.3 über xcrun mcpbridge ausgeliefert. Er kommuniziert über XPC (Apples Framework für Interprozesskommunikation) mit einem laufenden Xcode-Prozess 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. XcodeBuildMCP hat diese Einschränkung nicht.

Tool-Bestand (20 Tools in 5 Kategorien):

Tools, die es nur in Apple MCP gibt (nicht in XcodeBuildMCP verfügbar):

1. DocumentationSearch — Durchsucht Apples Entwicklerdokumentation einschließlich WWDC-Sessions. Schneller und zuverlässiger als Websuche bei Fragen zu Apple API. Fragen Sie „is HKQuantityType(.dietaryWater) valid?” und erhalten Sie eine verbindliche Antwort aus der Quelle.

2. ExecuteSnippet — Swift-REPL-Ausführung innerhalb des Projektkontexts. Der Agent kann API-Verhalten verifizieren, Typkonvertierungen testen und Ausdrücke validieren, ohne die vollständige App zu bauen.

3. RenderPreview — Rendert SwiftUI-Previews headless. Der Agent kann prüfen, ob eine View fehlerfrei rendert, kann die visuelle Korrektheit allerdings nicht bewerten (das Render-Ergebnis wird als Daten zurückgegeben, nicht visuell geprüft).

4. XcodeListNavigatorIssues — Gibt Echtzeitdiagnostik aus Xcodes Analyzer zurück, nicht nur Build-Fehler. Erkennt Probleme wie ungenutzte Variablen, potenzielle Retain Cycles und Deprecation-Warnungen, die das Build-System nicht ausgibt.

Warum beide Server

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

┌─────────────────────────────────────────────────────────────────┐
│                     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 umfangreichere Simulator- und Geräteverwaltung. Das ist Ihr primäres Build-Tool.

Verwenden Sie Apple Xcode MCP für: Dokumentationsabfragen, Swift-REPL-Verifizierung, SwiftUI-Preview-Rendering und Echtzeitdiagnostik. Lassen Sie Xcode während Sitzungen geöffnet, die diese Funktionen benötigen.

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

Verifizierung

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 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). Während einer Sitzung registrierte MCP-Server erscheinen möglicherweise erst nach einem Neustart.

Dem Agenten beibringen, MCP zu verwenden

MCP-Server zu installieren ist notwendig, reicht aber nicht aus. Ohne explizite Anleitung fällt der Agent möglicherweise darauf zurück, xcodebuild über Bash auszuführen (unstrukturierte Ausgabe, verschwendete Kontext-Tokens) oder Websuche für Apple-Dokumentation zu nutzen (langsamer, weniger zuverlässig).

Fügen Sie dies zu Ihrer CLAUDE.md oder Agentendefinition hinzu:

## 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` (NOT `xcrun simctl` via Bash)
- **Debug**: `debug_attach_sim`, `debug_stack`, `debug_variables`
- **Apple docs**: `DocumentationSearch` (NOT WebSearch for Apple APIs)
- **Swift verification**: `ExecuteSnippet` (NOT `swift` via Bash)
- **Previews**: `RenderPreview` for headless SwiftUI verification

MCP returns structured JSON. Bash returns unstructured text.
Structured data means fewer tokens consumed and better error diagnosis.

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 Kontext-Tokens beim Parsen der Ausgabe verbraucht und manchmal den eigentlichen Fehler falsch identifiziert.

CLAUDE.md-Muster 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 einer neuen Arbeitskraft, die die Architekturdokumentation gelesen hat, und einer, die rät.

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

Die wesentlichen Abschnitte

Jede iOS-CLAUDE.md braucht diese sechs Abschnitte. Alles Weitere 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 auf iOS 17 abzielt, verwendet NavigationView und @ObservedObject. Ein Agent, der auf iOS 26 abzielt, verwendet NavigationStack und @Observable. Die Bundle ID ist für Entitlements und die HealthKit-Konfiguration relevant. Die Swift-Version bestimmt das Concurrency-Modell (async/await vs. Completion Handler, strikte Concurrency vs. nachgiebige).

2. Dateistruktur mit Zweckannotationen

## 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 Dokumentation mit dem höchsten Hebel, die Sie schreiben können. Wenn der Agent entscheidet, wo er eine neue Funktion ergänzt, führen ihn diese Annotationen beim ersten Versuch zur richtigen Datei, statt dass er jede Datei lesen muss, um das Projektlayout zu verstehen.

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

3. Build- und Testbefehle

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

Nehmen Sie die Rohbefehle auf, auch wenn der Agent MCP bevorzugen sollte. Die Rohbefehle dienen als Fallback-Dokumentation und machen die Scheme-Namen und Destinations explizit.

4. Wichtige Muster 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 Muster verhindern, dass der Agent Inkonsistenzen einführt. Ohne explizite Musterdokumentation verwendet der Agent manchmal ObservableObject in einer Datei und @Observable in einer anderen oder erstellt einen neuen Einstellungsmechanismus, statt das vorhandene Settings.shared-Singleton zu nutzen.

5. Dinge, die 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 (tun / nicht tun) und nicht heuristisch (dies bevorzugen / manchmal jenes verwenden).

6. Framework-spezifischer Kontext

Dieser Abschnitt variiert je nach App. Nehmen Sie ihn für jedes Framework auf, dessen Konfiguration nicht offensichtlich ist:

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.

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

Hier ist ein annotiertes Beispiel, das zeigt, wie alle sechs Abschnitte in einer moderat komplexen App zusammenspielen. Dieses CLAUDE.md-Muster verwende ich für Banana List, eine Einkaufslisten-App mit 53 Dateien, iCloud-Synchronisierung und einem benutzerdefinierten MCP Server, der die Daten der App für Claude Desktop verfügbar macht:

# 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

## File Structure

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

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

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

### Query Patterns
- Lists: `@Query(sort: \GroceryList.name) var lists: [GroceryList]`
- Active items: `@Query(filter: #Predicate { !$0.isCompleted })`
- By category: filter in-memory after fetch (SwiftData predicate limitations)

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

Prefer MCP tools (`build_sim`, `test_sim`) over raw commands.

## Key Patterns

### Observable + SwiftData
- SwiftData `@Model` classes are automatically Observable
- DO NOT add `@Observable` to `@Model` classes (redundant, causes warnings)
- Use `@Bindable` for two-way bindings to model properties in forms
- Use `@Query` in views, `modelContext.fetch()` in non-view code

### iCloud Sync
- Automatic via SwiftData CloudKit integration
- Conflict resolution: last-write-wins (CloudKit default)
- Sync status exposed via `CloudSyncManager.shared.syncState`
- Test sync by running on two simulators with same iCloud account

### MCP Server Architecture
- Runs as a local WebSocket server on port 8765
- Exposes 6 tools: listAll, getList, createList, addItem, completeItem, deleteItem
- Claude Desktop connects via MCP config in `~/.config/claude-desktop/config.json`

## Rules

- NEVER modify .pbxproj or .xcodeproj contents
- NEVER change the model schema without updating SampleData.swift
- NEVER use `ObservableObject` — SwiftData models are already Observable
- NEVER use `@StateObject` — use `@State` with `@Observable` classes
- NEVER use `NavigationView` — always `NavigationStack`
- NEVER add `@Observable` macro to `@Model` classes
- ALWAYS use `@Bindable` for form bindings to model properties
- ALWAYS test iCloud sync changes on two simulator instances

Echte CLAUDE.md: Reps (minimale SwiftData-App — 14 Dateien)

Bei kleinen Projekten kann die CLAUDE.md knapp sein. Hier ist das Muster für Reps, einen Workout-Tracker mit 14 Dateien. Beachten Sie, dass selbst eine kurze CLAUDE.md alle sechs wesentlichen 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 der Agentenverwirrung.

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

Spieleprojekte benötigen mehr Framework-spezifischen Kontext. Der Agent muss den Scene Graph, die Physics Categories und die Game State Machine 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
```

## Rules

- NEVER modify .pbxproj
- NEVER modify PhysicsCategory bitmasks (breaks all collision detection)
- NEVER change the scene hierarchy z-ordering without understanding render order
- NEVER modify ShaderTypes.h without updating both Swift and Metal references
- Add new enemies by subclassing EnemyShip, not by modifying it
- Bullet pooling: recycle via removeFromParent() + re-add, never allocate new
- Game Center: always check isAuthenticated before submitting scores

Echte CLAUDE.md: amp97 (Metal + Audiovisualisierung — 41 Dateien)

Metal-Projekte benötigen den meisten Framework-spezifischen Kontext, weil Agenten 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

## Architecture

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

## File Structure

```
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 processes FFT data → texture
2. Render pass: Shaders.metal reads texture + uniforms → visualization
3. Post-process pass: PostProcess.metal applies bloom → final output

### Buffer Management
- Triple buffering with DispatchSemaphore(value: 3)
- Uniforms updated per-frame on CPU, consumed by GPU 1-2 frames later
- Audio data ring buffer: 4096 samples, lock-free single producer/consumer

## Rules

- NEVER modify ShaderTypes.h without updating BOTH Swift and Metal sides
- NEVER exceed 64 frequency bins (fixed buffer size in shader)
- NEVER test Metal visual output in simulator — device only
- NEVER modify the audio engine tap format (48kHz, mono, float32)
- Triple buffer discipline: always signal semaphore in completion handler
- Audio session: .playAndRecord category with .defaultToSpeaker option

CLAUDE.md mit der Projektgröße skalieren

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

Die Kosten einer Überdokumentation liegen nahe null (der Agent überspringt, was er nicht braucht). Die Kosten einer Unterdokumentation sind hoch (der Agent erfindet Muster, die mit Ihrer Codebasis kollidieren).

CLAUDE.md-Checkliste

Verwenden Sie diese Checkliste, wenn Sie eine CLAUDE.md für ein iOS-Projekt erstellen oder prüfen:

• [ ] Bundle ID und Deployment Target angegeben
• [ ] Swift-Version und Architekturmuster benannt
• [ ] Dateistruktur mit Inline-Zweckannotationen
• [ ] Build-Befehl mit korrektem Scheme und korrekter Destination
• [ ] Testbefehl mit korrektem Scheme und korrekter 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)
• [ ] Platform Availability Guards dokumentiert (#if canImport, #if os)
• [ ] Wichtige Singletons und gemeinsame Muster dokumentiert
• [ ] Bekannte Einschränkungen oder Fallstricke vermerkt

Ihre erste Agenten-Session

Wenn MCP konfiguriert ist und eine CLAUDE.md in Ihrem Projekt liegt, folgt hier eine exemplarische erste Sitzung, wie sie effektiv abläuft. Dieses Beispiel verwendet Claude Code CLI, der Workflow gilt aber für jede Runtime.

Schritt 1: Prüfen, ob der Agent Ihr Projekt sehen kann

You: 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 den Inhalt Ihrer CLAUDE.md Bezug nimmt, prüfen Sie, ob die Datei im Projekt-Root liegt (im selben Verzeichnis wie .xcodeproj oder Package.swift).

Schritt 2: Einen Health-Check-Build ausführen

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

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

You: 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 Agenten, .pbxproj nicht zu ändern, ist das Ergebnis der Regeln in CLAUDE.md. Ohne diese Regel würde der Agent versuchen, die Projektdatei zu ändern, und sie dabei wahrscheinlich beschädigen.

Was Agenten in iOS gut erledigen

Das sind die Aufgaben, bei denen Agenten zuverlässig korrekte, produktionsreife Ergebnisse mit minimaler menschlicher Prüfung liefern.

SwiftUI-Views und Modifier

Agenten verfügen über eine starke Mustererkennung für die deklarative SwiftUI-Syntax. View-Komposition, Modifier-Ketten, State-Bindings und Layout passen gut zu den Trainingsdaten des Agenten, weil die API-Oberfläche von SwiftUI gut dokumentiert ist und die Muster sehr konsistent sind.

Worin Agenten besonders stark sind: - Neue Views anhand einer Beschreibung erstellen („create a settings sheet with toggles for X, Y, Z“) - Modifier-Ketten anwenden (.glassEffect(), .sensoryFeedback(), .navigationTitle()) - Zwischen Layout-Mustern konvertieren (VStack zu LazyVGrid, List zu ScrollView) - @Bindable-Formular-Bindings für SwiftData-Modelle implementieren - Preview-Provider mit Beispieldaten erstellen

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.

Die Genauigkeit ist entscheidend. „Create a settings view“ führt zu generischem Output. „Create a SettingsView that matches the existing pattern in SettingsSheet.swift“ erzeugt Output, der zu Ihrer Codebase passt.

SwiftData-Modelle und Queries

Agenten kommen zuverlässig mit dem @Model-Macro von SwiftData, Relationships und @Query-Mustern zurecht. Die deklarative Natur des Frameworks (ähnlich wie Django ORM oder SQLAlchemy) passt gut zu Mustern, die der Agent in vielen Codebases gesehen hat.

Worin Agenten besonders stark sind: - @Model-Klassen mit Relationships definieren - @Query mit Sort Descriptors und Predicates schreiben - CRUD-Operationen über modelContext implementieren - Migrationspläne zwischen Schemaversionen erstellen - Preview-Daten und Test-Fixtures anlegen

Wobei Agenten Anleitung benötigen: - 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, manuellen Sync zu implementieren)

Unit Tests

Von Agenten geschriebene Unit Tests sind bei iOS-Projekten durchweg von hoher Qualität. Der Agent versteht XCTest-Muster, async-Testmethoden und den setup/teardown-Lifecycle.

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 erstellt gut strukturierte XCTest-Fälle mit setUp() und tearDown(), passenden Assertions und async-Handling für timerbasierte Tests.

Refactoring und Musteranwendung

Agenten sind hervorragend bei mechanischem Refactoring: Views in Komponenten extrahieren, ObservableObject in @Observable umwandeln, 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 jede Datei methodisch durch, wendet die Transformation korrekt an und erhält die bestehende Funktionalität. Das ist Arbeit mit hohem Hebel: Ein Refactoring, das manuell eine Stunde dauern würde, ist mit nahezu perfekter Genauigkeit in Minuten erledigt.

Build-Fehlerdiagnose über MCP

Mit strukturiertem MCP-Output diagnostizieren Agenten Build-Fehler schneller als die meisten Entwickler. Der Agent liest den Fehler-JSON, erkennt die exakte Datei und Zeile, versteht die Fehlermeldung und wendet die Korrektur an, oft in einem einzigen Turn.

Fehler, die Agenten eigenständig beheben: - Fehlende Imports - Typinkompatibilitäten - Lücken bei Protocol Conformance - Veraltete API-Nutzung (mit Ersatz) - Fehlende erforderliche Initializer-Parameter - Verstöße gegen Access Control

Fehler, bei denen Agenten Hilfe benötigen: - Uneindeutige Typauflösung (mehrere Module definieren denselben Typ) - Komplexe Fehler bei Generic Constraints - Macro-Expansion-Fehler (der Agent kann den expandierten Macro-Output nicht sehen)

Simulator-Verwaltung

Agenten handhaben den Simulator-Lifecycle 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 erstellen, alles über strukturierte MCP-Aufrufe.

Was Agenten bei iOS schlecht können

Eine ehrliche Bestandsaufnahme, wo Agenten scheitern. Wer diese Grenzen kennt, vermeidet Frust und verschwendete Tokens.

Änderungen an .pbxproj-Dateien — NIEMALS

Das ist die wichtigste Einzelregel in der iOS-Entwicklung mit Agenten. Die .pbxproj-Datei ist die Projektkonfiguration von Xcode: eine strukturierte Textdatei mit UUID-Referenzen, Build-Phase-Listen und Target-Zugehörigkeit. Sie ist dem Namen nach für Menschen lesbar, in der Praxis für AI Agents aber nicht zuverlässig parsebar.

Warum Agenten bei .pbxproj scheitern: - Die Datei verwendet ein eigenes Format (nicht JSON, nicht YAML, nicht XML) mit positionsabhängiger Bedeutung - Jeder Eintrag wird per UUID querverwiesen — zum Hinzufügen einer Datei müssen 3–5 verschiedene Abschnitte konsistent aktualisiert werden - Ein einziges falsch platziertes Zeichen beschädigt die gesamte Projektdatei - Xcodes Merge-Conflict-Auflösung für .pbxproj ist ohnehin fragil — Agenten-Edits machen es schlimmer

Was passiert, wenn ein Agent .pbxproj bearbeitet: 1. Der Edit scheint erfolgreich zu sein (der Agent meldet „file updated”) 2. Xcode weigert sich, das Projekt zu öffnen („The project file is corrupted”) 3. Sie verbringen 15–60 Minuten damit, den Stand aus der Git-Historie wiederherzustellen 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 verhindert stundenlange Wiederherstellung.

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

Komplexe Interface-Builder- / Storyboard-Edits

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

Die Gegenmaßnahme: Verwenden Sie für neue Views ausschließlich SwiftUI. Wenn Ihr Projekt ältere Interface-Builder-Dateien enthält, lassen Sie diese unangetastet und bauen Sie neue UI in SwiftUI.

Performance-Optimierung

Agenten schreiben korrekten Code, aber nicht zwangsläufig performanten Code. Sie können Ihre App nicht profilen, Engpässe nicht identifizieren und Framerates nicht messen. Performance-Optimierung erfordert:

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

Wo sich das zeigt: - Metal-Shader-Optimierung (der Agent schreibt gültiges Metal, kann aber die GPU-Frame-Time nicht messen) - Komplexität von SwiftUI-View-Bodys (der Agent erstellt 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 Gegenmaßnahme: Verwenden Sie Agenten für die Implementierung, profilen Sie manuell mit Instruments, und bitten Sie den Agenten anschließend, die konkret von Ihnen identifizierten Optimierungen umzusetzen.

Code Signing und Provisioning

Agenten können Code-Signing-Probleme nicht über das Auslesen der Fehlermeldung hinaus debuggen. Die Verwaltung von Provisioning Profiles, Zertifikatserstellung, Entitlement-Konfiguration und App-Store-Einreichung sind grundsätzlich menschlich gesteuerte Workflows, die das Apple Developer Portal, Keychain Access und Xcodes Signing-UI betreffen.

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 Profile das Gerät enthält, ob die Bundle ID zur App ID passt oder ob Ihre Entitlements-Datei korrekt ist.

Die Gegenmaßnahme: Erledigen Sie das gesamte Signing im Tab Signing & Capabilities von Xcode. Bitten Sie Agenten nicht, Signing-Fehler zu debuggen.

Komplexes Metal-Shader-Debugging

Agenten schreiben syntaktisch korrektes Metal Shading Language (MSL), können aber die visuelle Ausgabe nicht verifizieren und keine GPU-seitigen Probleme debuggen. Metal-Shader laufen auf der GPU — der Agent hat keinen Feedback-Mechanismus, um zu erkennen, ob der Shader visuell korrekte Ergebnisse erzeugt.

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

Was Agenten mit Metal nicht können: - Die visuelle Korrektheit der Shader-Ausgabe verifizieren - GPU-Performance debuggen (Frame-Time, Occupancy, Speicherbandbreite) - Visuelle Artefakte diagnostizieren (Banding, Präzisionsprobleme, falscher Farbraum) - Auf unterschiedlichen GPU-Architekturen testen (Verhaltensunterschiede zwischen A-Series und M-Series)

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

Visuelle Layout-Verifikation

Agenten können die UI Ihrer App nicht sehen. Sie schreiben SwiftUI-Layout-Code und können prüfen, ob er kompiliert, aber sie können nicht beurteilen, ob der resultierende Bildschirm korrekt aussieht. Eine View, die 10 Pixel dezentriert rendert, die falsche Schriftstärke verwendet oder überlappende Elemente enthält, erzeugt keinen Build-Fehler und besteht alle Logiktests.

Die Gegenmaßnahme: Prüfen Sie UI-Änderungen visuell. Verwenden Sie SwiftUI Previews in Xcode (oder RenderPreview über Apple MCP für Headless Rendering), um das Layout zu verifizieren. Erwägen Sie Snapshot-Testing mit Bibliotheken wie swift-snapshot-testing, um visuelle Regressionen automatisiert zu erkennen.

Hooks für die iOS-Entwicklung

Hooks sind Shell-Befehle, die an bestimmten Punkten im Workflow des Agenten deterministisch 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-Leitfaden. Dieser Abschnitt behandelt iOS-spezifische Hook-Muster.

PreToolUse: .pbxproj-Schreibvorgänge blockieren

Der wichtigste Hook in jedem iOS-Projekt. Er blockiert 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 Projektstamm oder in ~/.claude/settings.json für globalen Schutz.

So funktioniert es: Wenn der Agent versucht, das Edit- oder Write-Tool für eine Datei zu verwenden, die dem Muster entspricht, wird der Hook ausgeführt, erkennt den Dateipfad, gibt eine Warnung an stderr aus und beendet sich mit Code 2 (wodurch die Tool-Nutzung blockiert wird). Der Agent erhält die Fehlermeldung und passt seine Vorgehensweise 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

Formatieren Sie Swift-Dateien automatisch, 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'"
      }
    ]
  }
}

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

Warum das wichtig ist: Agenten erzeugen syntaktisch korrektes Swift, halten Formatierungskonventionen aber nicht konsequent ein. SwiftFormat normalisiert Einrückung, Klammerpositionierung und Import-Reihenfolge. Durch den Format-on-Save-Hook wird jede Swift-Datei, die der Agent berührt, automatisch formatiert, bevor Sie sie sehen.

Optional: Fügen Sie Ihrem Projektstamm eine .swiftformat-Konfigurationsdatei hinzu, 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'"
      }
    ]
  }
}

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

PostToolUse: Nach Änderungen automatisch bauen

Für aggressive Feedback-Schleifen können Sie nach jeder Änderung an einer Swift-Datei einen Build auslösen:

{
  "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 dies sparsam — es ist vor allem während Debugging-Sitzungen hilfreich, in denen Sie sofortiges Build-Feedback möchten. Für die normale Entwicklung sollte der Agent Builds manuell über MCP auslösen, sobald 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'"
      }
    ]
  }
}

Damit erhalten Sie zwei Garantien: 1. Der Agent kann keine Xcode-Projektdateien 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)

iOS-26+-Targets 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 nötig), das Ownership-Modell ist klarer (@State statt @StateObject vs. @ObservedObject), und Agenten erzeugen damit weniger Bugs, weil es weniger bewegliche Teile gibt.

Dokumentieren Sie das in CLAUDE.md: Selbst wenn iOS 26 das Ziel ist, greifen Agenten gelegentlich auf ObservableObject-Muster aus ihren Trainingsdaten zurück. Ein ausdrückliches 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 falsche 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 Formularbindungen: @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. Löschvorgänge bei Beziehungen brauchen ausdrückliche Regeln: .cascade, .nullify, .deny

Swift 6.2 Concurrency

Richten Sie neue Projekte auf strikte Swift 6.2 Concurrency aus:

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

Agentenleitlinien für Concurrency: - Markieren Sie alle View-Modelle mit @MainActor (verhindert Data-Race-Warnungen) - Verwenden Sie async/await für alle asynchronen Arbeiten (keine Completion Handler) - Machen Sie Werttypen für Actor-übergreifende Transfers Sendable - Verwenden Sie Task { } in Views für asynchrone Initialisierung - Verwenden Sie nonisolated nur, wenn Sie einen Performancebedarf gemessen haben

Liquid Glass Design System (iOS 26+)

iOS 26 hat das Liquid Glass Design System eingeführt. Agenten kommen damit gut zurecht, wenn sie klare Vorgaben erhalten:

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

In CLAUDE.md aufnehmen: “Use .glassEffect() on section backgrounds and card containers. Navigation bars automatically adopt glass material in iOS 26. Do not manually recreate glass effects with custom materials — use the system modifier.”

Framework-spezifischer Kontext

Jedes Apple-Framework hat agentenspezifische Besonderheiten. Dieser Abschnitt behandelt die Frameworks, die in den 8 Apps verwendet werden.

HealthKit

Apps, die es verwenden: Return, Water

HealthKit erfordert sorgfältiges Permission-Handling und Plattformprüfungen:

// 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: - Immer mit HKHealthStore.isHealthDataAvailable() absichern - Niemals von einer Autorisierung ausgehen — bei jedem Schreibvorgang prüfen - #if canImport(HealthKit) für Multiplattform-Code verwenden (HealthKit ist auf tvOS nicht verfügbar) - Gesundheitsdaten nie über das hinaus lokal speichern, was HealthKit bereitstellt - Sowohl NSHealthShareUsageDescription als auch NSHealthUpdateUsageDescription in Info.plist aufnehmen

SpriteKit

Apps, die es verwenden: TappyColor, Starfield Destroyer

Das Szenengraph-Modell von SpriteKit erfordert klare Agentenvorgaben:

## 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 mit SpriteKit: - Erstellen von SKAction-Sequenzen und -Gruppen - Einrichten von Physics Bodies und Kontakterkennung - Implementieren von Game-State-Machines - Erstellen von HUD-Overlays

Schwächen von Agenten mit SpriteKit: - Performancekritische Game Loops (der Agent fügt unnötige Arbeit pro Frame hinzu) - Komplexe Physiksimulationen (Custom Physics schlägt SKPhysicsBody bei Präzision) - Abstimmung von Partikeleffekten (visuell, erfordert Iteration)

Metal

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

Metal ist das Framework, mit dem Agenten am meisten kämpfen. Das GPU-Programmiermodell unterscheidet sich grundlegend von CPU-seitigem Swift, und Agenten können visuelle Ausgabe nicht verifizieren.

## 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 bei Metal-Projekten in CLAUDE.md aufnehmen sollten: - Die Definition des Uniforms-Structs (gemeinsam genutzt von 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 umgehen können, 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-Muster

Return umfasst iOS, watchOS und tvOS. Multi-Plattform-Entwicklung mit Agenten erfordert eine ausdrückliche Dokumentation der Plattformgrenzen.

Organisation gemeinsam genutzten 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, wirken sich Änderungen auf alle Plattformen aus. Wenn eine Datei in einem Plattformverzeichnis liegt, sind Änderungen isoliert. Prüfen Sie immer, in welchem Verzeichnis eine Datei liegt, bevor Sie sie ändern.”

Guards für Plattformverfügbarkeit

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

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

UI-Anpassung pro Plattform

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 wirkungsvollste Muster: Geben Sie dem Agenten eine Funktionsspezifikation und lassen Sie ihn eigenständig Build-Test-Fix-Zyklen durchlaufen.

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 menschliche 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 („make it look nice”), performancekritischer Code oder alles, was eine visuelle Überprüfung erfordert.

Subagent-Delegation für iOS

Das Subagent-System von Claude Code funktioniert 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 Codemuster in einem separaten Kontextfenster, gibt eine Zusammenfassung zurück, und die Hauptsitzung implementiert die Empfehlung. So wird verhindert, dass Recherche Ihren primären Kontext aufbraucht.

Musterübertragung zwischen Apps

Wenn Sie mehrere iOS-Apps mit konsistenten Mustern pflegen, können Agenten Muster 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 Quellmuster, versteht die Struktur und erstellt im Zielprojekt eine konsistente Implementierung.

Dual-Agent-Review (Claude + Codex)

Für kritische Änderungen verwenden Sie zwei Agenten aus unterschiedlichen Modellfamilien:

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

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

Unterschiedliche Modellfamilien erkennen unterschiedliche Fehlerklassen. Das ist besonders wertvoll bei Metal-Shadern und Concurrency-Mustern, bei denen subtile Bugs leicht entstehen.

Was ein Dual Review findet, das ein einzelnes Review übersieht:

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

Batch-Operationen über mehrere Apps hinweg

Wenn eine Framework- oder Musterä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 verwenden. Das Flag --dangerously-skip-permissions ist für den nicht interaktiven Modus erforderlich, umgeht aber alle Sicherheitsprüfungen. Stellen Sie sicher, dass Ihre PreToolUse-Hooks eingerichtet sind, um .pbxproj-Dateien zu schützen.

Apps, die Apples On-Device-LLM verwenden

Wenn Ihre App Apples Foundation Models-Framework aufruft (z. B. für Offline-Zusammenfassungen, Klassifizierung oder Structured-Output-Generierung), müssen Agenten das Prompt-Budget kennen. iOS 26.4 hat SystemLanguageModel um zwei APIs ergänzt, die die vorherige 4096-Token-Schätzung ersetzen: contextSize (maximale Tokenzahl, die das Modell in einer einzelnen Konversation akzeptiert) und tokenCount(for:) (async throws, gibt zurück, wie viele Token ein bestimmter Prompt tatsächlich kostet).¹⁷ Beide sind @backDeployed(before: iOS 26.4), stehen also ohne #available-Leiter auf allen FM-unterstützenden OS-Versionen zur Verfügung.

Dieses Muster sollte ein Agent befolgen, wenn er Code zur Prompt-Konstruktion generiert:

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 Muster Ihrer CLAUDE.md hinzu, wenn die App SystemLanguageModel berührt. Ohne dieses Muster fallen Agenten auf den alten 4096-Hardcode zurück und kürzen Prompts auf Geräten mit größeren Kontextfenstern stillschweigend. Die async throws-Signatur von tokenCount(for:) ist tragend: Agenten, die eine synchrone Version einfügen, werden beim Kompilieren scheitern.

Fallstudien aus der Praxis

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

Fallstudie 1: Eine TV-App zu Return hinzufügen (Erfolg)

Die Aufgabe: Ein tvOS-Target zu Return hinzufügen, einem Meditationstimer, für den es bereits iOS- und watchOS-Versionen gab. Die TV-App brauchte Siri Remote-Navigation, eine UI für große Bildschirme und Einstellungssynchronisierung mit der iOS-App.

Was der Agent gut gemacht hat: - Den vorhandenen iOS-TimerManager gelesen und einen TVTimerManager erstellt, der Live Activities und HealthKit ausließ (auf tvOS nicht verfügbar) - Eigene Schaltflächenstile für die Fokusnavigation mit Siri Remote erstellt (TVCapsuleButtonStyle, TVCircleButtonStyle) - Eine TVStepper-Komponente gebaut, die Wheel Picker (mit Siri Remote nicht nutzbar) durch +/- Schaltflächen ersetzt - Einstellungssynchronisierung über App Groups implementiert (group.com.941apps.Return) - Überall im gemeinsamen Code #if os(tvOS)-Guards hinzugefügt - Per 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 vorhandenen Scheme hinzufügen oder ein neues erstellen - Alle vom Agenten erstellten Swift-Dateien manuell zum TV-Target hinzufügen - Die Siri Remote-Navigation von Hand testen (der Agent kann Fokusverhalten nicht bewerten)

Ergebnis: 15 neue Swift-Dateien, eine vollständig funktionsfähige TV-App, in ungefähr 3 Stunden agentengestützter Arbeit. Meiner Einschätzung nach übernahm der Agent etwa 80 % der Implementierungsarbeit; ich erledigte die Teile, die Interaktion mit der Xcode-UI erforderten (Berechtigungen, Target-Einrichtung, Capability-Flags), sowie manuelles Fokustesten auf einem echten Apple TV. Vergleichbare Soloarbeit in dieser Codebasis — basierend auf ähnlichen Funktionen, die ich ohne Agenten ausgeliefert habe — wäre ein mehrtägiger Aufwand gewesen.

Fallstudie 2: Metal-Shader-Debugging in amp97 (teilweiser Fehlschlag)

Die Aufgabe: Dem Oszilloskop-Shader ein energiebasiertes Intensitätssystem hinzufügen. Die Visualisierung sollte mit der Audioenergie pulsieren.

Was passiert ist: 1. Der Agent schrieb eine gültige Metal-Shader-Änderung, die ein uEnergy-Uniform und HDR-Tonemapping hinzufügte 2. Der Code kompilierte fehlerfrei 3. Auf dem Gerät war die Visualisierung vollständig weiß — der Intensitätskoeffizient war 10-mal zu hoch (3,5 statt 0,30) 4. Der Agent konnte den weißen Bildschirm nicht sehen und hatte deshalb kein Feedbacksignal 5. Ich erkannte das Problem visuell und bat den Agenten, den Koeffizienten zu reduzieren 6. Der Agent reduzierte ihn, aber die gesamte Energy-State-Machine war zu komplex und beschädigte den Visualizer auf andere Weise 7. Komplett zurückgesetzt — zwei Commits (67959ed und cda4830) in 869d914 revertet

Die Lektion: Metal-Shader sind der schwierigste Bereich für agentengestützte Entwicklung, weil die Feedbackschleife unterbrochen ist. Der Agent kann Syntax (kompiliert) und Semantik (korrekte Typen) prüfen, aber nicht die Ausgabe (sieht richtig aus). Jede Shader-Änderung, die visuelles Verhalten verändert, erfordert menschliche Prüfung auf dem Gerät.

Was ich danach zu 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 auf V2 migrieren, mit einem neuen Feld quantity für GroceryItem und einem neuen Category-Modell mit Beziehungen.

Was der Agent getan hat: 1. Die vorhandenen V1-Modelldefinitionen gelesen 2. V2-Modelldefinitionen mit den neuen Feldern und Beziehungen erstellt 3. Einen GroceryMigrationPlan mit Konformität zum SchemaMigrationPlan-Protokoll geschrieben 4. Die Migrationsstufe V1toV2 implementiert: Standardwert quantity: 1 und category: nil hinzugefügt 5. Alle Views aktualisiert, um die neuen Felder zu unterstützen 6. SampleData.swift für Previews aktualisiert 7. Per MCP gebaut und Tests ausgeführt — alle bestanden 8. 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 umfassend vertreten ist. Die CLAUDE.md dokumentierte das V1-Modell explizit, sodass der Agent verstand, wovon migriert wurde.

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

Die Aufgabe: Geräteübergreifendes Logging von Meditationssitzungen implementieren. Sitzungen, die auf Apple TV oder Mac abgeschlossen werden, sollten zur HealthKit-Protokollierung auf das iPhone synchronisiert werden.

Was der Agent geliefert hat:

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

Der Agent: 1. Erstellte das Datenmodell MeditationSession mit UUID, Datumswerten, Dauer, Quellgerät und HealthKit-Synchronisierungsstatus 2. Baute ein SessionStore-Singleton, das NSUbiquitousKeyValueStore für iCloud-Synchronisierung verwaltet 3. Implementierte die Konfliktauflösung beim Zusammenführen (UUID-basierte Deduplizierung) 4. Fügte SessionHistoryView mit plattformspezifischen Anpassungen hinzu (Swipe-to-Delete auf iOS, fokusbasiert auf tvOS) 5. Verdrahtete die iPhone-seitige HealthKit-Synchronisierung für Sitzungen von anderen Geräten

Was Iteration erforderte: Die erste Implementierung behandelte den Fall nicht, in dem die iPhone-App im Hintergrund startet (keine Foreground-Benachrichtigung für die Synchronisierung). Der Agent brauchte konkrete Anleitung: “Use NSUbiquitousKeyValueStore.didChangeExternallyNotification to trigger sync on background KV changes.” Nach diesem Hinweis war die Implementierung korrekt.

Die Lektion: Agenten bewältigen plattformübergreifende Architekturmuster gut, wenn die Architektur klar beschrieben ist. Das iCloud-Synchronisierungsmuster ist nicht trivial, folgt aber einem dokumentierten Apple-Muster, das der Agent verstanden hat. Der Grenzfall (Hintergrundsynchronisierung) erforderte menschliches Domänenwissen, weil er nicht gut dokumentiert ist.

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

Die Aufgabe: Game Center-Leaderboards und Achievements zum Weltraum-Shooter hinzufügen.

Was der Agent gut gemacht hat: - GKLocalPlayer.local.authenticateHandler im App-Einstiegspunkt implementiert - Einen GameCenterManager mit Methoden zum Einreichen von Scores und Melden von Achievements erstellt - Vor allen Game Center-Operationen eine Prüfung des Authentifizierungsstatus hinzugefügt - Den Offline-Fall elegant behandelt (das Spiel läuft ohne Game Center und reicht Daten ein, sobald die Verbindung wiederhergestellt ist) - Achievement-Definitionen erstellt, die zum Fortschrittssystem mit 8 Schiffen passen

Was manuelle Arbeit erforderte: - Leaderboards und Achievements in App Store Connect erstellen (Webportal, für den Agenten nicht zugänglich) - Die Game Center-Berechtigung in Xcode konfigurieren - Mit einem Sandbox-Game Center-Konto testen (erfordert manuelle Anmeldung auf dem Gerät)

Projektlebenszyklus mit Agents

Ein neues iOS-Projekt starten

Der optimale Workflow, um ein neues Projekt mit Agentenunterstützung zu starten:

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

Phase 2: Implementierung durch den Agent (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-Schleife über MCP (autonom)

Phase 3: Menschliche Integration (30-60 Minuten) 1. Fügen Sie die vom Agent erstellten Dateien zu Xcode Targets hinzu 2. Prüfen Sie Signing und Entitlements 3. Testen Sie auf einem physischen Gerät 4. Überprüfen Sie visuelles Layout und 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 Agent skaliert damit, wie gut Ihre CLAUDE.md den aktuellen Projektstand widerspiegelt. Aktualisieren Sie Ihre CLAUDE.md, wenn Sie wichtige neue Funktionen hinzufügen, Architekturmuster ändern oder neue Frameworks einführen.

Wann Sie den Agent einbeziehen sollten und wann nicht

Agent-Definitionen konfigurieren

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

---
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 Agent mit @ios-developer in Claude Code-Sitzungen.

Testmuster für agentenunterstütztes iOS

Agents schreiben hervorragende Unit Tests, wenn sie klare Vorgaben bekommen. Diese Muster liefern die besten Ergebnisse.

Organisation von 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 Agent eine Checkliste. Der Verweis auf eine vorhandene Testdatei etabliert das Muster. Die Vorgabe zur Verwendung von setUp() verhindert, dass der Agent verschachtelten Testzustand erzeugt.

Ineffektiver Test-Prompt:

Write tests for TimerManager.

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

Async-Testmuster

Für das 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 Agents erinnert werden müssen: - @MainActor bei Testmethoden, die @MainActor-Klassen testen - async throws für Tests, die Task.sleep oder asynchrone Operationen verwenden - Toleranz bei zeitbasierten Assertions (1,1 Sekunden, nicht exakt 1,0) - Sauberes setUp() / tearDown() zur Testisolation

Snapshot Testing

Zur Erkennung visueller Regressionen sollten Sie swift-snapshot-testing in Betracht ziehen:

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.

Agents richten Snapshot Tests korrekt ein, können die Referenzbilder aber nicht beurteilen. Sie prüfen die initialen Snapshots; anschließend erkennen die Tests des Agent visuelle Regressionen bei künftigen Änderungen.

Kontextfenster-Management für iOS-Projekte

Das 1M-Kontextfenster (Opus 4.6) ist groß, aber nicht unbegrenzt. Bei iOS-Projekten gibt es spezifische Aspekte für das Kontextmanagement.

Token-Kosten von iOS-Dateien

Bei einem Projekt mit 50 Dateien: Das Lesen aller Dateien verbraucht etwa 50.000-100.000 Token und liegt damit deutlich innerhalb des 1M-Fensters. Der Agent kann das gesamte Projekt im Kontext halten.

Bei einem Projekt mit 100+ Dateien: Selektives Lesen wird notwendig. Der Agent liest zuerst CLAUDE.md (wegen der Anmerkungen zur Dateistruktur) und anschließend bei Bedarf bestimmte Dateien. Deshalb sind Dateianmerkungen in CLAUDE.md entscheidend: Sie führen den Agenten zu den richtigen Dateien, ohne dass er alles lesen muss.

Strategien für große Projekte

1. Detaillierte Dateianmerkungen in CLAUDE.md — Der Agent liest die Dateikarte und navigiert direkt zu relevanten Dateien
2. Subagent-Delegation — Lagern Sie Exploration und Recherche an Subagents aus (sauberer Kontext, Rückgabe von Zusammenfassungen)
3. Fokussierte Prompts — “Modify SettingsView.swift to add a new toggle” ist besser als “update the settings”
4. Sitzungsgrenzen — Starten Sie für nicht zusammenhängende Funktionen neue Sitzungen, statt eine lange Sitzung weiter auszudehnen
5. /compact verwenden — Der Komprimierungsbefehl von Claude Code fasst die Unterhaltung zusammen und gibt Kontext frei

Token-Effizienz von MCP

Eines der stärksten Argumente für MCP: Strukturierte JSON responses verbrauchen deutlich weniger Token als rohe xcodebuild-Ausgaben.

In einer typischen Entwicklungssitzung mit 10-20 Build-Zyklen spart MCP gegenüber rohem xcodebuild 30.000-150.000 Token. Diese Token bleiben für tatsächliches Code-Reasoning verfügbar.

Fehlerbehebung

“build_sim failed — scheme not found”

Der Agent rät den Scheme-Namen. So beheben Sie das Problem:

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

Oder fügen Sie den Scheme-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. Falls Sie Xcode 26.3+ haben, der Befehl aber weiterhin fehlschlägt:

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

# Verify
xcrun mcpbridge --help

“MCP tools not appearing in Claude Code”

Während einer 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

Überprüfen Sie anschließend:

You: List all available MCP tools from XcodeBuildMCP.

“Agent keeps using xcodebuild via Bash instead of MCP”

Der Agent entdeckt die MCP tools nicht über Tool Search. Zwei Lösungen:

1. Explizite Anleitung zu CLAUDE.md hinzufügen (siehe Dem Agenten beibringen, MCP zu verwenden)
2. Direkt prompten: “Use the build_sim MCP tool, not xcodebuild via Bash”

“Build succeeds but agent reports failure”

XcodeBuildMCP parst xcodebuild-Ausgaben. 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 Statusfeld in der MCP response.

“Simulator hangs during boot”

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 tried to modify .pbxproj despite CLAUDE.md rules”

CLAUDE.md-Regeln sind Empfehlungen. Hooks setzen sie durch. Wenn Sie keinen PreToolUse hook haben, der Schreibzugriffe auf .pbxproj 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: „Das geht nicht.”

Häufig gestellte Fragen

Mit welcher Agent-Runtime sollte ich anfangen?

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 Arbeitskontext halten kann. Fangen Sie damit an und ergänzen Sie später Codex für Reviews sowie native Xcode-Agents für schnelle Inline-Änderungen, sobald Ihr Workflow reifer wird.

Brauche ich beide MCP-Server?

Für die meisten Entwickler deckt XcodeBuildMCP allein 90 % der Anforderungen ab (Builds, Tests, Simulatoren, Debugging). Ergänzen Sie Apples Xcode MCP, wenn Sie Dokumentationssuche, Swift REPL-Verifizierung oder SwiftUI-Preview-Rendering benötigen. Sie können ihn jederzeit später hinzufügen; die beiden Server sind unabhängig voneinander.

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

XcodeBuildMCP enthält ein create_project-Tool, das neue Xcode-Projekte scaffolding-artig anlegt. Für Produktions-Apps empfehle ich allerdings, das Projekt in Xcode zu erstellen (damit Signing, Capabilities und Target-Konfiguration korrekt sind) und anschließend Agents für die gesamte Codeimplementierung zu nutzen. Die 5 Minuten im Assistenten für neue Xcode-Projekte sparen Stunden an Problemen mit agentengenerierter Projektkonfiguration.

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

Gut. Package.swift ist eine normale Swift-Datei, die Agents zuverlässig lesen und bearbeiten können. Abhängigkeiten hinzufügen, Versionsbereiche aktualisieren und Targets konfigurieren funktioniert alles. Die Einschränkung liegt beim .xcodeproj-basierten Abhängigkeitsmanagement (Xcodes UI zur Paketauflösung): Das wird von Xcode verwaltet und sollte nicht von Agents bearbeitet werden.

Können Agents Apps im App Store einreichen?

Nein. Die App Store-Einreichung umfasst Xcodes Organizer, Provisioning Profiles, Screenshots, Metadaten und das App Store Connect-Portal. Nichts davon ist über MCP oder Command-Line-Tools so zugänglich, dass Agents sinnvoll damit arbeiten könnten. Agents übernehmen alles bis zum Archive: Implementierung, Tests, Fehlerbehebung und Dokumentation. Der letzte Schritt der Einreichung bleibt menschlich.

Agents können jedoch bei App Store-Metadaten helfen. Bitten Sie den Agent, basierend auf den letzten Änderungen die App-Beschreibung, Keywords und den „What’s New“-Text zu schreiben. Das ist Textgenerierung, in der Agents stark sind.

Wie gehe ich bei agentengestützter iOS-Entwicklung mit Secrets und API-Schlüsseln um?

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

1. Verwenden Sie .xcconfig-Dateien für umgebungsspezifische Konfiguration
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 aufzunehmen

## 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 Schlüssel existieren und wo sie verwendet werden, sieht aber nie die tatsächlichen Werte.

Was ist mit SwiftUI-Animationen: Können Agents diese schreiben?

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

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

Ineffektiv: „Sorgen Sie dafür, dass sich die Timer-Animation zufriedenstellend anfühlt.“ (Subjektiv, erfordert visuelles Feintuning.)

Wie gehen Agents mit Error-Handling-Mustern um?

Sehr gut. Agents verstehen Swifts Muster mit do/catch, Result und async throws:

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

Agents erzeugen strukturiertes Error Handling mit passenden benutzerseitigen Meldungen. Manchmal behandeln sie Fehler zu breit (sie fangen Exceptions ab, die weitergereicht werden sollten), deshalb sollten Sie die Catch-Blöcke prüfen.

Kann ich Agents für die Accessibility-Implementierung nutzen?

Teilweise. Agents fügen Accessibility-Labels, Hinweise 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 Agents nicht können: verifizieren, ob die VoiceOver-Navigationsreihenfolge stimmt, Dynamic Type-Skalierung testen oder Farbkontrastverhältnisse bewerten. Verwenden Sie zur Verifizierung Xcodes Accessibility Inspector.

Wie gehen Agents mit Core Data-Migration um (wenn kein SwiftData verwendet wird)?

Agents schreiben Core Data-Migrationsmappings und Modellversionen, aber die manuellen Xcode-Schritte (neue Modellversionen erstellen, 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 Model Versions
- V1: Initial (GroceryList, GroceryItem)
- V2: Added Category model (current)
- Migration: Lightweight automatic for V1→V2

Wie gehen Agents mit SwiftUI-Previews um?

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

Für die visuelle Verifizierung von Previews müssen Sie Xcode weiterhin geöffnet haben.

Was ist mit visionOS und Apple Vision Pro?

Dieselben Muster gelten auch hier. XcodeBuildMCP unterstützt visionOS-Simulatoren, und die Architekturpatterns (@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ß darf ein Projekt sein, bevor Agents Schwierigkeiten bekommen?

Die Größe des Kontextfensters ist der begrenzende Faktor. Mit Opus 4.6s 1M-Token-Fenster kann Claude Code ungefähr 50-70 Swift-Dateien gleichzeitig im aktiven Arbeitskontext halten. Bei größeren Projekten nutzt der Agent Dateisuche und selektives Lesen, um mit Teilbereichen der Codebasis zu arbeiten. Projekte mit mehr als 100 Dateien funktionieren gut; der Agent liest Dateien nur bei Bedarf, statt alles im Kontext zu halten.

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

Muss ich Swift können, um Agents für iOS-Entwicklung zu nutzen?

Sie müssen Agent-Ausgaben prüfen und Architekturentscheidungen treffen können. Sie müssen nicht jede Zeile selbst schreiben, aber Swift gut genug verstehen, um falsche Entscheidungen des Agents zu erkennen, besonders bei Concurrency, Speicherverwaltung und framework-spezifischen Patterns. Ein Agent ist ein 10x-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 kostet der Einsatz von Agents für iOS-Entwicklung?

Mit Anthropic’s Max-Plan (Opus 4.6, 1M Kontext) dauert eine typische iOS-Entwicklungssitzung 30-120 Minuten und verarbeitet 200K-800K Tokens. MCP-Tool-Aufrufe erzeugen nur minimalen Overhead (strukturierte JSON-Antworten sind im Vergleich zu rohem Build-Output token-effizient). Die Kosten sind vergleichbar mit dem Einsatz von Claude Code für jede andere Codebasis; iOS-Entwicklung ist nicht wesentlich teurer oder günstiger als Webentwicklung.

Kann ich Agents mit UIKit-Projekten nutzen?

Ja, aber mit SwiftUI sind Agents effektiver. UIKit erfordert mehr Boilerplate, hat weniger deklarative Struktur und umfasst oft Interface Builder-Dateien, die Agents nicht bearbeiten können. Wenn Sie ein UIKit-Projekt haben, nutzen Sie Agents für die Model-Schicht und Businesslogik, während Sie die UI manuell bearbeiten, oder migrieren Sie Views schrittweise zu SwiftUI.

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 liefern und Konsistenz über Sprachen hinweg wahren. Das strukturierte JSON-Format von .xcstrings-Dateien ist agentenfreundlich. Auch mit .strings-Dateien (Legacy-Format) kommen Agents gut zurecht; das Key-Value-Format ist unkompliziert.

Häufige Agent-Fehler in iOS (und wie Sie sie verhindern)

Das sind die wiederkehrenden Fehler, die ich über Tausende Agent-Interaktionen in 8 iOS-Projekten hinweg beobachtet habe. Für jeden gibt es eine Präventionsstrategie.

Fehler 1: Observable-Patterns vermischen

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: Retain Cycles in Closures erzeugen

Was passiert: Der Agent erstellt Closures, die self stark referenzieren, insbesondere in Timer.publish, NotificationCenter und Completion Handlers.

Prävention: Nehmen Sie ein Closure-Pattern in CLAUDE.md auf:

## 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: @MainActor-Anforderungen ignorieren

Was passiert: Der Agent erstellt @Observable-Klassen ohne @MainActor-Isolation, was Swift 6.2-Concurrency-Warnungen oder Runtime-Abstürze verursacht, wenn UI-Updates außerhalb des Main Threads passieren.

Prävention:

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

Fehler 4: NavigationLink mit Destination Closure verwenden

Was passiert: Der Agent verwendet das veraltete NavigationLink(destination:label:) statt des typsicheren Patterns 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: Simulator-Namen hartcodieren

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

Prävention: MCP übernimmt das — list_sims findet 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: Dateien in falschen Verzeichnissen erstellen

Was passiert: Der Agent erstellt eine neue View-Datei im Projektwurzelverzeichnis statt im Unterverzeichnis Views/ oder legt ein Model in der falschen Gruppe ab.

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

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

Fehler 7: Plattformverfügbarkeit nicht behandeln

Was passiert: Der Agent verwendet HealthKit in gemeinsam genutztem 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: Einfache Funktionen überentwickeln

Was passiert: Der Agent erstellt ein Protokoll, eine Protokollerweiterung, eine konkrete Implementierung, eine Factory und einen Dependency-Injection-Container für etwas, das eine 20-zeilige Hilfsfunktion sein sollte.

Prävention: Nehmen Sie ein Einfachheitsprinzip auf:

## 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 Veröffentlichung von 8 iOS-Apps mit AI Agents lautet die Zusammenfassung:

Agents haben verändert: Implementierungsgeschwindigkeit. Was früher Tage dauerte, dauert Stunden. SwiftUI-Views, SwiftData-Models, Unit Tests, Refactoring — diese Arbeit wird inzwischen überwiegend von Agents erstellt und von Menschen geprüft.

Agents haben nicht verändert: Architekturentscheidungen, visuelles Design, Performance-Optimierung oder App Store-Einreichung. Das bleibt menschengesteuert.

Der Multiplikator ist real, aber begrenzt. Meine subjektive Schätzung über das Portfolio aus 8 Apps hinweg: 3- bis 5-fache Verbesserung der Time-to-Feature bei gut dokumentierten Projekten mit richtiger MCP- und Hook-Konfiguration. Das wurde nicht gegen eine Kontrollgruppe gemessen; es ist ein Wall-Clock-Vergleich zwischen Agent-unterstützten Funktionen und entsprechender Solo-Arbeit in denselben Codebases. 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: Zeit für CLAUDE.md, Hooks und MCP-Konfiguration. Jede Stunde Einrichtung spart viele Stunden, die Sie sonst mit dem Korrigieren von Agent-Fehlern verbringen würden. Die Konfiguration ist das Produkt — der Agent ist die Ausführungsmaschine.

Was mich überrascht hat: Wie stark die MCP-Server die Dynamik verändert haben. Vor MCP waren Agents anspruchsvolle Texteditoren, die zufällig Swift verstanden. Nach MCP sind sie Entwicklungspartner, die schreiben, bauen, testen, debuggen und iterieren. Die strukturierte Feedbackschleife macht den Unterschied zwischen einem Agent, 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), richten Sie MCP und Hooks richtig ein, schreiben Sie eine gründliche CLAUDE.md und skalieren Sie die Patterns anschließend auf größere Projekte. Starten Sie nicht mit der plattformübergreifenden App mit 63 Dateien. Die Infrastrukturinvestition ist unabhängig von der Projektgröße gleich — machen Sie es einmal in einem kleinen Projekt und kopieren Sie es dann in alles andere.

Die Zukunft: Die native Agent-Integration von Xcode 26.3 ist der Anfang, nicht das Ende. Dass Apple MCP-Support ausliefert, bedeutet, dass sich die Toolchain in Richtung Agent-First-Entwicklung bewegt. Entwickler, die jetzt in Agent-kompatible Projektstrukturen investieren — saubere CLAUDE.md-Dateien, testbare Architekturen, automatisierte Hooks — werden diese Investition mit jeder Verbesserung der Tools weiter verzinsen.

Kurzreferenz

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)

Änderungsprotokoll

Referenzen