iOS-Apps mit KI-Agenten entwickeln: Der Praxisleitfaden

Kurzfassung: Drei Agentenlaufzeitumgebungen liefern inzwischen Code für iOS aus: Claude Code CLI mit MCP, Codex CLI mit MCP und die nativen Intelligence-Agenten von Xcode — Claude Agent, Codex und seit Xcode 26.6 Google Gemini oder jeder Agent, der das Agent Client Protocol (ACP) unterstützt.¹⁷ Zwei MCP-Server (XcodeBuildMCP mit 82 Tools und Apples xcrun mcpbridge mit 20 Tools) ermöglichen Agenten strukturierten Zugriff auf Builds, Tests, Simulatoren und Debugging. Dieser Leitfaden behandelt praxiserprobte CLAUDE.md-Muster, Hook-Konfigurationen sowie ehrliche Einschätzungen dessen, was funktioniert und was scheitert — basierend auf 8 produktiven iOS-Apps mit insgesamt 293 Swift-Dateien.³⁰ Agenten sind besonders gut bei SwiftUI-Views, SwiftData-Modellen, Refactoring und der Diagnose von Build-Fehlern. Bei Änderungen an .pbxproj, Code Signing und visuellem Debugging scheitern sie. Die Lücke zwischen „Der Agent schreibt Swift“ und „Der Agent liefert eine iOS-App aus“ wird durch Konfiguration geschlossen, nicht durch Prompting. Seit der WWDC 2026 (8. Juni) befindet sich iOS 27 in der Betaphase — seit dem 20. Juli in Beta 4 — und bringt für Agenten relevante Frameworks mit sich (Kontrolle des Tool-Aufrufs in Foundation Models, Hintergrundausführung für App Intents sowie die neuen Frameworks Core AI und Evaluations). Diese sollten Sie im Kontext Ihres Agenten ausdrücklich nennen, da ein vor Juni 2026 trainiertes Modell sie nicht kennen wird. Xcode 26.6 (25.06.2026, Swift 6.3) ist die aktuelle stabile Toolchain; die Xcode-27-Beta (Swift 6.4, iOS 27 SDKs) folgt dem iOS-27-Zyklus.¹⁷¹⁸

Ich habe 8 iOS-Apps mit KI-Coding-Agenten entwickelt. Keine Prototypen — sondern Apps im App Store, mit HealthKit-Integrationen, Metal-Shadern, SpriteKit-Physik, iCloud-Synchronisierung, Live Activities, Game Center-Bestenlisten und plattformübergreifenden Targets für iOS, watchOS und tvOS. Jede Swift-Codezeile in diesen Apps wurde entweder von einem Agenten geschrieben und von mir geprüft oder von mir geschrieben und anschließend von einem Agenten überarbeitet. Meiner Einschätzung nach übernahmen die Agenten den Großteil der Arbeit auf Codezeilenebene; ich kümmerte mich um Reviews, Umfang und jene Bereiche, die menschliches Urteilsvermögen erfordern (visueller Feinschliff, Signierung, Performanceoptimierung und Einreichung im App Store).

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

Wichtigste Erkenntnisse

Für iOS-Entwickler, die erstmals mit KI-Agenten arbeiten:

• Beginnen Sie mit Claude Code CLI + XcodeBuildMCP. Dies 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 Builds ausführen, testen und debuggen, ohne dass Sie Fehlermeldungen kopieren müssen.
• Lassen Sie einen Agenten niemals .pbxproj ändern. Das ist die wichtigste Regel überhaupt. Ein PreToolUse-Hook, der Schreibzugriffe auf .pbxproj und .xcodeproj/ blockiert, erspart Ihnen stundenlange Wiederherstellungsarbeit.
• Ihre CLAUDE.md ist das Onboarding-Dokument des Agenten. Jede Stunde, die Sie darin investieren, zahlt sich in sämtlichen Agentensitzungen aus, in denen am Projekt gearbeitet wird.

Für erfahrene Agentenbenutzer, die iOS in ihren Arbeitsablauf aufnehmen:

• MCP verändert den iOS-Build-Zyklus grundlegend. Vor MCP schrieben Agenten Swift, konnten aber nicht überprüfen, ob der Code kompiliert wurde. Mit XcodeBuildMCP schreibt der Agent Code, führt den Build aus, liest strukturierte Fehlermeldungen, behebt sie und startet Tests — autonom.
• Drei Laufzeitumgebungen erfüllen unterschiedliche Anforderungen. Claude Code CLI für tiefgehende agentische Sitzungen, Codex CLI für Headless-Stapelverarbeitung und die nativen Agenten von Xcode 26.3 für schnelle Inline-Korrekturen, ohne die IDE zu verlassen.
• Die Hook-Infrastruktur lässt sich übernehmen. Ihre bestehenden PostToolUse-Formatierer, PreToolUse-Blocker und Testrunner-Hooks funktionieren mit geringfügigen Pfadanpassungen genauso für iOS-Projekte.

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

• Die Effektivität von Agenten skaliert mit der Projektdokumentation, nicht mit der Projektgröße. Eine App mit 63 Dateien und einer ausführlichen CLAUDE.md liefert bessere Agentenergebnisse als eine App mit 14 Dateien ohne eine solche Dokumentation.
• Die .pbxproj-Grenze ist nicht verhandelbar. Agenten können Xcode-Projektdateien nicht zuverlässig bearbeiten. Ihr Arbeitsablauf muss deshalb das manuelle Hinzufügen von Dateien zu Xcode-Targets berücksichtigen.
• Ehrliche ROI: Bei gut dokumentierten Projekten übernehmen Agenten den Großteil der Implementierung — sichtbar an der TV-App mit 15 Dateien, die nach 3 Stunden agentengestützter Arbeit ausgeliefert wurde (Fallstudie weiter unten). Die verbleibenden Aufgaben — visueller Feinschliff, Signierung, Performanceoptimierung und Einreichung im App Store — erfordern menschliches Urteilsvermögen.

Wählen Sie Ihren Einstieg

So verwenden Sie diesen Leitfaden

Dies ist ein Nachschlagewerk mit mehr als 3.000 Zeilen. Beginnen Sie bei Ihrem Erfahrungsstand:

Inhaltsverzeichnis

1. Das Portfolio: 8 Apps, 293 Dateien
2. Voraussetzungen
3. Drei Agentenlaufzeitumgebungen für iOS
4. MCP-Einrichtung: Die vollständige Konfiguration
5. CLAUDE.md-Muster für iOS-Projekte
6. Ihre erste Agentensitzung
7. Was Agenten bei iOS gut beherrschen
8. Was Agenten bei iOS schlecht beherrschen
9. Hooks für die iOS-Entwicklung
10. Architekturmuster, die mit Agenten funktionieren
11. Framework-spezifischer Kontext
12. Plattformübergreifende Muster
13. Fortgeschrittene Arbeitsabläufe
14. Fallstudien aus der Praxis
15. Projektlebenszyklus mit Agenten
16. Agentendefinitionen konfigurieren
17. Testmuster für agentengestützte iOS-Entwicklung
18. Kontextfensterverwaltung für iOS-Projekte
19. Fehlerbehebung
20. Häufige Fehler von Agenten bei iOS
21. Die ehrliche Einschätzung
22. FAQ
23. Kurzübersicht
24. Quellen

Verwandte Ressourcen

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

Serienübersicht: Apple-Ecosystem-Serie

Agentisches Apple (E4):

Frameworks (E2/E3):

Ausgelieferter Code (E1):

Synthese (E5):

iOS 27 und WWDC 2026: Womit Ihr Agent jetzt entwickelt

Auf der WWDC 2026 (8. Juni 2026) ging iOS 27 in die Betaphase. Der Workflow für die Agentenentwicklung in diesem Leitfaden ändert sich dadurch nicht: Sie steuern Claude Code, Codex oder die Intelligence-Agenten von Xcode weiterhin über MCP, schreiben nach wie vor eine CLAUDE.md und sichern destruktive Vorgänge weiterhin mit Hooks ab. Was sich ändert, ist die technische Oberfläche, für die Ihr Agent Code schreibt. iOS 27 umfasst mehrere neue Frameworks, die für Agenten relevant sind. Weisen Sie Ihren Coding-Agenten gezielt darauf hin, denn ein Modell, das vor Juni 2026 trainiert wurde, kennt sie nicht. iOS 26 bleibt die aktuell ausgelieferte Version; betrachten Sie die folgenden Punkte als Zielvorgaben, wenn Sie mit den iOS-27-Beta-SDKs entwickeln.

Die für Agenten relevanten Funktionen von iOS 27, jeweils mit einem ausführlichen weiterführenden Artikel:

• Foundation Models bietet jetzt Kontrolle über Tool-Aufrufe. Mit GenerationOptions.ToolCallingMode können Sie für jede Anfrage steuern, wie offensiv das On-Device-Modell Tools aufruft. Nach dem ersten Aufruf kann das Framework zudem den Modus wechseln, um die Tool-Aktivität einer Anfrage zu begrenzen. Das Vision-Framework enthält nun die einsatzbereiten Tools OCRTool und BarcodeReaderTool, die Sie ohne eigenen Erkennungscode mit einer LanguageModelSession verbinden können. Weitere Informationen finden Sie unter Foundation Models in iOS 27: Kontrolle über Tool-Aufrufe.¹²
• App Intents hat die 30-Sekunden-Grenze durchbrochen. LongRunningIntent verlängert über performBackgroundTask(options:operation:), das eine Fortschrittsanzeige voraussetzt, die Hintergrundlaufzeit eines Intents für Synchronisierung, Dateiverarbeitung und On-Device-Inferenz. SyncableEntity verleiht einer AppEntity eine geräteübergreifende Identität, während IndexedEntityQuery dem System ermöglicht, Ihre Abfrage zur Reparatur seines Spotlight-Index aufzufordern. Weitere Informationen finden Sie unter App Intents in iOS 27: Hintergrundausführung, Synchronisierung und Spotlight.¹³
• Core AI ist ein neues Framework zum Ausführen von Modellen auf Apple Silicon. Es ist unterhalb von Foundation Models angesiedelt und für Fälle gedacht, in denen Sie ein eigenes Modell statt des Systemmodells von Apple verwenden. Weitere Informationen finden Sie unter Core AI: Modelle auf Apple Silicon ausführen.¹⁴
• Evaluations ist XCTest für die Modellqualität. Das neue Framework für macOS 27 misst die Qualität von Modellausgaben als Bestandteil Ihrer Testsuite. Damit liefert es das bislang fehlende Element, um KI-Funktionen auszuliefern, die Sie mithilfe eines Agenten entwickelt haben. Weitere Informationen finden Sie unter Evaluations: XCTest für Modellqualität.¹⁵
• Auch SwiftData, HealthKit und SwiftUI wurden weiterentwickelt. SwiftData ergänzt in iOS 27 Beobachtung und Verlauf, HealthKit führt Trainingszonen und neue Typen ein, und SwiftUI erhält die üblichen umfangreichen Erweiterungen für iOS 27. Weitere Informationen finden Sie unter SwiftData in iOS 27, HealthKit in iOS 27 und Neuerungen in SwiftUI für iOS 27.¹⁶

Die Toolchain für die Entwicklung mit iOS 27 ist die Beta von Xcode 27. Xcode 27 erschien am ersten Tag der WWDC als Beta (8. Juni, Build 27A5194q) und liegt seit dem 20. Juli als Beta 4 (27A5228h) vor. Die Version umfasst Swift 6.4 sowie die SDKs für iOS 27, iPadOS 27, tvOS 27, watchOS 27, macOS 27 und visionOS 27 und setzt macOS Tahoe 26.4 oder neuer voraus.¹⁸ Vier Punkte aus den Versionshinweisen sind für Agenten-Workflows relevant: Coding Intelligence erhält einen Planungsmodus. Die Hinweise erwähnen ihn im Zusammenhang mit einem bekannten Problem der Bestätigungsleiste „Implement the plan?“ (178673449). Warten Sie daher, bis der Agent seine Streaming-Ausgabe abgeschlossen hat, bevor Sie einen Plan bestätigen oder verwerfen. Das MCP-Tool RenderPreview rendert nun Vorschaugruppen (174692209) und kann Ihre Benutzeroberfläche in einer anderen Lokalisierung anzeigen (181040291). Das für Agenten vorgesehene Tool „Prepare Project for Localization“ meldet jetzt Schlüssel aus dem String Catalog, die entfernt wurden, weil sie nicht mehr im Quellcode vorkommen (179755385). Außerdem kann Address Sanitizer bei 27.0-Zielen möglicherweise nicht gestartet werden, wenn die App mit Xcode 26.4 oder älter erstellt wurde. Verwenden Sie für ASan-Läufe Xcode 26.5 oder neuer (178072780).¹⁸ Auch die MCP-Tools unterstützen inzwischen die Beta: Mit XcodeBuildMCP v2.7.0 (2026-07-23) funktionieren die Tools zur UI-Automatisierung über Device Hub vollständig mit Xcode-27-Simulatoren, einschließlich des Öffnens von Simulatorfenstern und der Tastatursteuerung. Vor dieser Version war die UI-Automatisierung zur Laufzeit nur mit Xcode-26-Simulatoren zuverlässig, weshalb die agentengestützte UI-Verifizierung unter der Beta von iOS 27 manuell erfolgen musste.²¹

Die Lehre für Sie als Bediener bleibt dieselbe wie im übrigen Leitfaden: Der Agent schreibt den Code, doch Sie liefern ihm das fehlende Wissen. Bei Betaversionen von iOS 27 bedeutet das, diese Frameworks in Ihrem Prompt oder Ihrer CLAUDE.md ausdrücklich zu nennen und den Agenten auf die Dokumentation von Apple zu verweisen. Andernfalls greift das Modell für jedes API auf die Struktur von iOS 26 zurück. Alles Weitere aus diesem Leitfaden – Laufzeitumgebungen, MCP, Hooks und Fehlermuster – gilt unverändert für die Entwicklung mit iOS 27.

Das Portfolio: 8 Apps, 293 Dateien

Bevor wir uns mit der Konfiguration befassen, sehen Sie hier, auf welchen Projekten dieser Leitfaden basiert. Es handelt sich nicht um Spielzeugprojekte: Sie decken fünf Apple-Frameworks, drei Plattformen und die gesamte Bandbreite der iOS-Komplexität ab – von einem Workout-Tracker mit 14 Dateien bis zu einem plattformübergreifenden Meditationstimer mit 63 Dateien.

Warum die Anzahl der Dateien wichtig ist: Die Effektivität eines Agenten hängt stärker von der Verständlichkeit eines Projekts als von seiner Größe ab. Return (63 Dateien) liefert bessere Agentenergebnisse als amp97 (41 Dateien), weil Return über eine ausführliche CLAUDE.md mit Dateianmerkungen, Architekturdiagrammen und klar definierten Mustern verfügt. Die Metal-Shader von amp97 sind für Agenten unabhängig von der Qualität der Dokumentation grundsätzlich schwieriger nachzuvollziehen.

Voraussetzungen

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

Frist für App Store Connect: Ab dem 28.04.2026 müssen Uploads zu App Store Connect mit Xcode 26 oder neuer und unter Verwendung von SDKs für iOS 26, iPadOS 26, tvOS 26, visionOS 26 oder watchOS 26 erstellt werden.²⁴ (Einreichungen für macOS unterliegen dieser Anforderung nicht.) Falls Ihr Team noch Xcode 16.x verwendet, dient die agentengestützte Toolchain in diesem Leitfaden zugleich als zwingender Anlass für die Umstellung – keiner der folgenden MCP-Server funktioniert ohne Xcode 26.3 oder neuer.

Erforderlich: - macOS 15 oder neuer (Sequoia) beziehungsweise macOS Tahoe (Xcode 26.6 setzt macOS Tahoe 26.2 oder neuer voraus; die Beta von Xcode 27 erfordert Tahoe 26.4 oder neuer) - Xcode 26.3 oder neuer, installiert und konfiguriert (Mindestversion für xcrun mcpbridge); Xcode 26.6 oder neuer wird empfohlen. Xcode 26.6 (2026-06-25, Build 17F113) ist die neueste stabile Version und enthält drei für Agenten relevante Änderungen an Coding Intelligence: Google Gemini als Anbieter eines Coding-Assistenten, Unterstützung für das Agent Client Protocol (ACP) und das Rendern verschiedener Varianten – Hell-/Dunkelmodus, Ausrichtung und Schriftgrößen – im Vorschau-MCP-Tool. Außerdem behebt die Version zwei Abstürze während eines Agentendurchlaufs sowie das Hängenbleiben, wenn ein Agent eine Frage stellt, und enthält Swift 6.3 mit den SDKs der iOS-26.5-Generation.¹⁷ Die Workflow-Verbesserungen aus Version 26.5 – Nachrichtenwarteschlangen im Coding-Assistenten und Unterstützung für Rückfragen – sowie die Bildanhänge für Swift Testing, Schweregrade für protokollierte Probleme, Warnungen vor UI-Testabstürzen samt Absturzprotokollen und Verbesserungen am String-Catalog-Editor aus Version 26.4 sind ebenfalls enthalten.²⁵²⁶ Frühere stabile Versionen: 26.5 (2026-05-11, Build 17F42) und 26.4.1 (2026-04-16, Build 17E202).²⁷ - Mindestens eine installierte iOS-Simulatorlaufzeit - Ein Anthropic-API-Konto (für Claude Code) oder ein OpenAI-Konto (für Codex)

Empfohlen: - Installiertes SwiftFormat (brew install swiftformat) – wird von Hooks zur Formatierung beim Speichern verwendet - Installiertes SwiftLint (brew install swiftlint) – optional, aber hilfreich zur Durchsetzung von Stilregeln - Vertrautheit mit dem Terminal – alle drei Laufzeitumgebungen werden über die Befehlszeile ausgeführt oder darin integriert

Überprüfen Sie Ihre Xcode-Installation:

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

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

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

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

Drei Agent-Runtimes für iOS

Drei unterschiedliche Runtimes können iOS-Code schreiben, erstellen und testen. Sie sind nicht austauschbar – jede hat andere Stärken, andere Integrationsmuster für MCP und andere ideale Anwendungsfälle.

1. Claude Code CLI

Was es ist: Der terminalbasierte agentische Programmierassistent von Anthropic. Er liest Ihre Codebasis, führt Befehle aus, ändert Dateien und stellt über MCP eine Verbindung zu externen Tools her.⁷

MCP-Integration: Vollständige Unterstützung sowohl für XcodeBuildMCP als auch für Apples Xcode MCP. Der Agent erkennt Tools über das MCP-Protokoll und ruft sie mit strukturierten Parametern auf. Insgesamt stehen auf beiden Servern 82 + 20 Tools zur Verfügung.

Einrichtung:

# Install Claude Code (if not already installed)
claude --version  # verify installation

# Add XcodeBuildMCP (82 tools — builds, tests, simulators, debugging)
claude mcp add XcodeBuildMCP \
  -s user \
  -e XCODEBUILDMCP_SENTRY_DISABLED=true \
  -- npx -y xcodebuildmcp@latest mcp

# Add Apple Xcode MCP (20 tools — file ops, diagnostics, Swift REPL, previews)
claude mcp add --transport stdio xcode \
  -s user -- xcrun mcpbridge

Alternative – automatische Installation mit xcodebuildmcp init (ab v2.1.0, 23.02.2026):

Wenn Sie die manuelle MCP-Verknüpfung überspringen möchten, bietet XcodeBuildMCP ab v2.1.0 einen init-Unterbefehl. Dieser erkennt Claude Code, Cursor oder Codex automatisch und installiert die Agent-Skills sowie die MCP-Konfiguration in einem Schritt:

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

Flags: --print (Konfiguration für nicht unterstützte Clients in stdout ausgeben), --uninstall (entfernen). Überspringen Sie diese Option, wenn Sie ausdrücklich festlegen möchten, welche MCP-Server in welchem Geltungsbereich verknüpft werden. Mit den obigen manuellen claude mcp add-Aufrufen behalten Sie diese Kontrolle.²⁸

Am besten geeignet für: Umfangreiche Implementierungssitzungen – neue Funktionen entwickeln, mehrere Dateien umfassend refaktorieren, komplexe Probleme beheben und Build-Test-Korrektur-Schleifen autonom ausführen. Dank des Kontextfensters von 1 Million Tokens (mit Opus 5) kann Claude Code die meisten kleinen bis mittelgroßen iOS-Projekte im Arbeitsgedächtnis behalten – meiner Erfahrung nach je nach Dateigröße bis zu ungefähr 50 Dateien.²³

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 Arbeitsablauf vor MCP: Der Agent fordert Sie nie auf, den Build manuell auszuführen oder die Fehlerausgabe einzufügen. Die Build-Fehler-Korrektur-Schleife läuft autonom ab.

2. Codex CLI

Was es ist: Der terminalbasierte Programmieragent von OpenAI. Das Konzept ähnelt Claude Code, allerdings verwendet er OpenAI-Modelle (GPT-4o, o3) und verfügt über 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 mit Codex ebenfalls über denselben npx-Befehl:

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

Am besten geeignet für: Headless-Stapeloperationen, CI/CD-Integration und Aufgaben, bei denen Sie eine zweite Einschätzung von einer anderen Modellfamilie wünschen. Im Sandbox-Modus führt Codex Code in isolierten Umgebungen aus. Das ist bei destruktiven Vorgängen hilfreich, etwa beim Ausführen von Testsuiten, die Zustände verändern.

Wichtigste Unterschiede zu Claude Code: - Verwendet OpenAI-Modelle anstelle von Claude-Modellen - Andere Größen der Kontextfenster und andere Token-Kostenmodelle - Sandbox-orientiertes Berechtigungsmodell (standardmäßig restriktiver) - Kleineres MCP-Ökosystem (weniger getestete Community-Server) - Hook-System verfügbar (ab v0.119.0+), aber weniger ausgereift als das von Claude Code – weniger Ereignistypen und kein bedingtes if-Feld

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

Verwenden Sie Codex, wenn Sie Modellvielfalt wünschen – lässt man einen zweiten Agenten den vom ersten geschriebenen Code prüfen, werden andere Fehlerklassen erkannt. Der Collab-Arbeitsablauf (Claude entwickelt, Codex prüft) ist für iOS wirkungsvoll, weil SwiftUI-Muster, die einer Modellfamilie korrekt erscheinen, subtile Probleme enthalten können, die eine andere erkennt. Besonders Metal-Shader und Nebenläufigkeitsmuster profitieren von einer Prüfung durch zwei Modelle.

3. Native Agenten in Xcode 26.3

Was es ist: Apple hat KI-Programmieragenten direkt in Xcodes Intelligence-Bereich integriert. Ab Xcode 26.3 können Sie Claude Agent und Codex unter Xcode Settings > Intelligence als Intelligence-Anbieter konfigurieren.¹⁰ Xcode 26.6 erweitert die Auswahl: Google Gemini ist nun im Programmierassistenten verfügbar (171990272), außerdem unterstützt Xcode das Agent Client Protocol (ACP) (178294840). Was als Integration zweier Anbieter begann, umfasst damit jetzt drei Anbieter sowie ein offenes Protokoll, über das sich jeder ACP-kompatible Agent in den Intelligence-Bereich einbinden lässt.¹⁷

Einrichtung:

1. Öffnen Sie Xcode 26.3+
2. Navigieren Sie zu Settings > Intelligence
3. Fügen Sie einen neuen Anbieter hinzu:
4. Für Claude: Wählen Sie „Claude Agent“ aus und geben Sie Ihren Anthropic-API-Schlüssel ein
5. Für Codex: Wählen Sie „Codex“ aus und geben Sie Ihren OpenAI-API-Schlüssel ein
6. Für Gemini: Wählen Sie „Google Gemini“ aus (ab Xcode 26.6)
7. Für alle anderen: Verbinden Sie einen ACP-kompatiblen Agenten (ab Xcode 26.6)
8. Der Agent erscheint in der Intelligence-Seitenleiste und kann direkt im Editor aufgerufen werden

Am besten geeignet für: Schnelle Änderungen direkt im Editor, Codevervollständigung mit Schlussfolgerungsfähigkeiten auf Agentenniveau und Entwickler, die Xcode nicht verlassen möchten. Durch die native Integration hat der Agent ohne MCP-Brücke direkten Zugriff auf Xcodes Projektkontext – geöffnete Dateien, Build-Targets und Scheme-Konfigurationen.

Einschränkungen gegenüber CLI-Agenten: - Kein Hook-System – Sie können weder die Formatierung beim Speichern erzwingen noch Schreibzugriffe auf .pbxproj blockieren - CLAUDE.md wird nicht geladen – der Agent liest Ihre Konfigurationsdateien auf Projektebene nicht - Begrenzte Autonomie – der Agent arbeitet an der aktuellen Datei oder Auswahl, nicht am gesamten Projekt - Keine Delegierung an Subagenten – komplexe mehrstufige Aufgaben können nicht parallelisiert werden - Keine Konfiguration von MCP-Servern – der Agent verwendet ausschließlich die integrierten Tools von Xcode

Wann Sie native Xcode-Agenten verwenden sollten:

Für schnelle, klar abgegrenzte Änderungen, bei denen der Wechsel zum Terminal unnötigen Aufwand verursacht. „Fügen Sie diesem Modell eine berechnete Eigenschaft hinzu.“ „Schreiben Sie einen Unit-Test für diese Funktion.“ „Refaktorieren Sie diese View für die Verwendung von @Observable.“ Solche Aufgaben betreffen eine oder zwei Dateien und erfordern keinen Build-Test-Zyklus.

Verwenden Sie für alle Aufgaben, die Builds, Tests, Refaktorierungen über mehrere Dateien hinweg oder eine autonome Fehlerkorrektur erfordern, einen CLI-Agenten mit MCP.

Vergleichsmatrix der Runtimes

Empfehlung: Verwenden Sie Claude Code CLI als primäre Runtime. Nutzen Sie native Xcode-Agenten für schnelle Änderungen direkt im Editor und Codex CLI für Prüfungsdurchläufe und Stapeloperationen. Die drei ergänzen einander, statt miteinander zu konkurrieren.

MCP-Einrichtung: Die vollständige Konfiguration

MCP (Model Context Protocol) verwandelt einen Agenten, der „Swift schreibt und hofft, dass Sie es bauen“, in einen Agenten, der „Swift schreibt, es baut, strukturierte Fehler ausliest und sie behebt“.² Dieser Abschnitt geht ausführlicher darauf ein als der Blogbeitrag¹¹ — behandelt werden beide Server, sämtliche Installationsmethoden, die Verifizierung und die Agentenkonfiguration, die sicherstellt, dass die Tools tatsächlich verwendet werden.

XcodeBuildMCP: 82 Tools für die iOS-Entwicklung ohne Benutzeroberfläche

XcodeBuildMCP bündelt xcodebuild, xcrun simctl und LLDB in 82 strukturierten MCP-Tools (laut ausgewiesenem Bestand, der von v2.6.2 bis v2.7.0 unverändert geblieben ist), die in 12 Workflow-Kategorien unterteilt sind.³¹⁹²¹ Die kanonische Heimat des Projekts ist die GitHub-Organisation getsentry — Sentry pflegt es, und die ursprüngliche URL cameroncooke/XcodeBuildMCP leitet inzwischen dorthin weiter. Das ist relevant, wenn ältere Artikel die alte Adresse angeben.²¹ Das Projekt funktioniert auch ohne laufendes Xcode — der gesamte Build-Test-Debug-Zyklus wird ohne Benutzeroberfläche über Apples Kommandozeilentools ausgeführt. Zwei Hinweise zum Toolbestand sollten Sie kennen: Eine standardmäßige stdio-Sitzung stellt die rund zwei Dutzend Tools des Simulator-Workflows bereit und hält die übrigen aus dem Kontext Ihres Agenten heraus — legen Sie XCODEBUILDMCP_ENABLED_WORKFLOWS fest (durch Kommas getrennte Kategorienamen aus der nachstehenden Tabelle), um weitere zu laden. Dieselbe Engine wird außerdem als CLI ausgeliefert (xcodebuildmcp tools meldet 100 Befehle, davon 72 kanonische), falls Sie identische Vorgänge ohne MCP ausführen möchten.⁹

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

Mit dem Flag -s user ist der Server global in allen Projekten verfügbar. Lassen Sie es für eine projektspezifische Installation weg (sinnvoll, wenn Sie MCP nur in iOS-Projekten und nicht in Webprojekten verwenden möchten).

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

Toolbestand (82 Tools in 12 Workflow-Kategorien — repräsentative Tools je Kategorie):

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

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

2. test_sim — Gibt die Ergebnisse für jede einzelne Testmethode zurück. Der Agent weiß genau, welcher Test fehlgeschlagen ist und weshalb, statt lediglich „Tests fehlgeschlagen“ zu melden.

3. list_sims + boot_sim — Simulatorverwaltung, ohne dass Sie sich die Flags von xcrun simctl merken müssen. Der Agent ermittelt die verfügbaren Laufzeitumgebungen und wählt ein geeignetes Gerät aus.

4. discover_projs + list_schemes — Projektanalyse. Der Agent muss weder den Namen Ihres Schemes noch die Struktur Ihres Workspaces erraten.

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

Was sich mit v2.6.0 geändert hat (2026-06-01) — UI-Laufzeitautomatisierung:

Mit Version v2.6.0 wurde die UI-Automatisierung grundlegend überarbeitet: An die Stelle einmaliger Screenshots trat wiederverwendbarer Kontext.¹⁹ snapshot_ui gibt jetzt stabile Elementreferenzen und einen Bildschirm-Hash zurück und akzeptiert sinceScreenHash, sodass der Agent auf einen vollständigen Snapshot verzichten kann, wenn sich der Bildschirm nicht geändert hat. Drei neue Tools schließen den Kreislauf: wait_for_ui prüft wiederholt, bis eine Bedingung erfüllt ist (Vorhandensein, aktivierter Zustand, Fokus, sichtbarer Text oder stabiles Layout), statt den Agenten die Wartezeit mit Pausen erraten zu lassen; batch führt eine Folge von Aktionen mit Elementreferenzen in einem einzigen Aufruf aus; drag ermöglicht Ziehgesten mit Elementreferenzen für Sheets und das Scrollen in Listen. type_text erhielt replaceExisting, um den Wert eines Felds zu ersetzen, statt Text daran anzuhängen. Mögliche Steuerelemente werden anhand von Bedienungshilfedaten gewichtet, und strukturierte Ergebnisse enthalten nun nextSteps-Hinweise (die Ergebnisschemas wurden in dieser Version auf v2 angehoben; v2.7.0 hat Build-/Testergebnisse inzwischen auf schemaVersion: 3 umgestellt — siehe unten). Setzen Sie XCODEBUILDMCP_HEADLESS_LAUNCH=true, um Apps im Hintergrund zu starten, ohne den macOS-Fokus zu übernehmen — das entscheidet darüber, ob Sie eine Agentensitzung unbeaufsichtigt laufen lassen können oder ob Ihr Simulatorfenster ständig in den Vordergrund springt. Bei einer deterministischen Aufgabe mit einer Wetter-App weist der projekteigene Benchmark gegenüber dem Ablauf vor Version 2.6 eine um etwa 70 % kürzere Gesamtlaufzeit, 68 % weniger Tokens und 76 % weniger Toolaufrufe aus. Das sind die Zahlen des Projekts und keine unabhängige Messung, doch der Mechanismus (unveränderte Snapshots überspringen, Aktionen auf demselben Bildschirm bündeln) entspricht genau der Stelle, an der UI-Automatisierung Tokens verbraucht.¹⁹

Was sich mit v2.7.0 geändert hat (2026-07-23) — Xcode-27-Simulatoren, Schema v3 und Scheme-konforme Builds:

Version v2.7.0 fällt kleiner aus als 2.6.0, bringt jedoch eine inkompatible Änderung und eine Verhaltensänderung mit, die Sie vor dem Upgrade kennen sollten.²¹ Die wichtigste Neuerung: UI-Automatisierungstools funktionieren über Device Hub jetzt vollständig mit Xcode-27-Simulatoren, einschließlich des Öffnens von Simulatorfenstern und der Tastatursteuerung. Damit wird die Lücke geschlossen, durch die die UI-Laufzeitautomatisierung nur mit Xcode-26-Simulatoren zuverlässig funktionierte. Inkompatible Änderung: Build- und Testtools geben jetzt strukturierte Ergebnisse mit schemaVersion: 3 zurück (seit 2.6.0 war es v2) — von Ihnen geschriebener Code, der auf Version 2 festgelegte Ergebnisse validiert oder verarbeitet, muss aktualisiert werden. Verhaltensänderung: Wenn configuration fehlt, berücksichtigen Build-, Test-, Bereinigungs- und App-Pfad-Tools nun die Konfiguration der Scheme-Aktion, statt grundsätzlich Debug zu verwenden. Ist die Test-Aktion eines Schemes auf Release eingestellt, baut ein nicht weiter qualifiziertes test_sim jetzt Release. Übergeben Sie deshalb configuration ausdrücklich, wenn Ihr Workflow von einer bestimmten Konfiguration abhängt. Kleinere, aber nützliche Neuerungen: Wiederverwendbare .xctestproducts-Testvorbereitungspakete ermöglichen die erneute Ausführung von Tests ohne einen neuen Build, wobei bei jedem Durchlauf weiterhin eine neue .xcresult-Datei erzeugt wird; mit extraArgs in den Sitzungsvorgaben können Sie gemeinsame xcodebuild-Flags einmal pro Sitzung festlegen, statt sie bei jedem Aufruf zu wiederholen; der neue CLI-Befehl xcodebuildmcp purge meldet und bereinigt den Workspace-Speicher von XcodeBuildMCP (standardmäßig als Probelauf; für das Löschen ist eine ausdrückliche Zustimmung erforderlich); außerdem wurde ein Fehler behoben, durch den MCP-Clients 10–17 Sekunden darauf warteten, dass Tools verfügbar wurden — kurze Integritätsprüfungen konnten deshalb fälschlicherweise eine fehlgeschlagene Verbindung melden.²¹

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

Apples MCP-Server wird mit Xcode 26.3 über xcrun mcpbridge ausgeliefert.⁴ Er kommuniziert über XPC (Apples Framework für die Interprozesskommunikation) mit einem laufenden Xcode-Prozess und stellt interne Zustände bereit, auf die 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, schlägt jeder MCP-Aufruf über diesen Server fehl oder bleibt hängen. XcodeBuildMCP unterliegt dieser Einschränkung nicht.

Toolbestand (20 Tools in 5 Kategorien):

Tools, die ausschließlich in Apple MCP verfügbar sind (nicht in XcodeBuildMCP):

1. DocumentationSearch — Durchsucht Apples Entwicklerdokumentation einschließlich WWDC-Sitzungen. Bei Fragen zu Apple API ist dies schneller und zuverlässiger als eine Websuche. Fragen Sie „Ist HKQuantityType(.dietaryWater) gültig?“ und erhalten Sie eine eindeutige Antwort direkt von der Quelle.

2. ExecuteSnippet — Führt Swift REPL im Projektkontext aus. Der Agent kann das Verhalten von API überprüfen, Typumwandlungen testen und Ausdrücke validieren, ohne die vollständige App zu bauen.

3. RenderPreview — Rendert SwiftUI-Vorschauen ohne Benutzeroberfläche. Der Agent kann prüfen, ob eine Ansicht fehlerfrei gerendert wird, jedoch nicht deren visuelle Korrektheit beurteilen (das Rendering wird als Daten zurückgegeben und nicht visuell geprüft). Seit Xcode 26.6 rendert das Vorschau-MCP-Tool (in den Versionshinweisen zu 26.6 „Preview Snapshot“ genannt) Varianten — helle/dunkle Darstellung, Hoch-/Querformat und Überschreibungen der Schriftgröße (178831772) — sodass ein Agent eine Ansicht in einem Durchlauf über mehrere Darstellungen hinweg prüfen kann.¹⁷ Die Betaversion von Xcode 27 erweitert dies um das Rendern von Preview-Gruppen und Vorschauen in einer anderen Lokalisierung.¹⁸

4. XcodeListNavigatorIssues — Gibt Echtzeitdiagnosen aus dem Xcode-Analyzer zurück und nicht nur Build-Fehler. Das Tool erkennt Probleme wie ungenutzte Variablen, potenzielle Retain Cycles und Veraltungswarnungen, die das Build-System nicht ausgibt.

Warum Sie beide Server benötigen

Bei Builds und Tests überschneiden sie sich, unterscheiden sich jedoch grundlegend:

┌─────────────────────────────────────────────────────────────────┐
│                     MCP TOOL COVERAGE                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  XcodeBuildMCP (82 tools)        Apple Xcode MCP (20 tools)    │
│  ┌─────────────────────┐         ┌─────────────────────┐       │
│  │ Standalone           │         │ Requires Xcode      │       │
│  │ (no Xcode process)  │         │ (XPC bridge)        │       │
│  │                     │         │                     │       │
│  │ ✓ Simulators        │  BOTH   │ ✓ Documentation     │       │
│  │ ✓ Real devices      │ ┌─────┐ │ ✓ Swift REPL        │       │
│  │ ✓ LLDB debugging    │ │Build│ │ ✓ SwiftUI previews  │       │
│  │ ✓ UI automation     │ │Test │ │ ✓ Live diagnostics  │       │
│  │ ✓ Project scaffold  │ └─────┘ │ ✓ Analyzer issues   │       │
│  │ ✓ Screenshot        │         │                     │       │
│  └─────────────────────┘         └─────────────────────┘       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

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

Verwenden Sie Apple Xcode MCP für: Dokumentationsabfragen, Swift-REPL-Prüfungen, das Rendern von SwiftUI-Vorschauen und Echtzeitdiagnosen. Lassen Sie Xcode während Sitzungen geöffnet, in denen Sie diese Funktionen benötigen.

In der Praxis: Ich verwende XcodeBuildMCP für etwa 90 % der MCP-Aufrufe und Apple Xcode MCP für Dokumentationsabfragen und REPL-Prüfungen. Für Builds und Tests verwendet der Agent standardmäßig XcodeBuildMCP, da es schneller (kein zusätzlicher Aufwand durch den Xcode-Prozess) und zuverlässiger (keine XPC-Abhängigkeit) ist.

Die klare Trennung in zwei Server wird zunehmend durchlässiger. XcodeBuildMCP 2.6.x ergänzt eine xcode-ide-Proxy-Kategorie: xcode_ide_list_tools ermittelt die ausschließlich in der Xcode-IDE verfügbaren MCP-Funktionen, und xcode_ide_call_tool ruft sie auf (sie erscheinen unter Namen mit xcode_tools_*, beispielsweise xcode_tools_documentationsearch). Dadurch kann eine einzige XcodeBuildMCP-Registrierung nun auch auf Apples IDE-seitige Tools zugreifen.¹⁹ Die entscheidende Einschränkung bleibt bestehen: Für diese Proxy-Aufrufe muss weiterhin ein Xcode-Prozess laufen, genau wie bei einer direkten Registrierung von xcrun mcpbridge. Lassen Sie beide Server registriert, wenn Apples Tools als eigenständige Einträge in der Toolliste des Agenten erscheinen sollen. Der Proxy ist vor allem dann nützlich, wenn Sie nur einen Servereintrag und lediglich gelegentliche IDE-Zugriffe wünschen.

Verifizierung

Vergewissern Sie sich nach der Installation beider Server, dass sie verbunden sind:

# List all configured MCP servers
claude mcp list

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

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

1. XcodeBuildMCP stellt keine Verbindung her: Vergewissern Sie sich, dass Node.js installiert ist (node --version). Der Befehl npx erfordert Node.js 18+.
2. Apple Xcode MCP stellt keine Verbindung her: Vergewissern Sie sich, 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 Verwendung von MCP beibringen

Die Installation der MCP-Server ist notwendig, reicht jedoch nicht aus. Ohne ausdrückliche Anweisung greift der Agent möglicherweise darauf zurück, xcodebuild über Bash auszuführen (unstrukturierte Ausgabe, verschwendete Kontext-Tokens) oder die Apple-Dokumentation über eine Websuche abzufragen (langsamer und weniger zuverlässig).

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

## Build & Test — Always Use MCP

Prefer MCP tools over raw shell commands for ALL build operations:

- **Build**: `build_sim` / `build_device` (NOT `xcodebuild` via Bash)
- **Test**: `test_sim` / `test_device` (NOT `xcodebuild test` via Bash)
- **Simulators**: `list_sims`, `boot_sim`, `open_sim` (NOT `xcrun simctl` via Bash)
- **Debug**: `debug_attach_sim`, `debug_stack`, `debug_variables`
- **Apple docs**: `DocumentationSearch` (NOT WebSearch for Apple APIs)
- **Swift verification**: `ExecuteSnippet` (NOT `swift` via Bash)
- **Previews**: `RenderPreview` for headless SwiftUI verification

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

Diese Anweisung sorgt dafür, dass der Agent zuerst auf MCP-Tools zurückgreift. Ohne sie werden Sie beobachten, wie der Agent lange xcodebuild-Befehle über Bash zusammensetzt, beim Verarbeiten der Ausgabe Tausende Kontext-Tokens verbraucht und bisweilen den eigentlichen Fehler falsch identifiziert.⁶

Eine Verhaltensänderung in XcodeBuildMCP v2.7.0 gehört zum grundlegenden Verständnis dieses Abschnitts: Fehlt configuration, berücksichtigen Build-, Test-, Bereinigungs- und App-Pfad-Tools jetzt die Konfiguration der Scheme-Aktion, statt stets Debug zu verwenden.²¹ Die meisten Schemes werden in Debug ausgeführt und getestet, sodass die meisten Projekte keinen Unterschied feststellen werden. Ist die Aktion eines Schemes jedoch auf Release eingestellt (üblich bei Profiling-Schemes oder Konfigurationen in der Nähe von Archivierungsworkflows), baut ein nicht weiter qualifiziertes build_sim oder test_sim jetzt Release. Falls Ihre CLAUDE.md oder Ihre Hooks Debug-Artefakte voraussetzen, geben Sie dies entweder ausdrücklich im Toolaufruf an oder legen Sie es mit session_set_defaults einmal pro Sitzung fest.

Lang laufende Builds: Claude Code verschiebt sie jetzt in den Hintergrund

Zwei Claude Code-Versionen haben verändert, wie ein lang laufender Build innerhalb einer Sitzung abläuft. Seit v2.1.212 (2026-07-16) wird jeder MCP-Toolaufruf, der länger als 2 Minuten dauert, automatisch in den Hintergrund verschoben, damit die Sitzung weiter nutzbar bleibt. Der Schwellenwert lässt sich über CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS konfigurieren; darüber kann das Verhalten auch deaktiviert werden.²⁰ Saubere Builds und vollständige Testläufe über build_sim / test_sim überschreiten bei realen Projekten regelmäßig die 2-Minuten-Grenze. Rechnen Sie daher damit, dass der Agent weiterarbeitet — Dateien liest und die nächste Änderung plant —, während der Build im Hintergrund abgeschlossen wird, anstatt die aktuelle Ausführung zu blockieren. Die zugehörige Korrektur ist ebenso wichtig: Vor v2.1.206 (2026-07-09) wurde ein über --mcp-config oder .mcp.json konfiguriertes serverspezifisches request_timeout_ms in neuen Sitzungen ignoriert, sodass lange MCP-Aufrufe nach dem Standardzeitlimit von 60 Sekunden abgebrochen wurden. Das klassische Symptom war ein Timeout beim ersten sauberen Build, das sich beim erneuten Versuch „von selbst behob“.²⁰ Falls Sie eines dieser Verhaltensmuster mit Wrapper-Skripten oder vorab aufgewärmten Builds umgangen haben, können Sie diese Zwischenlösung entfernen.

CLAUDE.md-Muster für iOS-Projekte

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

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

Die wesentlichen Abschnitte

Jede iOS-CLAUDE.md braucht diese sechs Abschnitte. Alles Weitere ist optional.

1. Projektidentität

# Return - Zen Focus Timer

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

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

2. Dateistruktur mit Zweckannotationen

## File Structure

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

Die Inline-Kommentare nach jedem Dateinamen sind keine Dekoration. Sie sind die Dokumentation mit dem höchsten Hebel, die Sie schreiben können. Wenn der Agent entscheidet, wo er eine neue Funktion ergänzt, führen ihn diese Annotationen beim ersten Versuch zur richtigen Datei, statt dass er jede Datei lesen muss, um das Projektlayout zu verstehen.

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

3. Build- und Testbefehle

## Build & Test

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

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

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

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

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

4. Wichtige Muster und Regeln

## Key Patterns

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

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

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

Diese Muster verhindern, dass der Agent Inkonsistenzen einführt. Ohne explizite Musterdokumentation verwendet der Agent manchmal ObservableObject in einer Datei und @Observable in einer anderen oder erstellt einen neuen Einstellungsmechanismus, statt das vorhandene Settings.shared-Singleton zu nutzen.

5. Dinge, die der Agent niemals tun darf

## Rules

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

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

6. Framework-spezifischer Kontext

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

Für HealthKit-Apps:

## HealthKit Configuration

- Entitlement: `com.apple.developer.healthkit`
- Info.plist keys:
  - `NSHealthShareUsageDescription`: "Return reads your mindful minutes..."
  - `NSHealthUpdateUsageDescription`: "Return logs meditation sessions..."
- Category types: `HKCategoryType(.mindfulSession)`
- Authorization checked on every write (user can revoke at any time)
- HealthKit is unavailable on tvOS — guard with `#if canImport(HealthKit)`

Für SwiftData-Apps:

## SwiftData Models

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

### Model Container Setup
- Configured in App struct with `modelContainer(for:)`
- Schema versioning: currently V2
- Migration plan: `GroceryMigrationPlan` handles V1 → V2

### Queries
- `@Query(sort: \GroceryItem.name)` for sorted fetches
- `@Query(filter: #Predicate { !$0.isCompleted })` for active items
- Always use `@Query` in views, `modelContext.fetch()` in managers

Für SpriteKit-Apps:

## SpriteKit Scene Hierarchy

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

- Physics categories defined in `PhysicsCategory.swift` as bitmasks
- Contact detection via `didBegin(_ contact:)` on GameScene
- Bullet pooling: pre-allocate 50, recycle via `removeFromParent()` + re-add

Für Metal-Apps:

## Metal Pipeline

- Render pipeline: `MetalView` → `Renderer` → `ShaderLibrary`
- Compute pipeline: `AudioAnalyzer` → compute shader → texture output
- Shared uniforms struct: `Uniforms` in `ShaderTypes.h` (bridged to Swift)
- Frame timing: `CADisplayLink` drives render loop
- Buffer triple-buffering: 3 in-flight frames with semaphore

### Shader Files
- `Shaders.metal` — Main render shaders (vertex + fragment)
- `Compute.metal` — Audio analysis compute kernel
- `PostProcess.metal` — Bloom and color grading

### DO NOT modify Metal shaders without testing on device.
Simulator Metal is not representative of device GPU behavior.

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

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

# Banana List - Grocery List App

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

## Core Features

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

## File Structure

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

## SwiftData Models

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

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

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

## Build & Test

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

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

## Key Patterns

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

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

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

## Rules

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

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

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

# Reps - Workout Tracking

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

## File Structure

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

## Build & Test

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

## SwiftData Relationships

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

## Rules

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

Das sind 40 Zeilen CLAUDE.md für ein Projekt mit 14 Dateien. Das Schreiben dauert 10 Minuten und erspart Stunden der Agentenverwirrung.

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

Spieleprojekte benötigen mehr Framework-spezifischen Kontext. Der Agent muss den Scene Graph, die Physics Categories und die Game State Machine verstehen:

# Starfield Destroyer - Space Shooter

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

## Game Overview

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

## File Structure

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

## SpriteKit Scene Hierarchy

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

## Physics Categories

```swift
struct PhysicsCategory {
    static let none:      UInt32 = 0
    static let player:    UInt32 = 0b1        // 1
    static let enemy:     UInt32 = 0b10       // 2
    static let bullet:    UInt32 = 0b100      // 4
    static let powerUp:   UInt32 = 0b1000     // 8
    static let shield:    UInt32 = 0b10000    // 16
    static let bossBullet:UInt32 = 0b100000   // 32
}

// Contact pairs:
// player + enemy → damage
// player + powerUp → collect
// bullet + enemy → destroy
// player + bossBullet → damage
```

## Game State Machine

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

## Metal Post-Processing

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

## Build & Test

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

## Rules

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

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

Metal-Projekte benötigen den meisten Framework-spezifischen Kontext, weil Agenten visuelle Ausgabe nicht verifizieren können:

# amp97 - Audio Visualizer

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

## Architecture

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

## File Structure

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

## Metal Pipeline

### Uniforms (ShaderTypes.h)
```c
typedef struct {
    float time;
    float2 resolution;
    float audioLevel;       // 0.0-1.0 RMS amplitude
    float frequencyBins[64]; // FFT output, normalized
    float4x4 transform;
} Uniforms;
```

### Render Pipeline
1. Compute pass: AudioCompute.metal processes FFT data → texture
2. Render pass: Shaders.metal reads texture + uniforms → visualization
3. Post-process pass: PostProcess.metal applies bloom → final output

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

## Rules

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

CLAUDE.md mit der Projektgröße skalieren

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

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

CLAUDE.md-Checkliste

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

• [ ] Bundle ID und Deployment Target angegeben
• [ ] Swift-Version und Architekturmuster benannt
• [ ] Dateistruktur mit Inline-Zweckannotationen
• [ ] Build-Befehl mit korrektem Scheme und korrekter Destination
• [ ] Testbefehl mit korrektem Scheme und korrekter Destination
• [ ] MCP-Präferenz vermerkt („prefer build_sim over xcodebuild“)
• [ ] @Observable-Regel (niemals ObservableObject)
• [ ] NavigationStack-Regel (niemals NavigationView)
• [ ] .pbxproj-Verbot
• [ ] Framework-spezifischer Kontext (HealthKit-Berechtigungen, SwiftData-Beziehungen, SpriteKit-Hierarchie, Metal-Pipeline)
• [ ] Platform Availability Guards dokumentiert (#if canImport, #if os)
• [ ] Wichtige Singletons und gemeinsame Muster dokumentiert
• [ ] Bekannte Einschränkungen oder Fallstricke vermerkt

Ihre erste Agenten-Session

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

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

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

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

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

Wenn der Agent nicht auf den Inhalt Ihrer CLAUDE.md Bezug nimmt, prüfen Sie, ob die Datei im Projekt-Root liegt (im selben Verzeichnis wie .xcodeproj oder Package.swift).

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

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

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

        Build succeeded. 63 source files compiled.
        2 warnings:
        - HomeView.swift:132 — UIScreen.main deprecated in iOS 26.0
        - LogWaterIntent.swift:61 — Result of try? is unused
        0 errors.

Schritt 3: Tests ausführen

You: Run all tests and report pass/fail.

Claude: [calls test_sim]

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

Schritt 4: Eine Funktion implementieren

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

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

        Added Rain theme:
        - Theme.swift: new `static let rain` with video, cover, ambient
        - ThemeManager.swift: added to `allThemes` array
        - Build: success (0 errors, 2 existing warnings)
        - Tests: 12/12 passed

        Note: You'll need to add rain_ambient.wav to the project
        and add the new Theme.swift changes to the Xcode target manually
        (I did not modify .pbxproj).

Der Hinweis des Agenten, .pbxproj nicht zu ändern, ist das Ergebnis der Regeln in CLAUDE.md. Ohne diese Regel würde der Agent versuchen, die Projektdatei zu ändern, und sie dabei wahrscheinlich beschädigen.

Was Agenten in iOS gut erledigen

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

SwiftUI-Views und Modifier

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

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

Beispiel-Prompt, der hervorragende Ergebnisse liefert:

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

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

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

SwiftData-Modelle und Queries

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

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

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

Unit Tests

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

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

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

Refactoring und Musteranwendung

Agenten sind hervorragend bei mechanischem Refactoring: Views in Komponenten extrahieren, ObservableObject in @Observable umwandeln, von NavigationView zu NavigationStack migrieren und konsistente Muster über mehrere Dateien hinweg anwenden.

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

Der Agent arbeitet jede Datei methodisch durch, wendet die Transformation korrekt an und erhält die bestehende Funktionalität. Das ist Arbeit mit hohem Hebel: Ein Refactoring, das manuell eine Stunde dauern würde, ist mit nahezu perfekter Genauigkeit in Minuten erledigt.

Build-Fehlerdiagnose über MCP

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

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

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

Simulator-Verwaltung

Agenten handhaben den Simulator-Lifecycle gut über MCP:

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

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

Was Agenten bei iOS schlecht können

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

Änderungen an .pbxproj-Dateien — NIEMALS

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

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

Was passiert, wenn ein Agent .pbxproj bearbeitet: 1. Der Edit scheint erfolgreich zu sein (der Agent meldet „file updated”) 2. Xcode weigert sich, das Projekt zu öffnen („The project file is corrupted”) 3. Sie verbringen 15–60 Minuten damit, den Stand aus der Git-Historie wiederherzustellen 4. Sie lernen, den PreToolUse-Hook hinzuzufügen (siehe Hooks)

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

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

Komplexe Interface-Builder- / Storyboard-Edits

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

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

Performance-Optimierung

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

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

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

Die Gegenmaßnahme: Verwenden Sie Agenten für die Implementierung, profilen Sie manuell mit Instruments, und bitten Sie den Agenten anschließend, die konkret von Ihnen identifizierten Optimierungen umzusetzen.

Code Signing und Provisioning

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

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

Was der Agent nicht sehen kann: Ob Ihr Zertifikat abgelaufen ist, ob das Provisioning Profile das Gerät enthält, ob die Bundle ID zur App ID passt oder ob Ihre Entitlements-Datei korrekt ist.

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

Komplexes Metal-Shader-Debugging

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

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

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

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

Visuelle Layout-Verifikation

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

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

Hooks für die iOS-Entwicklung

Hooks sind Shell-Befehle, die an bestimmten Punkten im Workflow des Agenten deterministisch ausgeführt werden. Sie dienen als Durchsetzungsmechanismus – und machen den Unterschied zwischen „Bitte bearbeiten Sie .pbxproj nicht“ (eine Empfehlung, die der Agent möglicherweise ignoriert) und „Sie können .pbxproj nicht bearbeiten“ (eine harte Sperre).

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

PreToolUse: Schreibzugriffe auf .pbxproj blockieren

Der wichtigste Hook in jedem iOS-Projekt. Er verhindert, dass der Agent in .pbxproj-Dateien, .xcodeproj/-Verzeichnisse und andere von Xcode verwaltete Dateien schreibt:

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

Legen Sie dies im Projektstamm unter .claude/settings.json oder für einen globalen Schutz unter ~/.claude/settings.json ab.

Funktionsweise: Wenn der Agent versucht, das Tool Edit oder Write für eine Datei zu verwenden, die dem Muster entspricht, wird der Hook ausgeführt. Er erkennt den Dateipfad, gibt eine Warnung über stderr aus und beendet sich mit Code 2, wodurch die Tool-Nutzung blockiert wird. Der Agent erhält die Fehlermeldung und passt seine Vorgehensweise an.

Was der Hook erfasst: - Direkte Änderungen an .pbxproj - Alle Dateien innerhalb von .xcodeproj/- oder .xcworkspace/-Verzeichnissen - Interface-Builder-Dateien (.xib, .storyboard)

PostToolUse: Formatieren beim Speichern mit SwiftFormat

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

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

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

Warum das wichtig ist: Agenten erzeugen syntaktisch korrektes Swift, halten Formatierungskonventionen jedoch nicht durchgängig ein. SwiftFormat vereinheitlicht Einrückungen, die Platzierung von Klammern und die Reihenfolge von Importen.⁸ Durch den Hook zum Formatieren beim Speichern wird jede vom Agenten bearbeitete Swift-Datei automatisch formatiert, bevor Sie sie sehen.

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

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

PostToolUse: SwiftLint automatisch ausführen

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

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

|| true verhindert, dass Lint-Warnungen den Agenten blockieren. Sollen Lint-Verstöße die Ausführung blockieren, entfernen Sie es.

PostToolUse: Nach Änderungen automatisch bauen

Für besonders kurze Feedbackschleifen können Sie nach jeder Änderung an einer Swift-Datei einen Build auslösen:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.swift$\"; then xcodebuild -scheme Return -destination \"platform=iOS Simulator,name=iPhone 16 Pro\" build 2>&1 | tail -5; fi'"
      }
    ]
  }
}

Warnung: Das ist ressourcenintensiv. Jede Dateibearbeitung löst einen Build aus. Setzen Sie diese Funktion sparsam ein – am nützlichsten ist sie während Debugging-Sitzungen, in denen Sie sofortiges Build-Feedback benötigen. Bei der normalen Entwicklung sollten Sie den Agenten Builds manuell über MCP auslösen lassen, sobald er bereit ist.

PreToolUse: Änderungen an Entitlements blockieren

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

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.entitlements$\"; then echo \"BLOCKED: Do not modify entitlements files without explicit permission.\" >&2; exit 2; fi'"
      }
    ]
  }
}

Kombinierte iOS-Hook-Konfiguration

Hier sehen Sie 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 Xcode-Projektdateien nicht beschädigen (PreToolUse-Sperre) 2. Jede vom Agenten bearbeitete Swift-Datei wird automatisch formatiert (PostToolUse-Formatierung)

Architekturmuster, die gut mit Agents funktionieren

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

@Observable (niemals ObservableObject)

Für iOS 26+ sollten Sie ausschließlich @Observable verwenden. Dies ist sowohl das moderne als auch das Agent-freundliche 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 Agent-freundlich ist: Das Muster ist einfacher (keine @Published-Annotationen erforderlich), das Besitzmodell ist klarer (@State statt @StateObject bzw. @ObservedObject) und Agents verursachen damit weniger Fehler, weil es weniger bewegliche Teile gibt.

Dokumentieren Sie dies in CLAUDE.md: Selbst wenn iOS 26 das Ziel ist, greifen Agents gelegentlich auf ObservableObject-Muster aus ihren Trainingsdaten zurück. Ein ausdrückliches 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 seit iOS 16 verfügbar und das einzige Navigationsmuster, das Sie für neuen Code verwenden sollten. Das typsichere Muster navigationDestination(for:) verhindert, dass der Agent fehlerhafte Navigationslinks erstellt.

SwiftData für die Persistenz

SwiftData-Modelle sind das übersichtlichste Persistenzmuster für die Agent-gestü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 Ansichten für reaktive Daten: @Query var items: [GroceryItem] 4. Verwenden Sie modelContext.fetch() außerhalb von Ansichtscode 5. Für das Löschen von Beziehungen sind explizite Regeln erforderlich: .cascade, .nullify, .deny

Nebenläufigkeit mit Swift 6.2

Verwenden Sie für neue Projekte die strikte Nebenläufigkeit von Swift 6.2. Dabei handelt es sich um eine Wahl des Sprachmodus, nicht der Toolchain-Version — sowohl der Swift-6.3-Compiler im stabilen Xcode 26.6 als auch Swift 6.4 in der Xcode-27-Beta erstellen diese Muster unverändert:¹⁷¹⁸

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

Hinweise für Agents zur Nebenläufigkeit: - Kennzeichnen Sie alle Ansichtsmodelle mit @MainActor (verhindert Warnungen vor Datenrennen) - Verwenden Sie async/await für sämtliche asynchronen Aufgaben (keine Completion Handler) - Machen Sie Werttypen für Übertragungen zwischen Actors zu Sendable - Verwenden Sie Task { } in Ansichten für die asynchrone Initialisierung - Verwenden Sie nonisolated nur, wenn Messungen einen entsprechenden Leistungsbedarf ergeben haben

Liquid Glass-Designsystem (iOS 26+)

Mit iOS 26 wurde das Liquid Glass-Designsystem eingeführt. Agents können gut damit umgehen, wenn sie explizite Anweisungen 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()

Nehmen Sie Folgendes in CLAUDE.md auf: „Verwenden Sie .glassEffect() für Abschnittshintergründe und Kartencontainer. Navigationsleisten übernehmen in iOS 26 automatisch das Glass-Material. Erstellen Sie Glaseffekte nicht manuell mit benutzerdefinierten Materialien nach, sondern verwenden Sie den Systemmodifikator.“

Framework-spezifischer Kontext

Jedes Apple-Framework bringt besondere Aspekte für Agents mit sich. Dieser Abschnitt behandelt die Frameworks, die in den 8 Apps zum Einsatz kommen.

HealthKit

Verwendet von: Return, Water

HealthKit erfordert eine sorgfältige Handhabung von Berechtigungen 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
        }
    }
}

Regeln für Agents bei HealthKit: - Sichern Sie den Code immer mit HKHealthStore.isHealthDataAvailable() ab - Setzen Sie eine Autorisierung niemals voraus — prüfen Sie sie bei jedem Schreibvorgang - Verwenden Sie #if canImport(HealthKit) für plattformübergreifenden Code (HealthKit ist auf tvOS nicht verfügbar) - Speichern Sie Gesundheitsdaten niemals zusätzlich zu den von HealthKit bereitgestellten Daten lokal - Nehmen Sie sowohl NSHealthShareUsageDescription als auch NSHealthUpdateUsageDescription in Info.plist auf

SpriteKit

Verwendet von: TappyColor, Starfield Destroyer

Das Szenengraphmodell von SpriteKit erfordert explizite Anweisungen 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 Spielzustandsautomaten - Erstellen von HUD-Overlays

Schwächen von Agents bei SpriteKit: - Leistungskritische Spielschleifen (der Agent fügt unnötige Arbeit pro Frame hinzu) - Komplexe Physiksimulationen (für hohe Präzision ist benutzerdefinierte Physik besser geeignet als SKPhysicsBody) - Abstimmung von Partikeleffekten (visuell, erfordert Iterationen)

Metal

Verwendet von: amp97, Water, Starfield Destroyer

Metal ist das Framework, mit dem Agents die größten Schwierigkeiten haben. Das GPU-Programmiermodell unterscheidet sich grundlegend von CPU-seitigem Swift, und Agents können die visuelle Ausgabe nicht überprüfen.

## Metal Rules

- Shared types between Swift and Metal go in a bridging header (ShaderTypes.h)
- Triple buffer in-flight frames (semaphore with value 3)
- Test shaders on DEVICE, not simulator (Metal behavior differs)
- Compute shaders: threadgroup size must divide evenly into grid size
- Fragment shaders: output color must be in correct color space (sRGB or linear)
- DO NOT optimize shaders without Instruments GPU profiling data

Was Sie bei Metal-Projekten in CLAUDE.md aufnehmen sollten: - Die Definition der Uniforms-Struktur (wird gemeinsam von Swift und MSL verwendet) - Das Muster zur Einrichtung des Render-Pipeline-Zustands - Pufferindizes und deren Verwendungszwecke - Welche Shader vorhanden sind und welche Aufgabe sie jeweils erfüllen - Bekannte Präzisionsprobleme (half gegenüber float)

Live Activities

Verwendet von: Return

Live Activities erfordern eine spezifische Konfiguration, die Agents nach entsprechender Dokumentation gut umsetzen können:

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

Verwendet von: Starfield Destroyer

## Game Center

- Authentication: `GKLocalPlayer.local.authenticateHandler`
- Leaderboards: `GKLeaderboard.submitScore(_:context:player:leaderboardIDs:completionHandler:)`
- Achievements: `GKAchievement.report(_:withCompletionHandler:)` (takes `[GKAchievement]` array)
- Always check `GKLocalPlayer.local.isAuthenticated` before submitting
- Handle authentication failure gracefully (offline play must work)

Multi-Plattform-Muster

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

Organisation gemeinsam genutzten Codes

Shared/
├── MeditationSession.swift    # Data model (all platforms)
├── SessionStore.swift         # iCloud sync (all platforms)
└── SessionHistoryView.swift   # UI (adapts per platform)

Return/                        # iOS-specific
ReturnWatch Watch App/         # watchOS-specific
ReturnTV/                      # tvOS-specific

Regel für Agenten: “Wenn eine Datei in Shared/ liegt, wirken sich Änderungen auf alle Plattformen aus. Wenn eine Datei in einem Plattformverzeichnis liegt, sind Änderungen isoliert. Prüfen Sie immer, in welchem Verzeichnis eine Datei liegt, bevor Sie sie ändern.”

Guards für Plattformverfügbarkeit

// HealthKit: available on iOS and watchOS, not tvOS
#if canImport(HealthKit)
import HealthKit
// HealthKit code here
#endif

// ActivityKit: available on iOS only
#if canImport(ActivityKit)
import ActivityKit
// Live Activity code here
#endif

// WatchKit: available on watchOS only
#if os(watchOS)
import WatchKit
// Watch-specific code here
#endif

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

UI-Anpassung pro Plattform

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

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

Fortgeschrittene Workflows

Autonome Build-Test-Fix-Schleifen

Das wirkungsvollste Muster: Geben Sie dem Agenten eine Funktionsspezifikation und lassen Sie ihn eigenständig Build-Test-Fix-Zyklen durchlaufen.

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

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

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

Wann das funktioniert: Klar definierte Funktionen mit eindeutigen Akzeptanzkriterien.

Wann das scheitert: Offene Funktionen („make it look nice”), performancekritischer Code oder alles, was eine visuelle Überprüfung erfordert.

Subagent-Delegation für iOS

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

Use a subagent to research the best approach for implementing
iCloud key-value store sync for meditation sessions across iOS,
watchOS, and tvOS. Report back with the recommended pattern.

Der Subagent untersucht Dokumentation und Codemuster in einem separaten Kontextfenster, gibt eine Zusammenfassung zurück, und die Hauptsitzung implementiert die Empfehlung. So wird verhindert, dass Recherche Ihren primären Kontext aufbraucht.

Musterübertragung zwischen Apps

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

Look at how Settings.swift works in the Return project
(centralized singleton with validation). Apply the same pattern
to create a Settings.swift for the Water project.

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

Dual-Agent-Review (Claude + Codex)

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

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

# After Claude implements the feature:
codex "Review the changes in the last commit. Focus on Swift 6.2
      concurrency correctness, SwiftData relationship integrity,
      and potential retain cycles. Report issues only — no praise."

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

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

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

Batch-Operationen über mehrere Apps hinweg

Wenn eine Framework- oder Musteränderung mehrere Apps betrifft:

# Update @Observable pattern across all projects
for project in BananaList Return Water Reps; do
  cd ~/Projects/$project
  claude -p "Audit all files for any remaining ObservableObject usage.
             Convert to @Observable following the pattern in CLAUDE.md.
             Build and test after changes." --dangerously-skip-permissions
done

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

Apps, die Apples On-Device-LLM verwenden

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

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

import FoundationModels

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

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

Fallstudien aus der Praxis

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

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

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

Was der Agent gut gemacht hat: - Den vorhandenen iOS-TimerManager gelesen und einen TVTimerManager erstellt, der Live Activities und HealthKit ausließ (auf tvOS nicht verfügbar) - Eigene Schaltflächenstile für die Fokusnavigation mit Siri Remote erstellt (TVCapsuleButtonStyle, TVCircleButtonStyle) - Eine TVStepper-Komponente gebaut, die Wheel Picker (mit Siri Remote nicht nutzbar) durch +/- Schaltflächen ersetzt - Einstellungssynchronisierung über App Groups implementiert (group.com.941apps.Return) - Überall im gemeinsamen Code #if os(tvOS)-Guards hinzugefügt - Per MCP mit platform=tvOS Simulator,name=Apple TV gebaut und getestet

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

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

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

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

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

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

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

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

Die Aufgabe: Das Datenmodell von V1 auf V2 migrieren, mit einem neuen Feld quantity für GroceryItem und einem neuen Category-Modell mit Beziehungen.

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

Der Schlüssel: Der Agent war erfolgreich, weil SwiftData-Migrationen einem klar definierten Protokollmuster folgen, das in Apples Dokumentation und Trainingsdaten umfassend vertreten ist. Die CLAUDE.md dokumentierte das V1-Modell explizit, sodass der Agent verstand, wovon migriert wurde.

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

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

Was der Agent geliefert hat:

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

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

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

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

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

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

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

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

Projektlebenszyklus mit Agents

Ein neues iOS-Projekt starten

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

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

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

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

Ein bestehendes Projekt pflegen

Für die laufende Entwicklung etablierter Apps:

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

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

Die Effektivität des Agent skaliert damit, wie gut Ihre CLAUDE.md den aktuellen Projektstand widerspiegelt. Aktualisieren Sie Ihre CLAUDE.md, wenn Sie wichtige neue Funktionen hinzufügen, Architekturmuster ändern oder neue Frameworks einführen.

Wann Sie den Agent einbeziehen sollten und wann nicht

Agent-Definitionen konfigurieren

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

---
name: ios-developer
description: iOS development agent with MCP build tools and SwiftUI expertise
tools:
  - XcodeBuildMCP
  - xcode
---

# iOS Developer Agent

You are an iOS development agent for apps targeting iOS 26+ with SwiftUI.

## Architecture Rules
- @Observable for all view models (NEVER ObservableObject)
- NavigationStack for all navigation (NEVER NavigationView)
- SwiftData for persistence
- Swift 6.2 strict concurrency
- @MainActor on all Observable classes

## Build & Test — Always Use MCP

Prefer MCP tools over raw shell commands for ALL build operations:

- **Build**: `build_sim` / `build_device` (NOT `xcodebuild` via Bash)
- **Test**: `test_sim` / `test_device` (NOT `xcodebuild test` via Bash)
- **Simulators**: `list_sims`, `boot_sim`, `open_sim`
- **Debug**: `debug_attach_sim`, `debug_stack`, `debug_variables`
- **Apple docs**: `DocumentationSearch` (NOT WebSearch for Apple APIs)
- **Swift verification**: `ExecuteSnippet` (NOT `swift` via Bash)

MCP returns structured JSON. Bash returns unstructured text.

## File Management Rules
- NEVER modify .pbxproj, .xcodeproj/, .xcworkspace/, .xib, .storyboard
- Create Swift files in the correct directory
- Report files that need manual addition to Xcode targets

## SwiftData Rules
- @Model classes are automatically Observable — do not add @Observable
- Use @Bindable for form bindings to model properties
- Use @Query in views, modelContext.fetch() elsewhere
- Document relationship delete rules

## When You Get Stuck
- Build errors: use `build_sim` via MCP for structured output
- API questions: use `DocumentationSearch` via Apple MCP
- Swift verification: use `ExecuteSnippet` via Apple MCP
- Never guess — verify with tools

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

Testmuster für agentenunterstütztes iOS

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

Organisation von Testdateien

# In CLAUDE.md:
## Test Structure

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

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

Prompts für Tests

Effektiver Test-Prompt:

Write unit tests for TimerManager covering:

1. Initial state is .stopped with timeRemaining == selectedDuration
2. start() transitions state to .running
3. pause() from .running transitions to .paused
4. reset() from any state returns to .stopped with original duration
5. start() from .paused resumes (state becomes .running)
6. Edge case: reset() when already stopped is a no-op
7. Edge case: pause() when already paused is a no-op

Follow the existing test pattern in SettingsTests.swift.
Use setUp() to create a fresh TimerManager for each test.

Warum das funktioniert: Nummerierte Akzeptanzkriterien geben dem Agent eine Checkliste. Der Verweis auf eine vorhandene Testdatei etabliert das Muster. Die Vorgabe zur Verwendung von setUp() verhindert, dass der Agent verschachtelten Testzustand erzeugt.

Ineffektiver Test-Prompt:

Write tests for TimerManager.

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

Async-Testmuster

Für das Testen von timerbasiertem und asynchronem Code:

// Agent produces this pattern when guided correctly:
final class TimerManagerTests: XCTestCase {
    var sut: TimerManager!

    @MainActor
    override func setUp() {
        super.setUp()
        sut = TimerManager()
    }

    @MainActor
    func test_start_whenStopped_transitionsToRunning() {
        // Given
        XCTAssertEqual(sut.state, .stopped)

        // When
        sut.start()

        // Then
        XCTAssertEqual(sut.state, .running)
    }

    @MainActor
    func test_timerCountsDown_afterOneSecond() async throws {
        // Given
        sut.selectedDuration = 10
        sut.reset()
        sut.start()

        // When
        try await Task.sleep(for: .seconds(1.1))

        // Then
        XCTAssertLessThanOrEqual(sut.timeRemaining, 9.0)
    }
}

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

Snapshot Testing

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

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

Use SnapshotTesting library. Create reference images on first run.

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

Kontextfensterverwaltung für iOS-Projekte

Das Kontextfenster mit 1 Mio. Token (Opus 5) ist groß, aber nicht unbegrenzt. Bei iOS-Projekten gelten besondere Anforderungen an die Kontextverwaltung.

Token-Kosten von iOS-Dateien

Bei einem Projekt mit 50 Dateien: Das Einlesen aller Dateien verbraucht ungefähr 50.000–100.000 Token und liegt damit weit innerhalb des Kontextfensters von 1 Mio. Token. Der Agent kann das gesamte Projekt im Kontext behalten.

Bei einem Projekt mit mehr als 100 Dateien: Dateien müssen gezielt eingelesen werden. Der Agent liest zunächst CLAUDE.md mit den Anmerkungen zur Dateistruktur und anschließend bei Bedarf bestimmte Dateien. Deshalb sind Dateianmerkungen in CLAUDE.md unverzichtbar: Sie führen den Agenten zu den richtigen Dateien, ohne dass er alles einlesen muss.

Strategien für große Projekte

1. Detaillierte Dateianmerkungen in CLAUDE.md — Der Agent liest die Dateiübersicht und navigiert direkt zu den relevanten Dateien
2. Delegation an Subagenten — Übertragen Sie Erkundung und Recherche an Subagenten, die mit einem frischen Kontext arbeiten und Zusammenfassungen zurückgeben
3. Präzise Prompts — „Modify SettingsView.swift to add a new toggle“ ist besser als „update the settings“
4. Sitzungsgrenzen — Beginnen Sie für nicht zusammenhängende Funktionen neue Sitzungen, anstatt eine lange Sitzung immer weiterzuführen
5. /compact verwenden — Der Komprimierungsbefehl von Claude Code fasst die Unterhaltung zusammen und gibt Kontext frei

Token-Effizienz von MCP

Eines der stärksten Argumente für MCP: Strukturierte JSON-Antworten verbrauchen deutlich weniger Token als die unbearbeitete Ausgabe von xcodebuild.

In einer typischen Entwicklungssitzung mit 10–20 Build-Durchläufen spart MCP gegenüber der direkten Nutzung von xcodebuild 30.000–150.000 Token ein. Diese Token bleiben für die eigentliche Analyse des Codes verfügbar.

Fehlerbehebung

„build_sim failed — scheme not found“

Der Agent errät den Namen des Schemas. So beheben Sie das Problem:

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

Oder tragen Sie den Namen des Schemas ausdrücklich in Ihre CLAUDE.md ein:

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

„xcrun mcpbridge — command not found“

Sie benötigen Xcode 26.3 oder neuer. Prüfen Sie Ihre Version mit xcodebuild -version. Wenn Sie Xcode 26.3 oder neuer verwenden, der Befehl aber weiterhin fehlschlägt:

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

# Verify
xcrun mcpbridge --help

„MCP-Tools werden in Claude Code nicht angezeigt“

Während einer laufenden Sitzung registrierte MCP-Tools werden möglicherweise erst nach einem Neustart angezeigt. Beenden Sie Claude Code und starten Sie eine neue Sitzung:

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

Überprüfen Sie anschließend:

You: List all available MCP tools from XcodeBuildMCP.

„Der Agent verwendet weiterhin xcodebuild über Bash statt MCP“

Der Agent findet die MCP-Tools nicht über Tool Search. Dafür gibt es 2 Lösungen:

1. Fügen Sie CLAUDE.md ausdrückliche Anweisungen hinzu (siehe Dem Agenten die Verwendung von MCP beibringen)
2. Weisen Sie den Agenten direkt an: „Use the build_sim MCP tool, not xcodebuild via Bash“

„Der Build ist erfolgreich, aber der Agent meldet einen Fehler“

XcodeBuildMCP analysiert die Ausgabe von xcodebuild. Wenn der Build Warnungen erzeugt, die wie Fehler aussehen – was bei Hinweisen auf veraltete APIs häufig vorkommt –, interpretiert der Agent das Ergebnis möglicherweise falsch. Prüfen Sie das tatsächliche Statusfeld in der MCP-Antwort.

„Der Simulator hängt beim Start“

Beenden Sie alle Simulatoren und starten Sie sie neu:

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

Oder bitten Sie den Agenten darum:

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

„Der Agent hat trotz der Regeln in CLAUDE.md versucht, .pbxproj zu ändern“

Regeln in CLAUDE.md sind Empfehlungen. Hooks setzen Vorgaben durch. Wenn Sie keinen PreToolUse-Hook eingerichtet haben, der Schreibzugriffe auf .pbxproj blockiert, wird der Agent irgendwann versuchen, die Datei zu ändern. Installieren Sie den Hook:

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

Regeln sagen: „Bitte nicht.“ Hooks sagen: „Das ist nicht möglich.“

FAQ

Mit welcher Agent-Laufzeitumgebung sollte ich beginnen?

Claude Code CLI mit XcodeBuildMCP. Diese Kombination bietet die umfassendste MCP-Integration, das ausgereifteste Hook-System und ein Kontextfenster mit 1 Mio. Token (Opus 5), das vollständige iOS-Projekte im Arbeitsspeicher halten kann. Beginnen Sie damit und ergänzen Sie später Codex für Reviews sowie die nativen Xcode-Agenten für schnelle Inline-Änderungen, sobald sich Ihr Workflow weiterentwickelt.

Benötige ich beide MCP-Server?

Für die meisten Entwickler deckt XcodeBuildMCP allein 90 % des Bedarfs ab (Builds, Tests, Simulatoren und Debugging). Ergänzen Sie Apples Xcode MCP, wenn Sie die Dokumentationssuche, die Verifizierung mit Swift REPL oder das Rendern von SwiftUI-Vorschauen benötigen. Sie können ihn jederzeit später hinzufügen – die beiden Server arbeiten unabhängig voneinander.

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

XcodeBuildMCP enthält Scaffolding-Tools (scaffold_ios_project, scaffold_macos_project), die neue Xcode-Projekte aus Vorlagen erstellen. Für produktive Apps empfehle ich allerdings, das Projekt in Xcode anzulegen, damit Signierung, Capabilities und Target-Konfiguration korrekt eingerichtet werden, und anschließend Agenten für die gesamte Codeimplementierung einzusetzen. Die 5 Minuten, die Sie in den Assistenten für neue Xcode-Projekte investieren, ersparen Ihnen stundenlange Probleme mit agentengenerierten Projektkonfigurationen.

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

Gut. Package.swift ist eine standardmäßige Swift-Datei, die Agenten zuverlässig lesen und bearbeiten können. Das Hinzufügen von Abhängigkeiten, Aktualisieren von Versionsbereichen und Konfigurieren von Targets funktioniert problemlos. Die Einschränkung betrifft die Abhängigkeitsverwaltung auf Basis von .xcodeproj (die Benutzeroberfläche von Xcode zur Paketauflösung): Sie wird von Xcode verwaltet und sollte nicht von Agenten bearbeitet werden.

Können Agenten Apps beim App Store einreichen?

Nein. Für die Einreichung beim App Store sind der Organizer von Xcode, Bereitstellungsprofile, Screenshots, Metadaten und das App-Store-Connect-Portal erforderlich. Auf nichts davon können Agenten über MCP oder Befehlszeilentools so zugreifen, dass eine sinnvolle Bedienung möglich wäre. Agenten übernehmen alle Schritte bis zum Archiv: Implementierung, Tests, Fehlerbehebung und Dokumentation. Der letzte Schritt der Einreichung bleibt weiterhin Menschen vorbehalten.

Agenten können jedoch bei den App-Store-Metadaten helfen. Bitten Sie den Agenten, anhand der neuesten Änderungen die App-Beschreibung, Schlüsselwörter und den Text zu den Neuerungen zu verfassen. Bei solchen Aufgaben zur Textgenerierung spielen Agenten ihre Stärken aus.

Wie gehe ich bei der agentengestützten iOS-Entwicklung mit Geheimnissen und API-Schlüsseln um?

Committen Sie niemals Geheimnisse. Für iOS-Apps, die eine Verbindung zu Backend-APIs herstellen:

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

## Configuration

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

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

Der Agent weiß, dass die Schlüssel vorhanden sind und wo sie verwendet werden, sieht jedoch niemals deren tatsächliche Werte.

Wie sieht es mit SwiftUI-Animationen aus – können Agenten diese schreiben?

Agenten schreiben syntaktisch korrekten Animationscode, können das Ergebnis jedoch nicht visuell überprüfen. Einfache Animationen (.animation(.spring()), .transition(.slide), withAnimation { }) liefern korrekte Ergebnisse. Komplexe, mehrstufige Animationen mit präzisem Timing erfordern visuelle Iterationen, zu denen Agenten nicht in der Lage sind.

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

Ineffektiv: „Gestalten Sie die Timer-Animation so, dass sie sich befriedigend anfühlt.“ (Subjektiv und erfordert visuelle Feinabstimmung.)

Wie gehen Agenten mit Mustern zur Fehlerbehandlung um?

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

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

Agenten erstellen eine strukturierte Fehlerbehandlung mit geeigneten Meldungen für Benutzer. Manchmal behandeln sie Fehler übermäßig umfassend, indem sie Ausnahmen abfangen, die weitergereicht werden sollten. Prüfen Sie daher die Catch-Blöcke.

Kann ich Agenten für die Implementierung der Barrierefreiheit einsetzen?

Teilweise. Agenten fügen Beschriftungen, Hinweise und Eigenschaften für die Barrierefreiheit korrekt hinzu:

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

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

Wie gehen Agenten mit Core-Data-Migrationen um, wenn SwiftData nicht verwendet wird?

Agenten schreiben Migrationszuordnungen und Modellversionen für Core Data, die manuellen Schritte in Xcode – das Erstellen neuer Modellversionen und das Auswählen der aktuellen Version – lassen sich jedoch nicht automatisieren. Wenn Sie weiterhin Core Data statt SwiftData verwenden, dokumentieren Sie den Verlauf der Modellversionen in CLAUDE.md:

## Core Data Model Versions
- V1: Initial (GroceryList, GroceryItem)
- V2: Added Category model (current)
- Migration: Lightweight automatic for V1→V2

Wie gehen Agenten mit SwiftUI-Vorschauen um?

Dafür gibt es 2 Möglichkeiten: 1. Das Tool RenderPreview von Apple Xcode MCP rendert Vorschauen ohne Benutzeroberfläche und gibt das Ergebnis zurück. Der Agent kann überprüfen, ob eine Vorschau fehlerfrei kompiliert und gerendert wird, ihre visuelle Korrektheit jedoch nicht beurteilen. 2. Build-basierte Verifizierung über build_sim bestätigt, dass Preview-Provider kompiliert werden. Stürzt eine Vorschau zur Laufzeit ab, ist der Build dennoch erfolgreich – der Absturz tritt erst auf, wenn Xcode versucht, die Vorschau zu rendern.

Für die visuelle Überprüfung von Vorschauen müssen Sie Xcode weiterhin geöffnet haben.

Wie sieht es mit visionOS und Apple Vision Pro aus?

Es gelten dieselben Muster. XcodeBuildMCP unterstützt visionOS-Simulatoren, und die Architekturmuster (@Observable, NavigationStack, SwiftData) sind identisch. Für RealityKit-spezifischen Code (3D-Inhalte, immersive Räume und Hand-Tracking) gelten dieselben Einschränkungen wie für Metal: Agenten können korrekten Code schreiben, die räumliche Ausgabe jedoch nicht überprüfen.

Wie groß kann ein Projekt werden, bevor Agenten Schwierigkeiten bekommen?

Die Größe des Kontextfensters ist der begrenzende Faktor. Mit dem Kontextfenster von Opus 5 mit 1 Mio. Token kann Claude Code ungefähr 50–70 Swift-Dateien gleichzeitig im aktiven Arbeitsspeicher halten. Bei größeren Projekten arbeitet der Agent mithilfe der Dateisuche und des selektiven Lesens mit Teilmengen der Codebasis. Projekte mit mehr als 100 Dateien funktionieren problemlos – der Agent liest die Dateien lediglich bei Bedarf, anstatt alles im Kontext zu halten.

Die praktische Grenze liegt nicht in der Anzahl der Dateien, sondern in der Kohärenz der Codebasis. Ein gut dokumentiertes Projekt mit 200 Dateien und einer ausführlichen CLAUDE.md liefert bessere Ergebnisse als ein undokumentiertes Projekt mit 30 Dateien.

Muss ich Swift beherrschen, um Agenten für die iOS-Entwicklung einzusetzen?

Sie müssen die Ausgaben der Agenten prüfen und Architekturentscheidungen treffen können. Sie müssen nicht jede Zeile selbst schreiben, sollten Swift jedoch gut genug verstehen, um falsche Entscheidungen des Agenten zu erkennen – insbesondere bei Nebenläufigkeit, Speicherverwaltung und frameworkspezifischen Mustern. Ein Agent verstärkt Ihre vorhandenen Fähigkeiten um den Faktor 10, ersetzt sie aber nicht.

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

Agenten lösen Merge-Konflikte in Swift-Quelldateien zuverlässig. Die üblichen Konfliktmarkierungen (<<<<<<<, =======, >>>>>>>) werden von allen Agent-Laufzeitumgebungen verstanden. Merge-Konflikte in .pbxproj-Dateien müssen jedoch weiterhin manuell gelöst werden – bitten Sie Agenten nicht darum, .pbxproj-Konflikte zu beheben.

Welche Kosten entstehen beim Einsatz von Agenten für die iOS-Entwicklung?

Mit dem Max-Tarif von Anthropic (Opus 5, Kontextfenster mit 1 Mio. Token) dauert eine typische iOS-Entwicklungssitzung 30–120 Minuten und verarbeitet 200.000–800.000 Token. MCP-Tool-Aufrufe verursachen nur minimalen Zusatzaufwand, da strukturierte JSON-Antworten im Vergleich zu rohen Build-Ausgaben Token sparen. Die Kosten entsprechen ungefähr dem Einsatz von Claude Code für jede andere Codebasis – die iOS-Entwicklung ist weder nennenswert teurer noch günstiger als die Webentwicklung.

Kann ich Agenten mit UIKit-Projekten verwenden?

Ja, allerdings arbeiten Agenten mit SwiftUI effektiver. UIKit erfordert mehr Boilerplate-Code, besitzt eine weniger deklarative Struktur und umfasst häufig Interface-Builder-Dateien, die Agenten nicht bearbeiten können. Bei einem UIKit-Projekt sollten Sie erwägen, Agenten für die Modellebene und Geschäftslogik einzusetzen und die Benutzeroberfläche manuell zu bearbeiten oder Views schrittweise zu SwiftUI zu migrieren.

Wie gehen Agenten mit Lokalisierung um?

Agenten erstellen und bearbeiten .xcstrings-Dateien (Xcode-String-Kataloge) effektiv. Sie können neue Lokalisierungsschlüssel hinzufügen, Übersetzungen bereitstellen und die Konsistenz zwischen Sprachen wahren. Das strukturierte JSON-Format von .xcstrings-Dateien eignet sich gut für Agenten. Auch mit .strings-Dateien (dem Legacy-Format) arbeiten Agenten zuverlässig – das Schlüssel-Wert-Format ist unkompliziert.

Häufige Fehler von Agents bei iOS (und wie Sie sie vermeiden)

Dies sind die wiederkehrenden Fehler, die ich bei Tausenden von Agent-Interaktionen in 8 iOS-Projekten beobachtet habe. Für jeden gibt es eine Strategie zur Vermeidung.

Fehler 1: Observable-Muster vermischen

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

Vermeidung: Eindeutige Regeln in CLAUDE.md:

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

Fehler 2: Retain Cycles in Closures erzeugen

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

Vermeidung: Nehmen Sie ein Closure-Muster in CLAUDE.md auf:

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

Fehler 3: @MainActor-Anforderungen ignorieren

Was passiert: Der Agent erstellt @Observable-Klassen ohne @MainActor-Isolation. Dadurch entstehen Nebenläufigkeitswarnungen in Swift 6.2 oder Laufzeitabstürze, wenn UI-Aktualisierungen außerhalb des Hauptthreads erfolgen.

Vermeidung:

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

Fehler 4: NavigationLink mit Destination-Closure verwenden

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

Vermeidung:

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

Fehler 5: Simulatornamen fest codieren

Was passiert: Der Agent schreibt Build-Befehle mit bestimmten Simulatornamen („iPhone 16 Pro“), die auf Ihrem System möglicherweise nicht vorhanden sind.

Vermeidung: MCP übernimmt dies – list_sims ermittelt die verfügbaren Simulatoren. In CLAUDE.md:

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

Fehler 6: Dateien in falschen Verzeichnissen erstellen

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

Vermeidung: Die Dateistrukturanmerkungen in CLAUDE.md geben die richtige Platzierung vor. Zusätzlich:

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

Fehler 7: Plattformverfügbarkeit nicht berücksichtigen

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

Vermeidung:

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

Fehler 8: Einfache Funktionen unnötig komplex gestalten

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

Vermeidung: Nehmen Sie ein Einfachheitsprinzip auf:

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

Die ehrliche Einschätzung

Nach der Veröffentlichung von 8 iOS-Apps mit AI Agents lässt sich Folgendes zusammenfassen:

Was Agents grundlegend verändert haben: Die Implementierungsgeschwindigkeit. Was früher Tage dauerte, dauert heute Stunden. SwiftUI-Views, SwiftData-Modelle, Unit-Tests und Refactorings werden inzwischen überwiegend von Agents erstellt und von Menschen überprüft.

Was Agents nicht grundlegend verändert haben: Architekturentscheidungen, visuelles Design, Leistungsoptimierung oder die Einreichung im App Store. Diese Bereiche bleiben in menschlicher Hand.

Der Multiplikatoreffekt ist real, aber begrenzt. Meine subjektive Einschätzung für das Portfolio aus 8 Apps: Bei gut dokumentierten Projekten mit ordnungsgemäßer MCP- und Hook-Konfiguration verkürzt sich die Zeit bis zur fertigen Funktion um den Faktor 3 bis 5. Dieser Wert wurde nicht anhand einer Kontrollgruppe ermittelt, sondern basiert auf einem Vergleich der tatsächlich benötigten Zeit zwischen Agent-gestützten Funktionen und entsprechenden, allein umgesetzten Arbeiten in denselben Codebasen. Bei undokumentierten Projekten ohne Hooks liegt die Verbesserung vielleicht beim Faktor 1,5 bis 2 – der Agent verbringt zu viel Zeit mit Vermutungen, statt etwas zu entwickeln.³¹

Die Investition, die sich auszahlt: Zeit für die Konfiguration von CLAUDE.md, Hooks und MCP. Jede Stunde für die Einrichtung spart viele Stunden bei der Korrektur von Agent-Fehlern. Die Konfiguration ist das Produkt – der Agent ist die Ausführungsengine.

Was mich überrascht hat: Wie stark die MCP-Server die Zusammenarbeit verändert haben. Vor MCP waren Agents ausgefeilte Texteditoren, die zufällig Swift verstanden. Mit MCP sind sie Entwicklungspartner, die Code schreiben, Builds erstellen, Tests ausführen, Fehler beheben und iterieren. Der strukturierte Feedback-Zyklus macht den Unterschied zwischen einem Agent, der Code schreibt, und einem, der Code ausliefert.

Was ich meinem früheren Ich raten würde: Beginnen Sie mit der kleinsten App (Reps, 14 Dateien), richten Sie MCP und die Hooks richtig ein, schreiben Sie eine ausführliche CLAUDE.md und übertragen Sie die Muster anschließend auf größere Projekte. Starten Sie nicht mit der plattformübergreifenden App aus 63 Dateien. Der Aufwand für die Infrastruktur ist unabhängig von der Projektgröße gleich – erledigen Sie ihn einmal bei einem kleinen Projekt und übernehmen Sie die Konfiguration anschließend für alle anderen.

Die Zukunft: Die native Agent-Integration von Xcode 26.3 ist der Anfang, nicht das Ende. Dass Apple MCP-Unterstützung bereitstellt, zeigt, dass sich die Toolchain in Richtung einer Agent-First-Entwicklung bewegt. Entwickler, die jetzt in Agent-kompatible Projektstrukturen investieren – übersichtliche CLAUDE.md-Dateien, testbare Architekturen und automatisierte Hooks –, werden mit jeder Verbesserung der Tools stärker von dieser Investition profitieren.

Kurzreferenz

Installation (einmalige Einrichtung)

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

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

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

# Verify
claude mcp list

Wesentliche Abschnitte in CLAUDE.md

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

Wesentliche Hooks

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

Architekturregeln

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

Prioritäten für MCP-Tools

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

Änderungsprotokoll

Quellenangaben