Créer des applications iOS avec des agents d’IA : le guide du praticien

TL;DR : Trois environnements d’exécution d’agents produisent 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 compatible avec l’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 compilations, aux tests, aux simulateurs et au débogage. Ce guide présente des modèles CLAUDE.md éprouvés, des configurations de hooks et une évaluation honnête de ce qui fonctionne et de ce qui échoue — à partir de 8 applications iOS en production totalisant 293 fichiers Swift.³⁰ Les agents excellent dans la création de vues SwiftUI et de modèles SwiftData, la refactorisation et le diagnostic des erreurs de compilation. Ils échouent lorsqu’il s’agit de modifier des fichiers .pbxproj, de signer le code et d’effectuer un débogage visuel. C’est la configuration, et non la formulation des prompts, qui comble l’écart entre « l’agent écrit du Swift » et « l’agent livre une application iOS ». Depuis la WWDC 2026 (8 juin), iOS 27 est en version bêta — bêta 4 au 20 juillet — et ajoute des frameworks utiles aux agents (contrôle des appels d’outils de Foundation Models, exécution en arrière-plan d’App Intents, nouveaux frameworks Core AI et Evaluations) qu’il est pertinent de mentionner dans le contexte de votre agent, puisqu’un modèle entraîné avant juin 2026 ne les connaîtra pas. Xcode 26.6 (25 juin 2026, Swift 6.3) constitue la chaîne d’outils stable actuelle ; la version bêta de Xcode 27 (Swift 6.4, SDKs d’iOS 27) suit le cycle d’iOS 27.¹⁷¹⁸

J’ai développé 8 applications iOS avec des agents de programmation IA. Pas des prototypes — des applications publiées 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 applications a soit été écrite par un agent puis relue par mes soins, soit écrite par moi puis refactorisée par un agent. Selon mon estimation, les agents ont assuré l’essentiel de la rédaction ligne par ligne ; je me suis chargé de la révision, du périmètre et des aspects qui exigent un jugement humain (finitions visuelles, signature, optimisation des performances et soumission à l’App Store).

Ce guide est la référence que j’aurais aimé trouver à mes débuts. Il couvre l’ensemble de la chaîne : quel environnement d’exécution d’agents utiliser, comment configurer les serveurs MCP pour bénéficier d’un accès structuré à la compilation, quoi inclure dans votre CLAUDE.md, quels hooks empêchent l’agent d’endommager votre projet Xcode et — point essentiel — dans quels cas les agents échouent et vous devez reprendre la main.

Points clés

Pour les développeurs iOS qui découvrent les agents IA :

• Commencez avec Claude Code CLI + XcodeBuildMCP. Il s’agit de l’environnement d’exécution le plus mature, avec la couverture d’outils MCP la plus complète. Installez deux commandes, ajoutez un CLAUDE.md à votre projet, et l’agent pourra compiler, tester et déboguer sans que vous ayez à copier les messages d’erreur.
• Ne laissez jamais un agent modifier un fichier .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’intégration de l’agent. Les heures que vous y consacrez sont rentabilisées lors de chaque session d’agent intervenant sur le projet.

Pour les utilisateurs expérimentés des agents qui ajoutent iOS à leur flux de travail :

• MCP transforme la boucle de compilation iOS. Avant MCP, les agents écrivaient du Swift, mais ne pouvaient pas vérifier qu’il compilait. Avec XcodeBuildMCP, l’agent écrit le code, le compile, lit les erreurs structurées, les corrige et exécute les tests — de manière autonome.
• Trois environnements d’exécution répondent à des besoins différents. Claude Code CLI pour les sessions agentiques approfondies, Codex CLI pour les traitements par lots sans interface, et les agents natifs de Xcode 26.3 pour les corrections rapides directement dans l’IDE.
• L’infrastructure de hooks reste applicable. Vos formateurs PostToolUse, bloqueurs PreToolUse et hooks d’exécution des tests existants fonctionnent de la même manière pour les projets iOS, moyennant quelques ajustements mineurs des chemins.

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

• L’efficacité des agents dépend de la documentation du projet, pas de sa taille. Une application de 63 fichiers dotée d’un CLAUDE.md détaillé produit de meilleurs résultats avec les agents qu’une application de 14 fichiers qui n’en possède aucun.
• La limite du .pbxproj n’est pas négociable. Les agents ne peuvent pas modifier les fichiers de projet Xcode de manière fiable. Votre flux de travail doit prévoir l’ajout manuel des fichiers aux cibles Xcode.
• ROI honnête : les agents prennent en charge l’essentiel de l’implémentation sur les projets bien documentés — comme le montre l’application TV de 15 fichiers livrée en 3 heures de travail assisté par des agents (étude de cas ci-dessous). Le reste — finitions visuelles, signature, optimisation des performances et 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 par la section qui correspond à votre niveau d’expérience :

Sommaire

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

Ressources connexes

Série sur l’écosystème Apple. 21 articles de production consacrés aux applications SwiftUI qui s’intègrent à Apple Intelligence, MCP, Foundation Models, Vision, Core ML et à la pile de frameworks d’iOS 26. Tirés de Water, Get Bananas, Return et du reste du portfolio 941 :

Portail de la série : Série sur l’écosystème Apple

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 marqué le lancement de la version bêta d’iOS 27. Le workflow de développement avec des agents présenté dans ce guide ne change pas : vous pilotez toujours Claude Code, Codex ou les agents Intelligence de Xcode par l’intermédiaire de MCP, vous rédigez toujours un fichier CLAUDE.md et vous encadrez toujours les opérations destructrices à l’aide de hooks. Ce qui change, c’est l’étendue des technologies pour lesquelles votre agent écrit du code. iOS 27 fournit plusieurs nouveaux frameworks utiles aux agents. En pratique, mieux vaut orienter délibérément votre agent de codage vers ceux-ci, car un modèle entraîné avant juin 2026 ignorera leur existence. iOS 26 reste la version actuellement distribuée ; considérez les éléments ci-dessous comme les cibles à privilégier lorsque vous développez avec les SDK de la version bêta d’iOS 27.

Voici les nouveautés d’iOS 27 qui concernent les agents, chacune accompagnée d’une référence approfondie :

• Foundation Models offre désormais un contrôle sur les appels d’outils. GenerationOptions.ToolCallingMode vous permet de régler, pour chaque requête, la propension du modèle embarqué à appeler des outils. Le framework peut également changer de mode après le premier appel afin de limiter l’activité des outils au cours d’une requête. Le framework Vision fournit maintenant des outils prêts à l’emploi, OCRTool et BarcodeReaderTool, que vous pouvez rattacher à une LanguageModelSession sans écrire le code de reconnaissance. Consultez Foundation Models dans iOS 27 : contrôle des appels d’outils.¹²
• App Intents dépasse désormais la limite des 30 secondes. LongRunningIntent (par l’intermédiaire de performBackgroundTask(options:operation:), qui exige de signaler la progression) prolonge la durée d’exécution en arrière-plan d’une intention pour la synchronisation, le traitement de fichiers et l’inférence sur l’appareil ; SyncableEntity confère à une AppEntity une identité commune à plusieurs appareils ; IndexedEntityQuery permet au système de demander à votre requête de réparer son index Spotlight. Consultez App Intents dans iOS 27 : arrière-plan, synchronisation et Spotlight.¹³
• Core AI est un nouveau framework destiné à l’exécution de modèles sur Apple Silicon. Il se situe sous Foundation Models pour les cas où vous fournissez votre propre modèle au lieu d’utiliser le modèle système d’Apple. Consultez Core AI : exécuter des modèles sur Apple Silicon.¹⁴
• Evaluations est l’équivalent de XCTest pour la qualité des modèles. Ce nouveau framework (macOS 27) permet de mesurer la qualité des sorties d’un modèle dans votre suite de tests : c’est la pièce manquante pour distribuer des fonctionnalités d’IA qu’un agent vous a aidé à créer. Consultez Evaluations : XCTest pour la qualité des modèles.¹⁵
• SwiftData, HealthKit et SwiftUI ont également évolué. SwiftData ajoute l’observation et l’historique dans iOS 27 ; HealthKit introduit des zones d’entraînement et de nouveaux types ; quant à SwiftUI, ses ajouts dans iOS 27 couvrent, comme toujours, un large éventail de fonctionnalités. Consultez SwiftData dans iOS 27, HealthKit dans iOS 27 et Nouveautés de SwiftUI pour iOS 27.¹⁶

La chaîne d’outils pour développer avec iOS 27 est la version bêta de Xcode 27. Xcode 27 est sorti en version bêta le premier jour de la WWDC (8 juin, build 27A5194q) et se trouve en bêta 4 depuis le 20 juillet (27A5228h). Il comprend Swift 6.4 ainsi que les SDK d’iOS 27, d’iPadOS 27, de tvOS 27, de watchOS 27, de macOS 27 et de visionOS 27, et nécessite macOS Tahoe 26.4 ou version ultérieure.¹⁸ Quatre éléments des notes de version comptent pour les workflows avec agents : Coding Intelligence propose désormais un mode de planification — les notes le mentionnent dans le cadre d’un problème connu lié à la barre de confirmation « Implement the plan? » (178673449), alors attendez que l’agent ait fini de générer sa réponse avant de confirmer ou de rejeter un plan ; l’outil MCP RenderPreview affiche maintenant les groupes de Preview (174692209) et peut prévisualiser votre interface dans une autre langue (181040291) ; l’outil destiné aux agents « Prepare Project for Localization » signale désormais les clés du String Catalog supprimées parce qu’elles n’apparaissent plus dans le code source (179755385) ; enfin, Address Sanitizer peut ne pas démarrer sur les cibles 27.0 si l’app a été compilée avec Xcode 26.4 ou une version antérieure — utilisez Xcode 26.5 ou version ultérieure pour les exécutions avec ASan (178072780).¹⁸ Les outils MCP ont eux aussi rattrapé la version bêta : XcodeBuildMCP v2.7.0 (2026-07-23) a rendu ses outils d’automatisation de l’interface pleinement compatibles avec les simulateurs Xcode 27 par l’intermédiaire de Device Hub, notamment pour le lancement des fenêtres du simulateur et les commandes au clavier. Avant cette version, l’automatisation de l’interface à l’exécution n’était fiable qu’avec les simulateurs Xcode 26, ce qui imposait une vérification manuelle de l’interface pilotée par un agent sur la version bêta d’iOS 27.²¹

La leçon pour l’opérateur reste la même que dans le reste de ce guide : l’agent écrit le code, mais c’est vous qui lui fournissez les connaissances qui lui manquent. Pour les versions bêta d’iOS 27, cela signifie nommer ces frameworks dans votre prompt ou votre fichier CLAUDE.md et fournir à l’agent des liens vers la documentation d’Apple ; sinon, le modèle se rabattra sur la structure d’iOS 26 pour chaque API. Tout le reste de ce guide — runtimes, MCP, hooks et modes de défaillance — reste inchangé pour le développement avec iOS 27.

Le portfolio : 8 apps, 293 fichiers

Avant d’aborder la configuration, voici les projets dont ce guide tire ses enseignements. Il ne s’agit pas de projets jouets : ils couvrent cinq frameworks Apple, trois plateformes et tout l’éventail de complexité d’iOS, d’un suivi d’entraînement composé de 14 fichiers à un minuteur de méditation multiplateforme qui en compte 63.

Pourquoi le nombre de fichiers compte : l’efficacité d’un agent est corrélée à la lisibilité du projet, et non à sa taille. Return (63 fichiers) permet à l’agent de produire de meilleurs résultats qu’amp97 (41 fichiers), car Return dispose d’un fichier CLAUDE.md détaillé comprenant des annotations sur les fichiers, des diagrammes d’architecture et des modèles explicites. Les shaders Metal d’amp97 sont intrinsèquement plus difficiles à analyser 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 apps envoyées à App Store Connect devront être compilées avec Xcode 26 ou version ultérieure à l’aide des SDK pour iOS 26, iPadOS 26, tvOS 26, visionOS 26 ou watchOS 26.²⁴ (Cette exigence ne concerne pas les soumissions pour macOS.) Si votre équipe utilise encore Xcode 16.x, la chaîne d’outils assistée par agent présentée dans ce guide sert également de contrainte de migration : de toute façon, aucun des serveurs MCP ci-dessous ne fonctionne sans Xcode 26.3 ou version ultérieure.

Requis : - macOS 15 ou version ultérieure (Sequoia) ou macOS Tahoe (Xcode 26.6 nécessite macOS Tahoe 26.2 ou version ultérieure ; la version bêta de Xcode 27 nécessite Tahoe 26.4 ou version ultérieure) - Xcode 26.3 ou version ultérieure installé et configuré (version minimale pour xcrun mcpbridge) ; Xcode 26.6 ou version ultérieure recommandé. Xcode 26.6 (2026-06-25, build 17F113) est la dernière version stable et apporte trois changements de Coding Intelligence utiles aux agents : Google Gemini en tant que fournisseur d’assistant de codage, la prise en charge de l’Agent Client Protocol (ACP) et le rendu de variantes — mode clair ou sombre, orientation et tailles de caractères — dans l’outil de prévisualisation MCP. Cette version corrige également deux plantages pendant les tours d’un agent ainsi que le blocage qui survenait lorsqu’un agent posait une question, et fournit Swift 6.3 avec les SDK de génération iOS 26.5.¹⁷ Les améliorations du workflow de la version 26.5 — mise en file d’attente des messages dans l’assistant de codage et prise en charge des questions de clarification — ainsi que les pièces jointes d’images de Swift Testing, la gravité des problèmes enregistrés, les avertissements de plantage des tests d’interface accompagnés de crashlogs et les améliorations de l’éditeur String Catalog introduits dans la version 26.4 restent disponibles.²⁵²⁶ 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 API Anthropic (pour Claude Code) ou un compte OpenAI (pour Codex)

Recommandé : - SwiftFormat installé (brew install swiftformat) — utilisé par les hooks de formatage lors de l’enregistrement - SwiftLint installé (brew install swiftlint) — facultatif, mais utile pour faire respecter les règles de style - Une bonne connaissance du terminal — les trois runtimes fonctionnent depuis la ligne de commande ou s’y intègrent

Vérifiez votre installation de 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 devez utiliser Xcode 26.3 ou une version ultérieure. Installez ou mettez à jour Xcode depuis l’App Store ou developer.apple.com. Remarque : xcode-select --install installe uniquement les Command Line Tools, qui ne comprennent pas mcpbridge — vous avez besoin de l’app Xcode.app complète.

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

Trois environnements d’exécution distincts peuvent écrire, compiler et tester du code iOS. Ils ne sont pas interchangeables — chacun possède ses propres atouts, ses propres modes d’intégration avec MCP et ses propres cas d’usage privilégiés.

1. Claude Code CLI

Présentation : l’assistant de programmation agentique en ligne de commande 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 de 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. Les deux serveurs proposent respectivement 82 et 20 outils.

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

Autre possibilité — programme d’installation automatique xcodebuildmcp init (v2.1.0+, 23 février 2026) :

Si vous préférez éviter de configurer manuellement MCP, XcodeBuildMCP v2.1.0+ fournit une sous-commande init qui détecte automatiquement Claude Code, Cursor ou Codex, puis installe en une seule étape les compétences de l’agent et la configuration de MCP :

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

Options : --print (écrit la configuration dans stdout pour les clients non pris en charge), --uninstall (désinstalle). Ignorez cette méthode si vous souhaitez contrôler précisément les serveurs MCP connectés et leur portée ; les appels manuels à claude mcp add ci-dessus vous offrent ce contrôle.²⁸

Idéal pour : les sessions d’implémentation approfondies — développement de nouvelles fonctionnalités, refactorisation de plusieurs fichiers, débogage de problèmes complexes et exécution autonome de boucles compilation-test-correction. Grâce à la fenêtre de contexte de 1 million de tokens de Claude Code (avec Opus 5), l’agent peut conserver en mémoire de travail la majeure partie des projets iOS de petite ou moyenne taille — d’après mon expérience, jusqu’à environ 50 fichiers selon leur taille.²³

Session type :

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 principale différence par rapport au processus antérieur à MCP : l’agent ne vous demande jamais de lancer manuellement la compilation ni de coller les erreurs obtenues. La boucle compilation-erreur-correction est autonome.

2. Codex CLI

Présentation : l’agent de programmation en ligne de commande d’OpenAI. Son principe est similaire à celui de Claude Code, mais il utilise les modèles d’OpenAI (GPT-4o, o3) et un modèle d’autorisations différent.

Intégration de 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 au moyen de la même commande npx :

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

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

Principales différences avec Claude Code : - Utilise les modèles d’OpenAI au lieu des modèles Claude - Tailles de fenêtre de contexte et coûts en tokens différents - Modèle d’autorisations axé sur la 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 préférer Codex à Claude Code pour iOS :

Utilisez Codex lorsque vous recherchez une diversité de modèles — demander à un deuxième agent de réviser le code écrit par le premier permet de détecter d’autres catégories d’erreurs. Le processus de collaboration (Claude développe, Codex révise) est efficace pour iOS, car les modèles SwiftUI qui semblent corrects à une famille de modèles peuvent receler des problèmes subtils qu’une autre repérera. 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 de Xcode 26.3

Présentation : 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 comme fournisseurs d’intelligence dans Xcode Settings > Intelligence.¹⁰ Xcode 26.6 élargit cette sélection : Google Gemini est désormais disponible dans l’assistant de programmation (171990272), tandis que Xcode ajoute la prise en charge de l’Agent Client Protocol (ACP) (178294840) — l’intégration initialement limitée à deux fournisseurs en accueille donc maintenant trois, ainsi qu’un protocole ouvert permettant à tout agent compatible avec ACP de s’intégrer au panneau Intelligence.¹⁷

Configuration :

1. Ouvrez Xcode 26.3+
2. Accédez à Settings > 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 agent : connectez un agent compatible avec ACP (Xcode 26.6+)
8. L’agent apparaît dans la barre latérale Intelligence et peut être invoqué directement dans le code

Idéal pour : les modifications rapides directement dans le code, la complétion de code avec un raisonnement de niveau agent et les développeurs qui préfèrent rester dans Xcode. Grâce à l’intégration native, l’agent accède directement au contexte du projet dans Xcode — fichiers ouverts, cibles de compilation et configuration des schémas — sans passerelle MCP.

Limites par rapport aux agents CLI : - Aucun système de hooks — vous ne pouvez ni imposer le formatage à l’enregistrement ni bloquer les écritures dans .pbxproj - Aucun chargement de CLAUDE.md — l’agent ne lit pas les fichiers de configuration de votre projet - Autonomie limitée — l’agent intervient sur le fichier ou la sélection en cours, 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 à Xcode

Quand utiliser les agents natifs de Xcode :

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

Pour toute tâche nécessitant une compilation, des tests, une refactorisation de plusieurs fichiers ou une correction autonome des erreurs, utilisez un agent CLI avec MCP.

Tableau comparatif des environnements d’exécution

Recommandation : utilisez Claude Code CLI comme environnement d’exécution principal. Réservez les agents natifs de Xcode aux modifications rapides directement dans le code. Utilisez Codex CLI pour les passes de révision et les opérations par lots. Ces trois solutions sont complémentaires plutôt que concurrentes.

Configuration de MCP : configuration complète

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

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é, dont l’absence de changement a été vérifiée de la v2.6.2 à la v2.7.0), répartis en 12 catégories de workflows.³¹⁹²¹ Le projet réside officiellement dans l’organisation GitHub getsentry : Sentry en assure la maintenance, et l’ancienne URL cameroncooke/XcodeBuildMCP redirige désormais vers celle-ci, un détail utile lorsque des publications plus anciennes citent l’ancienne adresse.²¹ Il fonctionne sans que Xcode soit ouvert : l’intégralité du cycle de compilation, de test et de débogage s’exécute sans interface graphique grâce aux outils en ligne de commande d’Apple. Deux précisions concernant l’inventaire méritent votre attention : par défaut, une session stdio expose les quelque 24 outils du workflow de simulateur et laisse les autres hors du contexte de votre agent — définissez XCODEBUILDMCP_ENABLED_WORKFLOWS (avec les noms de catégories du tableau ci-dessous, séparés par des virgules) pour en charger davantage — et le même moteur est également proposé sous forme de CLI (xcodebuildmcp tools indique 100 commandes, dont 72 canoniques) si vous souhaitez effectuer les mêmes opérations 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’option -s user rend le serveur disponible globalement dans tous les projets. Omettez-la pour limiter l’installation au projet (utile si vous souhaitez disposer de MCP uniquement dans vos projets iOS, et non dans vos projets web).

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

Inventaire des outils (82 outils répartis en 12 catégories de workflows — outils représentatifs de chaque catégorie) :

Les outils les plus utiles au quotidien :

1. build_sim — Vous l’appellerez des centaines de fois. Il renvoie du JSON avec des erreurs classées par fichier, ligne et niveau de gravité. L’agent lit l’erreur, accède au fichier et la corrige sans aucune intervention de votre part.

2. test_sim — Renvoie les résultats de chaque méthode de test. L’agent sait précisément quel test a échoué et pourquoi, et ne reçoit pas simplement le message « échec des tests ».

3. list_sims + boot_sim — Gestion des simulateurs sans avoir à mémoriser les options de xcrun simctl. L’agent détecte les environnements d’exécution disponibles et sélectionne un appareil approprié.

4. discover_projs + list_schemes — Inspection du projet. L’agent n’a pas à deviner le nom de votre schéma ni la structure de votre espace de travail.

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

Ce que la v2.6.0 a changé (1er juin 2026) — automatisation de l’interface utilisateur à l’exécution :

La version v2.6.0 a entièrement repensé l’automatisation de l’interface utilisateur autour d’un contexte réutilisable, au lieu de captures d’écran ponctuelles.¹⁹ snapshot_ui renvoie désormais des références d’éléments stables et un hash de l’é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 workflow : wait_for_ui interroge l’interface jusqu’à ce qu’un prédicat soit satisfait (existence, état activé, focus, texte visible ou stabilisation de la mise en page), au lieu de laisser l’agent estimer des délais d’attente ; batch exécute une séquence d’actions reposant sur des références d’éléments en un seul appel ; drag effectue des gestes de glissement fondés sur ces références pour manipuler des feuilles et faire défiler des listes. type_text a reçu l’option replaceExisting, qui remplace la valeur d’un champ au lieu d’y ajouter du texte, les contrôles candidats sont classés à partir des données d’accessibilité, et les résultats structurés comprennent désormais des indications nextSteps (les schémas de résultats sont passés en v2 dans cette version ; depuis, la v2.7.0 a fait évoluer les résultats de compilation et de test vers schemaVersion: 3 — voir ci-dessous). Définissez XCODEBUILDMCP_HEADLESS_LAUNCH=true pour lancer les applications en arrière-plan sans détourner le focus de macOS : c’est ce qui distingue une session d’agent que vous pouvez laisser s’exécuter d’une session qui ramène sans cesse la fenêtre du simulateur au premier plan. Sur une tâche déterministe portant sur une application météo, le benchmark du projet annonce une réduction d’environ 70 % du temps réel écoulé, de 68 % du nombre de tokens et de 76 % du nombre d’appels d’outils par rapport au workflow antérieur à la version 2.6. Il s’agit des chiffres du projet, et non d’une mesure indépendante, mais le mécanisme employé (ignorer les captures inchangées et regrouper les actions effectuées sur un même écran) correspond précisément à la principale source de consommation de tokens dans l’automatisation de l’interface utilisateur.¹⁹

Ce que la v2.7.0 a changé (23 juillet 2026) — simulateurs Xcode 27, schéma v3 et compilations respectant les schémas :

La version v2.7.0 est moins importante que la 2.6.0, mais comporte une rupture de compatibilité et un changement de comportement à connaître avant toute mise à niveau.²¹ Principal changement : les outils d’automatisation de l’interface utilisateur fonctionnent désormais pleinement avec les simulateurs Xcode 27 grâce à Device Hub, notamment pour l’ouverture des fenêtres de simulateur et les commandes au clavier. Cela comble la lacune qui limitait la fiabilité de l’automatisation de l’interface utilisateur à l’exécution aux simulateurs Xcode 26. Rupture de compatibilité : les outils de compilation et de test renvoient désormais des résultats structurés avec schemaVersion: 3 (ils utilisaient la v2 depuis la version 2.6.0) ; tout code validant ou analysant des résultats exclusivement en version 2 doit être mis à jour. Changement de comportement : lorsque configuration est omis, les outils de compilation, de test, de nettoyage et de recherche du chemin de l’application respectent désormais la configuration de l’action du schéma, au lieu d’utiliser systématiquement Debug. Si l’action Test d’un schéma est configurée sur Release, un appel à test_sim sans précision compile désormais en Release ; transmettez donc explicitement configuration lorsque votre workflow dépend d’une configuration particulière. Parmi les changements plus modestes, mais utiles : les packages de préparation des tests .xctestproducts réutilisables permettent de relancer les tests sans nouvelle compilation, tout en produisant un nouveau fichier .xcresult à chaque exécution ; l’option extraArgs des paramètres par défaut de session permet de définir les options xcodebuild communes une seule fois par session, au lieu de les répéter à chaque appel ; une nouvelle commande CLI xcodebuildmcp purge analyse et nettoie l’espace de stockage de l’espace de travail de XcodeBuildMCP (simulation par défaut, avec consentement explicite requis pour supprimer) ; enfin, un correctif résout le problème des clients MCP qui attendaient 10 à 17 secondes avant que les outils soient disponibles, ce qui pouvait faire échouer les contrôles de bon fonctionnement de courte durée.²¹

MCP d’Apple pour Xcode : 20 outils faisant le lien avec Xcode

Le serveur MCP d’Apple est fourni avec Xcode 26.3 via xcrun mcpbridge.⁴ Il communique avec un processus Xcode en cours d’exécution par XPC (le framework de communication interprocessus d’Apple), ce qui lui donne accès à un état interne inaccessible à tout outil CLI.⁵

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, tous les appels MCP effectués par l’intermédiaire de ce serveur échoueront ou resteront bloqués. XcodeBuildMCP ne présente pas cette limite.

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

Outils propres au serveur MCP d’Apple (non disponibles dans XcodeBuildMCP) :

1. DocumentationSearch — Effectue des recherches dans la documentation destinée aux développeurs Apple, notamment dans les sessions WWDC. Cet outil est plus rapide et plus fiable qu’une recherche web pour les questions relatives à API d’Apple. Demandez « HKQuantityType(.dietaryWater) est-il valide ? » et obtenez une réponse définitive directement auprès de la source.

2. ExecuteSnippet — Exécute du code dans le REPL Swift au sein du contexte du projet. L’agent peut vérifier le comportement de API, tester des conversions de types et valider des expressions sans compiler l’intégralité de l’application.

3. RenderPreview — Génère des aperçus SwiftUI sans interface graphique. L’agent peut vérifier qu’une vue s’affiche sans erreur, mais ne peut pas évaluer sa justesse visuelle (le rendu est renvoyé sous forme de données et non inspecté visuellement). Depuis Xcode 26.6, l’outil MCP d’aperçu (appelé « Preview Snapshot » dans les notes de version 26.6) génère plusieurs variantes — apparence claire/sombre, orientation portrait/paysage et remplacement de la taille du texte (178831772) — afin qu’un agent puisse vérifier une vue dans plusieurs configurations en une seule opération.¹⁷ La version bêta de Xcode 27 va encore plus loin : elle permet de générer des groupes Preview et de prévisualiser le contenu dans une autre langue.¹⁸

4. XcodeListNavigatorIssues — Renvoie les diagnostics en temps réel de l’analyseur de Xcode, et 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 signale pas.

Pourquoi utiliser les deux serveurs

Leurs fonctions de compilation et de test se recoupent, mais ils 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 de compilation, de test et de débogage. Il fonctionne sans que Xcode soit ouvert, consomme moins de mémoire système et offre une gestion plus complète des simulateurs et des appareils. C’est votre principal outil de compilation.

Utilisez le serveur MCP d’Apple pour Xcode pour : consulter la documentation, effectuer des vérifications dans le REPL Swift, générer des aperçus SwiftUI et obtenir des diagnostics en temps réel. Gardez Xcode ouvert pendant les sessions nécessitant ces fonctionnalités.

En pratique : j’utilise XcodeBuildMCP pour environ 90 % des appels MCP, et le serveur MCP d’Apple pour Xcode pour consulter la documentation et effectuer des vérifications dans le REPL. Par défaut, l’agent utilise XcodeBuildMCP pour les compilations et les tests, car il est plus rapide (aucune surcharge liée au processus Xcode) et plus fiable (aucune dépendance à XPC).

La distinction entre les deux serveurs s’atténue. XcodeBuildMCP 2.6.x ajoute une catégorie proxy xcode-ide : xcode_ide_list_tools découvre les fonctionnalités MCP réservées à l’IDE Xcode et xcode_ide_call_tool les appelle (elles apparaissent sous des noms xcode_tools_*, par exemple xcode_tools_documentationsearch). Une seule inscription de XcodeBuildMCP peut donc désormais donner accès aux outils côté IDE d’Apple.¹⁹ La contrainte essentielle demeure inchangée : ces appels par proxy nécessitent toujours un processus Xcode en cours d’exécution, exactement comme une inscription directe de xcrun mcpbridge. Conservez l’inscription des deux serveurs si vous souhaitez que les outils d’Apple apparaissent directement dans la liste des outils de l’agent ; le proxy est surtout utile si vous préférez une seule entrée de serveur et n’accédez qu’occasionnellement à l’IDE.

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 ou version ultérieure.
2. Le serveur MCP d’Apple pour Xcode 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 inscrits en cours de session peuvent ne pas apparaître avant un redémarrage.

Apprendre à l’agent à utiliser MCP

L’installation des serveurs MCP est nécessaire, mais ne suffit pas. Sans instructions explicites, l’agent peut revenir à l’exécution de xcodebuild avec Bash (sortie non structurée, gaspillage de tokens de contexte) ou utiliser la recherche web pour consulter la documentation Apple (plus lente et 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 instructions garantissent que l’agent privilégie les outils MCP. Sans elles, vous constaterez que l’agent construit de longues commandes xcodebuild avec Bash, consomme des milliers de tokens de contexte pour analyser leur sortie et identifie parfois la mauvaise erreur.⁶

Un changement de comportement de XcodeBuildMCP v2.7.0 doit être intégré au modèle mental présenté dans cette section : lorsque configuration est omis, les outils de compilation, de test, de nettoyage et de recherche du chemin de l’application respectent désormais la configuration de l’action du schéma, au lieu d’utiliser systématiquement Debug.²¹ La plupart des schémas s’exécutent et se testent en Debug, de sorte que la majorité des projets ne constateront aucun changement. Toutefois, si l’action d’un schéma est configurée sur Release (ce qui est courant pour les schémas de profilage ou les configurations proches de l’archivage), un appel à build_sim ou test_sim sans précision compile désormais en Release. Si votre CLAUDE.md ou vos hooks supposent l’utilisation d’artefacts Debug, indiquez-le explicitement dans l’appel d’outil ou définissez cette configuration 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é le comportement des compilations longues au sein d’une session. Depuis la v2.1.212 (16 juillet 2026), tout appel d’outil MCP durant plus de 2 minutes passe automatiquement en arrière-plan afin que la session reste utilisable ; ce seuil peut être configuré — ou ce comportement désactivé — avec CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS.²⁰ Sur des projets réels, les compilations propres et les exécutions complètes des tests avec build_sim / test_sim dépassent régulièrement les 2 minutes. Attendez-vous donc à ce que l’agent poursuive son travail — lecture de fichiers, planification de la prochaine modification — pendant que la compilation se termine en arrière-plan, au lieu de bloquer l’échange. Le correctif associé est tout aussi important : avant la v2.1.206 (9 juillet 2026), une valeur request_timeout_ms propre à chaque serveur, configurée avec --mcp-config ou .mcp.json, était ignorée dans les nouvelles sessions. Les longs appels MCP expiraient donc après le délai par défaut de 60 secondes ; le symptôme classique était l’expiration de la première compilation propre, qui se « corrigeait toute seule » lors d’une nouvelle tentative.²⁰ Si vous aviez contourné l’un de ces comportements avec des scripts d’encapsulation 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)

Patterns multi-plateformes

Return couvre iOS, watchOS et tvOS. Le développement multi-plateformes avec des agents exige une documentation explicite des frontières entre 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 changements affectent toutes les plateformes. Si un fichier se trouve dans un dossier de plateforme, les changements sont isolés. Vérifiez toujours dans quel dossier se trouve un fichier avant de le modifier. »

Gardes de disponibilité par plateforme

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

Consigne pour l’agent : « Utilisez toujours des gardes #if canImport() ou #if os() lorsque vous utilisez des frameworks propres à 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 compilation-test-correction

Le pattern le plus puissant : donnez à l’agent une spécification de fonctionnalité et laissez-le itérer de manière autonome à travers des cycles compilation-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 compilation-erreur-correction se termine en une seule boucle autonome.

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

Quand cela échoue : fonctionnalités ouvertes (« rendez ça plus joli »), code sensible aux performances ou tout élément nécessitant une vérification visuelle.

Délégation à des subagents pour iOS

Le système de subagents 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 subagent explore la documentation et les patterns de code dans une fenêtre de contexte séparée, renvoie un résumé, puis la session principale implémente la recommandation. Cela évite que la recherche consomme votre contexte principal.

Application de patterns entre apps

Lorsque vous maintenez plusieurs apps iOS avec des patterns cohérents, les agents peuvent appliquer des patterns d’une app à 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 pattern source, comprend la structure et crée une implémentation cohérente dans le projet cible.

Revue à 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 une passe séparée

# 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 classes d’erreurs différentes. C’est particulièrement précieux pour les shaders Metal et les patterns de concurrence, où des bugs subtils sont faciles à introduire.

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

La double revue ne sert pas à trouver plus de bugs : elle sert à trouver des bugs différents. Chaque famille de modèles a ses propres modes d’échec dans sa reconnaissance des patterns.

Opérations par lot sur plusieurs apps

Lorsqu’un changement de framework ou de pattern affecte plusieurs apps :

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

Apps qui utilisent LLM on-device d’Apple

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

Le pattern qu’un agent doit suivre lorsqu’il génère du code de construction de prompt :

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 pattern à votre CLAUDE.md si l’app touche à SystemLanguageModel. Sans cela, les agents reviennent à l’ancien codage en dur à 4096 et tronquent silencieusement les prompts sur les appareils livrés avec des fenêtres de contexte plus grandes. La signature async throws de tokenCount(for:) est indispensable : les agents qui collent une version synchrone échoueront à la compilation.

É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