iOS-Apps mit KI-Agenten entwickeln: Der Leitfaden für Praktiker

TL;DR: Drei Agent-Runtimes 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 Client Protocol (ACP)-Agent.¹⁷ Zwei MCP-Server (XcodeBuildMCP mit 82 Tools und Apples xcrun mcpbridge mit 20 Tools) geben Agenten strukturierten Zugriff auf Builds, Tests, Simulatoren und Debugging. Dieser Leitfaden behandelt echte CLAUDE.md-Muster, Hook-Konfigurationen und ehrliche Einschätzungen darüber, 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. Sie scheitern bei .pbxproj-Änderungen, Code Signing und visuellem Debugging. 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 Beta — Stand 10. August bei Beta 5 (24A5408d) — und ergänzt agentenrelevante Frameworks (Foundation Models-Steuerung für Tool-Calling, App Intents-Hintergrundausführung sowie die neuen Frameworks Core AI und Evaluations), die Sie im Kontext Ihres Agenten erwähnen sollten, da ein vor Juni 2026 trainiertes Modell sie nicht kennen wird. Xcode 26.6 (2026-06-25, 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 AI-Coding-Agenten entwickelt. Keine Prototypen — 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 Zeile Swift in diesen Apps wurde entweder von einem Agenten geschrieben und von mir geprüft oder von mir geschrieben und von einem Agenten refaktoriert. Meiner Einschätzung nach übernahmen Agenten den Großteil der zeilenweisen Autorenschaft; ich übernahm die Prüfung, den Umfang und die Teile, die menschliches Urteilsvermögen erfordern (visuelle Ausarbeitung, Signierung, Performance-Tuning, App-Store-Einreichung).

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

Wichtigste Erkenntnisse

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

• Beginnen Sie mit Claude Code CLI + XcodeBuildMCP. Dies ist die ausgereifteste Runtime mit der umfassendsten MCP-Toolabdeckung. Installieren Sie zwei Befehle, fügen Sie Ihrem Projekt eine CLAUDE.md hinzu, und der Agent kann bauen, testen und debuggen, ohne dass Sie Fehlermeldungen kopieren müssen.
• Lassen Sie einen Agenten niemals .pbxproj ändern. Das ist die wichtigste Regel überhaupt. Ein PreToolUse-Hook, der Schreibzugriffe auf .pbxproj und .xcodeproj/ blockiert, erspart Ihnen Stunden der Wiederherstellung.
• Ihre CLAUDE.md ist das Onboarding-Dokument des Agenten. Die Stunden, die Sie darin investieren, zahlen sich über jede Agent-Sitzung aus, die das Projekt berührt.

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

• MCP verändert die iOS-Build-Schleife grundlegend. Vor MCP schrieben Agenten Swift, konnten aber nicht prüfen, ob es kompiliert. Mit XcodeBuildMCP schreibt der Agent Code, baut ihn, liest strukturierte Fehler, behebt sie und führt Tests aus — autonom.
• Drei Runtimes decken unterschiedliche Anforderungen ab. Claude Code CLI für tiefgehende agentische Sitzungen, Codex CLI für Headless-Stapelarbeit und die eigenen Agenten von Xcode — die in Xcode 27 nicht länger nur ein Tool für Inline-Korrekturen waren, sondern Plug-ins, MCP-Server und die Fähigkeit erhielten, Simulatoren zu steuern.²²
• Die Hook-Infrastruktur lässt sich übertragen. Ihre bestehenden PostToolUse-Formatierer, PreToolUse-Blocker und Test-Runner-Hooks funktionieren mit kleineren Pfadanpassungen identisch für iOS-Projekte.

Für Teamleiter, die AI-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 detaillierten CLAUDE.md erzeugt bessere Agent-Ergebnisse als eine App mit 14 Dateien ohne diese Dokumentation.
• Die .pbxproj-Grenze ist nicht verhandelbar. Agenten können Xcode-Projektdateien nicht zuverlässig bearbeiten. Ihr Workflow muss die manuelle Aufnahme von Dateien in Xcode-Targets berücksichtigen.
• Ehrliche ROI: Agenten übernehmen bei gut dokumentierten Projekten den Großteil der Implementierung — sichtbar an der TV-App mit 15 Dateien, die in 3 Stunden agentengestützter Arbeit ausgeliefert wurde (Fallstudie weiter unten). Die verbleibende Arbeit — visuelle Ausarbeitung, Signierung, Performance-Tuning, App-Store-Einreichung — erfordert menschliches Urteilsvermögen.

Wählen Sie Ihren Weg

So verwenden Sie diesen Leitfaden

Dies ist eine Referenz mit mehr als 3.000 Zeilen. Beginnen Sie dort, wo Ihr Erfahrungsniveau passt:

Inhaltsverzeichnis

1. Das Portfolio: 8 Apps, 293 Dateien
2. Voraussetzungen
3. Drei Agent-Runtimes für iOS
4. MCP-Setup: Die vollständige Konfiguration
5. CLAUDE.md-Muster für iOS-Projekte
6. Ihre erste Agent-Sitzung
7. Worin Agenten bei iOS gut sind
8. Worin Agenten bei iOS schwach sind
9. Hooks für die iOS-Entwicklung
10. Architekturmuster, die mit Agenten funktionieren
11. Framework-spezifischer Kontext
12. Plattformübergreifende Muster
13. Fortgeschrittene Workflows
14. Praxisnahe Fallstudien
15. Projektlebenszyklus mit Agenten
16. Agent-Definitionen konfigurieren
17. Testmuster für agentengestütztes iOS
18. Verwaltung des Kontextfensters für iOS-Projekte
19. Fehlerbehebung
20. Häufige Agent-Fehler bei iOS und wie Sie sie vermeiden
21. Die ehrliche Einschätzung
22. FAQ
23. Schnellreferenzkarte
24. Referenzen

Verwandte Ressourcen

Apple-Ecosystem-Serie. 21 produktive Beiträge über 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 Series

Agentic 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) wurde iOS 27 in die Beta überführt. Der in diesem Leitfaden beschriebene Workflow für die Agentenentwicklung ändert sich nicht: Sie steuern weiterhin Claude Code, Codex oder die Intelligence-Agenten von Xcode über MCP, schreiben weiterhin eine CLAUDE.md und sichern destruktive Vorgänge weiterhin mit Hooks ab. Was sich ändert, ist die Oberfläche, gegen die Ihr Agent entwickelt. iOS 27 bringt mehrere neue, für Agenten relevante Frameworks mit. Praktisch bedeutet das, Ihren Coding-Agenten gezielt darauf hinzuweisen, denn ein vor Juni 2026 trainiertes Modell wird sie nicht kennen. iOS 26 bleibt die veröffentlichte Version; betrachten Sie die folgenden Punkte als Ziel, wenn Sie gegen die iOS-27-Beta-SDK entwickeln.

Die für Agenten relevante iOS-27-Oberfläche, jeweils mit weiterführender Referenz:

• Foundation Models erhielt Kontrolle über Tool-Aufrufe. Mit GenerationOptions.ToolCallingMode können Sie pro Anfrage steuern, wie offensiv das On-Device-Modell Tools aufruft; nach dem ersten Aufruf kann das Framework den Modus wechseln, um die Tool-Aktivität einer Anfrage zu begrenzen. Das Vision-Framework enthält nun die sofort nutzbaren Tools OCRTool und BarcodeReaderTool, die Sie an eine LanguageModelSession anhängen, ohne den Erkennungscode selbst schreiben zu müssen. Siehe Foundation Models in iOS 27: Tool-Calling Control.¹²
• App Intents durchbrach die 30-Sekunden-Grenze. LongRunningIntent (über performBackgroundTask(options:operation:), das eine Fortschrittsmeldung erfordert) verlängert die Hintergrundlaufzeit eines Intents für Synchronisierung, Dateiarbeit und On-Device-Inferenz; SyncableEntity gibt einer AppEntity eine geräteübergreifende Identität; IndexedEntityQuery erlaubt dem System, Ihre Abfrage zur Reparatur ihres Spotlight-Index aufzufordern. Siehe App Intents in iOS 27: Background, Sync, Spotlight.¹³
• Core AI ist ein neues Framework zum Ausführen von Modellen auf Apple Silicon. Es liegt unterhalb von Foundation Models für Fälle, in denen Sie Ihr eigenes Modell mitbringen, statt das Systemmodell von Apple zu verwenden. Siehe Core AI: Running Models on Apple Silicon.¹⁴
• Evaluations ist XCTest für Modellqualität. Ein neues Framework (macOS 27), um die Qualität von Modellausgaben als Teil Ihrer Testsuite zu messen – das fehlende Puzzleteil, um AI-Funktionen auszuliefern, die ein Agent mitentwickelt hat. Siehe Evaluations: XCTest for Model Quality.¹⁵
• Auch SwiftData, HealthKit und SwiftUI wurden erweitert. SwiftData ergänzt in iOS 27 Beobachtung und Verlauf; HealthKit fügt Trainingszonen und neue Typen hinzu; die iOS-27-Ergänzungen in SwiftUI umfassen wie üblich eine breite Oberfläche. Siehe SwiftData in iOS 27, HealthKit in iOS 27 und What’s New in SwiftUI for iOS 27.¹⁶

Die Toolchain für iOS-27-Arbeit ist die Xcode-27-Beta. Xcode 27 erschien am ersten WWDC-Tag (8. Juni, Build 27A5194q) als Beta und steht seit dem 10. August bei Beta 5 (27A5237l). Sie enthält Swift 6.4 sowie die SDKs für iOS 27 / iPadOS 27 / tvOS 27 / watchOS 27 / macOS 27 / visionOS 27 und erfordert macOS Tahoe 26.4 oder neuer.¹⁸ Vier Punkte in den Release Notes sind für Agenten-Workflows relevant: Coding Intelligence erhält einen Planmodus – die Hinweise führen ihn über ein bekanntes Problem mit der Bestätigungsleiste „Implement the plan?“ auf (178673449). Warten Sie daher, bis der Agent das Streaming beendet hat, bevor Sie einen Plan bestätigen oder verwerfen; das MCP-Tool RenderPreview rendert nun Preview-Gruppen (174692209) und kann Ihre UI in einer anderen Lokalisierung anzeigen (181040291); das agentenorientierte Tool „Prepare Project for Localization“ meldet nun String-Catalog-Schlüssel, die entfernt wurden, weil sie nicht mehr im Quellcode vorkommen (179755385); und Address Sanitizer startet möglicherweise nicht für 27.0-Ziele, wenn die App mit Xcode 26.4 oder älter gebaut wurde – verwenden Sie Xcode 26.5+ für ASan-Läufe (178072780).¹⁸ Beta 5 ergänzt zwei weitere hier relevante Punkte. Agenten können nun watchOS-Apps verifizieren, „including rotating and pressing the Digital Crown, and pressing the side and Action buttons (Apple Watch Ultra)“ (181147968) – erstmals können Apples Agenten die physischen Eingaben einer Watch-App ausführen, was einen Teil der in diesem Leitfaden dokumentierten Lücke bei der visuellen Verifizierung schließt. Außerdem stellte Apple einen MCP-Server vor, für den Xcode nicht mehr geöffnet sein muss; siehe den Abschnitt zu Apples MCP-Server weiter unten.²² Auch die MCP-Tooling hat zur Beta aufgeschlossen: XcodeBuildMCP v2.7.0 (2026-07-23) machte seine UI-Automatisierungstools über Device Hub vollständig mit Xcode-27-Simulatoren nutzbar, einschließlich des Startens von Simulatorfenstern und Tastatursteuerungen – vor dieser Version war Runtime-UI-Automatisierung nur gegen Xcode-26-Simulatoren zuverlässig, wodurch agentengesteuerte UI-Verifizierung in der iOS-27-Beta zur manuellen Angelegenheit wurde.²¹

Die Lektion für Sie als Bediener ist dieselbe, die der Rest dieses Leitfadens vermittelt: Der Agent schreibt den Code, aber Sie liefern das Wissen, das ihm fehlt. Bei iOS-27-Betas bedeutet das, diese Frameworks in Ihrem Prompt oder Ihrer CLAUDE.md zu benennen und den Agenten mit Apples Dokumentation zu verlinken, denn das Modell wird sonst auf die iOS-26-Form jedes API zurückgreifen. Alles andere in diesem Leitfaden (Runtimes, MCP, Hooks, Fehlermodi) gilt für iOS-27-Arbeit unverändert.

Das Portfolio: 8 Apps, 293 Dateien

Bevor wir in die Konfiguration einsteigen, folgt hier die Grundlage dieses Leitfadens. Dabei handelt es 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 Dateianzahlen wichtig sind: Die Effektivität von Agenten korreliert mit der Verständlichkeit eines Projekts, nicht mit seiner Größe. Return (63 Dateien) liefert bessere Agentenausgaben als amp97 (41 Dateien), weil Return eine detaillierte CLAUDE.md mit Dateianmerkungen, Architekturdiagrammen und expliziten Mustern enthält. Die Metal-Shader von amp97 sind für Agenten unabhängig von der Qualität der Dokumentation grundsätzlich schwerer nachzuvollziehen.

Voraussetzungen

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

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

Erforderlich: - macOS 15+ (Sequoia) oder macOS Tahoe (Xcode 26.6 erfordert macOS Tahoe 26.2+; die Xcode-27-Beta erfordert Tahoe 26.4+) - Xcode 26.3+ installiert und konfiguriert (die Mindestversion für xcrun mcpbridge); Xcode 26.6+ empfohlen. Xcode 26.6 (2026-06-25, Build 17F113) ist die neueste stabile Version und bringt drei für Agenten relevante Änderungen an Coding Intelligence: Google Gemini als Anbieter für Coding-Assistenten, Unterstützung für Agent Client Protocol (ACP) und Varianten-Rendering – hell/dunkel, Ausrichtung, Schriftgrößen – im Preview-MCP-Tool; zudem behebt es zwei Abstürze während Agententurns sowie den Hänger, wenn ein Agent eine Frage stellt, und enthält Swift 6.3 mit SDKs der iOS-26.5-Generation.¹⁷ Die Workflow-Verbesserungen aus 26.5 – Nachrichtenwarteschlangen im Coding-Assistenten und Unterstützung für Rückfragen – sowie die Swift-Testing-Bildanhänge, Schweregrade für aufgezeichnete Probleme, UI-Test-Absturzwarnungen mit Crashlogs und Verbesserungen am String-Catalog-Editor aus 26.4 bleiben ebenfalls erhalten.²⁷²⁸ Frühere stabile Versionen: 26.5 (2026-05-11, Build 17F42) und 26.4.1 (2026-04-16, Build 17E202).²⁹ - Mindestens eine installierte iOS-Simulator-Runtime - Ein Anthropic-API-Konto (für Claude Code) oder ein OpenAI-Konto (für Codex)

Empfohlen: - SwiftFormat installiert (brew install swiftformat) – wird von Hooks zum Formatieren beim Speichern verwendet - SwiftLint installiert (brew install swiftlint) – optional, aber nützlich zur Durchsetzung von Stilvorgaben - Vertrautheit mit dem Terminal – alle drei Runtimes laufen über die Befehlszeile oder integrieren sich in sie

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

Wenn xcrun mcpbridge „command not found“ zurückgibt, benötigen Sie Xcode 26.3 oder neuer. Installieren oder aktualisieren Sie Xcode über den App Store oder developer.apple.com. Hinweis: xcode-select --install installiert nur die Command Line Tools; diese enthalten mcpbridge nicht – 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 Einsatzfälle.

1. Claude Code CLI

Was es ist: Der terminalbasierte agentische Coding-Assistent von Anthropic. Er liest Ihre Codebasis, führt Befehle aus, verändert Dateien und verbindet sich über MCP mit externen Tools.⁷

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

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 — Auto-Installer xcodebuildmcp init (v2.1.0+, 23.02.2026):

Wenn Sie die manuelle MCP-Einbindung lieber überspringen möchten, enthält XcodeBuildMCP v2.1.0+ einen Unterbefehl init, der Claude Code, Cursor oder Codex automatisch erkennt und die Agent-Skills + MCP-Konfiguration in einem Schritt installiert:

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

Flags: --print (schreibt die Konfiguration für nicht unterstützte Clients nach stdout), --uninstall (entfernt sie). Überspringen Sie dies, wenn Sie ausdrücklich festlegen möchten, welche MCP-Server in welchem Geltungsbereich eingebunden werden; die manuellen claude mcp add-Aufrufe oben ermöglichen Ihnen das.³⁰

Am besten geeignet für: Tiefgehende Implementierungssitzungen — neue Funktionen entwickeln, über mehrere Dateien hinweg refaktorieren, komplexe Probleme debuggen und Build-Test-Fix-Schleifen autonom ausführen. Das Kontextfenster von 1 Mio. Token von Claude Code (mit Opus 5) bedeutet, dass der Agent die meisten kleinen bis mittelgroßen iOS-Projekte im Arbeitsspeicher halten kann — meiner Erfahrung nach je nach Dateigröße bis zu etwa 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 Workflow vor MCP: Der Agent fordert Sie nie auf, manuell zu bauen oder Fehlerausgaben einzufügen. Die Build-Fehler-Fix-Schleife läuft autonom.

2. Codex CLI

Was es ist: Der terminalbasierte Coding-Agent von OpenAI. Vom Konzept her ähnelt er Claude Code, läuft jedoch mit den Codex-Modellen von OpenAI und hat ein anderes Berechtigungsmodell. Die aktuelle Modellreihe besteht aus GPT-5.6 Sol (Flaggschiff, am stärksten bei komplexem Coding), GPT-5.6 Terra (ausgewogener Standard für den Alltag) und GPT-5.6 Luna (schnell und am günstigsten), mit GPT-5.3 Codex Spark als reiner Text-Forschungsvorschau. GPT-5.4 und GPT-5.4-mini werden am 31. August 2026 aus Codex entfernt — migrieren Sie diese Konfigurationen jeweils zu Terra und Luna.²³

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. Der Sandbox-Modus von Codex führt Code in isolierten Umgebungen aus, was für destruktive Operationen wie Test-Suite-Läufe nützlich ist, die Zustände verändern.

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

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

Nutzen Sie Codex, wenn Sie Modellvielfalt wünschen — wenn ein zweiter Agent den vom ersten geschriebenen Code überprüft, werden andere Fehlerklassen erkannt. Der Collab-Workflow (Claude erstellt, Codex prüft) ist für iOS effektiv, weil SwiftUI-Muster, die für eine Modellfamilie korrekt aussehen, subtile Probleme enthalten können, die eine andere erkennt. Besonders Metal-Shader und Concurrency-Muster profitieren von einer Prüfung durch zwei Modelle.

3. Native Xcode-Agenten

Was es ist: Apple hat AI-Coding-Agenten direkt in das Intelligence-Panel von Xcode integriert. Seit Xcode 26.3 können Sie Claude Agent und Codex in den Xcode-Einstellungen unter Intelligence als Intelligence-Anbieter konfigurieren.¹⁰ Xcode 26.6 erweitert die Auswahl: Google Gemini ist jetzt im Coding-Assistenten verfügbar (171990272), und Xcode ergänzt die Unterstützung für Agent Client Protocol (ACP) (178294840) — aus der ursprünglich zweistufigen Integration sind damit drei Anbieter plus ein offenes Protokoll geworden, über das jeder ACP-kompatible Agent in das Intelligence-Panel eingebunden werden kann.¹⁷

Einrichtung:

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

Am besten geeignet für: Schnelle Inline-Änderungen, Codevervollständigung mit agentischem Schlussfolgern und Entwickler, die Xcode nicht verlassen möchten. Durch die native Integration hat der Agent direkten Zugriff auf den Projektkontext von Xcode — geöffnete Dateien, Build-Targets und Scheme-Konfiguration — ohne MCP-Bridging.

Einschränkungen gegenüber CLI-Agenten — unter Xcode 26.x: - Kein Hook-System — Sie können weder Formatierung beim Speichern erzwingen noch .pbxproj-Schreibvorgänge blockieren - Kein Laden von CLAUDE.md — der Agent liest Ihre projektweiten Konfigurationsdateien nicht - Begrenzte Autonomie — der Agent arbeitet in der aktuellen Datei oder Auswahl, nicht im gesamten Projekt - Keine Subagent-Delegation — komplexe mehrstufige Aufgaben können nicht parallelisiert werden - Keine MCP-Serverkonfiguration — der Agent verwendet nur die integrierten Tools von Xcode

Xcode 27 macht den Großteil dieser Liste hinfällig. Seit Beta 1 (8. Juni) sind die Agenten von Xcode eine Erweiterungsplattform statt eines Inline-Assistenten:²²

• Plug-ins: „Agents in Xcode can now be extended with plugins that contain skills, MCP servers, and ACP agent configurations. Skills are invokable as slash commands with completion support.“ (178289210) — damit entfallen die Einschränkungen „nur integrierte Tools“ und „keine MCP-Konfiguration“.
• Simulatorsteuerung: Agenten „can now boot simulators, install and launch apps, synthesize touch events, and capture screenshots to verify UI behavior“ (175179787), und ab Beta 5 können sie watchOS-Hardwareeingaben steuern (181147968).
• Debugger-Zugriff: Der Xcode MCP-Server erhielt Tools zum Manipulieren des Ausführungszustands, Lesen der Debugger-Konsole, Wechseln von Schemes und Ausführungszielen sowie zum Prüfen oder Ändern von „build settings, compiler flags, entitlements, and Info.plist keys“ (176935844).
• Eine Dateisystemsicherheitsebene, „that monitors and controls filesystem access by coding agents and any processes they spawn“ (178289431), sowie erstklassige Planung (172857081) und Projekt-Insights zu Abstürzen, Hängern, Energieverbrauch und Startproblemen (177568662).

Eine Warnung, die direkt aus 176935844 folgt: Die Agenten von Xcode können jetzt Build-Einstellungen, Entitlements und Info.plist-Schlüssel bearbeiten. Der Schutz für .pbxproj, den dieser Leitfaden mit einem PreToolUse-Hook aufbaut, greift innerhalb von Xcode nicht, weil der Hook in der Konfiguration Ihres CLI-Agenten lebt, nicht in Apples. Wenn Sie sich auf diesen Hook als Sicherheitsnetz verlassen, sollten Sie wissen, dass er für das Intelligence-Panel nicht zuständig ist.

Wann Sie native Xcode-Agenten verwenden sollten:

Für schnelle, klar abgegrenzte Änderungen, bei denen der Wechsel zum Terminal unnötigen Aufwand bedeutet. „Füge diesem Modell eine berechnete Eigenschaft hinzu.“ „Schreibe einen Unit-Test für diese Funktion.“ „Refaktoriere diese View, um @Observable zu verwenden.“ Aufgaben, die eine oder zwei Dateien betreffen und keinen Build-Test-Zyklus erfordern.

Für alles, was Builds, Tests, Refaktorierungen über mehrere Dateien oder autonome Fehlerkorrektur erfordert, verwenden Sie einen CLI-Agenten mit MCP.

Vergleichsmatrix der Runtimes

Die Empfehlung: Nutzen Sie Claude Code CLI als Ihre primäre Runtime. Verwenden Sie native Xcode-Agenten für schnelle Inline-Änderungen. Nutzen Sie Codex CLI für Review-Durchgänge und Stapeloperationen. Die drei ergänzen sich, statt miteinander zu konkurrieren.

MCP-Einrichtung: Die vollständige Konfiguration

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

XcodeBuildMCP: 82 Tools für die Headless-iOS-Entwicklung

XcodeBuildMCP fasst xcodebuild, xcrun simctl und LLDB in 82 strukturierte MCP-Tools zusammen (beworbener Bestand, unverändert von v2.6.2 bis v2.7.0 überprüft), die in 12 Workflow-Kategorien gruppiert sind.³¹⁹²¹ Die kanonische Heimat des Projekts ist die GitHub-Organisation getsentry — Sentry betreut es, und die ursprüngliche URL cameroncooke/XcodeBuildMCP leitet inzwischen dorthin weiter, was wichtig ist, wenn ältere Artikel die alte Adresse zitieren.²¹ Es funktioniert ohne laufendes Xcode — der gesamte Build-Test-Debug-Zyklus läuft Headless über Apples Kommandozeilentools. Zwei Hinweise zum Toolbestand sollten Sie kennen: Eine Standard-stdio-Sitzung stellt die zwei Dutzend Tools des Simulator-Workflows bereit und hält den Rest aus dem Kontext Ihres Agenten heraus — setzen Sie XCODEBUILDMCP_ENABLED_WORKFLOWS (kommagetrennte Kategorienamen aus der folgenden Tabelle), um weitere zu laden — und dieselbe Engine wird als CLI ausgeliefert (xcodebuildmcp tools meldet 100 Befehle, davon 72 kanonische), falls Sie identische Operationen ohne MCP wünschen.⁹

Installationsoptionen:

# Option 1: Via npx (recommended — always uses latest version)
claude mcp add XcodeBuildMCP \
  -s user \
  -e XCODEBUILDMCP_SENTRY_DISABLED=true \
  -- npx -y xcodebuildmcp@latest mcp

# Option 2: Via Homebrew (pinned version, manual updates)
brew install xcodebuildmcp
claude mcp add XcodeBuildMCP \
  -s user \
  -e XCODEBUILDMCP_SENTRY_DISABLED=true \
  -- xcodebuildmcp mcp

# Option 3: Project-scoped (omit -s user)
claude mcp add XcodeBuildMCP \
  -e XCODEBUILDMCP_SENTRY_DISABLED=true \
  -- npx -y xcodebuildmcp@latest mcp

Das Flag -s user macht den Server projektübergreifend global verfügbar. Lassen Sie es für eine projektbezogene Installation weg (nützlich, wenn Sie MCP nur in iOS-Projekten, nicht aber 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 dies, sofern Sie keine Diagnosedaten zum Projekt 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 — Dieses Tool werden Sie Hunderte Male aufrufen. Es gibt JSON zurück, deren Fehler nach Datei, Zeile und Schweregrad kategorisiert sind. Der Agent liest den Fehler, navigiert zur Datei und behebt ihn, ohne dass Sie etwas anfassen müssen.

2. test_sim — Gibt Ergebnisse pro Testmethode zurück. Der Agent weiß genau, welcher Test fehlgeschlagen ist und warum, statt nur „Tests fehlgeschlagen“ zu erhalten.

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

4. discover_projs + list_schemes — Projektinspektion. Der Agent muss weder Ihren Schemenamen noch die Workspace-Struktur erraten.

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

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

Das Release v2.6.0 hat die UI-Automatisierung rund um wiederverwendbaren Kontext statt Einmal-Screenshots neu aufgebaut.¹⁹ snapshot_ui gibt jetzt stabile Elementreferenzen und einen Screen-Hash zurück und akzeptiert sinceScreenHash, sodass der Agent einen vollständigen Snapshot überspringen kann, wenn sich der Bildschirm nicht geändert hat. Drei neue Tools schließen den Kreislauf: wait_for_ui fragt ab, bis ein Prädikat erfüllt ist (Existenz, aktivierter Zustand, Fokus, sichtbarer Text oder stabiles Layout), statt dass der Agent mit Sleeps raten muss; batch führt eine Folge von Aktionen auf Elementreferenzen in einem einzigen Aufruf aus; drag führt Drag-Gesten auf Elementreferenzen für Sheets und das Scrollen von Listen aus. type_text erhielt replaceExisting, um den Wert eines Felds zu ersetzen, statt Text daran anzuhängen, Kandidaten-Steuerelemente werden anhand von Accessibility-Daten eingestuft, und strukturierte Ergebnisse enthalten nun nextSteps-Hinweise (Ergebnisschemas wurden in diesem Release auf v2 versioniert; v2.7.0 hat Build-/Test-Ergebnisse inzwischen auf schemaVersion: 3 angehoben — siehe unten). Setzen Sie XCODEBUILDMCP_HEADLESS_LAUNCH=true, um Apps im Hintergrund zu starten, ohne den macOS-Fokus zu übernehmen — der Unterschied zwischen einer Agentensitzung, die Sie laufen lassen können, und einer, die Ihr Simulator-Fenster ständig nach vorn zieht. Bei einer deterministischen Aufgabe für eine Wetter-App behauptet der projekteeigene Benchmark gegenüber dem Ablauf vor 2.6 ungefähr 70 % weniger Wandzeit, 68 % weniger Tokens und 76 % weniger Toolaufrufe — die Zahlen des Projekts, keine unabhängige Messung, doch der Mechanismus (unveränderte Snapshots überspringen, Aktionen auf demselben Bildschirm bündeln) ist genau der Grund für den Tokenverbrauch bei UI-Automatisierung.¹⁹

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

Das Release v2.7.0 ist kleiner als 2.6.0, bringt aber eine Breaking Change und eine Verhaltensänderung mit, die Sie vor dem Upgrade kennen sollten.²¹ Die wichtigste Neuerung: UI-Automatisierungstools funktionieren jetzt über Device Hub vollständig mit Xcode-27-Simulatoren, einschließlich des Startens von Simulatorfenstern und der Tastatursteuerung — damit schließt sich die Lücke, durch die Laufzeit-UI-Automatisierung nur mit Xcode-26-Simulatoren zuverlässig war. Breaking: Build- und Test-Tools geben nun strukturierte Ergebnisse mit schemaVersion: 3 zurück (seit 2.6.0 war es v2) — alles, was Sie geschrieben haben und das Ergebnisse prüft oder parst, die auf Version 2 festgelegt sind, muss aktualisiert werden. Verhaltensänderung: Build-, Test-, Clean- und App-Pfad-Tools berücksichtigen jetzt die Konfiguration der Scheme-Aktion, wenn configuration weggelassen wird, statt stets standardmäßig Debug zu verwenden — wenn die Test-Aktion eines Schemes auf Release gesetzt ist, baut ein nicht weiter qualifiziertes test_sim jetzt Release. Übergeben Sie daher configuration explizit, wenn Ihr Workflow von einer bestimmten Konfiguration abhängt. Kleinere, aber nützliche Änderungen: Wiederverwendbare Testvorbereitungspakete .xctestproducts erlauben erneute Testläufe ohne Neubau und erzeugen dennoch bei jedem Lauf ein frisches .xcresult; mit extraArgs als Sitzungsstandard können Sie gemeinsame xcodebuild-Flags einmal pro Sitzung setzen, statt sie bei jedem Aufruf zu wiederholen; ein neuer CLI-Befehl xcodebuildmcp purge meldet und bereinigt den Workspace-Speicher von XcodeBuildMCP (standardmäßig Dry-Run, Löschen nur nach ausdrücklichem Opt-in); zudem wurde ein Fehler behoben, durch den MCP-Clients 10–17 Sekunden warten mussten, bis Tools verfügbar waren — was kurze Health Checks als fehlgeschlagene Verbindung melden lassen konnte.²¹

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

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

Installation:

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

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

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

Xcode 27 beta 5 zeigt einen Ausweg aus dieser Einschränkung. Apple hat „eine neue MCP-Server-Erfahrung hinzugefügt, die ohne einen geöffneten Xcode-Workspace ausgeführt wird“, aktiviert mit sudo xcrun mcp-server enable und geprüft mit xcrun mcp-server status. Dieselbe Vorschau erlaubt es Ihnen, Code-signierten Agenten dauerhafte Berechtigung für die Arbeit innerhalb eines Verzeichnisbaums zu geben, statt jedes Mal erneut zu bestätigen. Für unbeaufsichtigte Läufe genehmigt sudo xcrun mcp-server enable --unsafe-always-allow-all-agents alles im Voraus — Apple nennt das ausdrücklich „keine empfohlene Konfiguration für die Nutzung am Schreibtisch“, und ich ebenfalls nicht: Dadurch entfällt der Bestätigungsschritt, der einen Agenten von Verzeichnissen fernhält, die Sie nicht freigeben wollten. Behandeln Sie die gesamte Oberfläche als frühe Vorschau und behalten Sie XcodeBuildMCP als Headless-Pfad bei, bis sie die Vorschau verlässt.²²

Toolbestand (20 Tools in 5 Kategorien):

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

1. DocumentationSearch — Durchsucht Apples Entwicklerdokumentation einschließlich WWDC-Sessions. Für Fragen zu Apple API schneller und zuverlässiger als eine Websuche. Fragen Sie „is HKQuantityType(.dietaryWater) valid?“ und erhalten Sie eine definitive Antwort direkt aus der Quelle.

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

3. RenderPreview — Rendert SwiftUI-Previews Headless. Der Agent kann prüfen, ob eine View fehlerfrei rendert, jedoch nicht die visuelle Korrektheit bewerten (das Rendering wird als Daten zurückgegeben, nicht visuell geprüft). Ab Xcode 26.6 rendert das Preview-MCP-Tool (in den Release Notes zu 26.6 „Preview Snapshot“ genannt) Varianten — helles/dunkles Erscheinungsbild, Hoch-/Querformat und Überschreibungen der Schriftgröße (178831772) — sodass ein Agent eine View in einem Durchgang über mehrere Erscheinungsbilder hinweg prüfen kann.¹⁷ Die Xcode-27-Beta erweitert dies weiter: Rendering von Preview-Gruppen und Vorschau in einer anderen Lokalisierung.¹⁸

4. XcodeListNavigatorIssues — Gibt Echtzeitdiagnosen aus dem Xcode-Analyzer zurück, nicht nur Build-Fehler. Erkennt Probleme wie ungenutzte Variablen, mögliche Retain Cycles und Deprecation-Warnungen, die das Build-System nicht anzeigt.

Warum beide Server

Sie überschneiden sich bei Builds und Tests, unterscheiden sich aber 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, verbraucht weniger Systemspeicher und bietet umfangreichere Simulator- und Geräteverwaltung. Dies ist Ihr primäres Build-Tool.

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

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

Die Zwei-Server-Aufteilung weicht auf. XcodeBuildMCP 2.6.x fügt eine Proxy-Kategorie xcode-ide hinzu: xcode_ide_list_tools entdeckt die MCP-Funktionen, die nur für Xcode-IDE verfügbar sind, und xcode_ide_call_tool ruft sie auf (sie erscheinen mit xcode_tools_*-Namen, z. B. xcode_tools_documentationsearch), sodass eine einzige XcodeBuildMCP-Registrierung nun auch Apples IDE-seitige Tools erreichen kann.¹⁹ Die relevante Einschränkung bleibt bestehen: Diese weitergeleiteten Aufrufe erfordern weiterhin einen laufenden Xcode-Prozess, genau wie eine direkte xcrun mcpbridge-Registrierung. Lassen Sie beide Server registriert, wenn Sie Apples Tools erstklassig in der Toolliste des Agenten haben möchten; der Proxy ist am nützlichsten, wenn Sie einen einzigen Servereintrag und nur gelegentliche IDE-Lesezugriffe wünschen.

Verifizierung

Überprüfen Sie nach der Installation beider Server, ob sie verbunden sind:

# List all configured MCP servers
claude mcp list

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

Wenn ein Server „Disconnected“ anzeigt oder nicht erscheint:

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

Dem Agenten die Verwendung von MCP beibringen

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

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

## Build & Test — Always Use MCP

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

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

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

Diese Anleitung stellt sicher, dass der Agent zuerst zu MCP-Tools greift. Ohne sie werden Sie beobachten, wie der Agent lange xcodebuild-Befehle über Bash erstellt, Tausende Kontext-Tokens für die Auswertung der Ausgabe verbraucht und gelegentlich den tatsächlichen Fehler falsch identifiziert.⁶

Eine Verhaltensänderung von XcodeBuildMCP v2.7.0 gehört zu diesem mentalen Modell: Wenn configuration weggelassen wird, berücksichtigen Build-, Test-, Clean- und App-Pfad-Tools jetzt die Konfiguration der Scheme-Aktion, statt immer Debug zu verwenden.²¹ Die meisten Schemes führen in Debug aus und testen dort, daher werden die meisten Projekte nichts bemerken — ist jedoch die Aktion eines Schemes auf Release gesetzt (üblich bei Profiling-Schemes oder archive-nahen Setups), baut ein nicht weiter qualifiziertes build_sim oder test_sim jetzt Release. Wenn Ihre CLAUDE.md oder Hooks von Debug-Artefakten ausgehen, geben Sie dies entweder im Toolaufruf explizit an oder setzen Sie es einmal pro Sitzung mit session_set_defaults.

Lang laufende Builds: Claude Code führt sie jetzt im Hintergrund aus

Zwei Claude Code-Releases haben verändert, wie ein langer Build innerhalb einer Sitzung aussieht. 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 nutzbar bleibt; der Schwellenwert ist über CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS konfigurierbar — oder das Verhalten lässt sich damit deaktivieren.²⁰ Saubere Builds und vollständige Testläufe über build_sim / test_sim überschreiten bei echten Projekten regelmäßig die 2-Minuten-Grenze. Erwarten Sie daher, dass der Agent weiterarbeitet — Dateien liest, die nächste Änderung plant — während der Build im Hintergrund fertig wird, statt den Turn zu blockieren. Die ergänzende Fehlerbehebung ist genauso wichtig: Vor v2.1.206 (2026-07-09) wurde ein pro Server über --mcp-config oder .mcp.json konfiguriertes request_timeout_ms in neuen Sitzungen ignoriert, sodass lange MCP-Aufrufe nach dem Standardwert von 60 Sekunden abliefen — das klassische Symptom war ein Timeout beim ersten Clean Build, das sich bei einer Wiederholung „von selbst“ behob.²⁰ Wenn Sie eines dieser Verhaltensweisen mit Wrapper-Skripten oder vorgewärmten Builds umgangen haben, können Sie den Workaround 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)

Plattformübergreifende Muster

Return umfasst iOS, watchOS und tvOS. Plattformübergreifende Entwicklung mit Agents erfordert eine explizite Dokumentation der Plattformgrenzen.

Organisation gemeinsamen Codes

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

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

Regel für Agents: „Wenn sich eine Datei in Shared/ befindet, betreffen Änderungen alle Plattformen. Befindet sich eine Datei in einem Plattformspezifischen Verzeichnis, sind Änderungen isoliert. Prüfen Sie immer, in welchem Verzeichnis sich eine Datei befindet, bevor Sie sie ändern.“

Plattformverfügbarkeitsprüfungen

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

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

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

Hinweis für Agents: „Verwenden Sie immer #if canImport()- oder #if os()-Prüfungen, wenn Sie plattformspezifische Frameworks einsetzen. Gehen Sie nicht davon aus, dass ein Framework in 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
    }
}

Erweiterte Workflows

Autonome Build-Test-Fix-Schleifen

Das leistungsstärkste Muster: Geben Sie dem Agent eine Funktionsspezifikation und lassen Sie ihn autonom 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, erstellt den Build über MCP, liest strukturierte Fehler, behebt sie und wiederholt den Vorgang. Eine Funktion, die 5–10 Build-Fehlerbehebungszyklen durch Menschen erfordern würde, wird in einer einzigen autonomen Schleife fertiggestellt.

Wann dies funktioniert: Klar definierte Funktionen mit eindeutigen Akzeptanzkriterien.

Wann dies scheitert: Offen formulierte Funktionen („mach es hübsch“), leistungssensitiver Code oder alles, was eine visuelle Prüfung erfordert.

Subagent-Delegierung 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. Dadurch verbraucht Recherche nicht Ihren primären Kontext.

Anwendung appübergreifender Muster

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

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

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

Dual-Agent-Review (Claude + Codex)

Verwenden Sie für kritische Änderungen zwei Agents aus unterschiedlichen Modellfamilien:

1. Claude Code schreibt die Implementierung
2. Codex CLI prü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 Fehler leicht entstehen.

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

Beim Dual-Review geht es nicht darum, mehr Fehler zu finden – sondern andere Fehler. Jede Modellfamilie hat bei ihrer Mustererkennung unterschiedliche Fehlermodi.

Batch-Operationen für mehrere Apps

Wenn sich eine Framework- oder Musteränderung auf mehrere Apps auswirkt:

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

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

Apps, die Apples LLM auf dem Gerät verwenden

Wenn Ihre App Apples Foundation Models-Framework aufruft, etwa für Offline-Zusammenfassungen, Klassifizierung oder die Generierung strukturierter Ausgaben, müssen Agents das Prompt-Budget kennen. iOS 26.4 hat zwei APIs zu SystemLanguageModel hinzugefügt, die die bisherige Annahme von 4096 Tokens ersetzen: contextSize (die maximale Tokenanzahl, die das Modell in einer einzelnen Konversation akzeptiert) und tokenCount(for:) (async throws, gibt zurück, wie viele Tokens ein bestimmter Prompt tatsächlich kostet).³¹ Beide sind @backDeployed(before: iOS 26.4) und daher auf allen FM-unterstützenden OS-Versionen ohne eine #available-Kaskade verfügbar.

Das Muster, dem ein Agent beim Generieren von Code zur Prompt-Erstellung folgen sollte:

import FoundationModels

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

Fügen Sie dieses Muster zu Ihrer CLAUDE.md hinzu, wenn die App SystemLanguageModel verwendet. Andernfalls greifen Agents auf den alten 4096-Hardcode zurück und kürzen Prompts auf Geräten mit größeren Kontextfenstern stillschweigend. Die Signatur async throws von tokenCount(for:) ist entscheidend – Agents, die eine synchrone Version einfügen, erhalten einen Kompilierungsfehler.

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

Referenzen