iOS-Apps mit KI-Agenten entwickeln: Der Praxisleitfaden

TL;DR: Drei Agent-Laufzeitumgebungen generieren mittlerweile Code für iOS: Claude Code CLI mit MCP, Codex CLI mit MCP und die nativen Intelligence-Agents von Xcode 26.3. Zwei MCP-Server (XcodeBuildMCP mit 59 Tools und Apples xcrun mcpbridge mit 20 Tools) gewähren Agents strukturierten Zugriff auf Builds, Tests, Simulatoren und Debugging. Dieser Leitfaden behandelt reale CLAUDE.md-Muster, Hook-Konfigurationen und ehrliche Einschätzungen, was funktioniert und was scheitert — basierend auf 8 produktiven iOS-Apps mit insgesamt 293 Swift-Dateien. Agents glänzen bei SwiftUI-Views, SwiftData-Modellen, Refactoring und Build-Fehlerdiagnose. Sie versagen bei .pbxproj-Änderungen, Code-Signing und visuellem Debugging. Die Kluft zwischen „Agent schreibt Swift” und „Agent veröffentlicht eine iOS-App” wird durch Konfiguration überbrückt, nicht durch Prompting.

Ich entwickle 8 iOS-Apps mit KI-gestützten Coding-Agents. Keine Prototypen — Apps im App Store, mit HealthKit-Integrationen, Metal-Shadern, SpriteKit-Physik, iCloud-Sync, 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 Agent geschrieben und von mir überprüft oder von mir geschrieben und von einem Agent refaktorisiert. Nach meiner Schätzung liegt das Verhältnis bei etwa 85/15 zugunsten des Agents.

Dieser Leitfaden ist die Referenz, die ich mir gewünscht hätte, als ich anfing. Er deckt den gesamten Stack ab: welche Agent-Laufzeitumgebung Sie verwenden sollten, wie Sie MCP-Server für strukturierten Build-Zugriff konfigurieren, was in Ihre CLAUDE.md gehört, welche Hooks den Agent daran hindern, Ihr Xcode-Projekt zu zerstören, und — ganz entscheidend — wo Agents scheitern und Sie selbst eingreifen müssen.

Wichtigste Erkenntnisse

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

• Beginnen Sie mit Claude Code CLI + XcodeBuildMCP. Es ist die ausgereifteste Laufzeitumgebung mit der umfassendsten MCP-Tool-Abdeckung. Installieren Sie zwei Befehle, fügen Sie Ihrem Projekt eine CLAUDE.md hinzu, und der Agent kann bauen, testen und debuggen, ohne dass Sie Fehlermeldungen kopieren müssen.
• Lassen Sie niemals einen Agent .pbxproj modifizieren. Dies ist die wichtigste Regel überhaupt. Ein PreToolUse-Hook, der Schreibzugriffe auf .pbxproj und .xcodeproj/ blockiert, erspart Ihnen stundenlange Wiederherstellungsarbeit.
• Ihre CLAUDE.md ist das Onboarding-Dokument des Agents. Jede Stunde, die Sie in die CLAUDE.md investieren, spart zehn Stunden Korrektur von Agent-Fehlern.

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

• MCP transformiert den iOS-Build-Zyklus. Vor MCP schrieben Agents Swift, konnten aber nicht verifizieren, ob es kompilierte. Mit XcodeBuildMCP schreibt der Agent Code, baut ihn, liest strukturierte Fehler, behebt sie und führt Tests durch — vollständig autonom.
• Drei Laufzeitumgebungen für unterschiedliche Anforderungen. Claude Code CLI für tiefgreifende agentische Sitzungen, Codex CLI für kopflose Stapelverarbeitung, native Xcode-26.3-Agents für schnelle Inline-Korrekturen ohne die IDE zu verlassen.
• Hook-Infrastruktur lässt sich übertragen. Ihre bestehenden PostToolUse-Formatter, PreToolUse-Blocker und Test-Runner-Hooks funktionieren bei iOS-Projekten identisch — mit geringfügigen Pfadanpassungen.

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

• Die Effektivität von Agents skaliert mit der Projektdokumentation, nicht mit der Projektgröße. Eine App mit 63 Dateien und detaillierter CLAUDE.md liefert bessere Agent-Ergebnisse als eine App mit 14 Dateien ohne Dokumentation.
• Die .pbxproj-Grenze ist nicht verhandelbar. Agents können Xcode-Projektdateien nicht zuverlässig bearbeiten. Ihr Workflow muss das manuelle Hinzufügen von Dateien zu Xcode-Targets berücksichtigen.
• Ehrliche ROI: Agents bewältigen 70–80 % der Implementierungsarbeit. Die verbleibenden 20–30 % — visueller Feinschliff, Signing, Performance-Optimierung, App-Store-Einreichung — erfordern menschliches Urteilsvermögen.

Wählen Sie Ihren Einstieg

So nutzen Sie diesen Leitfaden

Dies ist eine Referenz mit über 3.000 Zeilen. Steigen Sie dort ein, wo Ihr Erfahrungsniveau passt:

Inhaltsverzeichnis

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

Verwandte Ressourcen

Das Portfolio: 8 Apps, 293 Dateien

Bevor wir in die Konfiguration eintauchen, hier die Grundlage dieses Leitfadens. Es handelt sich nicht um Spielzeugprojekte — sie umfassen fünf Apple-Frameworks, drei Plattformen und das gesamte Spektrum an iOS-Komplexität, von einem 14-Dateien-Workout-Tracker bis hin zu einem 63-Dateien-Meditations-Timer für mehrere Plattformen.

Warum die Dateizahlen wichtig sind: Die Effektivität eines Agenten korreliert mit der Lesbarkeit des Projekts, nicht mit dessen Größe. Return (63 Dateien) erzeugt bessere Agentenergebnisse als amp97 (41 Dateien), weil Return eine detaillierte CLAUDE.md mit Dateiannotationen, Architekturdiagrammen und expliziten Mustern besitzt. Die Metal-Shader von amp97 sind für Agenten unabhängig von der Dokumentationsqualität grundsätzlich schwerer zu verarbeiten.

Voraussetzungen

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

Erforderlich: - macOS 15+ (Sequoia) oder macOS Tahoe - Xcode 26.3+ installiert und konfiguriert (Lizenzvereinbarung akzeptiert, Plattformen heruntergeladen) - Mindestens eine iOS-Simulator-Laufzeitumgebung installiert - Ein Anthropic-API-Konto (für Claude Code) oder ein OpenAI-Konto (für Codex)

Empfohlen: - SwiftFormat installiert (brew install swiftformat) — wird von Format-beim-Speichern-Hooks verwendet - SwiftLint installiert (brew install swiftlint) — optional, aber nützlich zur Durchsetzung von Stilrichtlinien - Vertrautheit mit dem Terminal — alle drei Laufzeitumgebungen arbeiten über die Kommandozeile oder sind mit ihr integriert

Überprüfen Sie Ihre Xcode-Installation:

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

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

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

Falls xcrun mcpbridge die Meldung „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 Agenten-Laufzeitumgebungen für iOS

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

1. Claude Code CLI

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

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

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

Ideal für: Tiefgehende Implementierungssitzungen — Entwicklung neuer Funktionen, dateiübergreifendes Refactoring, Debugging komplexer Probleme und autonome Build-Test-Fix-Schleifen. Das 1M-Token-Kontextfenster von Claude Code (mit Opus 4.6) ermöglicht es dem Agenten, die meisten kleinen bis mittelgroßen iOS-Projekte im Arbeitsspeicher zu halten — erfahrungsgemäß 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-Fehler-Fix-Schleife läuft autonom.

2. Codex CLI

Was es ist: OpenAIs terminalbasierter Programmier-Agent. Im Konzept ä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

Ideal für: Headless-Batch-Operationen, CI/CD-Integration und Aufgaben, bei denen Sie eine zweite Meinung von einer anderen Modellfamilie einholen möchten. Der Sandbox-Modus von Codex führt Code in isolierten Umgebungen aus, was bei destruktiven Operationen wie Testdurchläufen mit Zustandsänderungen nützlich ist.

Wesentliche Unterschiede zu Claude Code: - Verwendet OpenAI-Modelle anstelle von Claude-Modellen - Unterschiedliche Kontextfenstergrößen und Token-Kosten - Sandbox-orientiertes 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 Ereignistypen und kein bedingtes if-Feld

Wann Sie Codex statt Claude Code für iOS verwenden sollten:

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

3. Native Agenten in Xcode 26.3

Was es ist: Apple hat KI-Programmier-Agenten direkt in Xcodes Intelligence-Panel integriert. Ab Xcode 26.3 können Sie Claude Agent und Codex als Intelligence-Anbieter unter Xcode-Einstellungen > Intelligence konfigurieren.

Einrichtung:

1. Öffnen Sie Xcode 26.3+
2. Navigieren Sie zu Einstellungen > Intelligence
3. Fügen Sie einen neuen Anbieter 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

Ideal für: Schnelle Inline-Bearbeitungen, Code-Vervollständigung mit agentenbasiertem Reasoning und Entwickler, die Xcode nicht verlassen möchten. Durch die native Integration hat der Agent direkten Zugriff auf Xcodes Projektkontext — geöffnete Dateien, Build-Targets, Scheme-Konfiguration — ohne MCP-Bridging.

Einschränkungen gegenüber CLI-Agenten: - Kein Hook-System — Sie können weder Format-beim-Speichern noch das Blockieren von .pbxproj-Schreibvorgängen erzwingen - Kein CLAUDE.md-Laden — der Agent liest keine projektspezifischen Konfigurationsdateien - Eingeschränkte Autonomie — der Agent arbeitet mit der aktuellen Datei oder Auswahl, nicht projektübergreifend - Keine Subagenten-Delegation — komplexe mehrstufige Aufgaben können nicht parallelisiert werden - Keine MCP-Server-Konfiguration — der Agent nutzt ausschließlich Xcodes eingebaute Werkzeuge

Wann Sie native Xcode-Agenten verwenden sollten:

Für schnelle, begrenzte Bearbeitungen, bei denen der Wechsel zum Terminal unnötigen Aufwand bedeutet. „Füge eine berechnete Eigenschaft zu diesem Modell hinzu.” „Schreibe einen Unit-Test für diese Funktion.” „Refaktorisiere diese View zur Verwendung von @Observable.” Aufgaben, die eine oder zwei Dateien betreffen und keinen Build-Test-Zyklus erfordern.

Für alles, was Kompilieren, Testen, dateiübergreifendes Refactoring oder autonome Fehlerkorrektur erfordert, verwenden Sie einen CLI-Agenten mit MCP.

Vergleichsmatrix der Laufzeitumgebungen

Die Empfehlung: Verwenden Sie Claude Code CLI als primäre Laufzeitumgebung. Nutzen Sie native Xcode-26.3-Agenten für schnelle Inline-Bearbeitungen. Setzen Sie Codex CLI für Review-Durchläufe und Batch-Operationen ein. Die drei ergänzen sich, statt miteinander zu konkurrieren.

MCP-Setup: Die vollständige Konfiguration

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

XcodeBuildMCP: 59 Tools für kopflose iOS-Entwicklung

XcodeBuildMCP kapselt xcodebuild, xcrun simctl und LLDB in 59 strukturierte MCP-Tools. Es funktioniert ohne laufendes Xcode — der gesamte Build-Test-Debug-Zyklus läuft kopflos über Apples Kommandozeilentools.

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 -s user-Flag macht den Server global über alle Projekte verfügbar. Lassen Sie es weg für eine projektbezogene Installation (sinnvoll, wenn Sie MCP nur in iOS-Projekten benötigen, nicht in Web-Projekten).

Die Umgebungsvariable -e XCODEBUILDMCP_SENTRY_DISABLED=true deaktiviert die Absturzbericht-Telemetrie. XcodeBuildMCP enthält standardmäßig Sentry, das Fehlerdaten einschließlich Dateipfaden sendet. Deaktivieren Sie dies, sofern Sie nicht zur Diagnose des Projekts beitragen möchten.¹

Vollständiges Tool-Inventar (59 Tools in 8 Kategorien):

Die wichtigsten Tools für den täglichen Einsatz:

1. build_sim — Dieses Tool werden Sie hundertfach aufrufen. Es liefert JSON mit Fehlern, kategorisiert nach Datei, Zeile und Schweregrad. Der Agent liest den Fehler, navigiert zur Datei und behebt ihn, ohne dass Sie eingreifen müssen.

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

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

4. discover_projs + list_schemes — Projektintrospektion. Der Agent muss weder Ihren Scheme-Namen noch Ihre Workspace-Struktur erraten.

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

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

Apples MCP-Server wird mit Xcode 26.3 über xcrun mcpbridge ausgeliefert. Er kommuniziert mit einem laufenden Xcode-Prozess über XPC (Apples Framework für Interprozesskommunikation) und legt internen Zustand offen, 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. Ist Xcode nicht geöffnet, schlagen alle MCP-Aufrufe über diesen Server fehl oder hängen sich auf. XcodeBuildMCP hat diese Einschränkung nicht.

Tool-Inventar (20 Tools in 5 Kategorien):

Tools, die exklusiv in Apple MCP verfügbar sind (nicht in XcodeBuildMCP):

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

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

3. RenderPreview — Rendert SwiftUI-Vorschauen kopflos. Der Agent kann prüfen, ob eine View fehlerfrei rendert, allerdings ohne visuelle Korrektheit beurteilen zu können (das Rendering wird als Daten zurückgegeben, nicht visuell inspiziert).

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

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)    │
│  ┌─────────────────────┐         ┌─────────────────────┐       │
│  │ Eigenständig         │         │ Erfordert Xcode     │       │
│  │ (kein Xcode-Prozess)│         │ (XPC-Bridge)        │       │
│  │                     │         │                     │       │
│  │ ✓ Simulatoren       │  BEIDE  │ ✓ Dokumentation     │       │
│  │ ✓ Reale Geräte      │ ┌─────┐ │ ✓ Swift REPL        │       │
│  │ ✓ LLDB-Debugging    │ │Build│ │ ✓ SwiftUI-Vorschau  │       │
│  │ ✓ UI-Automatisierung│ │Test │ │ ✓ Live-Diagnosen    │       │
│  │ ✓ Projektgerüst     │ └─────┘ │ ✓ Analyzer-Probleme │       │
│  │ ✓ Screenshot        │         │                     │       │
│  └─────────────────────┘         └─────────────────────┘       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

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

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

In der Praxis: Ich nutze XcodeBuildMCP für ca. 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, da es schneller (kein Xcode-Prozess-Overhead) und zuverlässiger (keine XPC-Abhängigkeit) ist.

Verifizierung

Nach der Installation beider Server überprüfen Sie die Verbindung:

# List all configured MCP servers
claude mcp list

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

Falls ein Server als „Disconnected” angezeigt wird oder nicht erscheint:

1. XcodeBuildMCP verbindet nicht: Stellen Sie sicher, dass Node.js installiert ist (node --version). Der npx-Befehl erfordert Node.js 18+.
2. Apple Xcode MCP verbindet 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 werden möglicherweise erst nach einem Neustart angezeigt.

Dem Agenten die Nutzung von MCP beibringen

Die Installation von MCP-Servern ist notwendig, aber nicht ausreichend. Ohne explizite Anleitung greift der Agent möglicherweise auf xcodebuild über Bash zurück (unstrukturierte Ausgabe, verschwendete Kontext-Token) oder nutzt die Websuche für Apple-Dokumentation (langsamer, weniger zuverlässig).

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

## Build & Test — Immer MCP verwenden

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

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

MCP liefert strukturiertes JSON. Bash liefert unstrukturierten Text.
Strukturierte Daten bedeuten weniger verbrauchte Token und bessere Fehlerdiagnose.

Diese Anleitung stellt sicher, dass der Agent zuerst zu MCP-Tools greift. Ohne sie werden Sie beobachten, wie der Agent lange xcodebuild-Befehle über Bash konstruiert, Tausende von Kontext-Token beim Parsen der Ausgabe verbraucht und den eigentlichen Fehler manchmal 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 einem neuen Mitarbeiter, der die Architektur-Dokumentation gelesen hat, und einem, der nur rät.

Jedes meiner iOS-Projekte hat eine CLAUDE.md. Hier sind die Muster, die funktionieren, abgeleitet aus allen 8 Apps.

Die wesentlichen Abschnitte

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

1. Projektidentität

# Return - Zen Focus Timer

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

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

2. Dateistruktur mit Zweck-Annotationen

## File Structure

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

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

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

3. Build- und Test-Befehle

## Build & Test

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

Run tests:

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

Run tvOS tests:

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 direkten Befehle trotzdem auf, auch wenn der Agent MCP bevorzugen sollte. Die direkten Befehle dienen als Fallback-Dokumentation und machen Scheme-Namen sowie Zielplattformen explizit.

#### 4. Zentrale Muster und Regeln

```markdown

## Key Patterns

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

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

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

Diese Muster verhindern, dass der Agent Inkonsistenzen einführt. Ohne explizite Muster-Dokumentation wird der Agent manchmal ObservableObject in einer Datei und @Observable in einer anderen verwenden — oder einen neuen Einstellungsmechanismus erstellen, statt den vorhandenen Settings.shared-Singleton zu nutzen.

5. Was der Agent niemals tun darf

## Rules

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

Explizite Verbote sind wirksamer als implizite Erwartungen. Der Agent befolgt negative Einschränkungen zuverlässiger als positive Vorschläge, da sie binär sind (tun / nicht tun) statt heuristisch (bevorzuge dies / verwende manchmal jenes).

6. Framework-spezifischer Kontext

Dieser Abschnitt variiert je nach App. Nehmen Sie ihn für jedes Framework auf, das eine nicht offensichtliche Konfiguration erfordert:

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 kommentiertes Beispiel, das zeigt, wie alle sechs Abschnitte bei einer mittelkomplexen App zusammenwirken. Dies ist das CLAUDE.md-Muster, das ich für Banana List verwende — eine 53-Dateien-Einkaufslisten-App mit iCloud-Synchronisierung und einem eigenen MCP-Server, der die App-Daten für Claude Desktop bereitstellt:

# Banana List - Grocery List App

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

## Core Features

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

## Dateistruktur

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

## SwiftData-Modelle

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

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

Query-Muster

• Listen: @Query(sort: \GroceryList.name) var lists: [GroceryList]
• Aktive Elemente: @Query(filter: #Predicate { !$0.isCompleted })
• Nach Kategorie: In-Memory-Filterung nach dem Abruf (aufgrund von SwiftData-Predicate-Einschränkungen)

Build & Test

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

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

Wichtige Muster

Observable + SwiftData

• SwiftData-@Model-Klassen sind automatisch Observable
• Fügen Sie @Observable NICHT zu @Model-Klassen hinzu (redundant, verursacht Warnungen)
• Verwenden Sie @Bindable für bidirektionale Bindungen an Modelleigenschaften in Formularen
• Verwenden Sie @Query in Views, modelContext.fetch() in Nicht-View-Code

iCloud-Synchronisation

• Automatisch über die SwiftData-CloudKit-Integration
• Konfliktlösung: Last-Write-Wins (CloudKit-Standard)
• Synchronisationsstatus wird über CloudSyncManager.shared.syncState bereitgestellt
• Testen Sie die Synchronisation, indem Sie zwei Simulatoren mit demselben iCloud-Account verwenden

MCP-Serverarchitektur

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

Regeln

• .pbxproj- oder .xcodeproj-Inhalte NIEMALS ändern
• Das Modellschema NIEMALS ändern, ohne SampleData.swift zu aktualisieren
• NIEMALS ObservableObject verwenden — SwiftData-Modelle sind bereits Observable
• NIEMALS @StateObject verwenden — nutzen Sie @State mit @Observable-Klassen
• NIEMALS NavigationView verwenden — immer NavigationStack
• NIEMALS das @Observable-Macro zu @Model-Klassen hinzufügen
• IMMER @Bindable für Formularbindungen an Modelleigenschaften verwenden
• IMMER iCloud-Synchronisationsänderungen auf zwei Simulatorinstanzen testen

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

Bei kleinen Projekten kann die CLAUDE.md knapp gehalten werden. Hier ist das Muster für Reps, einen Workout-Tracker mit 14 Dateien. Beachten Sie, wie selbst eine kurze CLAUDE.md alle sechs wesentlichen Abschnitte abdeckt:

```markdown
# 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 Erstellen dauert 10 Minuten und erspart Stunden an Agent-Verwirrung.

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

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

```markdown
# Starfield Destroyer - Space Shooter

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

## Game Overview

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

## File Structure

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

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)

## Physikkategorien

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

Spielzustandsmaschine

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

Metal-Nachbearbeitung

• Bloom-Shader: BloomShader.metal — Mehrpass-Gaußscher Weichzeichner + additive Überblendung
• Uniforms: PostProcessUniforms { float intensity; float threshold; float2 resolution; }
• Wird nach dem Rendern jedes Frames durch SpriteKit über SKView.presentScene(:transition:) angewendet
• Metal-Shader NICHT ohne Tests auf dem Gerät ändern

Build & Test

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

## Regeln

- NIEMALS .pbxproj modifizieren
- NIEMALS PhysicsCategory-Bitmasks modifizieren (zerstört die gesamte Kollisionserkennung)
- NIEMALS die Z-Reihenfolge der Szenenhierarchie ändern, ohne die Render-Reihenfolge zu verstehen
- NIEMALS ShaderTypes.h modifizieren, ohne sowohl die Swift- als auch die Metal-Referenzen zu aktualisieren
- Neue Gegner durch Ableitung von EnemyShip hinzufügen, nicht durch dessen Modifikation
- Bullet-Pooling: Wiederverwendung über removeFromParent() + erneutes Hinzufügen, niemals neu allozieren
- Game Center: Vor dem Übermitteln von Punktzahlen immer isAuthenticated prüfen

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

Metal-Projekte benötigen den umfangreichsten Framework-spezifischen Kontext, da Agenten visuelle Ausgaben 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 an die Projektgröße anpassen

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

| Projektgröße | CLAUDE.md-Tiefe | Beispiel |
|-------------|----------------|---------|
| **Klein (< 20 Dateien)** | Identität + Dateiliste + Regeln | Reps (14 Dateien): grundlegende SwiftData-Muster, Build-Befehle, Verbote |
| **Mittel (20–40 Dateien)** | + Framework-Kontext + zentrale Muster | TappyColor (30 Dateien): SpriteKit-Szenenhierarchie, Physik-Kategorien, Game Loop |
| **Groß (40+ Dateien)** | + Architekturdiagramme + Beziehungskarten + Multi-Target-Informationen | Return (63 Dateien): plattformübergreifende Architektur, Session-Sync-Diagramm, plattformspezifische Unterschiede |
| **Spezialisiert (Metal/GPU)** | + Pipeline-Diagramme + gemeinsame Typdefinitionen + Buffer-Layouts | amp97 (41 Dateien): Render-Pipeline-Stufen, Uniform-Struct, Buffer-Management |

Die Kosten einer Überdokumentation sind nahezu null (der Agent überspringt, was er nicht benötigt). Die Kosten einer Unterdokumentation hingegen sind hoch (der Agent erfindet Muster, die mit Ihrer Codebasis kollidieren).

### CLAUDE.md-Checkliste

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

- [ ] Bundle-ID und Deployment-Target angegeben
- [ ] Swift-Version und Architekturmuster benannt
- [ ] Dateistruktur mit eingebetteten Zweckbeschreibungen
- [ ] Build-Befehl mit korrektem Scheme und Destination
- [ ] Test-Befehl mit korrektem Scheme und Destination
- [ ] MCP-Präferenz vermerkt („build_sim gegenüber xcodebuild bevorzugen")
- [ ] @Observable-Regel (niemals ObservableObject)
- [ ] NavigationStack-Regel (niemals NavigationView)
- [ ] .pbxproj-Verbot
- [ ] Framework-spezifischer Kontext (HealthKit-Berechtigungen, SwiftData-Beziehungen, SpriteKit-Hierarchie, Metal-Pipeline)
- [ ] Plattformverfügbarkeits-Guards dokumentiert (#if canImport, #if os)
- [ ] Zentrale Singletons und gemeinsame Muster dokumentiert
- [ ] Bekannte Einschränkungen oder Fallstricke vermerkt

---

## Ihre erste Agenten-Sitzung

Mit konfiguriertem MCP und einer CLAUDE.md in Ihrem Projekt folgt hier eine Schritt-für-Schritt-Anleitung für eine effektive erste Sitzung. Das Beispiel verwendet Claude Code CLI, der Workflow lässt sich jedoch auf jede Runtime übertragen.

### Schritt 1: Prüfen Sie, ob der Agent Ihr Projekt erkennt

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.

Falls der Agent nicht auf den Inhalt Ihrer CLAUDE.md Bezug nimmt, überprüfen Sie, ob die Datei im Projektstammverzeichnis liegt (dasselbe Verzeichnis wie `.xcodeproj` oder `Package.swift`).

### Schritt 2: Führen Sie einen Health-Check-Build durch

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: Führen Sie die Tests aus

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: Implementieren Sie ein Feature

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 modifiziert zu haben, ist das direkte Ergebnis der Regeln in der CLAUDE.md. Ohne diese Regel würde der Agent versuchen, die Projektdatei zu ändern — und sie dabei höchstwahrscheinlich beschädigen.

---

## Was Agents bei iOS gut können

Dies sind die Aufgaben, bei denen Agents durchgehend korrekte, produktionsreife Ergebnisse liefern, die nur minimale manuelle Überprüfung erfordern.

### SwiftUI Views und Modifiers

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

**Worin Agents besonders stark sind:**
- Neue Views anhand einer Beschreibung erstellen („Erstelle ein Einstellungs-Sheet mit Toggles für X, Y, Z")
- Modifier-Ketten anwenden (`.glassEffect()`, `.sensoryFeedback()`, `.navigationTitle()`)
- Zwischen Layout-Mustern konvertieren (VStack zu LazyVGrid, List zu ScrollView)
- `@Bindable`-Formularbindungen zu SwiftData-Modellen implementieren
- Preview-Provider mit Beispieldaten erstellen

**Beispiel-Prompt mit hervorragenden Ergebnissen:**

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 Spezifität ist entscheidend. „Erstelle eine Einstellungs-View" liefert generische Ergebnisse. „Create a SettingsView that matches the existing pattern in SettingsSheet.swift" hingegen erzeugt Ausgaben, die mit Ihrer Codebasis konsistent sind.

### SwiftData-Modelle und Queries

Agents bewältigen SwiftDatas `@Model`-Makro, Beziehungen und `@Query`-Muster zuverlässig. Die deklarative Natur des Frameworks (vergleichbar mit Django ORM oder SQLAlchemy) lässt sich gut auf Muster abbilden, die der Agent über viele Codebasen hinweg gesehen hat.

**Worin Agents besonders stark sind:**
- `@Model`-Klassen mit Beziehungen definieren
- `@Query` mit Sort-Deskriptoren und Prädikaten schreiben
- CRUD-Operationen über `modelContext` implementieren
- Migrationspläne zwischen Schema-Versionen erstellen
- Preview-Daten und Test-Fixtures anlegen

**Wobei Agents Anleitung benötigen:**
- Komplexe `#Predicate`-Ausdrücke (SwiftDatas Prädikats-DSL hat Einschränkungen, die der Agent nicht immer kennt — dokumentieren Sie bekannte Limitierungen in CLAUDE.md)
- CloudKit-Synchronisierungskonfiguration (automatisch über SwiftData, allerdings versucht der Agent möglicherweise, eine manuelle Synchronisierung zu implementieren)

### Unit-Tests

Von Agents geschriebene Unit-Tests sind bei iOS-Projekten durchgehend von hoher Qualität. Der Agent versteht XCTest-Muster, asynchrone Testmethoden und den setUp/tearDown-Lebenszyklus.

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

Der Agent erstellt gut strukturierte XCTest-Fälle mit `setUp()` und `tearDown()`, passenden Assertions und korrekter Async-Behandlung für timerbasierte Tests.

### Refactoring und Musteranwendung

Agents zeichnen sich bei mechanischem Refactoring aus: Views in Komponenten extrahieren, `ObservableObject` zu `@Observable` konvertieren, von `NavigationView` zu `NavigationStack` migrieren und konsistente Muster über mehrere Dateien hinweg anwenden.

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

Der Agent arbeitet methodisch jede Datei durch, wendet die Transformation korrekt an und erhält die bestehende Funktionalität. Dies ist hocheffektive Arbeit — ein Refactoring, das manuell eine Stunde dauern würde, wird in Minuten mit nahezu perfekter Genauigkeit abgeschlossen.

### Build-Fehlerdiagnose über MCP

Mit strukturierter MCP-Ausgabe diagnostizieren Agents Build-Fehler schneller als die meisten Entwickler. Der Agent liest die Fehler-JSON, identifiziert die exakte Datei und Zeile, versteht die Fehlermeldung und wendet den Fix an — oft in einem einzigen Durchgang.

**Fehler, die Agents eigenständig beheben:**
- Fehlende Imports
- Typ-Inkompatibilitäten
- Lücken bei Protokollkonformität
- Veraltete API-Nutzung (mit Ersetzung)
- Fehlende erforderliche Initialisierer-Parameter
- Zugriffskontrollverletzungen

**Fehler, bei denen Agents Hilfe benötigen:**
- Mehrdeutige Typauflösung (mehrere Module definieren denselben Typ)
- Komplexe generische Constraint-Fehler
- Makro-Expansionsfehler (der Agent kann die expandierte Makro-Ausgabe nicht einsehen)

### Simulator-Verwaltung

Agents bewältigen den Simulator-Lebenszyklus über MCP problemlos:

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 Laufzeitumgebungen zu finden, `boot_sim` zum Starten des Simulators, `build_sim` zum Erstellen und Installieren sowie `screenshot` zum Aufnehmen — alles über strukturierte MCP-Aufrufe.

---

## Was Agents bei iOS schlecht können

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

### .pbxproj-Dateiänderungen — NIEMALS

Dies ist die wichtigste Regel in der iOS-Agent-Entwicklung überhaupt. Die `.pbxproj`-Datei ist Xcodes Projektkonfiguration — eine strukturierte Textdatei mit UUID-Referenzen, Build-Phase-Auflistungen und Target-Zugehörigkeiten. Sie ist nominell menschenlesbar, aber für AI-Agents praktisch nicht parsebar.

**Warum Agents an .pbxproj scheitern:**
- Die Datei verwendet ein proprietäres Format (weder JSON noch YAML noch XML) mit positionsabhängiger Bedeutung
- Jeder Eintrag ist per UUID querverwiesen — das Hinzufügen einer Datei erfordert konsistente Aktualisierungen in 3–5 verschiedenen Abschnitten
- Ein einziges falsch platziertes Zeichen beschädigt die gesamte Projektdatei
- Xcodes Merge-Conflict-Auflösung für .pbxproj ist ohnehin fragil — Agent-Bearbeitungen verschlimmern die Lage

**Was passiert, wenn ein Agent .pbxproj bearbeitet:**
1. Die Bearbeitung scheint erfolgreich zu sein (der Agent meldet „Datei aktualisiert")
2. Xcode verweigert das Öffnen des Projekts („The project file is corrupted")
3. Sie verbringen 15–60 Minuten mit der Wiederherstellung aus der Git-Historie
4. Sie lernen, den PreToolUse-Hook einzurichten (siehe [Hooks](#hooks-for-ios-development))

**Der Workflow:** Der Agent erstellt Swift-Dateien. Sie fügen diese manuell zum Xcode-Projekt hinzu (per Drag-and-Drop in Xcode oder über File > Add Files). Das dauert 5 Sekunden pro Datei und verhindert stundenlange Wiederherstellungsarbeit.

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

### Komplexe Interface Builder / Storyboard-Bearbeitungen

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

**Die Abhilfe:** Verwenden Sie für neue Views ausschließlich SwiftUI. Falls Ihr Projekt Legacy-Interface-Builder-Dateien enthält, lassen Sie diese unverändert und erstellen Sie neue UI in SwiftUI.

### Performance-Optimierung

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

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

**Wo sich das bemerkbar macht:**
- Metal-Shader-Optimierung (der Agent schreibt valides Metal, kann aber die GPU-Framezeit nicht messen)
- SwiftUI-View-Body-Komplexität (der Agent erzeugt tief verschachtelte Views, die Redraw-Overhead verursachen)
- Core Data / SwiftData Fetch-Optimierung (der Agent schreibt korrekte Abfragen, die bei großen Datenmengen langsam sein können)

**Die Abhilfe:** Nutzen Sie Agents für die Implementierung, profilen Sie manuell mit Instruments und bitten Sie den Agent dann, gezielt die von Ihnen identifizierten Optimierungen anzuwenden.

### Code Signing und Provisioning

Agents können Code-Signing-Probleme nicht über das Lesen der Fehlermeldung hinaus debuggen. Provisioning-Profile-Verwaltung, Zertifikatserstellung, Entitlement-Konfiguration und App-Store-Einreichung sind grundsätzlich manuell gesteuerte Workflows, die das Apple Developer Portal, die Schlüsselbundverwaltung und Xcodes Signing-UI erfordern.

**Was der Agent sieht:** „Signing for 'Return' requires a development team."

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

**Die Abhilfe:** Erledigen Sie sämtliches Signing in Xcodes Tab „Signing & Capabilities". Bitten Sie Agents nicht, Signing-Fehler zu debuggen.

### Komplexes Metal-Shader-Debugging

Agents schreiben syntaktisch korrekte Metal Shading Language (MSL), können aber weder die visuelle Ausgabe verifizieren noch GPU-seitige Probleme debuggen. Metal-Shader werden auf der GPU ausgeführt — der Agent hat keinen Feedback-Mechanismus dafür, ob der Shader visuell korrekte Ergebnisse liefert.

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

**Was Agents mit Metal nicht können:**
- Visuelle Korrektheit der Shader-Ausgabe verifizieren
- GPU-Performance debuggen (Framezeit, Auslastung, Speicherbandbreite)
- Visuelle Artefakte diagnostizieren (Banding, Präzisionsprobleme, falscher Farbraum)
- Auf verschiedenen GPU-Architekturen testen (Verhaltensunterschiede zwischen A-Serie und M-Serie)

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

### Visuelle Layout-Überprüfung

Agents können die UI Ihrer App nicht sehen. Sie schreiben SwiftUI-Layout-Code und können verifizieren, dass er kompiliert — aber sie können nicht beurteilen, ob der resultierende Bildschirm korrekt aussieht. Eine View, die 10 Pixel außerhalb der Mitte rendert, die falsche Schriftstärke verwendet oder überlappende Elemente aufweist, erzeugt keinen Build-Fehler und besteht alle Logiktests.

**Die Abhilfe:** Überprüfen Sie UI-Änderungen visuell. Nutzen Sie SwiftUI Previews in Xcode (oder `RenderPreview` über Apple MCP für Headless-Rendering), um das Layout zu verifizieren. Ziehen Sie Snapshot-Testing mit Bibliotheken wie swift-snapshot-testing für automatisierte visuelle Regressionserkennung in Betracht.

---

## Hooks für die iOS-Entwicklung

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

Hintergrundinformationen zum Hook-System finden Sie im [Claude Code-Hooks-Leitfaden](/blog/claude-code-hooks-tutorial). Dieser Abschnitt behandelt iOS-spezifische Hook-Muster.

### PreToolUse: .pbxproj-Schreibzugriffe 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:

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

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

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

Was erfasst wird: - Direkte .pbxproj-Bearbeitungen - Alle Dateien innerhalb von .xcodeproj/- oder .xcworkspace/-Verzeichnissen - Interface-Builder-Dateien (.xib, .storyboard)

PostToolUse: Format-on-Save mit SwiftFormat

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

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

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

Optional: Fügen Sie eine .swiftformat-Konfigurationsdatei im Projektstammverzeichnis hinzu, um die Formatierungsregeln anzupassen:

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

PostToolUse: SwiftLint automatisch ausführen

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

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

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

PostToolUse: Automatischer Build nach Änderungen

Für aggressive Feedback-Schleifen können Sie nach jeder Swift-Datei-Änderung 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: Dies ist ressourcenintensiv. Jede Dateibearbeitung löst einen Build aus. Setzen Sie es sparsam ein — am nützlichsten ist es während Debugging-Sitzungen, in denen Sie sofortiges Build-Feedback wünschen. Für die normale Entwicklung lassen Sie den Agenten Builds manuell über MCP auslösen, wenn er bereit ist.

PreToolUse: Entitlement-Änderungen 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-Blockierung) 2. Jede Swift-Datei, die der Agent bearbeitet, wird automatisch formatiert (PostToolUse-Formatierung)

Architekturmuster, die gut mit Agents funktionieren

Nicht alle Swift-Architekturen eignen sich gleichermaßen für die Arbeit mit Agents. Die folgenden Muster liefern die besten Ergebnisse, da sie explizit, konsistent und in den Trainingsdaten gut repräsentiert sind.

@Observable (Niemals ObservableObject)

Projekte mit iOS 26+ als Zielplattform sollten ausschließlich @Observable verwenden. Dies ist sowohl das moderne als auch das agentfreundliche 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 agentfreundlich ist: Das Muster ist einfacher (keine @Published-Annotationen erforderlich), das Ownership-Modell ist klarer (@State statt der Unterscheidung zwischen @StateObject und @ObservedObject), und Agents produzieren damit weniger Fehler, da es weniger bewegliche Teile gibt.

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

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 ab iOS 16 verfügbar und das einzige Navigationsmuster, das Sie für neuen Code verwenden sollten. Das typsichere navigationDestination(for:)-Muster verhindert, dass der Agent fehlerhafte Navigationslinks erstellt.

SwiftData für Persistenz

SwiftData-Modelle sind das sauberste Persistenzmuster für agentenunterstü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 Agents bei der Arbeit mit SwiftData: 1. @Model-Klassen sind automatisch Observable — fügen Sie nicht zusätzlich @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 Nicht-View-Code 5. Beziehungslöschungen benötigen explizite Regeln: .cascade, .nullify, .deny

Swift 6.2 Concurrency

Neue Projekte sollten Swift 6.2 Strict Concurrency als Ziel verwenden:

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

Agent-Leitfaden für Concurrency: - Markieren Sie alle View-Models mit @MainActor (verhindert Data-Race-Warnungen) - Verwenden Sie async/await für alle asynchronen Operationen (keine Completion-Handler) - Machen Sie Werttypen Sendable für aktorübergreifende Übertragungen - Verwenden Sie Task { } in Views für asynchrone Initialisierung - Verwenden Sie nonisolated nur bei nachgewiesenem Performancebedarf

Liquid Glass Design System (iOS 26+)

Mit iOS 26 wurde das Liquid Glass Design System eingeführt. Agents kommen damit gut zurecht, wenn sie explizite Anleitung 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: „Verwenden Sie .glassEffect() auf Abschnittshintergründen und Karten-Containern. Navigationsleisten übernehmen in iOS 26 automatisch das Glass-Material. Erstellen Sie keine Glass-Effekte manuell mit benutzerdefinierten Materialien — verwenden Sie den System-Modifier.”

Framework-spezifischer Kontext

Jedes Apple-Framework hat agentspezifische Besonderheiten. Dieser Abschnitt behandelt die Frameworks, die in den 8 Apps zum Einsatz kommen.

HealthKit

Apps, die es verwenden: Return, Water

HealthKit erfordert sorgfältige Berechtigungsverwaltung 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
        }
    }
}

Agent-Regeln für HealthKit: - Prüfen Sie immer mit HKHealthStore.isHealthDataAvailable() - Gehen Sie niemals von einer erteilten Berechtigung aus — prüfen Sie bei jedem Schreibvorgang - Verwenden Sie #if canImport(HealthKit) für plattformübergreifenden Code (HealthKit ist auf tvOS nicht verfügbar) - Speichern Sie niemals Gesundheitsdaten lokal über das hinaus, was HealthKit bereitstellt - Fügen Sie sowohl NSHealthShareUsageDescription als auch NSHealthUpdateUsageDescription in die Info.plist ein

SpriteKit

Apps, die es verwenden: TappyColor, Starfield Destroyer

Das Szenengraph-Modell von SpriteKit erfordert explizite Anleitung für Agents:

## 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 Agents bei SpriteKit: - Erstellen von SKAction-Sequenzen und -Gruppen - Einrichten von Physikkörpern und Kontakterkennung - Implementieren von Spielzustandsmaschinen - Erstellen von HUD-Overlays

Schwächen von Agents bei SpriteKit: - Performancekritische Spielschleifen (der Agent fügt unnötige Arbeit pro Frame hinzu) - Komplexe Physiksimulationen (eigene Physik ist präziser als SKPhysicsBody) - Partikeleffekt-Feinabstimmung (visuell, erfordert Iteration)

Metal

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

Metal ist das Framework, bei dem Agents am meisten Schwierigkeiten haben. Das GPU-Programmiermodell unterscheidet sich grundlegend von CPU-seitigem Swift, und Agents können visuelle Ausgaben 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 in CLAUDE.md für Metal-Projekte aufnehmen sollten: - Die Uniforms-Struct-Definition (geteilt zwischen Swift und MSL) - Das Setup-Muster für den Render-Pipeline-State - Buffer-Indizes und ihre Zwecke - Welche Shader existieren und was jeder einzelne tut - Bekannte Präzisionsprobleme (half vs. float)

Live Activities

Apps, die es verwenden: Return

Live Activities erfordern eine spezifische Konfiguration, die Agents gut handhaben, 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)

Multiplattform-Muster

Return umfasst iOS, watchOS und tvOS. Multiplattform-Entwicklung mit Agenten erfordert eine explizite Dokumentation der Plattformgrenzen.

Organisation von gemeinsam genutztem Code

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: „Befindet sich eine Datei in Shared/, wirken sich Änderungen auf alle Plattformen aus. Liegt eine Datei in einem plattformspezifischen Verzeichnis, bleiben Änderungen isoliert. Prüfen Sie vor jeder Änderung immer, in welchem Verzeichnis sich die Datei befindet.”

Plattformverfügbarkeits-Guards

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

Anleitung für Agenten: „Verwenden Sie immer #if canImport()- oder #if os()-Guards bei plattformspezifischen Frameworks. Gehen Sie niemals davon aus, dass ein Framework auf allen Targets verfügbar ist.”

Plattformspezifische UI-Anpassung

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

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

Fortgeschrittene Workflows

Autonome Build-Test-Fix-Schleifen

Das leistungsstärkste Muster: Geben Sie dem Agenten eine Feature-Spezifikation und lassen Sie ihn eigenständig durch Build-Test-Fix-Zyklen iterieren.

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

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

Der Agent schreibt Code, baut über MCP, liest strukturierte Fehlermeldungen, behebt sie und wiederholt den Vorgang. Ein Feature, das normalerweise 5–10 menschliche Build-Fehler-Fix-Zyklen erfordern würde, wird in einer einzigen autonomen Schleife abgeschlossen.

Wann das funktioniert: Klar definierte Features mit eindeutigen Akzeptanzkriterien.

Wann das scheitert: Offene Features („mach es hübsch”), performancekritischer Code oder alles, was eine visuelle Überprüfung erfordert.

Subagent-Delegation für iOS

Das Subagent-System von Claude Code eignet sich 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 durchsucht Dokumentation und Code-Muster in einem separaten Kontextfenster, liefert eine Zusammenfassung zurück, und die Hauptsitzung setzt die Empfehlung um. So wird verhindert, dass Recherchen Ihren primären Kontext aufbrauchen.

Anwendung von App-übergreifenden Mustern

Wenn Sie mehrere iOS-Apps mit einheitlichen 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 eine konsistente Implementierung im Zielprojekt.

Dual-Agent-Review (Claude + Codex)

Setzen Sie bei kritischen Änderungen zwei Agenten aus unterschiedlichen Modellfamilien ein:

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. Besonders wertvoll ist dies bei Metal-Shadern und Concurrency-Mustern, bei denen sich subtile Bugs leicht einschleichen.

Was ein Dual-Review erkennt, das ein Einzel-Review übersieht:

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

Batch-Operationen über mehrere Apps

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 jedoch sämtliche Sicherheitsprüfungen. Stellen Sie sicher, dass Ihre PreToolUse-Hooks zum Schutz von .pbxproj-Dateien eingerichtet sind.

Praxisnahe Fallstudien

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

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

Die Aufgabe: Ein tvOS-Target zu Return hinzufügen, einem Meditations-Timer, der bereits iOS- und watchOS-Versionen hatte. Die TV-App benötigte Siri-Remote-Navigation, eine Großbildschirm-UI und Einstellungssynchronisation mit der iOS-App.

Was der Agent gut gemacht hat: - Den bestehenden iOS-TimerManager gelesen und einen TVTimerManager erstellt, der Live Activities und HealthKit (auf tvOS nicht verfügbar) ausließ - Benutzerdefinierte Button-Styles für die Siri-Remote-Fokus-Navigation erstellt (TVCapsuleButtonStyle, TVCircleButtonStyle) - Eine TVStepper-Komponente gebaut, die Rad-Picker (mit Siri Remote nicht nutzbar) durch +/−-Buttons ersetzt - Einstellungssynchronisation über App Groups (group.com.941apps.Return) implementiert - #if os(tvOS)-Guards im gesamten gemeinsam genutzten Code eingefügt - Über MCP mit platform=tvOS Simulator,name=Apple TV gebaut und getestet

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

Ergebnis: 15 neue Swift-Dateien, eine voll funktionsfähige TV-App, implementiert in etwa 3 Stunden agentengestützter Arbeit. Die entsprechende manuelle Implementierung hätte 1–2 Tage gedauert. Der Agent übernahm rund 80 % des Codes, ich die 20 %, die Xcode-UI-Interaktion und manuelles Testen erforderten.

Fallstudie 2: Metal-Shader-Debugging in amp97 (Teilerfolg)

Die Aufgabe: Ein energiebasiertes Intensitätssystem zum Oszilloskop-Shader hinzufügen. Die Visualisierung sollte mit der Audio-Energie pulsieren.

Was geschah: 1. Der Agent schrieb eine valide Metal-Shader-Modifikation mit einem uEnergy-Uniform und HDR-Tonemapping 2. Der Code kompilierte fehlerfrei 3. Auf dem Gerät war die Visualisierung komplett weiß — der Intensitätskoeffizient war 10-fach zu hoch (3,5 statt 0,30) 4. Der Agent konnte den weißen Bildschirm nicht sehen und hatte somit kein Feedback-Signal 5. Ich identifizierte das Problem visuell und bat den Agenten, den Koeffizienten zu reduzieren 6. Der Agent reduzierte ihn, allerdings war die gesamte Energie-Zustandsmaschine zu komplex und brach den Visualizer auf andere Weise 7. Vollständig zurückgesetzt — zwei Commits (67959ed und cda4830) wurden in 869d914 revertiert

Die Lektion: Metal-Shader sind der schwierigste Bereich für agentengestützte Entwicklung, weil die Feedback-Schleife unterbrochen ist. Der Agent kann Syntax (kompiliert) und Semantik (korrekte Typen) verifizieren, jedoch nicht die Ausgabe (sieht richtig aus). Jede Shader-Änderung, die visuelles Verhalten beeinflusst, erfordert menschliche Überprüfung auf dem Gerät.

Was ich danach in CLAUDE.md ergänzt habe: „KEINE Energie-Zustandsmodifikationen am Oszilloskop-Shader ohne äußerst sorgfältiges Koeffizienten-Testing versuchen. Vorheriger Versuch hat den Visualizer mit 10-fach zu hohen Koeffizienten zerstört.”

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

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

Was der Agent tat: 1. Die bestehenden V1-Modelldefinitionen gelesen 2. V2-Modelldefinitionen mit den neuen Feldern und Beziehungen erstellt 3. Einen GroceryMigrationPlan mit SchemaMigrationPlan-Protokollkonformität geschrieben 4. Die V1toV2-Migrationsstufe implementiert: Standard 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. Über 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 wusste, wovon er migrierte.

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

Die Aufgabe: Geräteübergreifendes Meditations-Sitzungsprotokoll implementieren. Auf Apple TV oder Mac abgeschlossene Sitzungen sollten zum iPhone synchronisiert werden, um dort ins HealthKit geschrieben zu werden.

Was der Agent produzierte:

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

Der Agent: 1. Erstellte ein MeditationSession-Datenmodell mit UUID, Daten, Dauer, Quellgerät und HealthKit-Synchronisationsstatus 2. Baute einen SessionStore-Singleton, der NSUbiquitousKeyValueStore für die iCloud-Synchronisation verwaltet 3. Implementierte Merge-Konfliktlösung (UUID-basierte Deduplizierung) 4. Fügte eine SessionHistoryView mit plattformspezifischen Anpassungen hinzu (Wischen-zum-Löschen auf iOS, fokusbasiert auf tvOS) 5. Verdrahtete die iPhone-seitige HealthKit-Synchronisation 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 Vordergrund-Benachrichtigung für die Synchronisation). Der Agent benötigte einen gezielten Hinweis: „Verwende NSUbiquitousKeyValueStore.didChangeExternallyNotification, um die Synchronisation bei Hintergrund-KV-Änderungen auszulösen.” Nach diesem Hinweis war die Implementierung korrekt.

Die Lektion: Agenten bewältigen plattformübergreifende Architekturmuster gut, wenn die Architektur klar beschrieben ist. Das iCloud-Synchronisationsmuster ist nicht trivial, folgt aber einem dokumentierten Apple-Pattern, das der Agent verstand. Der Grenzfall (Hintergrundsynchronisation) erforderte menschliches Domänenwissen, da er nur unzureichend dokumentiert ist.

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

Die Aufgabe: Game Center-Bestenlisten und Erfolge zum Space-Shooter hinzufügen.

Was der Agent gut gemacht hat: - GKLocalPlayer.local.authenticateHandler im App-Einstiegspunkt implementiert - Einen GameCenterManager mit Methoden für Score-Übermittlung und Achievement-Meldung erstellt - Authentifizierungsstatus-Prüfung vor allen Game Center-Operationen hinzugefügt - Den Offline-Fall elegant behandelt (Spiel läuft ohne Game Center, übermittelt bei erneuter Verbindung) - Achievement-Definitionen passend zum 8-Schiff-Progressionssystem erstellt

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

Projektlebenszyklus mit Agenten

Ein neues iOS-Projekt starten

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

Phase 1: Menschliches Setup (15–30 Minuten) 1. Das Xcode-Projekt erstellen (File > New > Project) 2. Signierung und Capabilities konfigurieren 3. Deployment-Target und unterstützte Zielplattformen festlegen 4. Erforderliche Entitlements hinzufügen (HealthKit, Game Center usw.) 5. Die initiale CLAUDE.md mit Projektidentität und Regeln erstellen

Phase 2: Agentenimplementierung (Stunden bis Tage) 1. Agent erstellt das Datenmodell (SwiftData, Core Data oder einfache Structs) 2. Agent baut Views gemäß den dokumentierten Patterns 3. Agent implementiert Geschäftslogik in Manager-/Service-Klassen 4. Agent schreibt Unit-Tests 5. Build-Test-Fix-Schleife über MCP (autonom)

Phase 3: Menschliche Integration (30–60 Minuten) 1. Vom Agenten erstellte Dateien zu Xcode-Targets hinzufügen 2. Signierung und Entitlements verifizieren 3. Auf physischem Gerät testen 4. Visuelles Layout und UX überprüfen 5. An App Store Connect übermitteln

Ein bestehendes Projekt pflegen

Für die laufende Entwicklung an etablierten Apps:

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

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

Die Effektivität des Agenten skaliert mit der Aktualität Ihrer CLAUDE.md. Aktualisieren Sie Ihre CLAUDE.md, wenn Sie bedeutende neue Funktionen hinzufügen, Architekturmuster ändern oder neue Frameworks einführen.

Wann den Agenten einsetzen — und wann nicht

Agent-Definitionen konfigurieren

Wenn Sie das Agent-Definitionssystem von Claude Code (.claude/agents/) nutzen, 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 agentengestützte iOS-Entwicklung

Agents schreiben hervorragende Unit-Tests, wenn sie klare Anweisungen erhalten. Die folgenden Muster liefern die besten Ergebnisse.

Organisation der Testdateien

# In CLAUDE.md:

## Test Structure

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

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

Effektive 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 bestehende Testdatei legt das Muster fest. Die Vorgabe von setUp() verhindert, dass der Agent verflochtene Testzustände erzeugt.

Ineffektiver Test-Prompt:

Write tests for TimerManager.

Daraus entstehen generische, oberflächliche Tests, die Grenzfälle übersehen und möglicherweise nicht den Mustern Ihres Projekts entsprechen.

Asynchrone Testmuster

Für das Testen von Timer-basiertem 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 mit Task.sleep oder asynchronen Operationen - Toleranz bei zeitbasierten Assertions (1,1 Sekunden, nicht exakt 1,0) - Sauberes setUp() / tearDown() zur Testisolation

Snapshot-Tests

Zur Erkennung visueller Regressionen können Sie swift-snapshot-testing einsetzen:

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.