Créer des apps iOS avec des agents d’IA : le guide pratique

TL;DR : Trois runtimes d’agents livrent désormais du code pour iOS : Claude Code CLI avec MCP, Codex CLI avec MCP, et les agents Intelligence natifs de Xcode — Claude Agent, Codex et, depuis Xcode 26.6, Google Gemini ou tout agent Agent Client Protocol (ACP).¹⁷ Deux serveurs MCP (XcodeBuildMCP avec 82 outils et xcrun mcpbridge d’Apple avec 20 outils) donnent aux agents un accès structuré aux builds, tests, simulateurs et au débogage. Ce guide couvre de véritables modèles de CLAUDE.md, des configurations de hooks et des évaluations honnêtes de ce qui fonctionne ou échoue — issus de 8 apps iOS en production totalisant 293 fichiers Swift.³² Les agents excellent pour les vues SwiftUI, les modèles SwiftData, la refactorisation et le diagnostic des erreurs de build. Ils échouent sur les modifications de .pbxproj, la signature de code et le débogage visuel. L’écart entre « l’agent écrit du Swift » et « l’agent livre une app iOS » se comble par la configuration, non par le prompting. Depuis la WWDC 2026 (8 juin), iOS 27 est en bêta — bêta 5 (24A5408d) au 10 août — et ajoute des frameworks pertinents pour les agents (contrôle des tool calls de Foundation Models, exécution en arrière-plan d’App Intents, nouveaux frameworks Core AI et Evaluations) qu’il est utile de nommer dans le contexte de votre agent, car un modèle entraîné avant juin 2026 ne les connaîtra pas. Xcode 26.6 (2026-06-25, Swift 6.3) est la toolchain stable actuelle ; la bêta de Xcode 27 (Swift 6.4, SDKs iOS 27) suit le cycle d’iOS 27.¹⁷¹⁸

J’ai développé 8 apps iOS avec des agents de programmation IA. Pas des prototypes — des apps sur l’App Store, avec des intégrations HealthKit, des shaders Metal, de la physique SpriteKit, la synchronisation iCloud, des Live Activities, des classements Game Center et des cibles multiplateformes couvrant iOS, watchOS et tvOS. Chaque ligne de Swift de ces apps a été soit écrite par un agent puis revue par moi, soit écrite par moi puis refactorisée par un agent. Selon mon estimation, les agents ont assuré l’essentiel de la paternité ligne par ligne ; j’ai pris en charge la revue, le périmètre et les éléments exigeant un jugement humain (finitions visuelles, signature, réglages de performance, soumission à l’App Store).

Ce guide est la référence que j’aurais aimé trouver lorsque j’ai commencé. Il couvre toute la stack : quel runtime d’agent utiliser, comment configurer les serveurs MCP pour un accès structuré au build, quoi mettre dans votre CLAUDE.md, quels hooks empêchent l’agent de détruire votre projet Xcode et — surtout — où les agents échouent et où vous devez reprendre la main.

Points clés

Pour les développeurs iOS découvrant les agents IA :

• Commencez avec Claude Code CLI + XcodeBuildMCP. C’est le runtime le plus mature, avec la couverture d’outils MCP la plus approfondie. Installez deux commandes, ajoutez un CLAUDE.md à votre projet, et l’agent peut builder, tester et déboguer sans que vous ayez à copier les messages d’erreur.
• Ne laissez jamais un agent modifier .pbxproj. C’est la règle la plus importante. Un hook PreToolUse qui bloque les écritures dans .pbxproj et .xcodeproj/ vous épargnera des heures de récupération.
• Votre CLAUDE.md est le document d’onboarding de l’agent. Les heures que vous y consacrez sont rentabilisées à chaque session d’agent touchant le projet.

Pour les utilisateurs expérimentés d’agents qui ajoutent iOS à leur workflow :

• MCP transforme la boucle de build iOS. Avant MCP, les agents écrivaient du Swift sans pouvoir vérifier qu’il compilait. Avec XcodeBuildMCP, l’agent écrit le code, le build, lit les erreurs structurées, les corrige et lance les tests — de manière autonome.
• Trois runtimes répondent à des besoins différents. Claude Code CLI pour des sessions agentiques approfondies, Codex CLI pour le travail batch sans interface, et les propres agents de Xcode — qui ont cessé d’être un outil de correction en ligne dans Xcode 27, où ils ont gagné des plug-ins, des serveurs MCP et la capacité à piloter des simulateurs.²²
• L’infrastructure de hooks se réutilise. Vos formateurs PostToolUse existants, bloqueurs PreToolUse et hooks d’exécution de tests fonctionnent de manière identique pour les projets iOS, avec de légers ajustements de chemins.

Pour les responsables d’équipe évaluant le développement iOS assisté par IA :

• L’efficacité des agents dépend de la documentation du projet, non de sa taille. Une app de 63 fichiers avec un CLAUDE.md détaillé produit de meilleurs résultats d’agent qu’une app de 14 fichiers sans documentation.
• La frontière .pbxproj n’est pas négociable. Les agents ne peuvent pas modifier de façon fiable les fichiers de projet Xcode. Votre workflow doit prévoir l’ajout manuel de fichiers aux cibles Xcode.
• Évaluation honnête ROI : les agents prennent en charge l’essentiel de l’implémentation sur des projets bien documentés — comme le montre l’app TV de 15 fichiers livrée en 3 heures de travail assisté par agent (étude de cas ci-dessous). Le travail restant — finitions visuelles, signature, réglages de performance, soumission à l’App Store — exige un jugement humain.

Choisissez votre parcours

Comment utiliser ce guide

Cette référence compte plus de 3 000 lignes. Commencez au niveau correspondant à votre expérience :

Table des matières

1. Le portfolio : 8 apps, 293 fichiers
2. Prérequis
3. Trois runtimes d’agents pour iOS
4. Configuration de MCP : la configuration complète
5. Modèles de CLAUDE.md pour les projets iOS
6. Votre première session d’agent
7. Ce que les agents font bien dans iOS
8. Ce que les agents font mal dans iOS
9. Hooks pour le développement iOS
10. Modèles d’architecture qui fonctionnent avec les agents
11. Contexte spécifique aux frameworks
12. Modèles multiplateformes
13. Workflows avancés
14. Études de cas réelles
15. Cycle de vie du projet avec les agents
16. Configuration des définitions d’agents
17. Modèles de tests pour iOS assisté par agent
18. Gestion de la fenêtre de contexte pour les projets iOS
19. Dépannage
20. Erreurs courantes des agents dans iOS
21. L’évaluation honnête
22. FAQ
23. Fiche de référence rapide
24. Références

Ressources connexes

Série Apple Ecosystem. 21 articles de production sur des apps SwiftUI qui s’intègrent à Apple Intelligence, MCP, Foundation Models, Vision, Core ML et à la stack de frameworks iOS 26. Issus de Water, Get Bananas, Return et du reste du portfolio 941 :

Hub de la série : Série Apple Ecosystem

Apple agentique (E4) :

Frameworks (E2/E3) :

Code livré (E1) :

Synthèse (E5) :

iOS 27 et WWDC 2026 : ce que votre agent peut désormais créer

La WWDC 2026 (8 juin 2026) a placé iOS 27 en bêta. Le workflow de développement avec agents présenté dans ce guide ne change pas : vous pilotez toujours Claude Code, Codex ou les agents Intelligence de Xcode via MCP, vous rédigez toujours un CLAUDE.md et vous encadrez toujours les opérations destructrices avec des hooks. Ce qui change, c’est l’étendue des éléments sur lesquels votre agent écrit. iOS 27 apporte plusieurs nouveaux frameworks pertinents pour les agents, et, en pratique, vous devez y orienter délibérément votre agent de programmation, car un modèle entraîné avant juin 2026 ne saura pas qu’ils existent. iOS 26 reste la version publiée ; considérez les éléments ci-dessous comme des cibles lorsque vous développez avec la bêta iOS 27 SDK.

Les éléments d’iOS 27 pertinents pour les agents, chacun accompagné d’une référence détaillée :

• Foundation Models a acquis le contrôle des appels d’outils. GenerationOptions.ToolCallingMode vous permet d’orienter, requête par requête, le niveau d’utilisation des outils par le modèle embarqué, et le framework peut changer de mode après le premier appel afin de limiter l’activité des outils d’une requête. Le framework Vision propose désormais des OCRTool et BarcodeReaderTool prêts à l’emploi, que vous attachez à un LanguageModelSession sans écrire le code de reconnaissance. Consultez Foundation Models in iOS 27: Tool-Calling Control.¹²
• App Intents a franchi la limite des 30 secondes. LongRunningIntent (via performBackgroundTask(options:operation:), qui nécessite un rapport de progression) prolonge le temps d’exécution en arrière-plan d’un intent pour la synchronisation, les opérations sur les fichiers et l’inférence embarquée ; SyncableEntity donne à une AppEntity une identité interappareils ; IndexedEntityQuery permet au système de demander à votre requête de réparer son index Spotlight. Consultez App Intents in iOS 27: Background, Sync, Spotlight.¹³
• Core AI est un nouveau framework permettant d’exécuter des modèles sur Apple Silicon. Il se situe sous Foundation Models pour les cas où vous fournissez votre propre modèle plutôt que d’utiliser le modèle système d’Apple. Consultez Core AI: Running Models on Apple Silicon.¹⁴
• Evaluations est XCTest pour la qualité des modèles. Il s’agit d’un nouveau framework (macOS 27) qui mesure la qualité des sorties de modèle dans votre suite de tests, soit la pièce manquante pour livrer des fonctionnalités d’IA qu’un agent vous a aidé à créer. Consultez Evaluations: XCTest for Model Quality.¹⁵
• SwiftData, HealthKit et SwiftUI ont également évolué. SwiftData ajoute l’observation et l’historique dans iOS 27 ; HealthKit ajoute des zones d’entraînement et de nouveaux types ; les ajouts de SwiftUI dans iOS 27 couvrent, comme d’habitude, une large surface. Consultez SwiftData in iOS 27, HealthKit in iOS 27 et What’s New in SwiftUI for iOS 27.¹⁶

L’outil de développement pour les travaux iOS 27 est la bêta de Xcode 27. Xcode 27 est sorti en bêta le premier jour de la WWDC (8 juin, build 27A5194q) et en est à la bêta 5 au 10 août (27A5237l). Il comprend Swift 6.4 et les SDKs iOS 27 / iPadOS 27 / tvOS 27 / watchOS 27 / macOS 27 / visionOS 27, et nécessite macOS Tahoe 26.4 ou version ultérieure.¹⁸ Quatre éléments des notes de version sont importants pour les workflows avec agents : Coding Intelligence gagne un mode de planification — les notes le signalent à travers un problème connu lié à la barre de confirmation « Implement the plan? » (178673449), donc attendez que l’agent ait fini de diffuser sa réponse avant de confirmer ou d’ignorer un plan ; l’outil MCP RenderPreview affiche désormais les groupes Preview (174692209) et peut prévisualiser votre interface dans une autre localisation (181040291) ; l’outil « Prepare Project for Localization » destiné aux agents indique désormais les clés String Catalog supprimées parce qu’elles n’apparaissent plus dans le code source (179755385) ; et Address Sanitizer peut ne pas se lancer sur des cibles 27.0 lorsque l’app a été compilée avec Xcode 26.4 ou une version antérieure — utilisez Xcode 26.5+ pour les exécutions ASan (178072780).¹⁸ La bêta 5 ajoute deux autres éléments qui comptent ici. Les agents peuvent désormais vérifier les apps watchOS, « including rotating and pressing the Digital Crown, and pressing the side and Action buttons (Apple Watch Ultra) » (181147968) — c’est la première fois que les agents d’Apple peuvent exercer les commandes physiques d’une app watch, ce qui réduit une partie de la lacune de vérification visuelle documentée dans ce guide. Apple a également présenté un serveur MCP qui n’a plus besoin que Xcode soit ouvert ; consultez la section consacrée au serveur MCP d’Apple ci-dessous.²² L’outillage MCP a également rattrapé la bêta : XcodeBuildMCP v2.7.0 (2026-07-23) a rendu ses outils d’automatisation d’interface entièrement compatibles avec les simulateurs Xcode 27 via Device Hub, y compris le lancement de fenêtres de simulateur et les commandes clavier — avant cette version, l’automatisation d’interface à l’exécution n’était fiable qu’avec les simulateurs Xcode 26, ce qui rendait manuelle la vérification d’interface pilotée par agent sur la bêta iOS 27.²¹

La leçon pour l’opérateur reste celle que développe le reste de ce guide : l’agent écrit le code, mais vous lui apportez les connaissances qui lui manquent. Pour les bêtas iOS 27, cela signifie nommer ces frameworks dans votre prompt ou votre CLAUDE.md et relier l’agent à la documentation d’Apple, car le modèle utilisera sinon la forme iOS 26 de chaque API. Tout le reste de ce guide (runtimes, MCP, hooks, modes d’échec) reste inchangé pour les travaux iOS 27.

Le portfolio : 8 apps, 293 fichiers

Avant d’aborder la configuration, voici sur quoi repose ce guide. Il ne s’agit pas de projets jouets : ils couvrent cinq frameworks Apple, trois plateformes et toute la gamme de complexité iOS, d’un suivi d’entraînement de 14 fichiers à un minuteur de méditation multiplateforme de 63 fichiers.

Pourquoi le nombre de fichiers compte : l’efficacité des agents est corrélée à la lisibilité du projet, et non à sa taille. Return (63 fichiers) produit de meilleures sorties d’agent qu’amp97 (41 fichiers), car Return possède un CLAUDE.md détaillé avec annotations de fichiers, diagrammes d’architecture et patterns explicites. Les shaders Metal d’amp97 sont intrinsèquement plus difficiles à appréhender pour les agents, quelle que soit la qualité de la documentation.

Prérequis

Avant de configurer un runtime d’agent pour le développement iOS :

Échéance App Store Connect : à compter du 2026-04-28, les envois d’app vers App Store Connect doivent être compilés avec Xcode 26 ou version ultérieure, en utilisant des SDKs pour iOS 26, iPadOS 26, tvOS 26, visionOS 26 ou watchOS 26.²⁶ (Les soumissions macOS ne sont pas concernées par cette exigence.) Si votre équipe utilise encore Xcode 16.x, la chaîne d’outils assistée par agent de ce guide fait également office de levier de transition — aucun des serveurs MCP ci-dessous ne fonctionne de toute façon sans Xcode 26.3+.

Obligatoire : - macOS 15+ (Sequoia) ou macOS Tahoe (Xcode 26.6 nécessite macOS Tahoe 26.2+ ; la bêta de Xcode 27 nécessite Tahoe 26.4+) - Xcode 26.3+ installé et configuré (le minimum pour xcrun mcpbridge) ; Xcode 26.6+ recommandé. Xcode 26.6 (2026-06-25, build 17F113) est la dernière version stable et apporte trois changements Coding Intelligence pertinents pour les agents : Google Gemini comme fournisseur d’assistant de programmation, la prise en charge d’Agent Client Protocol (ACP) et le rendu de variantes — clair/sombre, orientation, tailles de texte — dans l’outil MCP de prévisualisation ; il corrige aussi deux plantages lors de tours d’agent ainsi que le blocage lorsqu’un agent pose une question, et fournit Swift 6.3 avec les SDKs de génération iOS 26.5.¹⁷ Les améliorations du workflow 26.5 — mise en file des messages dans l’assistant de programmation et prise en charge des questions de clarification — ainsi que les pièces jointes d’images Swift Testing de 26.4, la gravité des incidents enregistrés, les avertissements de plantage des tests d’interface avec crashlogs et les améliorations de l’éditeur String Catalog sont toutes conservées.²⁷²⁸ Versions stables précédentes : 26.5 (2026-05-11, build 17F42) et 26.4.1 (2026-04-16, build 17E202).²⁹ - Au moins un runtime iOS Simulator installé - Un compte Anthropic API (pour Claude Code) ou un compte OpenAI (pour Codex)

Recommandé : - SwiftFormat installé (brew install swiftformat) — utilisé par les hooks de formatage à l’enregistrement - SwiftLint installé (brew install swiftlint) — facultatif, mais utile pour l’application des styles - Une familiarité avec le terminal — les trois runtimes fonctionnent depuis la ligne de commande ou s’y intègrent

Vérifiez votre installation Xcode :

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

Si xcrun mcpbridge renvoie « command not found », vous avez besoin de Xcode 26.3 ou version ultérieure. Installez ou mettez à jour Xcode via l’App Store ou developer.apple.com. Remarque : xcode-select --install installe uniquement les Command Line Tools, qui n’incluent pas mcpbridge — vous avez besoin de l’application Xcode.app complète.

Trois environnements d’exécution d’agents pour iOS

Trois environnements distincts peuvent écrire, compiler et tester du code iOS. Ils ne sont pas interchangeables — chacun présente des atouts, des modes d’intégration MCP et des cas d’usage idéaux différents.

1. Claude Code CLI

De quoi s’agit-il : l’assistant de programmation agentique en terminal de Anthropic. Il lit votre base de code, exécute des commandes, modifie des fichiers et se connecte à des outils externes via MCP.⁷

Intégration MCP : prise en charge complète de XcodeBuildMCP et du MCP Xcode d’Apple. L’agent découvre les outils via le protocole MCP et les appelle avec des paramètres structurés. 82 + 20 outils répartis sur les deux serveurs.

Configuration :

# 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 — programme d’installation automatique xcodebuildmcp init (v2.1.0+, 2026-02-23) :

Si vous préférez éviter le câblage manuel de MCP, XcodeBuildMCP v2.1.0+ fournit une sous-commande init qui détecte automatiquement Claude Code, Cursor ou Codex et installe les compétences de l’agent ainsi que la configuration MCP en une étape :

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

Options : --print (écrit la configuration sur stdout pour les clients non pris en charge), --uninstall (supprime). Ignorez cette étape si vous souhaitez contrôler explicitement les serveurs MCP connectés et leur portée ; les invocations manuelles de claude mcp add ci-dessus vous le permettent.³⁰

Idéal pour : les sessions d’implémentation approfondies — création de nouvelles fonctionnalités, refactorisation sur plusieurs fichiers, débogage de problèmes complexes, exécution autonome de boucles compilation-test-correction. La fenêtre de contexte de 1 M de Claude Code (avec Opus 5) permet à l’agent de garder la plupart des projets iOS petits à moyens en mémoire de travail — selon mon expérience, jusqu’à environ 50 fichiers selon leur taille.²⁵

Session typique :

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]

La différence essentielle avec le flux de travail pré-MCP : l’agent ne vous demande jamais de compiler manuellement ni de coller la sortie d’erreur. La boucle compilation-erreur-correction est autonome.

2. Codex CLI

De quoi s’agit-il : l’agent de programmation en terminal d’OpenAI. Son concept est proche de Claude Code, mais il exécute les modèles Codex d’OpenAI et adopte un modèle d’autorisations différent. La gamme actuelle comprend GPT-5.6 Sol (modèle phare, le plus performant pour la programmation complexe), GPT-5.6 Terra (équilibre par défaut pour le quotidien) et GPT-5.6 Luna (rapide et le moins cher), ainsi que GPT-5.3 Codex Spark, un aperçu de recherche uniquement textuel. GPT-5.4 et GPT-5.4-mini seront retirés de Codex le 31 août 2026 — migrez ces configurations vers Terra et Luna, respectivement.²³

Intégration MCP : Codex prend en charge MCP via la commande codex mcp add. Le MCP Xcode d’Apple fonctionne directement :

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

XcodeBuildMCP fonctionne également avec Codex via la même commande npx :

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

Idéal pour : les opérations batch sans interface, l’intégration CI/CD et les tâches pour lesquelles vous souhaitez un second avis issu d’une autre famille de modèles. Le mode sandbox de Codex exécute le code dans des environnements isolés, ce qui est utile pour les opérations destructrices, comme les exécutions de suites de tests qui modifient l’état.

Différences clés avec Claude Code : - Utilise des modèles OpenAI plutôt que des modèles Claude - Fenêtres de contexte et économie de jetons différentes - Modèle d’autorisations privilégiant le sandbox (plus restrictif par défaut) - Écosystème MCP plus restreint (moins de serveurs communautaires testés) - Système de hooks disponible (v0.119.0+) mais moins mature que celui de Claude Code — moins de types d’événements et aucun champ conditionnel if

Quand utiliser Codex plutôt que Claude Code pour iOS :

Utilisez Codex lorsque vous souhaitez diversifier les modèles — faire réviser par un second agent le code écrit par le premier permet de détecter des catégories d’erreurs différentes. Le flux de travail collaboratif (Claude construit, Codex révise) est efficace pour iOS, car des motifs SwiftUI qui semblent corrects à une famille de modèles peuvent contenir des problèmes subtils qu’une autre détectera. Les shaders Metal et les modèles de concurrence bénéficient tout particulièrement d’une révision par deux modèles.

3. Agents natifs Xcode

De quoi s’agit-il : Apple a intégré des agents de programmation IA directement dans le panneau Intelligence de Xcode. Depuis Xcode 26.3, vous pouvez configurer Claude Agent et Codex en tant que fournisseurs d’intelligence dans Réglages Xcode > Intelligence.¹⁰ Xcode 26.6 élargit la sélection : Google Gemini est désormais disponible dans l’assistant de programmation (171990272), et Xcode ajoute la prise en charge du protocole Agent Client Protocol (ACP) (178294840) — une intégration lancée avec deux fournisseurs en compte maintenant trois, plus un protocole ouvert permettant à tout agent compatible ACP de se connecter au panneau Intelligence.¹⁷

Configuration :

1. Ouvrez Xcode 26.3+
2. Accédez à Réglages > Intelligence
3. Ajoutez un nouveau fournisseur :
4. Pour Claude : sélectionnez « Claude Agent », puis saisissez votre clé API Anthropic
5. Pour Codex : sélectionnez « Codex », puis saisissez votre clé API OpenAI
6. Pour Gemini : sélectionnez « Google Gemini » (Xcode 26.6+)
7. Pour tout autre outil : connectez un agent compatible ACP (Xcode 26.6+)
8. L’agent apparaît dans la barre latérale Intelligence et peut être invoqué en ligne

Idéal pour : les modifications rapides en ligne, la complétion de code avec un raisonnement de niveau agent et les développeurs qui préfèrent ne pas quitter Xcode. L’intégration native donne directement à l’agent accès au contexte du projet Xcode — fichiers ouverts, cibles de compilation, configuration des schémas — sans pont MCP.

Limites par rapport aux agents CLI — dans Xcode 26.x : - Aucun système de hooks — vous ne pouvez pas imposer un formatage à l’enregistrement ni bloquer les écritures dans .pbxproj - Aucun chargement de CLAUDE.md — l’agent ne lit pas vos fichiers de configuration au niveau du projet - Autonomie limitée — l’agent agit sur le fichier ou la sélection actuelle, et non sur l’ensemble du projet - Aucune délégation à des sous-agents — les tâches complexes en plusieurs étapes ne peuvent pas être parallélisées - Aucune configuration de serveur MCP — l’agent utilise uniquement les outils intégrés de Xcode

Xcode 27 invalide la majeure partie de cette liste. Depuis la bêta 1 (8 juin), les agents de Xcode constituent une plateforme d’extension plutôt qu’un assistant en ligne :²²

• Plug-ins : « Les agents dans Xcode peuvent désormais être étendus avec des plug-ins contenant des compétences, des serveurs MCP et des configurations d’agents ACP. Les compétences sont invocables sous forme de commandes slash avec prise en charge de la complétion. » (178289210) — les limites « outils intégrés uniquement » et « aucune configuration MCP » ont donc disparu.
• Contrôle du simulateur : les agents « peuvent désormais démarrer des simulateurs, installer et lancer des apps, synthétiser des événements tactiles et capturer des captures d’écran afin de vérifier le comportement de l’UI » (175179787), et, depuis la bêta 5, ils peuvent piloter les entrées matérielles watchOS (181147968).
• Accès au débogueur : le serveur MCP Xcode a reçu des outils permettant de manipuler l’état d’exécution, lire la console du débogueur, changer de schéma et de destination d’exécution, ainsi que d’inspecter ou modifier les « paramètres de compilation, options du compilateur, entitlements et clés Info.plist » (176935844).
• Une couche de sécurité du système de fichiers « qui surveille et contrôle l’accès au système de fichiers par les agents de programmation et tous les processus qu’ils lancent » (178289431), ainsi qu’une planification de premier plan (172857081) et des informations de projet couvrant les crashs, blocages, problèmes d’énergie et de lancement (177568662).

Un avertissement qui découle directement de 176935844 : les agents Xcode peuvent désormais modifier les paramètres de compilation, les entitlements et les clés Info.plist. La protection .pbxproj que ce guide met en place avec un hook PreToolUse ne s’applique pas dans Xcode, car le hook réside dans la configuration de votre agent CLI, et non dans celle d’Apple. Si vous comptez sur ce hook comme filet de sécurité, sachez qu’il n’a aucune autorité sur le panneau Intelligence.

Quand utiliser les agents natifs Xcode :

Pour des modifications rapides et ciblées, lorsque passer au terminal représente une surcharge. « Ajoutez une propriété calculée à ce modèle. » « Écrivez un test unitaire pour cette fonction. » « Refactorisez cette vue pour utiliser @Observable. » Des tâches qui touchent un ou deux fichiers et ne nécessitent pas de cycle compilation-test.

Pour tout ce qui exige de compiler, tester, refactoriser plusieurs fichiers ou corriger des erreurs de manière autonome, utilisez un agent CLI avec MCP.

Matrice de comparaison des environnements d’exécution

La recommandation : utilisez Claude Code CLI comme environnement principal. Utilisez les agents natifs Xcode pour les modifications rapides en ligne. Utilisez Codex CLI pour les passes de révision et les opérations batch. Les trois se complètent plutôt qu’ils ne se concurrencent.

Configuration de MCP : le guide complet

MCP (Model Context Protocol) transforme un agent qui « écrit du Swift en espérant que vous le compilerez » en un agent qui « écrit du Swift, le compile, lit les erreurs structurées et les corrige ».² Cette section va plus loin que le billet de blog¹¹ — elle couvre les deux serveurs, toutes les méthodes d’installation, la vérification et la configuration de l’agent qui garantit que les outils sont réellement utilisés.

XcodeBuildMCP : 82 outils pour le développement iOS sans interface graphique

XcodeBuildMCP encapsule xcodebuild, xcrun simctl et LLDB dans 82 outils MCP structurés (inventaire annoncé, vérifié comme inchangé de v2.6.2 à v2.7.0), répartis en 12 catégories de flux de travail.³¹⁹²¹ Le dépôt canonique du projet se trouve dans l’organisation GitHub getsentry — Sentry l’assure, et l’URL d’origine cameroncooke/XcodeBuildMCP redirige désormais vers celle-ci, ce qui compte lorsque d’anciens articles citent l’ancienne adresse.²¹ Il fonctionne sans que Xcode soit ouvert — l’ensemble du cycle compilation-test-débogage opère sans interface graphique via les outils en ligne de commande d’Apple. Deux précisions sur l’inventaire méritent d’être connues : une session stdio par défaut expose les deux douzaines d’outils du flux de travail du simulateur et laisse les autres hors du contexte de votre agent — définissez XCODEBUILDMCP_ENABLED_WORKFLOWS (noms de catégories séparés par des virgules dans le tableau ci-dessous) pour en charger davantage — et le même moteur est livré sous forme de CLI (xcodebuildmcp tools rapporte 100 commandes, dont 72 canoniques) si vous voulez des opérations identiques sans MCP.⁹

Options d’installation :

# 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

L’indicateur -s user rend le serveur disponible globalement dans tous les projets. Omettez-le pour une installation limitée au projet (utile si vous voulez MCP uniquement dans les projets iOS, et non dans les projets web).

La variable d’environnement -e XCODEBUILDMCP_SENTRY_DISABLED=true désactive la télémétrie des rapports de plantage. XcodeBuildMCP inclut Sentry par défaut, qui envoie des données d’erreur incluant les chemins de fichiers. Désactivez-la, sauf si vous souhaitez contribuer des diagnostics au projet.¹

Inventaire des outils (82 outils répartis en 12 catégories de flux de travail — outils représentatifs par catégorie) :

Les outils les plus importants au quotidien :

1. build_sim — Vous l’appellerez des centaines de fois. Il retourne JSON avec les erreurs classées par fichier, ligne et gravité. L’agent lit l’erreur, accède au fichier et la corrige sans que vous ayez à intervenir.

2. test_sim — Retourne les résultats par méthode de test. L’agent sait précisément quel test a échoué et pourquoi, et non simplement que « les tests ont échoué ».

3. list_sims + boot_sim — Gestion des simulateurs sans mémoriser les indicateurs de xcrun simctl. L’agent découvre les runtimes disponibles et choisit un appareil approprié.

4. discover_projs + list_schemes — Inspection du projet. L’agent n’a pas besoin de deviner le nom de votre scheme ni la structure de votre workspace.

5. debug_attach_sim + debug_stack + debug_variables — Débogage LLDB distant. L’agent peut définir des points d’arrêt, inspecter des variables et parcourir le code pas à pas sans que vous ouvriez le débogueur.

Ce que v2.6.0 a changé (2026-06-01) — automatisation de l’interface à l’exécution :

La version v2.6.0 a reconstruit l’automatisation de l’interface autour d’un contexte réutilisable plutôt que de captures d’écran ponctuelles.¹⁹ snapshot_ui retourne désormais des références d’éléments stables et un hash d’écran, et accepte sinceScreenHash afin que l’agent puisse éviter une capture complète lorsque l’écran n’a pas changé. Trois nouveaux outils bouclent le flux : wait_for_ui interroge jusqu’à ce qu’un prédicat soit satisfait (existence, état activé, focus, texte visible ou mise en page stabilisée), au lieu que l’agent devine avec des pauses ; batch effectue une séquence d’actions par référence d’élément en un seul appel ; drag réalise des gestes de glissement par référence d’élément pour les feuilles et le défilement de listes. type_text a gagné replaceExisting pour remplacer la valeur d’un champ plutôt que l’ajouter, les contrôles candidats sont classés à partir des données d’accessibilité, et les résultats structurés incluent désormais des indications nextSteps (les schémas de résultats ont été versionnés en v2 dans cette version ; v2.7.0 a depuis fait passer les résultats de compilation/test à schemaVersion: 3 — voir ci-dessous). Définissez XCODEBUILDMCP_HEADLESS_LAUNCH=true pour lancer les apps en arrière-plan sans détourner le focus de macOS — c’est la différence entre une session d’agent que vous pouvez laisser tourner et une autre qui ramène sans cesse votre fenêtre Simulator au premier plan. Dans une tâche déterministe sur une app météo, le benchmark du projet affirme environ 70 % de temps réel en moins, 68 % de tokens en moins et 76 % d’appels d’outils en moins par rapport au flux antérieur à 2.6 — ce sont les chiffres du projet, pas une mesure indépendante, mais le mécanisme (éviter les captures inchangées, regrouper les actions sur le même écran) correspond précisément aux sources de consommation de tokens de l’automatisation d’interface.¹⁹

Ce que v2.7.0 a changé (2026-07-23) — simulateurs Xcode 27, schéma v3, compilations respectant les schemes :

La version v2.7.0 est plus modeste que 2.6.0, mais elle apporte un changement cassant et une évolution de comportement à connaître avant la mise à niveau.²¹ L’essentiel : les outils d’automatisation de l’interface fonctionnent désormais pleinement avec les simulateurs Xcode 27 via Device Hub, y compris le lancement de fenêtres de simulateur et les contrôles clavier — comblant le manque qui rendait l’automatisation de l’interface à l’exécution fiable uniquement sur les simulateurs Xcode 26. Changement cassant : les outils de compilation et de test retournent désormais des résultats structurés schemaVersion: 3 (ils étaient en v2 depuis 2.6.0) — tout ce que vous avez écrit pour valider ou analyser des résultats verrouillés sur la version 2 doit être mis à jour. Évolution de comportement : les outils de compilation, de test, de nettoyage et de chemin d’app respectent désormais la configuration de l’action du scheme lorsque configuration est omis, au lieu de toujours choisir Debug par défaut — si l’action Test d’un scheme est définie sur Release, un test_sim non qualifié compile désormais en Release ; transmettez donc configuration explicitement lorsque votre flux dépend d’une configuration précise. Plus discret mais utile : les packages réutilisables de préparation de test .xctestproducts permettent de relancer des tests sans reconstruire tout en produisant un nouveau .xcresult à chaque exécution ; extraArgs par défaut au niveau de la session vous permet de définir une fois les indicateurs xcodebuild communs pour une session au lieu de les répéter à chaque appel ; une nouvelle commande CLI xcodebuildmcp purge signale et nettoie le stockage de l’espace de travail de XcodeBuildMCP (simulation par défaut, suppression uniquement sur demande explicite) ; et une correction a été apportée pour les clients MCP qui attendaient 10 à 17 secondes avant que les outils deviennent disponibles — ce qui pouvait faire échouer de brèves vérifications de santé de connexion.²¹

Apple Xcode MCP : 20 outils faisant le lien avec Xcode

Le serveur MCP d’Apple est livré avec Xcode 26.3 via xcrun mcpbridge.⁴ Il communique avec un processus Xcode en cours d’exécution via XPC (le framework de communication interprocessus d’Apple), exposant un état interne auquel aucun outil CLI ne peut accéder.⁵

Installation :

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

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

Nécessite Xcode 26.3+ et un processus Xcode en cours d’exécution. Si Xcode n’est pas ouvert, chaque appel MCP via ce serveur échouera ou se bloquera. XcodeBuildMCP n’a pas cette limitation.

La bêta 5 de Xcode 27 préfigure une sortie de cette contrainte. Apple a ajouté « une nouvelle expérience de serveur MCP qui fonctionne sans nécessiter un workspace Xcode ouvert », activée avec sudo xcrun mcp-server enable et inspectée avec xcrun mcp-server status. Cette même préversion vous permet d’accorder à des agents signés par code une autorisation durable de travailler dans une arborescence de répertoires au lieu de réapprouver à chaque fois. Pour les exécutions sans surveillance, sudo xcrun mcp-server enable --unsafe-always-allow-all-agents approuve tout à l’avance — Apple indique explicitement qu’il ne s’agit pas d’« une configuration recommandée pour une utilisation au bureau », et moi non plus : elle supprime l’étape d’approbation qui empêche un agent d’accéder à des répertoires que vous ne souhaitiez pas exposer. Considérez l’ensemble comme une préversion précoce et conservez XcodeBuildMCP comme solution sans interface graphique jusqu’à sa sortie de préversion.²²

Inventaire des outils (20 outils répartis en 5 catégories) :

Outils propres à Apple MCP (non disponibles dans XcodeBuildMCP) :

1. DocumentationSearch — Recherche dans la documentation développeur d’Apple, y compris les sessions WWDC. Plus rapide et plus fiable que la recherche web pour les questions API relatives à Apple. Demandez « is HKQuantityType(.dietaryWater) valid? » et obtenez une réponse définitive de la source.

2. ExecuteSnippet — Exécution Swift REPL dans le contexte du projet. L’agent peut vérifier le comportement de API, tester les conversions de type et valider des expressions sans compiler l’app complète.

3. RenderPreview — Effectue le rendu des SwiftUI previews sans interface graphique. L’agent peut vérifier si une vue se rend sans erreur, mais ne peut pas évaluer sa justesse visuelle (le rendu est retourné sous forme de données, sans inspection visuelle). Depuis Xcode 26.6, l’outil MCP de preview (appelé « Preview Snapshot » dans les notes de version de 26.6) rend des variantes — apparence claire/sombre, orientation portrait/paysage et surcharges de taille de texte (178831772) — afin qu’un agent puisse vérifier une vue sous plusieurs apparences en un seul passage.¹⁷ La bêta de Xcode 27 l’étend davantage : rendu des groupes Preview et prévisualisation dans une autre localisation.¹⁸

4. XcodeListNavigatorIssues — Retourne les diagnostics en temps réel de l’analyseur de Xcode, pas seulement les erreurs de compilation. Il détecte des problèmes tels que les variables inutilisées, les cycles de rétention potentiels et les avertissements de dépréciation que le système de compilation ne remonte pas.

Pourquoi les deux serveurs

Ils se chevauchent pour les compilations et les tests, mais diffèrent fondamentalement :

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

Utilisez XcodeBuildMCP pour : le cycle compilation-test-débogage. Il fonctionne sans que Xcode soit ouvert, consomme moins de mémoire système et fournit une gestion plus riche des simulateurs et appareils. C’est votre outil de compilation principal.

Utilisez Apple Xcode MCP pour : les recherches dans la documentation, la vérification avec Swift REPL, le rendu de SwiftUI previews et les diagnostics en temps réel. Gardez Xcode ouvert pendant les sessions qui nécessitent ces capacités.

En pratique : j’utilise XcodeBuildMCP pour environ 90 % des appels MCP et Apple Xcode MCP pour la documentation et la vérification REPL. L’agent choisit par défaut XcodeBuildMCP pour les compilations et les tests, car il est plus rapide (pas de surcharge de processus Xcode) et plus fiable (pas de dépendance XPC).

La distinction entre les deux serveurs s’estompe. XcodeBuildMCP 2.6.x ajoute une catégorie de proxy xcode-ide : xcode_ide_list_tools découvre les capacités MCP disponibles uniquement dans Xcode-IDE et xcode_ide_call_tool les invoque (elles apparaissent sous des noms xcode_tools_*, par exemple xcode_tools_documentationsearch), de sorte qu’un seul enregistrement XcodeBuildMCP peut désormais aussi atteindre les outils côté IDE d’Apple.¹⁹ La contrainte importante ne change pas : ces appels proxifiés nécessitent toujours un processus Xcode en cours d’exécution, exactement comme un enregistrement direct xcrun mcpbridge. Gardez les deux serveurs enregistrés si vous souhaitez que les outils d’Apple soient des outils de premier plan dans la liste de l’agent ; le proxy est surtout utile si vous ne voulez qu’une seule entrée de serveur et seulement des lectures IDE occasionnelles.

Vérification

Après avoir installé les deux serveurs, vérifiez qu’ils sont connectés :

# List all configured MCP servers
claude mcp list

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

Si un serveur affiche « Disconnected » ou n’apparaît pas :

1. XcodeBuildMCP ne se connecte pas : vérifiez que Node.js est installé (node --version). La commande npx nécessite Node.js 18+.
2. Apple Xcode MCP ne se connecte pas : vérifiez que Xcode 26.3+ est installé et que la commande xcrun mcpbridge fonctionne dans votre terminal. Ouvrez Xcode au moins une fois pour accepter le contrat de licence.
3. Aucun des deux n’apparaît : redémarrez Claude Code (claude dans un nouveau terminal). Les serveurs MCP enregistrés en cours de session peuvent ne pas apparaître avant le redémarrage.

Apprendre à l’agent à utiliser MCP

Installer les serveurs MCP est nécessaire, mais insuffisant. Sans consignes explicites, l’agent peut revenir à l’exécution de xcodebuild via Bash (sortie non structurée, tokens de contexte gaspillés) ou à la recherche web pour la documentation Apple (plus lente, moins fiable).

Ajoutez ceci à votre CLAUDE.md ou à la définition de votre agent :

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

Ces consignes garantissent que l’agent privilégie les outils MCP. Sans elles, vous verrez l’agent construire de longues commandes xcodebuild via Bash, consommer des milliers de tokens de contexte pour analyser la sortie et parfois identifier à tort l’erreur réelle.⁶

Un changement de comportement de XcodeBuildMCP v2.7.0 appartient au modèle mental de cette section : lorsque configuration est omis, les outils de compilation, de test, de nettoyage et de chemin d’app respectent désormais la configuration de l’action du scheme au lieu de toujours utiliser Debug.²¹ La plupart des schemes s’exécutent et testent en Debug, donc la plupart des projets ne remarqueront rien — mais si l’action d’un scheme est réglée sur Release (fréquent pour les schemes de profilage ou les configurations proches de l’archivage), un build_sim ou test_sim non qualifié compile désormais en Release. Si votre CLAUDE.md ou vos hooks supposent des artefacts Debug, indiquez-le explicitement dans l’appel d’outil ou définissez-le une fois par session avec session_set_defaults.

Compilations longues : Claude Code les exécute désormais en arrière-plan

Deux versions de Claude Code ont changé l’apparence d’une longue compilation dans une session. Depuis v2.1.212 (2026-07-16), tout appel d’outil MCP durant plus de 2 minutes passe automatiquement en arrière-plan afin que la session reste utilisable ; le seuil est configurable — ou ce comportement peut être désactivé — via CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS.²⁰ Les compilations propres et les exécutions complètes de tests via build_sim / test_sim dépassent régulièrement le seuil de 2 minutes dans des projets réels : attendez-vous donc à ce que l’agent continue à travailler — lire des fichiers, planifier la prochaine modification — pendant que la compilation se termine en arrière-plan au lieu de bloquer le tour. La correction associée compte tout autant : avant v2.1.206 (2026-07-09), un request_timeout_ms par serveur configuré via --mcp-config ou .mcp.json était ignoré dans les nouvelles sessions, si bien que les longs appels MCP expiraient avec le délai par défaut de 60 secondes — le symptôme classique était un délai d’expiration lors de la première compilation propre qui « se corrigeait » à la nouvelle tentative.²⁰ Si vous aviez contourné l’un ou l’autre comportement avec des scripts wrapper ou des compilations préchauffées, vous pouvez supprimer ce contournement.

Modèles CLAUDE.md pour projets iOS

Votre CLAUDE.md est le fichier le plus important du projet pour le développement assisté par agent. C’est le document d’intégration de l’agent : la différence entre une nouvelle recrue qui a lu la documentation d’architecture et une autre qui avance au jugé.

Chaque projet iOS que je maintiens possède un CLAUDE.md. Voici les modèles qui fonctionnent, tirés des 8 apps.

Les sections essentielles

Chaque CLAUDE.md iOS a besoin de ces six sections. Tout le reste est facultatif.

1. Identité du projet

# 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

Pourquoi c’est important : l’agent doit connaître la cible de déploiement avant d’écrire le moindre code. Un agent ciblant iOS 17 utilisera NavigationView et @ObservedObject. Un agent ciblant iOS 26 utilisera NavigationStack et @Observable. Le bundle ID compte pour les entitlements et la configuration HealthKit. La version de Swift détermine le modèle de concurrence (async/await ou gestionnaires de complétion, concurrence stricte ou souple).

2. Structure des fichiers avec annotations d’intention

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

Les commentaires en ligne après chaque nom de fichier ne sont pas décoratifs. Ce sont la documentation au meilleur levier que vous puissiez écrire. Quand l’agent décide où ajouter une nouvelle fonctionnalité, ces annotations le guident vers le bon fichier dès la première tentative, au lieu de lui faire lire tous les fichiers pour comprendre l’organisation du projet.

Anti-modèle : lister les fichiers sans annotations. TimerManager.swift n’indique pas à l’agent s’il gère l’état, l’UI, ou les deux. TimerManager.swift # Timer state, logic, and repeat handling lui dit exactement ce qui doit s’y trouver et ce qui n’y a pas sa place.

3. Commandes de build et de test

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

Incluez les commandes brutes même si l’agent devrait préférer MCP. Elles servent de documentation de repli et rendent explicites les noms de schemes et les destinations.

4. Modèles et règles clés

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

Ces modèles empêchent l’agent d’introduire des incohérences. Sans documentation explicite des modèles, l’agent utilisera parfois ObservableObject dans un fichier et @Observable dans un autre, ou créera un nouveau mécanisme de paramètres au lieu d’utiliser le singleton Settings.shared existant.

5. Ce que l’agent ne doit jamais faire

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

Les interdictions explicites sont plus efficaces que les attentes implicites. L’agent suit plus fiablement les contraintes négatives que les suggestions positives, car elles sont binaires (faire / ne pas faire) plutôt qu’heuristiques (préférer ceci / utiliser parfois cela).

6. Contexte propre aux frameworks

Cette section varie selon l’app. Ajoutez-la pour tout framework dont la configuration n’est pas évidente :

Pour les apps HealthKit :

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

Pour les apps SwiftData :

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

Pour les apps SpriteKit :

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

Pour les apps Metal :

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

CLAUDE.md réel : Banana List (SwiftUI + SwiftData + iCloud + serveur MCP)

Voici un exemple annoté montrant comment les six sections fonctionnent ensemble pour une app de complexité moyenne. C’est le modèle CLAUDE.md que j’utilise pour Banana List, une app de liste de courses de 53 fichiers avec synchronisation iCloud et serveur MCP personnalisé qui expose les données de l’app à Claude Desktop :

# 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

CLAUDE.md réel : Reps (app SwiftData minimale — 14 fichiers)

Pour les petits projets, le CLAUDE.md peut être concis. Voici le modèle pour Reps, un suivi d’entraînement de 14 fichiers. Remarquez que même un CLAUDE.md court couvre les six sections essentielles :

# 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

Cela fait 40 lignes de CLAUDE.md pour un projet de 14 fichiers. Il faut 10 minutes pour l’écrire, et cela économise des heures de confusion pour l’agent.

CLAUDE.md réel : Starfield Destroyer (SpriteKit + Metal — 32 fichiers)

Les projets de jeu exigent davantage de contexte propre aux frameworks. L’agent doit comprendre le graphe de scène, les catégories physiques et la machine à états du jeu :

# 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

CLAUDE.md réel : amp97 (Metal + visualisation audio — 41 fichiers)

Les projets Metal exigent le plus de contexte propre aux frameworks, car les agents ne peuvent pas vérifier le rendu visuel :

# 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

Adapter CLAUDE.md à la taille du projet

Le bon niveau de détail dépend du nombre de fichiers et de la complexité des frameworks :

Le coût d’une documentation trop détaillée est presque nul (l’agent ignore ce dont il n’a pas besoin). Le coût d’une documentation insuffisante est élevé (l’agent invente des modèles qui entrent en conflit avec votre codebase).

Checklist CLAUDE.md

Utilisez cette checklist lors de la création ou de l’audit d’un CLAUDE.md pour un projet iOS :

• [ ] Bundle ID et cible de déploiement spécifiés
• [ ] Version de Swift et modèle d’architecture nommés
• [ ] Structure des fichiers avec annotations d’intention en ligne
• [ ] Commande de build avec le bon scheme et la bonne destination
• [ ] Commande de test avec le bon scheme et la bonne destination
• [ ] Préférence MCP indiquée (« préférer build_sim à xcodebuild »)
• [ ] Règle @Observable (jamais ObservableObject)
• [ ] Règle NavigationStack (jamais NavigationView)
• [ ] Interdiction .pbxproj
• [ ] Contexte propre aux frameworks (permissions HealthKit, relations SwiftData, hiérarchie SpriteKit, pipeline Metal)
• [ ] Gardes de disponibilité des plateformes documentées (#if canImport, #if os)
• [ ] Singletons clés et modèles partagés documentés
• [ ] Limitations ou pièges connus signalés

Votre première session d’agent

Avec MCP configuré et un CLAUDE.md dans votre projet, voici le déroulé d’une première session efficace. Cet exemple utilise Claude Code CLI, mais le workflow s’applique à n’importe quel runtime.

Étape 1 : vérifier que l’agent voit votre projet

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.

Si l’agent ne fait pas référence au contenu de votre CLAUDE.md, vérifiez que le fichier se trouve à la racine du projet (dans le même dossier que .xcodeproj ou Package.swift).

Étape 2 : lancer un build de contrôle

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.

Étape 3 : lancer les tests

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.

Étape 4 : implémenter une fonctionnalité

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

La remarque de l’agent indiquant qu’il ne doit pas modifier .pbxproj vient des règles définies dans CLAUDE.md. Sans cette règle, l’agent essaierait de modifier le fichier de projet et risquerait fort de le corrompre.

Ce que les agents font bien dans iOS

Voici les tâches pour lesquelles les agents produisent régulièrement un résultat correct et prêt pour la production, avec un minimum de revue humaine.

Vues et modifiers SwiftUI

Les agents reconnaissent très bien les patterns de la syntaxe déclarative SwiftUI. Composition de vues, chaînes de modifiers, liaisons d’état et mise en page : ces éléments correspondent bien aux données d’entraînement de l’agent, car la surface API de SwiftUI est bien documentée et les patterns sont très cohérents.

Domaines où les agents excellent : - Créer de nouvelles vues à partir d’une description (« créez une feuille de paramètres avec des toggles pour X, Y, Z ») - Appliquer des chaînes de modifiers (.glassEffect(), .sensoryFeedback(), .navigationTitle()) - Convertir des patterns de mise en page (VStack vers LazyVGrid, List vers ScrollView) - Implémenter des liaisons de formulaire @Bindable vers des modèles SwiftData - Créer des preview providers avec des données d’exemple

Exemple de prompt qui produit d’excellents résultats :

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.

La précision compte. « Créez une vue de paramètres » produit un résultat générique. « Créez une SettingsView qui suit le pattern existant dans SettingsSheet.swift » produit un résultat cohérent avec votre codebase.

Modèles et queries SwiftData

Les agents gèrent de manière fiable la macro @Model de SwiftData, les relations et les patterns @Query. La nature déclarative du framework (similaire à Django ORM ou SQLAlchemy) correspond bien aux patterns que l’agent a vus dans de nombreux codebases.

Domaines où les agents excellent : - Définir des classes @Model avec des relations - Écrire des @Query avec des sort descriptors et des predicates - Implémenter des opérations CRUD via modelContext - Préparer des plans de migration entre versions de schéma - Créer des données de preview et des fixtures de test

Domaines où les agents ont besoin d’indications : - Expressions #Predicate complexes (le DSL de predicate de SwiftData a des limites que l’agent ne connaît pas toujours ; documentez les limites connues dans CLAUDE.md) - Configuration de la synchronisation CloudKit (automatique via SwiftData, mais l’agent peut essayer d’implémenter une synchronisation manuelle)

Tests unitaires

Les tests unitaires écrits par les agents sont régulièrement de grande qualité pour les projets iOS. L’agent comprend les patterns XCTest, les méthodes de test async et le cycle de vie setup/teardown.

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)

L’agent produit des cas XCTest bien structurés avec setUp() et tearDown(), des assertions appropriées et une gestion async pour les tests basés sur des timers.

Refactoring et application de patterns

Les agents excellent dans le refactoring mécanique : extraction de vues en composants, conversion de ObservableObject vers @Observable, migration de NavigationView vers NavigationStack et application de patterns cohérents dans plusieurs fichiers.

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.

L’agent avance méthodiquement fichier par fichier, applique correctement la transformation et conserve les fonctionnalités existantes. C’est un travail à fort levier : un refactoring qui prendrait une heure d’édition manuelle se termine en quelques minutes avec une précision presque parfaite.

Diagnostic des erreurs de build via MCP

Avec une sortie MCP structurée, les agents diagnostiquent les erreurs de build plus vite que la plupart des développeurs. L’agent lit la JSON d’erreur, identifie le fichier et la ligne exacts, comprend le message d’erreur et applique le correctif, souvent en un seul tour.

Erreurs que les agents corrigent de manière autonome : - Imports manquants - Incompatibilités de types - Lacunes de conformance à des protocoles - Utilisation obsolète de API (avec remplacement) - Paramètres d’initializer requis manquants - Violations du contrôle d’accès

Erreurs pour lesquelles les agents ont besoin d’aide : - Résolution de type ambiguë (plusieurs modules définissent le même type) - Échecs complexes de contraintes génériques - Erreurs d’expansion de macros (l’agent ne peut pas voir la sortie des macros expansées)

Gestion du simulator

Les agents gèrent bien le cycle de vie du simulator via MCP :

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

L’agent appelle list_sims pour trouver les runtimes disponibles, boot_sim pour démarrer le simulator, build_sim pour builder et installer, puis screenshot pour capturer l’écran, le tout via des appels MCP structurés.

Ce que les agents font mal dans iOS

Bilan honnête des situations où les agents échouent. Connaître ces limites évite frustration et tokens gaspillés.

Modifications du fichier .pbxproj — JAMAIS

C’est la règle la plus importante dans le développement iOS avec des agents. Le fichier .pbxproj est la configuration de projet de Xcode : un fichier texte structuré avec des références UUID, des listes de phases de build et l’appartenance aux targets. Il est théoriquement lisible par un humain, mais pratiquement impossible à analyser correctement pour des agents IA.

Pourquoi les agents échouent avec .pbxproj : - Le fichier utilise un format personnalisé (ni JSON, ni YAML, ni XML) où la position a une importance - Chaque entrée est référencée par UUID : ajouter un fichier exige de mettre à jour 3 à 5 sections différentes de manière cohérente - Un seul caractère mal placé corrompt tout le fichier de projet - La résolution des conflits de fusion de Xcode pour .pbxproj est déjà fragile : les modifications par agent aggravent le problème

Ce qui se passe quand un agent modifie .pbxproj : 1. La modification semble réussir (l’agent indique « file updated ») 2. Xcode refuse d’ouvrir le projet (« The project file is corrupted ») 3. Vous passez 15 à 60 minutes à récupérer depuis l’historique git 4. Vous apprenez à ajouter le hook PreToolUse (voir Hooks)

Le workflow : L’agent crée les fichiers Swift. Vous les ajoutez manuellement au projet Xcode (glisser-déposer dans Xcode, ou File > Add Files). Cela prend 5 secondes par fichier et évite des heures de récupération.

Pour les projets Swift Package Manager : Cette limite est moins sévère. Package.swift est un fichier Swift standard que les agents peuvent modifier de manière fiable. Si votre projet utilise exclusivement SPM (sans .xcodeproj), l’agent peut gérer toute la structure du projet.

Modifications complexes d’Interface Builder / Storyboard

Si votre projet utilise Interface Builder (fichiers .xib) ou des Storyboards (fichiers .storyboard), les agents ne peuvent pas les modifier utilement. Ce sont des fichiers XML avec des UUID générés automatiquement, des références de contraintes et des connexions d’outlets conçus pour une édition visuelle, pas textuelle.

La mitigation : Utilisez exclusivement SwiftUI pour les nouvelles vues. Si votre projet contient d’anciens fichiers Interface Builder, laissez-les tels quels et construisez la nouvelle UI en SwiftUI.

Optimisation des performances

Les agents écrivent du code correct, mais pas nécessairement performant. Ils ne peuvent pas profiler votre app, identifier les goulots d’étranglement ni mesurer les fréquences d’images. L’optimisation des performances exige :

1. Un profilage avec Instruments (outil visuel, inaccessible aux agents)
2. Une compréhension des caractéristiques GPU/CPU de l’appareil précis
3. Des modifications itératives pilotées par la mesure

Où cela apparaît : - Optimisation de shaders Metal (l’agent écrit du Metal valide, mais ne peut pas mesurer le temps de frame GPU) - Complexité du body des vues SwiftUI (l’agent crée des vues profondément imbriquées qui entraînent un surcoût de redessin) - Optimisation des fetchs Core Data / SwiftData (l’agent écrit des requêtes correctes qui peuvent être lentes sur de grands jeux de données)

La mitigation : Utilisez les agents pour l’implémentation, profilez manuellement avec Instruments, puis demandez à l’agent d’appliquer les optimisations spécifiques que vous avez identifiées.

Signature de code et provisioning

Les agents ne peuvent pas déboguer les problèmes de signature de code au-delà de la lecture du message d’erreur. La gestion des profils de provisioning, la création de certificats, la configuration des entitlements et la soumission à l’App Store sont fondamentalement des workflows opérés par des humains, qui passent par le portail Apple Developer, Keychain Access et l’interface de signature de Xcode.

Ce que l’agent voit : « Signing for ‘Return’ requires a development team. »

Ce que l’agent ne peut pas voir : Si votre certificat a expiré, si le profil de provisioning inclut l’appareil, si le bundle ID correspond à l’App ID, ou si votre fichier d’entitlements est correct.

La mitigation : Gérez toute la signature dans l’onglet Signing & Capabilities de Xcode. Ne demandez pas aux agents de déboguer les échecs de signature.

Débogage complexe de shaders Metal

Les agents écrivent du Metal Shading Language (MSL) syntaxiquement correct, mais ne peuvent pas vérifier le rendu visuel ni déboguer les problèmes côté GPU. Les shaders Metal s’exécutent sur le GPU : l’agent ne dispose d’aucun mécanisme de retour pour savoir si le shader produit des résultats visuels corrects.

Ce que les agents peuvent faire avec Metal : - Écrire des shaders vertex et fragment à partir de descriptions - Configurer le pipeline de rendu Metal en Swift - Créer des compute shaders pour des opérations parallèles sur les données - Corriger les erreurs de compilation dans les fichiers .metal

Ce que les agents ne peuvent pas faire avec Metal : - Vérifier la justesse visuelle de la sortie du shader - Déboguer les performances GPU (temps de frame, occupancy, bande passante mémoire) - Diagnostiquer les artefacts visuels (banding, problèmes de précision, espace colorimétrique incorrect) - Tester sur différentes architectures GPU (différences de comportement entre A-series et M-series)

La mitigation : Testez les shaders Metal sur des appareils physiques. L’implémentation Metal du Simulator n’est pas représentative du comportement GPU des appareils. Utilisez GPU Frame Capture de Xcode pour le débogage visuel.

Vérification visuelle de la mise en page

Les agents ne peuvent pas voir l’UI de votre app. Ils écrivent du code de layout SwiftUI et peuvent vérifier qu’il compile, mais ils ne peuvent pas déterminer si l’écran obtenu a l’apparence attendue. Une vue rendue 10 pixels trop à gauche, utilisant la mauvaise graisse de police ou contenant des éléments qui se chevauchent ne produit aucune erreur de build et passe tous les tests logiques.

La mitigation : Relisez visuellement les modifications d’UI. Utilisez SwiftUI Previews dans Xcode (ou RenderPreview via Apple MCP pour un rendu headless) afin de vérifier la mise en page. Envisagez des snapshot tests avec des bibliothèques comme swift-snapshot-testing pour détecter automatiquement les régressions visuelles.

Hooks pour le développement iOS

Les hooks sont des commandes shell qui s’exécutent de manière déterministe à des étapes précises du workflow de l’agent. Ils constituent le mécanisme d’application des règles — toute la différence entre « veuillez ne pas modifier .pbxproj » (une suggestion que l’agent peut ignorer) et « vous ne pouvez pas modifier .pbxproj » (un blocage strict).

Pour en savoir plus sur le système de hooks, consultez le guide des hooks Claude Code. Cette section présente les modèles de hooks propres à iOS.

PreToolUse : bloquer les écritures dans .pbxproj

Le hook le plus important de tout projet iOS. Il empêche l’agent d’écrire dans les fichiers .pbxproj, les dossiers .xcodeproj/ et les autres fichiers gérés par Xcode :

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

Placez-le dans .claude/settings.json à la racine du projet ou dans ~/.claude/settings.json pour une protection globale.

Fonctionnement : lorsque l’agent tente d’utiliser l’outil Edit ou Write sur un fichier correspondant au motif, le hook s’exécute, détecte le chemin du fichier, affiche un avertissement dans stderr et se termine avec le code 2 (ce qui bloque l’utilisation de l’outil). L’agent reçoit le message d’erreur et adapte son approche.

Ce qu’il intercepte : - Les modifications directes de .pbxproj - Tout fichier situé dans les dossiers .xcodeproj/ ou .xcworkspace/ - Les fichiers Interface Builder (.xib, .storyboard)

PostToolUse : formatage à l’enregistrement avec SwiftFormat

Formatez automatiquement les fichiers Swift chaque fois que l’agent les écrit ou les modifie :

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

Prérequis : SwiftFormat doit être installé (brew install swiftformat).

Pourquoi c’est important : les agents produisent du code Swift syntaxiquement correct, mais ne respectent pas toujours les conventions de formatage. SwiftFormat normalise l’indentation, le placement des accolades et l’ordre des imports.⁸ Grâce au hook de formatage à l’enregistrement, chaque fichier Swift manipulé par l’agent est automatiquement formaté avant que vous ne le voyiez.

Facultatif : ajoutez un fichier de configuration .swiftformat à la racine de votre projet pour personnaliser les règles de formatage :

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

PostToolUse : exécuter automatiquement SwiftLint

Si vous utilisez SwiftLint, exécutez-le après chaque modification d’un fichier Swift :

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

Le || true empêche les avertissements de lint de bloquer l’agent. Si vous souhaitez que les violations détectées par le lint soient bloquantes, supprimez-le.

PostToolUse : lancer automatiquement une compilation après les modifications

Pour une boucle de rétroaction intensive, déclenchez une compilation après chaque modification d’un fichier Swift :

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

Avertissement : cette approche est coûteuse. Chaque modification de fichier déclenche une compilation. Utilisez-la avec parcimonie — elle est particulièrement utile pendant les sessions de débogage, lorsque vous souhaitez obtenir immédiatement le résultat de la compilation. Pour le développement courant, laissez l’agent déclencher manuellement les compilations via MCP lorsqu’il est prêt.

PreToolUse : bloquer les modifications des entitlements

Protégez votre fichier d’entitlements contre les modifications accidentelles de l’agent :

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

Configuration combinée des hooks iOS

Voici le fichier .claude/settings.json complet que j’utilise dans tous mes projets iOS :

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

Vous bénéficiez ainsi de deux garanties : 1. L’agent ne peut pas corrompre les fichiers de projet Xcode (blocage PreToolUse) 2. Chaque fichier Swift manipulé par l’agent est automatiquement formaté (formatage PostToolUse)

Modèles d’architecture adaptés aux agents

Toutes les architectures Swift ne se prêtent pas aussi bien au travail avec des agents. Ces modèles produisent les meilleurs résultats, car ils sont explicites, cohérents et bien représentés dans les données d’entraînement.

@Observable (jamais ObservableObject)

Les projets ciblant iOS 26 ou une version ultérieure doivent utiliser exclusivement @Observable. Il s’agit à la fois du modèle moderne et de celui qui convient le mieux aux agents :

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

Pourquoi @Observable convient bien aux agents : le modèle est plus simple (aucune annotation @Published nécessaire), le modèle de propriété est plus clair (@State au lieu d’avoir à choisir entre @StateObject et @ObservedObject) et les agents génèrent moins de bugs, car il comporte moins d’éléments mobiles.

Documentez cette règle dans CLAUDE.md : même lorsque la cible est iOS 26, les agents reviennent parfois aux modèles ObservableObject issus de leurs données d’entraînement. Une interdiction explicite permet de l’éviter.

NavigationStack (jamais 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 est disponible à partir d’iOS 16 et constitue le seul modèle de navigation à utiliser pour tout nouveau code. Le modèle fortement typé navigationDestination(for:) empêche l’agent de créer des liens de navigation incorrects.

SwiftData pour la persistance

Les modèles SwiftData constituent le modèle de persistance le plus clair pour le développement assisté par des agents :

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

Règles essentielles pour les agents travaillant avec SwiftData : 1. Les classes @Model sont automatiquement Observable — n’ajoutez pas @Observable 2. Utilisez @Bindable pour les liaisons de formulaires : @Bindable var item: GroceryItem 3. Utilisez @Query dans les vues pour obtenir des données réactives : @Query var items: [GroceryItem] 4. Utilisez modelContext.fetch() dans le code hors des vues 5. La suppression des relations nécessite des règles explicites : .cascade, .nullify, .deny

Concurrence avec Swift 6.2

Pour les nouveaux projets, ciblez le mode de concurrence stricte de Swift 6.2. Il s’agit d’un choix de mode de langage, et non d’une version de la chaîne d’outils : le compilateur Swift 6.3 de la version stable de Xcode 26.6 et Swift 6.4 dans la version bêta de Xcode 27 compilent tous deux ces modèles sans aucune modification :¹⁷¹⁸

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

Consignes pour les agents concernant la concurrence : - Marquez tous les modèles de vue avec @MainActor (afin d’éviter les avertissements de concurrence d’accès aux données) - Utilisez async/await pour toutes les opérations asynchrones (aucun gestionnaire de complétion) - Rendez les types valeur Sendable pour les transferts entre acteurs - Utilisez Task { } dans les vues pour l’initialisation asynchrone - Utilisez nonisolated uniquement après avoir mesuré un besoin en matière de performances

Système de conception Liquid Glass (iOS 26+)

iOS 26 a introduit le système de conception Liquid Glass. Les agents le maîtrisent bien lorsqu’ils reçoivent des consignes explicites :

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

À inclure dans CLAUDE.md : « Utilisez .glassEffect() sur les arrière-plans de section et les conteneurs de cartes. Sous iOS 26, les barres de navigation adoptent automatiquement le matériau en verre. Ne recréez pas manuellement des effets de verre à l’aide de matériaux personnalisés : utilisez le modificateur système. »

Contexte propre à chaque framework

Chaque framework Apple présente des particularités pour les agents. Cette section couvre les frameworks utilisés dans les 8 applications.

HealthKit

Applications qui l’utilisent : Return, Water

HealthKit nécessite une gestion rigoureuse des autorisations et des garde-fous propres à chaque plateforme :

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

Règles pour les agents concernant HealthKit : - Vérifiez toujours la disponibilité avec HKHealthStore.isHealthDataAvailable() - Ne présumez jamais que l’autorisation a été accordée — vérifiez-la à chaque écriture - Utilisez #if canImport(HealthKit) pour le code multiplateforme (HealthKit n’est pas disponible sur tvOS) - Ne stockez jamais localement de données de santé au-delà de ce que fournit HealthKit - Incluez NSHealthShareUsageDescription et NSHealthUpdateUsageDescription dans Info.plist

SpriteKit

Applications qui l’utilisent : TappyColor, Starfield Destroyer

Le modèle de graphe de scène de SpriteKit nécessite de fournir des consignes explicites aux 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)

Points forts des agents avec SpriteKit : - Création de séquences et de groupes SKAction - Configuration des corps physiques et de la détection des contacts - Mise en œuvre de machines à états pour les jeux - Création de superpositions pour l’interface de jeu

Points faibles des agents avec SpriteKit : - Boucles de jeu sensibles aux performances (l’agent ajoute des opérations inutiles à chaque image) - Simulations physiques complexes (une physique personnalisée offre une meilleure précision que SKPhysicsBody) - Réglage des effets de particules (travail visuel nécessitant plusieurs itérations)

Metal

Applications qui l’utilisent : amp97, Water, Starfield Destroyer

Metal est le framework qui pose le plus de difficultés aux agents. Le modèle de programmation GPU diffère fondamentalement de celui de Swift côté CPU, et les agents ne peuvent pas vérifier le résultat visuel.

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

Éléments à inclure dans CLAUDE.md pour les projets Metal : - La définition de la structure Uniforms (partagée entre Swift et MSL) - Le modèle de configuration de l’état du pipeline de rendu - Les indices des tampons et leur fonction - Les shaders existants et le rôle de chacun - Les problèmes de précision connus (half ou float)

Live Activities

Applications qui l’utilisent : Return

Live Activities nécessite une configuration particulière que les agents gèrent correctement une fois celle-ci documentée :

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

Applications qui l’utilisent : 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)

Modèles multi-plateformes

Return couvre iOS, watchOS et tvOS. Le développement multi-plateforme avec des agents exige une documentation explicite des limites entre les plateformes.

Organisation du code partagé

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

Règle pour les agents : « Si un fichier se trouve dans Shared/, les modifications affectent toutes les plateformes. Si un fichier se trouve dans un répertoire de plateforme, les modifications sont isolées. Vérifiez toujours dans quel répertoire se trouve un fichier avant de le modifier. »

Gardes de disponibilité des plateformes

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

Instructions pour les agents : « Utilisez toujours des gardes #if canImport() ou #if os() lorsque vous utilisez des frameworks spécifiques à une plateforme. Ne supposez pas qu’un framework est disponible sur toutes les cibles. »

Adaptation de l’interface par plateforme

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

Workflows avancés

Boucles autonomes de build-test-correction

Le modèle le plus puissant : donnez à l’agent une spécification de fonctionnalité et laissez-le itérer de façon autonome à travers des cycles de build-test-correction.

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.

L’agent écrit le code, compile via MCP, lit les erreurs structurées, les corrige, puis recommence. Une fonctionnalité qui nécessiterait 5 à 10 cycles humains de build-erreur-correction est terminée en une seule boucle autonome.

Quand cela fonctionne : des fonctionnalités bien définies avec des critères d’acceptation clairs.

Quand cela échoue : des fonctionnalités ouvertes (« rends ça joli »), du code sensible aux performances ou tout ce qui exige une vérification visuelle.

Délégation à des sous-agents pour iOS

Le système de sous-agents de Claude Code fonctionne pour les projets iOS :

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.

Le sous-agent explore la documentation et les modèles de code dans une fenêtre de contexte distincte, renvoie un résumé, puis la session principale implémente la recommandation. Cela évite que la recherche ne consomme votre contexte principal.

Application de modèles entre applications

Lorsque vous maintenez plusieurs applications iOS aux modèles cohérents, les agents peuvent appliquer les modèles d’une application à une autre :

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.

L’agent lit le modèle source, en comprend la structure et crée une implémentation cohérente dans le projet cible.

Revue par deux agents (Claude + Codex)

Pour les changements critiques, utilisez deux agents issus de familles de modèles différentes :

1. Claude Code écrit l’implémentation
2. Codex CLI la relit dans un passage séparé

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

Des familles de modèles différentes détectent des catégories d’erreurs différentes. C’est particulièrement utile pour les shaders Metal et les modèles de concurrence, où il est facile d’introduire des bugs subtils.

Ce que la revue double détecte et qu’une revue unique manque :

La revue double ne vise pas à trouver davantage de bugs — elle vise à trouver des bugs différents. Chaque famille de modèles présente des modes de défaillance différents dans sa reconnaissance des modèles.

Opérations par lots sur plusieurs applications

Lorsqu’un changement de framework ou de modèle affecte plusieurs applications :

# 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

À utiliser avec prudence. Le flag --dangerously-skip-permissions est requis pour le mode non interactif, mais il contourne toutes les vérifications de sécurité. Assurez-vous que vos hooks PreToolUse sont en place pour protéger les fichiers .pbxproj.

Applications qui utilisent le LLM embarqué d’Apple

Si votre application appelle le framework Foundation Models d’Apple (par exemple pour la synthèse hors ligne, la classification ou la génération de sorties structurées), les agents doivent connaître le budget de prompt. iOS 26.4 a ajouté deux API à SystemLanguageModel qui remplacent l’ancienne estimation de 4 096 tokens : contextSize (le nombre maximal de tokens que le modèle accepte dans une seule conversation) et tokenCount(for:) (async throws, renvoie le nombre de tokens que coûte réellement un prompt donné).³¹ Les deux sont @backDeployed(before: iOS 26.4), ils sont donc disponibles sur toutes les versions d’OS compatibles avec FM sans échelle #available.

Le modèle qu’un agent doit suivre lorsqu’il génère du code de construction de prompts :

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
}

Ajoutez ce modèle à votre CLAUDE.md si l’application utilise SystemLanguageModel. Sans cela, les agents reviennent au hardcode historique de 4 096 et tronquent silencieusement les prompts sur les appareils dotés de fenêtres de contexte plus grandes. La signature async throws de tokenCount(for:) est essentielle : les agents qui collent une version synchrone ne pourront pas compiler.

Études de cas concrets

Les conseils abstraits sont faciles. Voici des scénarios précis tirés des 8 apps qui montrent comment le développement iOS assisté par agents fonctionne en pratique — échecs compris.

Étude de cas 1 : ajouter une app TV à Return (réussite)

La tâche : ajouter une cible tvOS à Return, un minuteur de méditation qui disposait déjà de versions iOS et watchOS. L’app TV devait prendre en charge la navigation avec Siri Remote, une UI grand écran et la synchronisation des paramètres avec l’app iOS.

Ce que l’agent a bien fait : - Il a lu le TimerManager iOS existant et créé un TVTimerManager qui omettait Live Activities et HealthKit (indisponibles sur tvOS) - Il a créé des styles de boutons personnalisés pour la navigation au focus avec Siri Remote (TVCapsuleButtonStyle, TVCircleButtonStyle) - Il a construit un composant TVStepper qui remplace les sélecteurs à roue (inutilisables avec Siri Remote) par des boutons +/- - Il a implémenté la synchronisation des paramètres via App Groups (group.com.941apps.Return) - Il a ajouté des gardes #if os(tvOS) dans tout le code partagé - Il a compilé et testé via MCP avec platform=tvOS Simulator,name=Apple TV

Ce que j’ai dû faire manuellement : - Créer la cible tvOS dans Xcode (File > New > Target > tvOS App) - Ajouter la nouvelle cible au projet Xcode (modifications du .pbxproj) - Configurer l’autorisation App Groups pour la cible TV - Ajouter la cible TV au schéma existant ou en créer un nouveau - Ajouter manuellement tous les fichiers Swift créés par l’agent à la cible TV - Tester la navigation Siri Remote à la main (l’agent ne peut pas évaluer le comportement du focus)

Résultat : 15 nouveaux fichiers Swift, une app TV entièrement fonctionnelle, en environ 3 heures de travail assisté par agent. D’après mon estimation, l’agent a géré environ 80 % du travail d’implémentation ; je me suis occupé des parties qui nécessitaient une interaction avec l’UI de Xcode (autorisations, configuration de cible, indicateurs de capacité) et des tests manuels du focus sur une vraie Apple TV. Un travail solo équivalent dans cette base de code — d’après des fonctionnalités similaires que j’ai livrées sans agents — aurait pris plusieurs jours.

Étude de cas 2 : débogage d’un shader Metal dans amp97 (échec partiel)

La tâche : ajouter un système d’intensité basé sur l’énergie au shader d’oscilloscope. La visualisation devait pulser avec l’énergie audio.

Ce qui s’est passé : 1. L’agent a écrit une modification valide du shader Metal en ajoutant un uniforme uEnergy et du tonemapping HDR 2. Le code s’est compilé sans erreur 3. Sur appareil, la visualisation était entièrement blanche — le coefficient d’intensité était 10 fois trop élevé (3.5 au lieu de 0.30) 4. L’agent ne pouvait pas voir l’écran blanc, il n’avait donc aucun signal de retour 5. J’ai identifié le problème visuellement et demandé à l’agent de réduire le coefficient 6. L’agent l’a réduit, mais la machine à états globale de l’énergie était trop complexe et a cassé le visualiseur autrement 7. Retour arrière complet — deux commits (67959ed et cda4830) annulés dans 869d914

La leçon : les shaders Metal sont le domaine le plus difficile pour le développement assisté par agents, car la boucle de retour est rompue. L’agent peut vérifier la syntaxe (ça compile) et la sémantique (types corrects), mais pas la sortie (l’aspect visuel est correct). Toute modification de shader qui change le comportement visuel nécessite une vérification humaine sur appareil.

Ce que j’ai ajouté à CLAUDE.md ensuite : « 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. »

Étude de cas 3 : migration SwiftData dans Banana List (réussite)

La tâche : migrer le modèle de données de V1 vers V2, en ajoutant un champ quantity à GroceryItem et un nouveau modèle Category avec des relations.

Ce que l’agent a fait : 1. Il a lu les définitions existantes du modèle V1 2. Il a créé les définitions du modèle V2 avec les nouveaux champs et les nouvelles relations 3. Il a écrit un GroceryMigrationPlan conforme au protocole SchemaMigrationPlan 4. Il a implémenté l’étape de migration V1toV2 : ajout de quantity: 1 par défaut et de category: nil 5. Il a mis à jour toutes les vues pour prendre en charge les nouveaux champs 6. Il a mis à jour SampleData.swift pour les aperçus 7. Il a compilé et exécuté les tests via MCP — tout est passé 8. Il a créé des tests unitaires spécifiques à la migration

Le point clé : l’agent a réussi parce que les migrations SwiftData suivent un modèle de protocole bien défini, largement représenté dans la documentation Apple et les données d’entraînement. Le CLAUDE.md documentait explicitement le modèle V1, l’agent comprenait donc depuis quoi il migrait.

Étude de cas 4 : synchronisation de sessions iCloud dans Return (réussite avec complexité)

La tâche : implémenter la journalisation de sessions de méditation entre appareils. Les sessions terminées sur Apple TV ou Mac devaient se synchroniser vers l’iPhone pour la journalisation HealthKit.

Ce que l’agent a produit :

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

L’agent : 1. A créé le modèle de données MeditationSession avec UUID, dates, durée, appareil source et statut de synchronisation HealthKit 2. A construit le singleton SessionStore qui gère NSUbiquitousKeyValueStore pour la synchronisation iCloud 3. A implémenté la résolution des conflits de fusion (déduplication basée sur l’UUID) 4. A ajouté SessionHistoryView avec des adaptations propres à chaque plateforme (balayer pour supprimer sur iOS, focus sur tvOS) 5. A câblé la synchronisation HealthKit côté iPhone pour les sessions provenant d’autres appareils

Ce qui a nécessité des itérations : l’implémentation initiale ne gérait pas le cas où l’app iPhone se lance en arrière-plan (pas de notification au premier plan pour la synchronisation). L’agent avait besoin d’une consigne précise : « Use NSUbiquitousKeyValueStore.didChangeExternallyNotification to trigger sync on background KV changes. » Après cet indice, l’implémentation était correcte.

La leçon : les agents gèrent bien les modèles d’architecture multiplateformes lorsque l’architecture est clairement décrite. Le modèle de synchronisation iCloud n’est pas trivial, mais il suit un schéma Apple documenté que l’agent a compris. Le cas limite (synchronisation en arrière-plan) a nécessité une connaissance humaine du domaine, car il est mal documenté.

Étude de cas 5 : intégration Game Center dans Starfield Destroyer (réussite)

La tâche : ajouter des classements et des succès Game Center au jeu de tir spatial.

Ce que l’agent a bien fait : - Il a implémenté GKLocalPlayer.local.authenticateHandler au point d’entrée de l’app - Il a créé un GameCenterManager avec des méthodes de soumission de score et de signalement des succès - Il a ajouté une vérification de l’état d’authentification avant toutes les opérations Game Center - Il a géré proprement le cas hors ligne (le jeu fonctionne sans Game Center et soumet les scores à la reconnexion) - Il a créé des définitions de succès correspondant au système de progression à 8 vaisseaux

Ce qui a nécessité un travail manuel : - Créer les classements et les succès dans App Store Connect (portail web, inaccessible à l’agent) - Configurer l’autorisation Game Center dans Xcode - Tester avec un compte Game Center sandbox (nécessite une connexion manuelle sur l’appareil)

Cycle de vie du projet avec des agents

Démarrer un nouveau projet iOS

Le workflow optimal pour démarrer un nouveau projet avec l’aide d’un agent :

Phase 1 : configuration humaine (15 à 30 minutes) 1. Créez le projet Xcode (Fichier > Nouveau > Projet) 2. Configurez la signature et les capacités 3. Définissez la cible de déploiement et les destinations prises en charge 4. Ajoutez les entitlements requis (HealthKit, Game Center, etc.) 5. Créez le CLAUDE.md initial avec l’identité et les règles du projet

Phase 2 : implémentation par l’agent (de quelques heures à quelques jours) 1. L’agent crée le modèle de données (SwiftData, Core Data ou structs simples) 2. L’agent construit les vues en suivant vos patterns documentés 3. L’agent implémente la logique métier dans des classes manager/service 4. L’agent écrit les tests unitaires 5. Boucle build-test-fix via MCP (autonome)

Phase 3 : intégration humaine (30 à 60 minutes) 1. Ajoutez les fichiers créés par l’agent aux targets Xcode 2. Vérifiez la signature et les entitlements 3. Testez sur un appareil physique 4. Relisez la mise en page visuelle et l’UX 5. Soumettez à App Store Connect

Maintenir un projet existant

Pour le développement continu d’apps établies :

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]

L’efficacité de l’agent augmente avec la qualité avec laquelle votre CLAUDE.md reflète l’état actuel du projet. Mettez à jour votre CLAUDE.md lorsque vous ajoutez de nouvelles fonctionnalités importantes, modifiez des patterns d’architecture ou introduisez de nouveaux frameworks.

Quand impliquer l’agent, ou non

Configurer les définitions d’agents

Si vous utilisez le système de définition d’agents de Claude Code (.claude/agents/), créez un agent spécifique à iOS :

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

Référencez cet agent avec @ios-developer dans les sessions Claude Code.

Patterns de test pour iOS assisté par agent

Les agents écrivent d’excellents tests unitaires lorsqu’ils reçoivent des consignes claires. Voici les patterns qui produisent les meilleurs résultats.

Organisation des fichiers de test

# 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 pour les tests

Prompt de test efficace :

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.

Pourquoi cela fonctionne : les critères d’acceptation numérotés donnent une checklist à l’agent. La référence à un fichier de test existant établit le pattern. La mention de l’utilisation de setUp() empêche l’agent de créer un état de test enchevêtré.

Prompt de test inefficace :

Write tests for TimerManager.

Cela produit des tests génériques et superficiels qui ratent les cas limites et peuvent ne pas suivre les patterns de votre projet.

Patterns de test async

Pour tester du code async et basé sur des timers :

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

Patterns clés à rappeler aux agents : - @MainActor sur les méthodes de test qui testent des classes @MainActor - async throws pour les tests qui utilisent Task.sleep ou des opérations async - Une tolérance dans les assertions basées sur le temps (1,1 seconde, pas exactement 1,0) - setUp() / tearDown() propres pour isoler les tests

Snapshot Testing

Pour détecter les régressions visuelles, envisagez d’ajouter swift-snapshot-testing :

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.

Les agents configurent correctement les snapshot tests, mais ne peuvent pas examiner les images de référence. Vous relisez les snapshots initiaux, puis les tests de l’agent détectent les régressions visuelles lors des changements futurs.

Gestion de la fenêtre de contexte pour les projets iOS

La fenêtre de contexte de 1 M (Opus 5) est vaste, mais pas infinie. Les projets iOS présentent des contraintes particulières en matière de gestion du contexte.

Coût en tokens des fichiers iOS

Pour un projet de 50 fichiers : la lecture de tous les fichiers consomme environ 50,000-100,000 tokens — bien en deçà de la fenêtre de 1 M. L’agent peut conserver l’intégralité du projet dans son contexte.

Pour un projet de plus de 100 fichiers : une lecture sélective devient nécessaire. L’agent commence par lire CLAUDE.md (pour les annotations relatives à la structure des fichiers), puis consulte les fichiers requis au fur et à mesure. C’est pourquoi les annotations de fichiers dans CLAUDE.md sont essentielles : elles orientent l’agent vers les bons fichiers sans qu’il ait à tout lire.

Stratégies pour les projets volumineux

1. Annotations détaillées des fichiers dans CLAUDE.md — L’agent consulte la cartographie des fichiers et accède directement aux fichiers pertinents
2. Délégation aux sous-agents — Confiez l’exploration et la recherche à des sous-agents (contexte vierge, restitution sous forme de synthèses)
3. Prompts ciblés — « Modifier SettingsView.swift pour ajouter un nouveau bouton d’activation » est préférable à « mettre à jour les paramètres »
4. Limites de session — Démarrez de nouvelles sessions pour les fonctionnalités sans rapport entre elles, au lieu de prolonger une session déjà longue
5. Utilisation de /compact — La commande de compactage de Claude Code résume la conversation et libère de l’espace dans le contexte

Efficacité de MCP en matière de tokens

L’un des arguments les plus convaincants en faveur de MCP : les réponses structurées de JSON consomment bien moins de tokens que la sortie brute de xcodebuild.

Au cours d’une session de développement classique comprenant 10 à 20 cycles de compilation, MCP économise 30,000-150,000 tokens par rapport à la sortie brute de xcodebuild — autant de tokens qui restent disponibles pour le véritable raisonnement sur le code.

Résolution des problèmes

« build_sim a échoué — schéma introuvable »

L’agent devine le nom du schéma. Pour corriger ce problème :

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

Vous pouvez aussi ajouter explicitement le nom du schéma à votre CLAUDE.md :

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

« xcrun mcpbridge — commande introuvable »

Vous devez disposer de Xcode 26.3 ou version ultérieure. Vérifiez la version avec xcodebuild -version. Si vous utilisez Xcode 26.3 ou une version ultérieure, mais que la commande échoue toujours :

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

# Verify
xcrun mcpbridge --help

« Les outils MCP n’apparaissent pas dans Claude Code »

Il se peut que les outils MCP enregistrés en cours de session n’apparaissent qu’après un redémarrage. Quittez Claude Code et démarrez une nouvelle session :

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

Puis vérifiez :

You: List all available MCP tools from XcodeBuildMCP.

« L’agent continue d’utiliser xcodebuild via Bash au lieu de MCP »

L’agent ne découvre pas les outils MCP via Tool Search. Deux solutions :

1. Ajoutez des instructions explicites dans CLAUDE.md (consultez Apprendre à l’agent à utiliser MCP)
2. Formulez une demande directe : « Utilisez l’outil MCP build_sim, et non xcodebuild via Bash »

« La compilation réussit, mais l’agent signale un échec »

XcodeBuildMCP analyse la sortie de xcodebuild. Si la compilation génère des avertissements qui ressemblent à des erreurs (ce qui arrive souvent avec les avertissements d’obsolescence), l’agent peut mal interpréter le résultat. Vérifiez le champ d’état réel dans la réponse de MCP.

« Le simulateur se bloque pendant le démarrage »

Arrêtez tous les simulateurs et redémarrez-les :

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

Vous pouvez aussi demander à l’agent :

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

« L’agent a tenté de modifier .pbxproj malgré les règles de CLAUDE.md »

Les règles de CLAUDE.md sont des recommandations. Les hooks assurent leur application. Sans hook PreToolUse pour bloquer les écritures dans .pbxproj, l’agent finira par tenter de le modifier. Installez le 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'"
      }
    ]
  }
}

Les règles disent « merci de ne pas le faire ». Les hooks disent « vous ne pouvez pas le faire ».

FAQ

Par quel environnement d’exécution d’agent dois-je commencer ?

Claude Code CLI avec XcodeBuildMCP. Il offre l’intégration MCP la plus poussée, le système de hooks le plus abouti et la fenêtre de contexte de 1 million de tokens (Opus 5), capable de conserver des projets iOS entiers dans la mémoire de travail. Commencez par cette configuration, puis ajoutez Codex pour la révision et les agents natifs de Xcode pour les modifications rapides directement dans le code, à mesure que votre workflow évolue.

Ai-je besoin des deux serveurs MCP ?

Pour la plupart des développeurs, XcodeBuildMCP couvre à lui seul 90 % des besoins (compilations, tests, simulateurs et débogage). Ajoutez le serveur Xcode MCP d’Apple si vous souhaitez rechercher dans la documentation, effectuer des vérifications avec le REPL Swift ou générer des aperçus SwiftUI. Vous pourrez toujours l’ajouter ultérieurement : les deux serveurs sont indépendants.

Les agents peuvent-ils créer un nouveau projet Xcode de A à Z ?

XcodeBuildMCP comprend des outils de génération de structure (scaffold_ios_project, scaffold_macos_project) qui créent de nouveaux projets Xcode à partir de modèles. Toutefois, pour les apps destinées à la production, je vous recommande de créer le projet dans Xcode (afin de configurer correctement la signature, les fonctionnalités et la cible), puis de confier aux agents toute l’implémentation du code. Les 5 minutes passées dans l’assistant de création de projet de Xcode vous éviteront des heures de problèmes liés à une configuration de projet générée par un agent.

Comment les agents gèrent-ils les dépendances Swift Package Manager ?

Très bien. Package.swift est un fichier Swift standard que les agents peuvent lire et modifier de manière fiable. L’ajout de dépendances, la mise à jour des plages de versions et la configuration des cibles fonctionnent correctement. La limite concerne la gestion des dépendances fondée sur .xcodeproj (l’interface de résolution des packages de Xcode) : celle-ci est gérée par Xcode et ne doit pas être modifiée par un agent.

Les agents peuvent-ils soumettre une app à l’App Store ?

Non. La soumission à l’App Store implique l’Organizer de Xcode, les profils de provisionnement, les captures d’écran, les métadonnées et le portail App Store Connect. Aucun de ces éléments n’est accessible via MCP ou des outils en ligne de commande d’une manière permettant aux agents de les manipuler utilement. Les agents prennent en charge tout ce qui précède la création de l’archive : implémentation, tests, correction de bugs et documentation. La dernière étape de la soumission reste effectuée par une personne.

Toutefois, les agents peuvent vous aider à rédiger les métadonnées de l’App Store. Demandez à l’agent de rédiger la description de l’app, les mots-clés et le texte des nouveautés à partir des dernières modifications. Les agents excellent dans ce type de génération de texte.

Comment gérer les secrets et les clés d’API dans le développement iOS assisté par des agents ?

Ne validez jamais de secrets dans le dépôt. Pour les apps iOS qui se connectent à des APIs backend :

1. Utilisez des fichiers .xcconfig pour la configuration propre à chaque environnement
2. Ajoutez les fichiers .xcconfig à .gitignore
3. Référencez les valeurs de configuration via les paramètres de compilation d’Info.plist
4. Documentez les secrets requis dans CLAUDE.md sans inclure leurs valeurs réelles

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

L’agent sait que les clés existent et où elles sont utilisées, mais n’accède jamais à leurs valeurs réelles.

Qu’en est-il des animations SwiftUI : les agents peuvent-ils les écrire ?

Les agents écrivent correctement le code d’animation sur le plan syntaxique, mais ne peuvent pas en vérifier visuellement le résultat. Les animations simples (.animation(.spring()), .transition(.slide), withAnimation { }) produisent des résultats corrects. Les animations complexes, en plusieurs étapes et au timing précis nécessitent des ajustements visuels que les agents ne peuvent pas effectuer.

Efficace : « Ajoutez une animation avec effet de ressort lorsque le minuteur passe d’un état à l’autre. »

Inefficace : « Rendez l’animation du minuteur agréable. » (Appréciation subjective nécessitant des ajustements visuels.)

Comment les agents gèrent-ils les modèles de gestion des erreurs ?

Très bien. Les agents maîtrisent les modèles do/catch, Result et async throws de Swift :

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

Les agents produisent une gestion structurée des erreurs avec des messages appropriés pour l’utilisateur. Ils ont parfois tendance à gérer trop d’erreurs (en interceptant des exceptions qui devraient se propager) ; relisez donc les blocs catch.

Puis-je utiliser des agents pour implémenter l’accessibilité ?

En partie. Les agents ajoutent correctement les libellés, les indications et les traits d’accessibilité :

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

Ce que les agents ne peuvent pas faire : vérifier que l’ordre de navigation VoiceOver est correct, tester l’adaptation à Dynamic Type ou évaluer les rapports de contraste des couleurs. Utilisez l’Accessibility Inspector de Xcode pour effectuer ces vérifications.

Comment les agents gèrent-ils les migrations Core Data (si SwiftData n’est pas utilisé) ?

Les agents écrivent les correspondances de migration et les versions de modèle Core Data, mais les étapes manuelles dans Xcode (création de nouvelles versions de modèle et sélection de la version actuelle) ne peuvent pas être automatisées. Si vous utilisez encore Core Data plutôt que SwiftData, documentez l’historique des versions du modèle dans CLAUDE.md :

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

Comment les agents gèrent-ils les aperçus SwiftUI ?

De deux manières : 1. L’outil RenderPreview du serveur Xcode MCP d’Apple génère les aperçus sans interface graphique et renvoie le résultat. L’agent peut vérifier qu’un aperçu se compile et s’affiche sans erreur, mais il ne peut pas en évaluer la justesse visuelle. 2. La vérification par compilation via build_sim confirme que les fournisseurs d’aperçus se compilent. Si un aperçu plante à l’exécution, la compilation réussit tout de même : le plantage ne se manifeste que lorsque Xcode tente de générer l’aperçu.

Pour vérifier visuellement les aperçus, vous devez toujours ouvrir Xcode.

Qu’en est-il de visionOS et de l’Apple Vision Pro ?

Les mêmes principes s’appliquent. XcodeBuildMCP prend en charge les simulateurs visionOS, et les modèles architecturaux (@Observable, NavigationStack, SwiftData) sont identiques. Le code propre à RealityKit (contenu 3D, espaces immersifs, suivi des mains) présente les mêmes limites que Metal : les agents peuvent écrire du code correct, mais ne peuvent pas en vérifier le rendu spatial.

Quelle taille un projet peut-il atteindre avant que les agents rencontrent des difficultés ?

La taille de la fenêtre de contexte constitue le facteur limitant. Avec la fenêtre de 1 million de tokens d’Opus 5, Claude Code peut conserver simultanément environ 50 à 70 fichiers Swift dans sa mémoire de travail active. Pour les projets plus volumineux, l’agent utilise la recherche de fichiers et la lecture sélective afin de travailler sur des sous-ensembles du code. Les projets de plus de 100 fichiers ne posent aucun problème : l’agent lit simplement les fichiers à la demande au lieu de tout conserver dans le contexte.

Dans la pratique, la limite ne tient pas au nombre de fichiers, mais à la cohérence du code. Un projet bien documenté de 200 fichiers, accompagné d’un CLAUDE.md détaillé, produit de meilleurs résultats qu’un projet non documenté de 30 fichiers.

Dois-je connaître Swift pour utiliser des agents dans le développement iOS ?

Vous devez être capable de relire le travail de l’agent et de prendre des décisions architecturales. Il n’est pas nécessaire d’écrire vous-même chaque ligne, mais vous devez suffisamment maîtriser Swift pour repérer les mauvais choix de l’agent, en particulier concernant la concurrence, la gestion de la mémoire et les modèles propres aux frameworks. Un agent multiplie par 10 vos compétences existantes ; il ne les remplace pas.

Comment les agents gèrent-ils les conflits de fusion dans les fichiers Swift ?

Les agents résolvent de manière fiable les conflits de fusion dans les fichiers source Swift. Les marqueurs de conflit standard (<<<<<<<, =======, >>>>>>>) sont bien compris par tous les environnements d’exécution d’agents. Toutefois, les conflits de fusion dans les fichiers .pbxproj doivent toujours être résolus manuellement : ne demandez pas aux agents de résoudre les conflits .pbxproj.

Quel est le coût d’utilisation des agents pour le développement iOS ?

Avec l’offre Max de Anthropic (Opus 5, contexte de 1 million de tokens), une session classique de développement iOS dure de 30 à 120 minutes et traite entre 200 000 et 800 000 tokens. Les appels aux outils MCP ajoutent une surcharge minime (les réponses JSON structurées utilisent efficacement les tokens par rapport aux sorties de compilation brutes). Le coût est comparable à celui de l’utilisation de Claude Code avec n’importe quel autre code : le développement iOS n’est pas sensiblement plus ou moins coûteux que le développement web.

Puis-je utiliser des agents avec des projets UIKit ?

Oui, mais les agents sont plus efficaces avec SwiftUI. UIKit nécessite davantage de code standard, présente une structure moins déclarative et implique souvent des fichiers Interface Builder que les agents ne peuvent pas modifier. Si vous avez un projet UIKit, envisagez d’utiliser les agents pour la couche modèle et la logique métier tout en gérant manuellement l’interface utilisateur, ou migrez progressivement les vues vers SwiftUI.

Comment les agents gèrent-ils la localisation ?

Les agents créent et modifient efficacement les fichiers .xcstrings (catalogues de chaînes Xcode). Ils peuvent ajouter de nouvelles clés de localisation, fournir des traductions et maintenir la cohérence entre les langues. Le format JSON structuré des fichiers .xcstrings se prête bien au travail des agents. Les agents sont également performants avec les fichiers .strings (ancien format) : le format clé-valeur est simple.

Erreurs courantes des agents sous iOS (et comment les éviter)

Voici les erreurs récurrentes que j’ai observées au fil de milliers d’interactions avec des agents sur 8 projets iOS. Chacune peut être évitée grâce à une stratégie adaptée.

Erreur 1 : mélanger les modèles d’observation

Ce qui se passe : l’agent utilise @Observable dans un fichier et ObservableObject dans un autre, ou ajoute @Observable à une classe @Model (qui est déjà Observable).

Prévention : ajoutez des règles explicites dans 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

Erreur 2 : créer des cycles de rétention dans les closures

Ce qui se passe : l’agent crée des closures qui capturent fortement self, en particulier dans Timer.publish, NotificationCenter et les gestionnaires de fin d’exécution.

Prévention : incluez un modèle de closure dans CLAUDE.md :

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

Erreur 3 : ignorer les exigences de @MainActor

Ce qui se passe : l’agent crée des classes @Observable sans isolation @MainActor, ce qui provoque des avertissements de concurrence Swift 6.2 ou des plantages à l’exécution lorsque les mises à jour de l’interface ont lieu en dehors du thread principal.

Prévention :

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

Erreur 4 : utiliser NavigationLink avec une closure de destination

Ce qui se passe : l’agent utilise la forme obsolète NavigationLink(destination:label:) au lieu du modèle avec typage sûr NavigationLink(value:) + .navigationDestination(for:).

Prévention :

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

Erreur 5 : coder en dur les noms des simulateurs

Ce qui se passe : l’agent écrit des commandes de build avec des noms de simulateurs précis (« iPhone 16 Pro ») qui peuvent ne pas exister sur votre système.

Prévention : MCP s’en charge — list_sims détecte les simulateurs disponibles. Dans 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.

Erreur 6 : créer des fichiers dans les mauvais dossiers

Ce qui se passe : l’agent crée un nouveau fichier de vue à la racine du projet plutôt que dans le sous-dossier Views/, ou place un modèle dans le mauvais groupe.

Prévention : les annotations de la structure des fichiers dans CLAUDE.md indiquent où les placer. Ajoutez également :

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

Erreur 7 : ne pas gérer la disponibilité selon la plateforme

Ce qui se passe : l’agent utilise HealthKit dans du code partagé compilé pour tvOS (où HealthKit n’est pas disponible), ou utilise ActivityKit dans du code watchOS.

Prévention :

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

Erreur 8 : surconcevoir des fonctionnalités simples

Ce qui se passe : l’agent crée un protocole, une extension de protocole, une implémentation concrète, une fabrique et un conteneur d’injection de dépendances pour ce qui devrait être une fonction utilitaire de 20 lignes.

Prévention : incluez un principe de simplicité :

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

Une évaluation honnête

Après avoir publié 8 applications iOS avec des agents IA, voici le bilan :

Ce que les agents ont transformé : la vitesse d’implémentation. Ce qui prenait plusieurs jours ne prend plus que quelques heures. Les vues SwiftUI, les modèles SwiftData, les tests unitaires et les refactorisations sont désormais principalement produits par les agents, puis révisés par des humains.

Ce que les agents n’ont pas transformé : les décisions d’architecture, la conception visuelle, l’optimisation des performances ou la soumission sur l’App Store. Ces tâches restent pilotées par des humains.

Le gain est réel, mais limité. Mon estimation subjective sur l’ensemble des 8 applications : une amélioration de 3 à 5 fois du délai de développement d’une fonctionnalité sur les projets bien documentés, avec une configuration appropriée de MCP et des hooks. Cette estimation ne repose pas sur une comparaison avec un groupe témoin ; il s’agit d’une comparaison du temps réel écoulé entre des fonctionnalités développées avec l’aide d’un agent et un travail équivalent réalisé seul dans les mêmes bases de code. Sur les projets non documentés et dépourvus de hooks, le gain ne dépasse peut-être pas 1,5 à 2 fois : l’agent passe trop de temps à deviner au lieu de construire.³³

L’investissement qui porte ses fruits : le temps consacré à CLAUDE.md, aux hooks et à la configuration de MCP. Chaque heure de configuration évite de nombreuses heures passées à corriger les erreurs des agents. La configuration est le produit ; l’agent en est le moteur d’exécution.

Ce qui m’a surpris : à quel point les serveurs MCP ont changé la dynamique. Avant MCP, les agents étaient des éditeurs de texte sophistiqués qui, accessoirement, comprenaient Swift. Après MCP, ils deviennent des partenaires de développement capables d’écrire, de compiler, de tester, de déboguer et d’itérer. Cette boucle de rétroaction structurée fait toute la différence entre un agent qui écrit du code et un agent qui livre du code.

Ce que je dirais à mon ancien moi : commence par la plus petite application (Reps, 14 fichiers), configure correctement MCP et les hooks, rédige un CLAUDE.md détaillé, puis applique ces modèles à des projets plus importants. Ne commence pas par l’application multiplateforme de 63 fichiers. L’investissement dans l’infrastructure est le même quelle que soit la taille du projet : faites-le une fois sur un petit projet, puis reproduisez-le partout ailleurs.

L’avenir : l’intégration native des agents dans Xcode 26.3 n’est qu’un début. La prise en charge de MCP par Apple montre que la chaîne d’outils évolue vers un développement centré sur les agents. Les développeurs qui investissent dès maintenant dans des structures de projet compatibles avec les agents — fichiers CLAUDE.md clairs, architectures testables, hooks automatisés — verront les bénéfices de cet investissement se cumuler à mesure que les outils progresseront.

Fiche de référence rapide

Installation (configuration initiale)

# 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

Sections essentielles de 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

Hooks essentiels

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

Règles d’architecture

@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és des outils MCP

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)

Journal des modifications

Références