Criando apps para iOS com agentes de IA: o guia prático

TL;DR: Três ambientes de execução de agentes agora entregam código para iOS: Claude Code CLI com MCP, Codex CLI com MCP e os agentes nativos de Intelligence do Xcode — Claude Agent, Codex e, desde o Xcode 26.6, Google Gemini ou qualquer agente Agent Client Protocol (ACP).¹⁷ Dois servidores MCP (XcodeBuildMCP, com 82 ferramentas, e o xcrun mcpbridge da Apple, com 20 ferramentas) dão aos agentes acesso estruturado a builds, testes, simuladores e depuração. Este guia aborda padrões reais de CLAUDE.md, configurações de hooks e avaliações honestas do que funciona e do que quebra — extraídos de 8 apps iOS em produção que somam 293 arquivos Swift.³² Os agentes se destacam em views SwiftUI, modelos SwiftData, refatoração e diagnóstico de erros de build. Eles falham em modificações de .pbxproj, code signing e depuração visual. A lacuna entre “o agente escreve Swift” e “o agente entrega um app iOS” é preenchida pela configuração, não por prompting. Desde a WWDC 2026 (8 de junho), o iOS 27 está em beta — beta 5 (24A5408d) em 10 de agosto — e adiciona frameworks relevantes para agentes (controle de tool-calling do Foundation Models, execução em segundo plano de App Intents e os novos frameworks Core AI e Evaluations) que vale mencionar no contexto do seu agente, pois um modelo treinado antes de junho de 2026 não os conhecerá. O Xcode 26.6 (25/06/2026, Swift 6.3) é a toolchain estável atual; o beta do Xcode 27 (Swift 6.4, SDKs do iOS 27) acompanha o ciclo do iOS 27.¹⁷¹⁸

Criei 8 apps iOS com agentes de programação por IA. Não são protótipos — são apps na App Store, com integrações HealthKit, shaders Metal, física SpriteKit, sincronização com iCloud, Live Activities, placares do Game Center e targets multiplataforma abrangendo iOS, watchOS e tvOS. Cada linha de Swift desses apps foi escrita por um agente e revisada por mim, ou escrita por mim e refatorada por um agente. Na minha estimativa, os agentes assumiram a maior parte da autoria linha a linha; eu cuidei da revisão, do escopo e das partes que exigem julgamento humano (polimento visual, assinatura, ajuste de desempenho e envio à App Store).

Este guia é a referência que eu gostaria que existisse quando comecei. Ele cobre toda a stack: qual ambiente de execução de agente usar, como configurar servidores MCP para acesso estruturado a builds, o que colocar no seu CLAUDE.md, quais hooks impedem o agente de destruir seu projeto Xcode e — fundamentalmente — onde os agentes falham e você precisa assumir o controle.

Principais conclusões

Para desenvolvedores iOS que estão começando com agentes de IA:

• Comece com Claude Code CLI + XcodeBuildMCP. É o ambiente de execução mais maduro, com a cobertura mais ampla de ferramentas MCP. Instale dois comandos, adicione um CLAUDE.md ao seu projeto, e o agente poderá compilar, testar e depurar sem que você precise copiar mensagens de erro.
• Nunca deixe um agente modificar .pbxproj. Esta é a regra mais importante. Um hook PreToolUse que bloqueia escritas em .pbxproj e .xcodeproj/ economizará horas de recuperação.
• Seu CLAUDE.md é o documento de onboarding do agente. As horas investidas nele se pagam em todas as sessões de agente que tocam o projeto.

Para usuários experientes de agentes que estão adicionando iOS ao fluxo de trabalho:

• MCP transforma o loop de build do iOS. Antes do MCP, os agentes escreviam Swift, mas não conseguiam verificar se o código compilava. Com XcodeBuildMCP, o agente escreve código, faz o build, lê erros estruturados, corrige-os e executa testes — de forma autônoma.
• Três ambientes de execução atendem a necessidades diferentes. Claude Code CLI para sessões agentivas profundas, Codex CLI para trabalho em lote sem interface e os próprios agentes do Xcode — que deixaram de ser uma ferramenta de correções inline no Xcode 27, quando ganharam plug-ins, servidores MCP e a capacidade de controlar simuladores.²²
• A infraestrutura de hooks é transferível. Seus formatadores PostToolUse, bloqueadores PreToolUse e hooks de execução de testes existentes funcionam de forma idêntica em projetos iOS, com pequenos ajustes de caminho.

Para líderes de equipe avaliando o desenvolvimento iOS assistido por IA:

• A eficácia dos agentes escala com a documentação do projeto, não com o tamanho dele. Um app com 63 arquivos e um CLAUDE.md detalhado produz resultados melhores dos agentes do que um app com 14 arquivos e nenhum.
• O limite do .pbxproj é inegociável. Agentes não conseguem editar arquivos de projeto do Xcode de maneira confiável. Seu fluxo de trabalho precisa considerar a adição manual de arquivos aos targets do Xcode.
• Avaliação honesta ROI: os agentes realizam a maior parte da implementação em projetos bem documentados — isso fica evidente no app de TV com 15 arquivos entregue em 3 horas de trabalho assistido por agentes (estudo de caso abaixo). O trabalho restante — polimento visual, assinatura, ajuste de desempenho e envio à App Store — exige julgamento humano.

Escolha seu caminho

Como usar este guia

Esta é uma referência com mais de 3.000 linhas. Comece pelo ponto adequado ao seu nível de experiência:

Índice

1. O portfólio: 8 apps, 293 arquivos
2. Pré-requisitos
3. Três ambientes de execução de agentes para iOS
4. Configuração de MCP: a configuração completa
5. Padrões de CLAUDE.md para projetos iOS
6. Sua primeira sessão de agente
7. No que os agentes são bons em iOS
8. No que os agentes são ruins em iOS
9. Hooks para desenvolvimento iOS
10. Padrões de arquitetura que funcionam com agentes
11. Contexto específico de frameworks
12. Padrões multiplataforma
13. Fluxos de trabalho avançados
14. Estudos de caso reais
15. Ciclo de vida de projetos com agentes
16. Configurando definições de agentes
17. Padrões de teste para iOS assistido por agentes
18. Gerenciamento da janela de contexto para projetos iOS
19. Solução de problemas
20. Erros comuns de agentes em iOS
21. A avaliação honesta
22. FAQ
23. Cartão de referência rápida
24. Referências

Recursos relacionados

Série Ecossistema Apple. 21 posts de produção sobre apps SwiftUI que se integram com Apple Intelligence, MCP, Foundation Models, Vision, Core ML e a stack de frameworks do iOS 26. Extraídos de Water, Get Bananas, Return e o restante do portfólio 941:

Central da série: Série Ecossistema Apple

Apple agentivo (E4):

Frameworks (E2/E3):

Código entregue (E1):

Síntese (E5):

iOS 27 e WWDC 2026: com o que seu agente agora desenvolve

A WWDC 2026 (8 de junho de 2026) colocou o iOS 27 em beta. O fluxo de desenvolvimento com agentes deste guia não muda: você ainda usa Claude Code, Codex ou os agentes de Intelligence do Xcode por meio do MCP, ainda escreve um CLAUDE.md e ainda restringe operações destrutivas com hooks. O que muda é a superfície contra a qual seu agente escreve código. O iOS 27 traz vários frameworks novos relevantes para agentes, e o movimento prático é direcionar seu agente de programação deliberadamente a eles, porque um modelo treinado antes de junho de 2026 não saberá que eles existem. O iOS 26 continua sendo a versão lançada; considere os itens abaixo como alvos ao desenvolver com o SDK beta do iOS 27.

A superfície relevante para agentes no iOS 27, cada uma com uma referência detalhada:

• Foundation Models ganhou controle de chamadas de ferramentas. GenerationOptions.ToolCallingMode permite controlar, por solicitação, com que intensidade o modelo no dispositivo chama ferramentas, e o framework pode mudar de modo após a primeira chamada para limitar a atividade de ferramentas de uma solicitação. O framework Vision agora inclui OCRTool e BarcodeReaderTool prontos para uso, que você anexa a uma LanguageModelSession sem escrever o código de reconhecimento. Veja Foundation Models no iOS 27: controle de chamadas de ferramentas.¹²
• App Intents rompeu a barreira dos 30 segundos. LongRunningIntent (por meio de performBackgroundTask(options:operation:), que exige o relatório de progresso) estende o tempo de execução em segundo plano de uma intent para sincronização, trabalho com arquivos e inferência no dispositivo; SyncableEntity fornece a um AppEntity uma identidade entre dispositivos; IndexedEntityQuery permite que o sistema peça à sua consulta para reparar o índice do Spotlight. Veja App Intents no iOS 27: execução em segundo plano, sincronização e Spotlight.¹³
• Core AI é um novo framework para executar modelos no Apple Silicon. Ele fica abaixo de Foundation Models para os casos em que você traz seu próprio modelo, em vez de usar o modelo de sistema da Apple. Veja Core AI: executando modelos no Apple Silicon.¹⁴
• Evaluations é o XCTest para a qualidade de modelos. Um novo framework (macOS 27) para medir a qualidade da saída de modelos como parte da sua suíte de testes, que é a peça que faltava para lançar recursos de IA que um agente ajudou você a desenvolver. Veja Evaluations: XCTest para qualidade de modelos.¹⁵
• SwiftData, HealthKit e SwiftUI também evoluíram. SwiftData adiciona observação e histórico no iOS 27; HealthKit adiciona zonas de treino e novos tipos; as adições do iOS 27 ao SwiftUI trazem a habitual superfície ampla. Veja SwiftData no iOS 27, HealthKit no iOS 27 e Novidades do SwiftUI para iOS 27.¹⁶

A ferramenta para trabalhar com o iOS 27 é o Xcode 27 beta. O Xcode 27 foi lançado como beta no primeiro dia da WWDC (8 de junho, build 27A5194q) e está no beta 5 desde 10 de agosto (27A5237l). Ele inclui Swift 6.4 e os SDKs do iOS 27 / iPadOS 27 / tvOS 27 / watchOS 27 / macOS 27 / visionOS 27, e exige macOS Tahoe 26.4 ou posterior.¹⁸ Quatro itens das notas de versão importam para fluxos de trabalho com agentes: Coding Intelligence ganha um modo de plano — as notas o apresentam por meio de um problema conhecido com a barra de confirmação “Implement the plan?” (178673449), então espere o agente terminar a transmissão antes de confirmar ou dispensar um plano; a ferramenta MCP RenderPreview agora renderiza grupos de Preview (174692209) e pode visualizar sua interface em outra localização (181040291); a ferramenta voltada a agentes “Prepare Project for Localization” agora informa chaves do String Catalog removidas porque não aparecem mais no código-fonte (179755385); e o Address Sanitizer pode falhar ao iniciar em destinos 27.0 quando o app foi compilado com o Xcode 26.4 ou anterior — use o Xcode 26.5+ para execuções do ASan (178072780).¹⁸ O beta 5 adiciona mais dois itens relevantes aqui. Agora os agentes podem verificar apps do watchOS, “incluindo girar e pressionar a Digital Crown e pressionar os botões lateral e Action (Apple Watch Ultra)” (181147968) — a primeira vez que os agentes da Apple conseguem testar as entradas físicas de um app de relógio, o que fecha parte da lacuna de verificação visual documentada neste guia. A Apple também apresentou um servidor MCP que não precisa mais do Xcode aberto; veja a seção sobre o servidor MCP da Apple abaixo.²² As ferramentas MCP também acompanharam o beta: o XcodeBuildMCP v2.7.0 (2026-07-23) tornou suas ferramentas de automação de interface totalmente compatíveis com simuladores do Xcode 27 via Device Hub, incluindo abertura da janela do simulador e controles de teclado — antes dessa versão, a automação de interface em tempo de execução era confiável apenas com simuladores do Xcode 26, o que tornava a verificação de interface conduzida por agentes no beta do iOS 27 uma tarefa manual.²¹

A lição para o operador é a mesma apresentada no restante deste guia: o agente escreve o código, mas você fornece o conhecimento que ele não tem. Para betas do iOS 27, isso significa nomear esses frameworks no seu prompt ou CLAUDE.md e vincular o agente à documentação da Apple, porque, caso contrário, o modelo recorrerá ao formato de iOS 26 de cada API. Todo o restante deste guia (runtimes, MCP, hooks e os modos de falha) permanece inalterado para o trabalho com iOS 27.

O portfólio: 8 apps, 293 arquivos

Antes de mergulhar na configuração, veja de onde este guia foi extraído. Estes não são projetos de brinquedo — eles abrangem cinco frameworks da Apple, três plataformas e toda a gama de complexidade do iOS, de um rastreador de exercícios com 14 arquivos a um timer de meditação multiplataforma com 63 arquivos.

Por que a quantidade de arquivos importa: A eficácia dos agentes se correlaciona com a legibilidade do projeto, não com o tamanho do projeto. Return (63 arquivos) produz uma saída melhor dos agentes do que amp97 (41 arquivos) porque Return tem um CLAUDE.md detalhado, com anotações de arquivos, diagramas de arquitetura e padrões explícitos. Os shaders Metal do amp97 são inerentemente mais difíceis para os agentes analisarem, independentemente da qualidade da documentação.

Pré-requisitos

Antes de configurar qualquer runtime de agente para desenvolvimento iOS:

Prazo do App Store Connect: A partir de 2026-04-28, os uploads de apps para o App Store Connect devem ser compilados com o Xcode 26 ou posterior, usando SDKs para iOS 26, iPadOS 26, tvOS 26, visionOS 26 ou watchOS 26.²⁶ (Envios para macOS não estão sujeitos a esse requisito.) Se sua equipe ainda usa o Xcode 16.x, a cadeia de ferramentas assistida por agentes deste guia também funciona como um fator de pressão — afinal, nenhum dos servidores MCP abaixo funciona sem o Xcode 26.3+.

Obrigatório: - macOS 15+ (Sequoia) ou macOS Tahoe (o Xcode 26.6 exige macOS Tahoe 26.2+; o Xcode 27 beta exige Tahoe 26.4+) - Xcode 26.3+ instalado e configurado (o mínimo para xcrun mcpbridge); Xcode 26.6+ recomendado. O Xcode 26.6 (2026-06-25, build 17F113) é a versão estável mais recente e traz três mudanças no Coding Intelligence relevantes para agentes: Google Gemini como provedor de assistente de programação, suporte a Agent Client Protocol (ACP) e renderização de variantes — claro/escuro, orientação, tamanhos de texto — na ferramenta MCP de preview; ele também corrige dois crashes durante turnos de agentes e o travamento quando um agente faz uma pergunta, e inclui Swift 6.3 com os SDKs da geração iOS 26.5.¹⁷ As melhorias de fluxo de trabalho da 26.5 — enfileiramento de mensagens no assistente de programação e suporte a perguntas de esclarecimento — e os anexos de imagem do Swift Testing da 26.4, a severidade de problemas registrados, os avisos de crash em testes de interface com crashlogs e as melhorias do editor de String Catalog também continuam disponíveis.²⁷²⁸ Versões estáveis anteriores: 26.5 (2026-05-11, build 17F42) e 26.4.1 (2026-04-16, build 17E202).²⁹ - Pelo menos um runtime do iOS Simulator instalado - Uma conta API da Anthropic (para Claude Code) ou uma conta OpenAI (para Codex)

Recomendado: - SwiftFormat instalado (brew install swiftformat) — usado por hooks de formatação ao salvar - SwiftLint instalado (brew install swiftlint) — opcional, mas útil para impor estilo - Familiaridade com o terminal — os três runtimes operam a partir da linha de comando ou se integram a ela

Verifique sua instalação do 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")

Se xcrun mcpbridge retornar “command not found”, você precisa do Xcode 26.3 ou posterior. Instale ou atualize o Xcode pela App Store ou pelo developer.apple.com. Observação: xcode-select --install instala apenas as Command Line Tools, que não incluem mcpbridge — você precisa do Xcode.app completo.

Três runtimes de agentes para iOS

Três runtimes distintos podem escrever, compilar e testar código iOS. Eles não são intercambiáveis — cada um tem pontos fortes, padrões diferentes de integração com MCP e casos de uso ideais distintos.

1. Claude Code CLI

O que é: Assistente de programação agêntico baseado em terminal da Anthropic. Lê sua base de código, executa comandos, modifica arquivos e se conecta a ferramentas externas via MCP.⁷

**Integração com MCP: ** Suporte completo tanto para XcodeBuildMCP quanto para o Xcode MCP da Apple. O agente descobre ferramentas pelo protocolo MCP e as chama com parâmetros estruturados. São 82 + 20 ferramentas nos dois servidores.

Configuração:

# 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

Alternativa — instalador automático xcodebuildmcp init (v2.1.0+, 23 de fevereiro de 2026):

Se você preferir pular a configuração manual do MCP, o XcodeBuildMCP v2.1.0+ inclui um subcomando init que detecta automaticamente Claude Code, Cursor ou Codex e instala as skills do agente + a configuração do MCP em uma etapa:

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

Flags: --print (grava a configuração em stdout para clientes não compatíveis), --uninstall (remove). Ignore isto se quiser controlar explicitamente quais servidores MCP serão conectados e em qual escopo; as invocações manuais de claude mcp add acima oferecem esse controle.³⁰

Ideal para: Sessões profundas de implementação — criar novos recursos, refatorar vários arquivos, depurar problemas complexos e executar loops autônomos de compilar-testar-corrigir. A janela de contexto de 1M do Claude Code (com Opus 5) permite que o agente mantenha a maior parte de projetos iOS pequenos e médios na memória de trabalho — na minha experiência, até aproximadamente 50 arquivos, dependendo do tamanho deles.²⁵

Sessão típica:

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]

A principal diferença em relação ao fluxo de trabalho pré-MCP: o agente nunca pede que você compile manualmente ou cole a saída de erros. O loop de compilar-corrigir-erros é autônomo.

2. Codex CLI

O que é: Agente de programação baseado em terminal da OpenAI. É semelhante em conceito ao Claude Code, mas executa os modelos Codex da OpenAI e tem um modelo de permissões diferente. A linha atual é composta por GPT-5.6 Sol (carro-chefe, mais forte em programação complexa), GPT-5.6 Terra (padrão equilibrado para o dia a dia) e GPT-5.6 Luna (rápido e mais barato), com o GPT-5.3 Codex Spark como prévia de pesquisa somente de texto. GPT-5.4 e GPT-5.4-mini deixam o Codex em 31 de agosto de 2026 — migre essas configurações para Terra e Luna, respectivamente.²³

**Integração com MCP: ** O Codex oferece suporte a MCP pelo comando codex mcp add. O Xcode MCP da Apple funciona diretamente:

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

O XcodeBuildMCP também funciona com Codex pelo mesmo comando npx:

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

Ideal para: Operações em lote sem interface, integração de CI/CD e tarefas nas quais você quer uma segunda opinião de uma família de modelos diferente. O modo sandbox do Codex executa código em ambientes isolados, o que é útil para operações destrutivas, como execuções de suítes de testes que modificam estado.

Principais diferenças em relação ao Claude Code: - Usa modelos da OpenAI em vez de modelos Claude - Tamanhos diferentes de janela de contexto e economia de tokens - Modelo de permissões sandbox-first (mais restritivo por padrão) - Ecossistema menor de MCP (menos servidores da comunidade testados) - Sistema de hooks disponível (v0.119.0+), mas menos maduro que o do Claude Code — menos tipos de eventos e sem campo condicional if

Quando usar Codex em vez de Claude Code para iOS:

Use Codex quando quiser diversidade de modelos — ter um segundo agente revisando código escrito pelo primeiro identifica classes diferentes de erros. O fluxo de trabalho colaborativo (Claude cria, Codex revisa) é eficaz para iOS porque padrões SwiftUI que parecem corretos para uma família de modelos podem ter problemas sutis que outra identifica. Shaders Metal e padrões de concorrência se beneficiam especialmente de revisão por dois modelos.

3. Agentes nativos do Xcode

O que é: A Apple integrou agentes de programação com IA diretamente ao painel Intelligence do Xcode. Desde o Xcode 26.3, você pode configurar o Claude Agent e o Codex como provedores de inteligência em Xcode Settings > Intelligence.¹⁰ O Xcode 26.6 amplia a lista: o Google Gemini agora está disponível no assistente de programação (171990272), e o Xcode adiciona suporte ao Agent Client Protocol (ACP) (178294840) — portanto, o que foi lançado como uma integração com dois provedores agora são três provedores mais um protocolo aberto que permite conectar qualquer agente compatível com ACP ao painel Intelligence.¹⁷

Configuração:

1. Abra o Xcode 26.3+
2. Navegue até Settings > Intelligence
3. Adicione um novo provedor:
4. Para Claude: selecione “Claude Agent” e informe sua chave API da Anthropic
5. Para Codex: selecione “Codex” e informe sua chave API da OpenAI
6. Para Gemini: selecione “Google Gemini” (Xcode 26.6+)
7. Para qualquer outra opção: conecte um agente compatível com ACP (Xcode 26.6+)
8. O agente aparece na barra lateral Intelligence e pode ser invocado inline

Ideal para: Edições inline rápidas, conclusão de código com raciocínio de nível de agente e desenvolvedores que preferem não sair do Xcode. A integração nativa significa que o agente tem acesso direto ao contexto do projeto no Xcode — arquivos abertos, targets de compilação e configuração de scheme — sem a ponte do MCP.

Limitações em comparação com agentes CLI — no Xcode 26.x: - Sem sistema de hooks — você não pode aplicar formatação ao salvar nem bloquear gravações em .pbxproj - Sem carregamento de CLAUDE.md — o agente não lê seus arquivos de configuração no nível do projeto - Autonomia limitada — o agente opera no arquivo ou seleção atual, não no projeto inteiro - Sem delegação de subagentes — tarefas complexas em várias etapas não podem ser paralelizadas - Sem configuração de servidor MCP — o agente usa apenas as ferramentas integradas do Xcode

O Xcode 27 invalida a maior parte dessa lista. Desde a beta 1 (8 de junho), os agentes do Xcode são uma plataforma de extensões, e não um assistente inline:²²

• Plug-ins: “Os agentes no Xcode agora podem ser estendidos com plugins que contêm skills, servidores MCP e configurações de agentes ACP. As skills podem ser invocadas como comandos de barra com suporte a conclusão.” (178289210) — portanto, os limites de “apenas ferramentas integradas” e “sem configuração de MCP ” deixaram de existir.
• Controle do Simulator: os agentes “agora podem inicializar simuladores, instalar e iniciar apps, sintetizar eventos de toque e capturar screenshots para verificar o comportamento da UI” (175179787) e, na beta 5, podem controlar entradas de hardware do watchOS (181147968).
• Acesso ao debugger: o servidor MCP do Xcode ganhou ferramentas para manipular o estado de execução, ler o console do debugger, alternar schemes e destinos de execução, além de inspecionar ou modificar “configurações de compilação, flags do compilador, entitlements e chaves do Info.plist” (176935844).
• Uma camada de segurança do sistema de arquivos “que monitora e controla o acesso ao sistema de arquivos por agentes de programação e quaisquer processos que eles iniciem” (178289431), além de planejamento de primeira classe (172857081) e insights de projeto que abrangem crashes, travamentos, energia e problemas de inicialização (177568662).

Um alerta que decorre diretamente de 176935844: os agentes do Xcode agora podem editar configurações de compilação, entitlements e chaves do Info.plist. A proteção de .pbxproj que este guia cria com um hook PreToolUse não se aplica dentro do Xcode, porque o hook está na configuração do seu agente CLI, e não na da Apple. Se você depende desse hook como rede de segurança, saiba que ele não tem jurisdição sobre o painel Intelligence.

Quando usar agentes nativos do Xcode:

Para edições rápidas e delimitadas, quando alternar para o terminal representa sobrecarga. “Adicione uma propriedade computada a este modelo.” “Escreva um teste unitário para esta função.” “Refatore esta view para usar @Observable.” Tarefas que afetam um ou dois arquivos e não exigem um ciclo de compilar-testar.

Para qualquer tarefa que exija compilação, testes, refatoração de vários arquivos ou correção autônoma de erros, use um agente CLI com MCP.

Matriz de comparação dos runtimes

A recomendação: Use Claude Code CLI como seu runtime principal. Use agentes nativos do Xcode para edições inline rápidas. Use Codex CLI para revisões e operações em lote. Os três se complementam, em vez de competir.

Configuração do MCP: a configuração completa

O MCP (Model Context Protocol) é o que transforma um agente de “escreve Swift e torce para você compilá-lo” em “escreve Swift, compila, lê erros estruturados e os corrige.”² Esta seção aprofunda o post do blog¹¹ — abordando ambos os servidores, todos os métodos de instalação, a verificação e a configuração do agente que garante que as ferramentas sejam realmente usadas.

XcodeBuildMCP: 82 ferramentas para desenvolvimento iOS headless

O XcodeBuildMCP encapsula xcodebuild, xcrun simctl e LLDB em 82 ferramentas estruturadas de MCP (inventário anunciado, confirmado como inalterado da v2.6.2 à v2.7.0), agrupadas em 12 categorias de fluxo de trabalho.³¹⁹²¹ A casa canônica do projeto é a organização getsentry GitHub — a Sentry o mantém, e a URL original cameroncooke/XcodeBuildMCP agora redireciona para lá, o que importa quando textos mais antigos citam o endereço antigo.²¹ Ele funciona sem o Xcode em execução — todo o ciclo de compilar-testar-depurar opera headlessly pelas ferramentas de linha de comando da Apple. Vale conhecer duas observações sobre o inventário: uma sessão stdio padrão expõe as duas dúzias de ferramentas do fluxo de simulador e mantém o restante fora do contexto do agente — defina XCODEBUILDMCP_ENABLED_WORKFLOWS (nomes de categorias separados por vírgulas na tabela abaixo) para carregar mais — e o mesmo motor é distribuído como um CLI (xcodebuildmcp tools informa 100 comandos, 72 canônicos) se você quiser operações idênticas sem MCP.⁹

Opções de instalação:

# 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

A flag -s user disponibiliza o servidor globalmente em todos os projetos. Omita-a para uma instalação no escopo do projeto (útil se você quiser MCP apenas em projetos iOS, não em projetos web).

A variável de ambiente -e XCODEBUILDMCP_SENTRY_DISABLED=true desativa a telemetria de relatórios de falhas. O XcodeBuildMCP inclui a Sentry por padrão, que envia dados de erro, incluindo caminhos de arquivos. Desative isso, a menos que você queira contribuir com diagnósticos para o projeto.¹

Inventário de ferramentas (82 ferramentas em 12 categorias de fluxo de trabalho — ferramentas representativas por categoria):

As ferramentas mais importantes para o trabalho diário:

1. build_sim — Você vai chamá-la centenas de vezes. Ela retorna JSON com erros categorizados por arquivo, linha e severidade. O agente lê o erro, navega até o arquivo e o corrige sem que você precise tocar em nada.

2. test_sim — Retorna resultados por método de teste. O agente sabe exatamente qual teste falhou e por quê, não apenas “os testes falharam”.

3. list_sims + boot_sim — Gerenciamento de simuladores sem memorizar flags do xcrun simctl. O agente descobre runtimes disponíveis e escolhe um dispositivo apropriado.

4. discover_projs + list_schemes — Inspeção do projeto. O agente não precisa adivinhar o nome da sua scheme ou a estrutura do workspace.

5. debug_attach_sim + debug_stack + debug_variables — Depuração remota com LLDB. O agente pode definir breakpoints, inspecionar variáveis e percorrer o código sem que você abra o depurador.

O que a v2.6.0 mudou (2026-06-01) — automação de UI em runtime:

A versão v2.6.0 reconstruiu a automação de UI em torno de contexto reutilizável, em vez de screenshots de uso único.¹⁹ Agora, snapshot_ui retorna referências estáveis de elementos e um hash da tela, e aceita sinceScreenHash para que o agente possa pular um snapshot completo quando a tela não mudou. Três novas ferramentas fecham o ciclo: wait_for_ui consulta até que um predicado seja satisfeito (existência, estado ativado, foco, texto visível ou layout estabilizado), em vez de o agente tentar adivinhar usando pausas; batch executa uma sequência de ações com referência a elementos em uma única chamada; drag realiza gestos de arrastar com referência a elementos para sheets e rolagem de listas. type_text ganhou replaceExisting para substituir o valor de um campo em vez de acrescentá-lo, os controles candidatos são classificados a partir de dados de acessibilidade e os resultados estruturados agora incluem dicas de nextSteps (os schemas de resultado foram versionados para v2 nesta versão; desde então, a v2.7.0 moveu os resultados de build/teste para schemaVersion: 3 — veja abaixo). Defina XCODEBUILDMCP_HEADLESS_LAUNCH=true para iniciar apps em segundo plano sem roubar o foco do macOS — a diferença entre uma sessão de agente que você pode deixar em execução e outra que continua trazendo sua janela do Simulator para a frente. Em uma tarefa determinística de app de clima, o benchmark do próprio projeto afirma cerca de 70% menos tempo total, 68% menos tokens e 76% menos chamadas de ferramenta em comparação ao fluxo anterior à 2.6 — são números do projeto, não uma medição independente, mas o mecanismo (pular snapshots inalterados, agrupar ações na mesma tela) é exatamente de onde vem o consumo de tokens da automação de UI.¹⁹

O que a v2.7.0 mudou (2026-07-23) — simuladores do Xcode 27, schema v3, builds que respeitam a scheme:

A versão v2.7.0 é menor do que a 2.6.0, mas traz uma mudança incompatível e uma mudança de comportamento que vale conhecer antes de atualizar.²¹ O destaque: as ferramentas de automação de UI agora funcionam plenamente com simuladores do Xcode 27 pelo Device Hub, incluindo abertura da janela do simulador e controles de teclado — eliminando a lacuna em que a automação de UI em runtime só era confiável com simuladores do Xcode 26. Incompatibilidade: as ferramentas de build e teste agora retornam resultados estruturados schemaVersion: 3 (elas eram v2 desde a 2.6.0) — qualquer coisa que você tenha escrito para validar ou analisar resultados fixados na versão 2 precisa ser atualizada. Mudança de comportamento: as ferramentas de build, teste, limpeza e caminho do app agora respeitam a configuração da ação da scheme quando configuration é omitido, em vez de sempre usar Debug por padrão — se a ação Test de uma scheme estiver definida como Release, um test_sim sem qualificação agora compila em Release, portanto informe configuration explicitamente quando seu fluxo depender de uma configuração específica. Menores, mas úteis: pacotes reutilizáveis de preparação de testes .xctestproducts permitem executar testes novamente sem recompilar, ainda produzindo um .xcresult novo a cada execução; extraArgs padrão da sessão permite definir flags comuns do xcodebuild uma vez por sessão, em vez de repeti-las em cada chamada; um novo comando CLI xcodebuildmcp purge informa e limpa o armazenamento de workspace do XcodeBuildMCP (simulação por padrão, opt-in explícito para excluir); e foi incluída uma correção para clientes de MCP que esperavam de 10 a 17 segundos até que as ferramentas ficassem disponíveis — o que poderia fazer verificações curtas de integridade informarem uma conexão com falha.²¹

Apple Xcode MCP: 20 ferramentas que fazem ponte com o Xcode

O servidor MCP da Apple vem com o Xcode 26.3 por meio de xcrun mcpbridge.⁴ Ele se comunica com um processo do Xcode em execução por XPC (o framework de comunicação entre processos da Apple), expondo estado interno ao qual nenhuma ferramenta CLI pode acessar.⁵

Instalação:

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

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

Requer o Xcode 26.3+ e um processo do Xcode em execução. Se o Xcode não estiver aberto, todas as chamadas de MCP por este servidor falharão ou ficarão travadas. O XcodeBuildMCP não tem essa limitação.

O beta 5 do Xcode 27 apresenta uma forma de eliminar essa restrição. A Apple adicionou “uma nova experiência de servidor MCP que funciona sem exigir um workspace do Xcode aberto”, ativada com sudo xcrun mcp-server enable e inspecionada com xcrun mcp-server status. A mesma prévia permite conceder a agentes com assinatura de código permissão persistente para trabalhar dentro de uma árvore de diretórios, em vez de aprovar novamente a cada vez. Para execuções sem supervisão, sudo xcrun mcp-server enable --unsafe-always-allow-all-agents aprova tudo antecipadamente — a Apple afirma explicitamente que isso “não é uma configuração recomendada para uso na mesa”, e eu também não recomendo: ela remove a etapa de aprovação que mantém um agente fora de diretórios que você não pretendia expor. Trate toda essa superfície como uma prévia inicial e mantenha o XcodeBuildMCP como o caminho headless até que ela saia da prévia.²²

Inventário de ferramentas (20 ferramentas em 5 categorias):

Ferramentas exclusivas do MCP da Apple (não disponíveis no XcodeBuildMCP):

1. DocumentationSearch — Pesquisa a documentação para desenvolvedores da Apple, incluindo sessões da WWDC. É mais rápida e confiável do que a busca na web para perguntas sobre API da Apple. Pergunte “is HKQuantityType(.dietaryWater) valid?” e obtenha uma resposta definitiva da fonte.

2. ExecuteSnippet — Execução de Swift REPL dentro do contexto do projeto. O agente pode verificar o comportamento de API, testar conversões de tipo e validar expressões sem compilar o app inteiro.

3. RenderPreview — Renderiza previews SwiftUI headlessly. O agente pode verificar se uma view é renderizada sem erros, embora não possa avaliar a correção visual (a renderização é retornada como dados, não inspecionada visualmente). A partir do Xcode 26.6, a ferramenta de MCP de preview (as notas da versão 26.6 a chamam de “Preview Snapshot”) renderiza variantes — aparência clara/escura, orientação retrato/paisagem e substituições de tamanho de tipo (178831772) — para que um agente possa verificar uma view em diferentes aparências de uma vez.¹⁷ O beta do Xcode 27 amplia isso ainda mais: renderização de grupos de Preview e visualização em outra localização.¹⁸

4. XcodeListNavigatorIssues — Retorna diagnósticos em tempo real do analisador do Xcode, não apenas erros de build. Detecta problemas como variáveis não usadas, possíveis ciclos de retenção e avisos de descontinuação que o sistema de build não mostra.

Por que ambos os servidores

Eles se sobrepõem em builds e testes, mas diferem fundamentalmente:

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

Use o XcodeBuildMCP para: O ciclo de compilar-testar-depurar. Ele funciona sem o Xcode aberto, consome menos memória do sistema e oferece gerenciamento mais rico de simuladores e dispositivos. Esta é sua ferramenta de build principal.

Use o Apple Xcode MCP para: Consultas de documentação, verificação com Swift REPL, renderização de previews SwiftUI e diagnósticos em tempo real. Mantenha o Xcode aberto durante sessões que precisam desses recursos.

Na prática: Uso o XcodeBuildMCP para cerca de 90% das chamadas de MCP e o Apple Xcode MCP para documentação e verificação com REPL. O agente usa o XcodeBuildMCP por padrão para builds e testes porque ele é mais rápido (sem sobrecarga do processo do Xcode) e mais confiável (sem dependência de XPC).

O enquadramento de dois servidores está ficando mais flexível. O XcodeBuildMCP 2.6.x adiciona uma categoria de proxy xcode-ide: xcode_ide_list_tools descobre as capacidades de MCP exclusivas do Xcode-IDE e xcode_ide_call_tool as invoca (elas aparecem com nomes xcode_tools_*, por exemplo, xcode_tools_documentationsearch), de modo que um único registro do XcodeBuildMCP agora também pode alcançar as ferramentas do lado IDE da Apple.¹⁹ A restrição relevante não muda: essas chamadas por proxy ainda exigem um processo do Xcode em execução, exatamente como um registro direto de xcrun mcpbridge. Mantenha ambos os servidores registrados se quiser as ferramentas da Apple como recursos de primeira classe na lista de ferramentas do agente; o proxy é mais útil quando você quer uma entrada de servidor e apenas leituras ocasionais do IDE.

Verificação

Depois de instalar ambos os servidores, verifique se estão conectados:

# List all configured MCP servers
claude mcp list

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

Se um servidor mostrar “Disconnected” ou não aparecer:

1. XcodeBuildMCP não conecta: Verifique se o Node.js está instalado (node --version). O comando npx requer Node.js 18+.
2. Apple Xcode MCP não conecta: Verifique se o Xcode 26.3+ está instalado e se o comando xcrun mcpbridge funciona no terminal. Abra o Xcode pelo menos uma vez para aceitar o contrato de licença.
3. Nenhum dos dois aparece: Reinicie o Claude Code (claude em um novo terminal). Servidores MCP registrados no meio da sessão podem não aparecer até a reinicialização.

Ensinando o agente a usar MCP

Instalar servidores MCP é necessário, mas não suficiente. Sem orientação explícita, o agente pode voltar a executar xcodebuild pelo Bash (saída não estruturada, desperdício de tokens de contexto) ou usar a busca na web para documentação da Apple (mais lenta, menos confiável).

Adicione isto ao seu CLAUDE.md ou à definição do agente:

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

Essa orientação garante que o agente recorra primeiro às ferramentas de MCP. Sem ela, você verá o agente construindo longos comandos xcodebuild pelo Bash, consumindo milhares de tokens de contexto ao analisar a saída e, às vezes, identificando incorretamente o erro real.⁶

Uma mudança de comportamento do XcodeBuildMCP v2.7.0 pertence ao modelo mental desta seção: quando configuration é omitido, as ferramentas de build, teste, limpeza e caminho do app agora respeitam a configuração da ação da scheme, em vez de sempre usarem Debug.²¹ A maioria das schemes executa e testa em Debug, portanto a maioria dos projetos não perceberá nada — mas, se a ação de uma scheme estiver definida como Release (comum em schemes de profiling ou configurações próximas de archive), um build_sim ou test_sim sem qualificação agora compila em Release. Se seu CLAUDE.md ou seus hooks pressupõem artefatos Debug, informe isso explicitamente na chamada da ferramenta ou defina-o uma vez por sessão com session_set_defaults.

Builds de longa duração: o Claude Code agora os executa em segundo plano

Duas versões do Claude Code mudaram como um build longo se apresenta dentro de uma sessão. Desde a v2.1.212 (2026-07-16), qualquer chamada de ferramenta MCP que dure mais de 2 minutos passa automaticamente para segundo plano, para que a sessão permaneça utilizável; o limite é configurável — ou o comportamento pode ser desativado — por meio de CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS.²⁰ Builds limpos e execuções completas de testes via build_sim / test_sim rotineiramente ultrapassam a marca de 2 minutos em projetos reais, então espere que o agente continue trabalhando — lendo arquivos, planejando a próxima edição — enquanto o build termina em segundo plano, em vez de bloquear o turno. A correção complementar importa tanto quanto: antes da v2.1.206 (2026-07-09), um request_timeout_ms por servidor configurado via --mcp-config ou .mcp.json era ignorado em sessões novas, de modo que chamadas longas de MCP expiravam no padrão de 60 segundos — o sintoma clássico era um timeout no primeiro build limpo que “se resolvia” ao tentar novamente.²⁰ Se você contornou um desses comportamentos com scripts wrapper ou builds pré-aquecidos, pode remover essa solução temporária.

Padrões de CLAUDE.md para projetos iOS

Seu CLAUDE.md é o arquivo mais importante do projeto para desenvolvimento assistido por agentes. Ele é o documento de onboarding do agente: a diferença entre uma pessoa recém-contratada que leu a documentação de arquitetura e uma que está tentando adivinhar.

Todo projeto iOS que mantenho tem um CLAUDE.md. Aqui estão os padrões que funcionam, extraídos dos 8 apps.

As seções essenciais

Todo CLAUDE.md de iOS precisa destas 6 seções. Todo o resto é opcional.

1. Identidade do projeto

# 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

Por que isso importa: o agente precisa saber o deployment target antes de escrever qualquer código. Um agente mirando iOS 17 vai usar NavigationView e @ObservedObject. Um agente mirando iOS 26 vai usar NavigationStack e @Observable. O bundle ID importa para entitlements e configuração do HealthKit. A versão do Swift determina o modelo de concorrência (async/await vs. completion handlers, concorrência estrita vs. flexível).

2. Estrutura de arquivos com anotações de propósito

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

Os comentários inline depois de cada nome de arquivo não são decoração. Eles são a documentação de maior alavancagem que você pode escrever. Quando o agente decide onde adicionar um novo recurso, essas anotações o guiam para o arquivo correto na primeira tentativa, em vez de fazê-lo ler todos os arquivos para entender a estrutura do projeto.

Antipadrão: listar arquivos sem anotações. TimerManager.swift não diz nada ao agente sobre se ele lida com estado, UI ou ambos. TimerManager.swift # Timer state, logic, and repeat handling diz exatamente o que pertence ali e o que não pertence.

3. Comandos de build e teste

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

Inclua os comandos brutos mesmo que o agente deva preferir MCP. Os comandos brutos servem como documentação de fallback e deixam explícitos os nomes de schemes e destinations.

4. Principais padrões e regras

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

Esses padrões evitam que o agente introduza inconsistências. Sem documentação explícita dos padrões, às vezes o agente vai usar ObservableObject em um arquivo e @Observable em outro, ou criar um novo mecanismo de configurações em vez de usar o singleton Settings.shared existente.

5. Coisas que o agente nunca deve fazer

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

Proibições explícitas são mais eficazes do que expectativas implícitas. O agente segue restrições negativas de forma mais confiável do que sugestões positivas porque elas são binárias (faça / não faça) em vez de heurísticas (prefira isto / às vezes use aquilo).

6. Contexto específico de framework

Esta seção varia por app. Inclua-a para qualquer framework que tenha configuração não óbvia:

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

Para 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

Para 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

Para 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 real: Banana List (SwiftUI + SwiftData + iCloud + servidor MCP)

Aqui está um exemplo anotado que mostra como todas as 6 seções funcionam juntas em um app moderadamente complexo. Este é o padrão de CLAUDE.md que uso para Banana List, um app de lista de compras com 53 arquivos, sincronização com iCloud e um servidor MCP personalizado que expõe os dados do app para o 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 real: Reps (app SwiftData mínimo — 14 arquivos)

Para projetos pequenos, o CLAUDE.md pode ser conciso. Aqui está o padrão para Reps, um tracker de treino com 14 arquivos. Perceba como até um CLAUDE.md curto cobre todas as 6 seções essenciais:

# 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

São 40 linhas de CLAUDE.md para um projeto com 14 arquivos. Leva 10 minutos para escrever e economiza horas de confusão do agente.

CLAUDE.md real: Starfield Destroyer (SpriteKit + Metal — 32 arquivos)

Projetos de jogo exigem mais contexto específico de framework. O agente precisa entender o scene graph, as categorias de física e a máquina de estados do jogo:

# 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 real: amp97 (Metal + visualização de áudio — 41 arquivos)

Projetos Metal precisam do maior volume de contexto específico de framework porque agentes não conseguem verificar a saída visual:

# 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

Escalando o CLAUDE.md conforme o tamanho do projeto

O nível certo de detalhe depende da contagem de arquivos e da complexidade do framework:

O custo de documentar em excesso é próximo de zero (o agente pula o que não precisa). O custo de documentar de menos é alto (o agente inventa padrões que entram em conflito com sua codebase).

Checklist de CLAUDE.md

Use este checklist ao criar ou auditar um CLAUDE.md para um projeto iOS:

• [ ] Bundle ID e deployment target especificados
• [ ] Versão do Swift e padrão de arquitetura nomeados
• [ ] Estrutura de arquivos com anotações inline de propósito
• [ ] Comando de build com scheme e destination corretos
• [ ] Comando de teste com scheme e destination corretos
• [ ] Preferência por MCP anotada (“prefer build_sim over xcodebuild”)
• [ ] Regra de @Observable (nunca ObservableObject)
• [ ] Regra de NavigationStack (nunca NavigationView)
• [ ] Proibição de .pbxproj
• [ ] Contexto específico de framework (permissões do HealthKit, relacionamentos SwiftData, hierarquia SpriteKit, pipeline Metal)
• [ ] Guards de disponibilidade de plataforma documentados (#if canImport, #if os)
• [ ] Principais singletons e padrões compartilhados documentados
• [ ] Limitações conhecidas ou pontos de atenção anotados

Sua primeira sessão com um agente

Com MCP configurado e um CLAUDE.md no seu projeto, aqui está um passo a passo de uma primeira sessão eficaz. Este exemplo usa Claude Code CLI, mas o fluxo de trabalho se aplica a qualquer runtime.

Etapa 1: verifique se o agente consegue ver seu projeto

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.

Se o agente não mencionar o conteúdo do seu CLAUDE.md, verifique se o arquivo está na raiz do projeto (o mesmo diretório de .xcodeproj ou Package.swift).

Etapa 2: execute um build de verificação de integridade

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.

Etapa 3: execute os testes

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.

Etapa 4: implemente um recurso

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

A observação do agente sobre não modificar .pbxproj é resultado das regras no CLAUDE.md. Sem essa regra, o agente tentaria modificar o arquivo do projeto e provavelmente o corromperia.

O que os agentes fazem bem em iOS

Estas são as tarefas em que os agentes produzem de forma consistente uma saída correta e pronta para produção, com revisão humana mínima.

Views e modificadores SwiftUI

Os agentes têm um reconhecimento profundo de padrões para a sintaxe declarativa do SwiftUI. Composição de views, cadeias de modificadores, bindings de estado e layout — tudo isso se encaixa bem nos dados de treinamento do agente porque a superfície API do SwiftUI é bem documentada e os padrões são muito consistentes.

Onde os agentes se destacam: - Criar novas views a partir de uma descrição (“crie uma folha de configurações com toggles para X, Y, Z”) - Aplicar cadeias de modificadores (.glassEffect(), .sensoryFeedback(), .navigationTitle()) - Converter entre padrões de layout (VStack para LazyVGrid, List para ScrollView) - Implementar bindings de formulário @Bindable para modelos SwiftData - Criar preview providers com dados de exemplo

Exemplo de prompt que produz resultados excelentes:

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.

A especificidade importa. “Crie uma view de configurações” produz uma saída genérica. “Crie uma SettingsView que siga o padrão existente em SettingsSheet.swift” produz uma saída consistente com sua codebase.

Modelos e queries SwiftData

Os agentes lidam de forma confiável com a macro @Model do SwiftData, relacionamentos e padrões @Query. A natureza declarativa do framework (semelhante ao Django ORM ou SQLAlchemy) se encaixa bem nos padrões que o agente viu em muitas codebases.

Onde os agentes se destacam: - Definir classes @Model com relacionamentos - Escrever @Query com descritores de ordenação e predicados - Implementar operações CRUD via modelContext - Planos de migração entre versões de schema - Dados de preview e fixtures de teste

Onde os agentes precisam de orientação: - Expressões #Predicate complexas (a DSL de predicados do SwiftData tem limitações que o agente nem sempre conhece — documente limitações conhecidas no CLAUDE.md) - Configuração de sincronização com CloudKit (automática via SwiftData, mas o agente pode tentar implementar sincronização manual)

Testes unitários

Testes unitários escritos por agentes têm qualidade consistentemente alta em projetos iOS. O agente entende padrões XCTest, métodos de teste async e o ciclo de vida de 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)

O agente produz casos XCTest bem estruturados com setUp() e tearDown(), asserções apropriadas e tratamento async para testes baseados em timers.

Refatoração e aplicação de padrões

Os agentes se destacam em refatoração mecânica: extrair views para componentes, converter ObservableObject para @Observable, migrar de NavigationView para NavigationStack e aplicar padrões consistentes em vários arquivos.

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.

O agente percorre metodicamente cada arquivo, aplica a transformação corretamente e mantém a funcionalidade existente. Este é um trabalho de alto impacto — uma refatoração que levaria uma hora de edição manual é concluída em minutos com precisão quase perfeita.

Diagnóstico de erros de build via MCP

Com a saída estruturada do MCP, os agentes diagnosticam erros de build mais rápido do que a maioria dos desenvolvedores. O agente lê o JSON do erro, identifica o arquivo e a linha exatos, entende a mensagem de erro e aplica a correção — muitas vezes em um único turno.

Erros que os agentes corrigem de forma autônoma: - Imports ausentes - Incompatibilidades de tipo - Lacunas de conformidade com protocolos - Uso obsoleto de API (com substituição) - Parâmetros obrigatórios ausentes no inicializador - Violações de controle de acesso

Erros em que os agentes precisam de ajuda: - Resolução ambígua de tipos (vários módulos definem o mesmo tipo) - Falhas complexas de constraints genéricas - Erros de expansão de macro (o agente não consegue ver a saída expandida da macro)

Gerenciamento do simulador

Os agentes lidam bem com o ciclo de vida do simulador via MCP:

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

O agente chama list_sims para encontrar runtimes disponíveis, boot_sim para iniciar o simulador, build_sim para compilar e instalar, e screenshot para capturar — tudo por meio de chamadas estruturadas do MCP.

O que os agentes fazem mal no iOS

Um retrato honesto de onde os agentes falham. Conhecer esses limites evita frustração e tokens desperdiçados.

Modificações no arquivo .pbxproj — NUNCA

Esta é a regra mais importante no desenvolvimento iOS com agentes. O arquivo .pbxproj é a configuração de projeto do Xcode: um arquivo de texto estruturado com referências UUID, listas de fases de build e associação a targets. Em tese, ele é legível por humanos; na prática, é impossível de analisar com segurança para agentes de AI.

Por que os agentes falham com .pbxproj: - O arquivo usa um formato próprio (não JSON, não YAML, não XML) com significado posicional - Cada entrada é referenciada por UUID: adicionar um arquivo exige atualizar de 3 a 5 seções diferentes de forma consistente - Um único caractere fora do lugar corrompe todo o arquivo de projeto - A resolução de conflitos de merge do Xcode para .pbxproj já é frágil; edições por agentes pioram isso

O que acontece quando um agente edita .pbxproj: 1. A edição parece funcionar (o agente informa “arquivo atualizado”) 2. O Xcode se recusa a abrir o projeto (“The project file is corrupted”) 3. Você passa de 15 a 60 minutos recuperando a partir do histórico do git 4. Você aprende a adicionar o hook PreToolUse (veja Hooks)

O workflow: O agente cria arquivos Swift. Você os adiciona manualmente ao projeto Xcode (arrastando para o Xcode ou usando File > Add Files). Isso leva 5 segundos por arquivo e evita horas de recuperação.

Para projetos Swift Package Manager: Essa limitação é menos grave. Package.swift é um arquivo Swift padrão que agentes conseguem editar de forma confiável. Se o seu projeto usa exclusivamente SPM (sem .xcodeproj), o agente consegue gerenciar toda a estrutura do projeto.

Edições complexas no Interface Builder / Storyboard

Se o seu projeto usa Interface Builder (arquivos .xib) ou Storyboards (arquivos .storyboard), agentes não conseguem editá-los de forma significativa. Eles são arquivos XML com UUIDs gerados automaticamente, referências de constraints e conexões de outlets, projetados para edição visual, não para edição em texto.

A mitigação: Use SwiftUI exclusivamente para novas views. Se o seu projeto tem arquivos legados do Interface Builder, deixe-os como estão e crie novas UIs em SwiftUI.

Otimização de performance

Agentes escrevem código correto, mas não necessariamente código performático. Eles não conseguem fazer profiling do app, identificar gargalos nem medir frame rates. Otimização de performance exige:

1. Profiling com Instruments (ferramenta visual, inacessível ao agente)
2. Entendimento das características de GPU/CPU do dispositivo específico
3. Mudanças iterativas guiadas por medição

Onde isso aparece: - Otimização de shaders Metal (o agente escreve Metal válido, mas não consegue medir o tempo de frame da GPU) - Complexidade do body de views SwiftUI (o agente cria views profundamente aninhadas que causam overhead de redesenho) - Otimização de fetch em Core Data / SwiftData (o agente escreve queries corretas que podem ser lentas em datasets grandes)

A mitigação: Use agentes para a implementação, faça profiling manualmente com Instruments e depois peça ao agente para aplicar otimizações específicas que você identificou.

Code signing e provisioning

Agentes não conseguem depurar problemas de code signing além de ler a mensagem de erro. Gerenciamento de provisioning profiles, criação de certificados, configuração de entitlements e envio para a App Store são workflows fundamentalmente operados por humanos, envolvendo o portal Apple Developer, Keychain Access e a UI de signing do Xcode.

O que o agente vê: “Signing for ‘Return’ requires a development team.”

O que o agente não consegue ver: Se o seu certificado expirou, se o provisioning profile inclui o dispositivo, se o bundle ID corresponde ao App ID ou se o arquivo de entitlements está correto.

A mitigação: Faça todo o signing na aba Signing & Capabilities do Xcode. Não peça a agentes para depurar falhas de signing.

Debugging complexo de shaders Metal

Agentes escrevem Metal Shading Language (MSL) sintaticamente correto, mas não conseguem verificar a saída visual nem depurar problemas no lado da GPU. Shaders Metal executam na GPU; o agente não tem nenhum mecanismo de feedback para saber se o shader produz resultados visuais corretos.

O que agentes conseguem fazer com Metal: - Escrever vertex e fragment shaders a partir de descrições - Configurar o pipeline de renderização Metal em Swift - Criar compute shaders para operações paralelas em dados - Corrigir erros de compilação em arquivos .metal

O que agentes não conseguem fazer com Metal: - Verificar a correção visual da saída do shader - Depurar performance da GPU (tempo de frame, occupancy, largura de banda de memória) - Diagnosticar artefatos visuais (banding, problemas de precisão, color space incorreto) - Testar em diferentes arquiteturas de GPU (diferenças de comportamento entre A-series e M-series)

A mitigação: Teste shaders Metal em dispositivos físicos. A implementação de Metal do Simulator não representa o comportamento da GPU no dispositivo. Use o GPU Frame Capture do Xcode para debugging visual.

Verificação visual de layout

Agentes não conseguem ver a UI do seu app. Eles escrevem código de layout em SwiftUI e conseguem verificar se ele compila, mas não conseguem dizer se a tela resultante está correta. Uma view renderizada 10 pixels fora do centro, usando o peso de fonte errado ou com elementos sobrepostos não gera erro de build e passa em todos os testes de lógica.

A mitigação: Revise visualmente as mudanças de UI. Use SwiftUI Previews no Xcode (ou RenderPreview via Apple MCP para renderização headless) para verificar o layout. Considere snapshot testing com bibliotecas como swift-snapshot-testing para detecção automatizada de regressões visuais.

Hooks para desenvolvimento iOS

Hooks são comandos shell executados de forma determinística em pontos específicos do fluxo de trabalho do agente. Eles funcionam como mecanismo de imposição — a diferença entre “não edite o .pbxproj, por favor” (uma sugestão que o agente pode ignorar) e “você não pode editar o .pbxproj” (um bloqueio rígido).

Para entender melhor o sistema de hooks, consulte o guia de hooks do Claude Code. Esta seção aborda padrões de hooks específicos para iOS.

PreToolUse: bloquear gravações no .pbxproj

O hook mais importante em qualquer projeto iOS. Ele impede que o agente grave em arquivos .pbxproj, pastas .xcodeproj/ e outros arquivos gerenciados pelo 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'"
      }
    ]
  }
}

Coloque isso em .claude/settings.json na raiz do projeto ou em ~/.claude/settings.json para ter proteção global.

Como funciona: quando o agente tenta usar a ferramenta Edit ou Write em qualquer arquivo que corresponda ao padrão, o hook é executado, detecta o caminho do arquivo, exibe um aviso no stderr e encerra com o código 2 (o que bloqueia o uso da ferramenta). O agente recebe a mensagem de erro e ajusta sua abordagem.

O que ele detecta: - Edições diretas no .pbxproj - Qualquer arquivo dentro das pastas .xcodeproj/ ou .xcworkspace/ - Arquivos do Interface Builder (.xib, .storyboard)

PostToolUse: formatar ao salvar com SwiftFormat

Formate automaticamente os arquivos Swift sempre que o agente gravar ou editar esses arquivos:

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

Requisitos: o SwiftFormat deve estar instalado (brew install swiftformat).

Por que isso é importante: os agentes produzem código Swift sintaticamente correto, mas nem sempre seguem as convenções de formatação. O SwiftFormat padroniza a indentação, o posicionamento das chaves e a ordem dos imports.⁸ Com o hook de formatação ao salvar, todo arquivo Swift modificado pelo agente é formatado automaticamente antes que você o veja.

Opcional: adicione um arquivo de configuração .swiftformat à raiz do projeto para personalizar as regras de formatação:

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

PostToolUse: executar o SwiftLint automaticamente

Se você usa o SwiftLint, execute-o após cada edição de arquivo 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'"
      }
    ]
  }
}

O || true impede que os avisos do lint bloqueiem o agente. Se quiser que as violações do lint gerem um bloqueio, remova-o.

PostToolUse: compilar automaticamente após as alterações

Para ciclos de feedback mais intensos, inicie uma compilação após cada alteração em um arquivo 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'"
      }
    ]
  }
}

Aviso: isso consome muitos recursos. Cada edição de arquivo inicia uma compilação. Use com moderação — é mais útil durante sessões de depuração nas quais você precisa de feedback imediato da compilação. No desenvolvimento normal, deixe o agente iniciar as compilações manualmente por meio do MCP quando estiver pronto.

PreToolUse: bloquear alterações em entitlements

Proteja seu arquivo de entitlements contra alterações acidentais feitas pelo agente:

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

Configuração combinada de hooks para iOS

Aqui está o .claude/settings.json completo que uso em todos os projetos 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'"
      }
    ]
  }
}

Isso oferece duas garantias: 1. O agente não pode corromper os arquivos de projeto do Xcode (bloqueio PreToolUse) 2. Todo arquivo Swift modificado pelo agente é formatado automaticamente (formatação PostToolUse)

Padrões de arquitetura que funcionam com agentes

Nem todas as arquiteturas Swift são igualmente adequadas para agentes. Estes padrões produzem os melhores resultados porque são explícitos, consistentes e bem representados nos dados de treinamento.

@Observable (nunca ObservableObject)

Projetos para iOS 26 ou posterior devem usar exclusivamente @Observable. Esse é tanto o padrão moderno quanto o mais adequado para agentes:

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

Por que @Observable é adequado para agentes: O padrão é mais simples (não exige anotações @Published), o modelo de propriedade é mais claro (@State em vez da distinção entre @StateObject e @ObservedObject) e os agentes produzem menos bugs com ele porque há menos elementos envolvidos.

Documente isso no CLAUDE.md: Mesmo com o iOS 26 como versão mínima, os agentes ocasionalmente voltam aos padrões de ObservableObject presentes nos dados de treinamento. Uma proibição explícita evita isso.

NavigationStack (nunca 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á disponível a partir do iOS 16 e é o único padrão de navegação que você deve usar em código novo. O padrão type-safe navigationDestination(for:) evita que o agente crie links de navegação incorretos.

SwiftData para persistência

Os modelos SwiftData são o padrão de persistência mais limpo para o desenvolvimento assistido por agentes:

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

Regras essenciais para agentes que trabalham com SwiftData: 1. As classes @Model são automaticamente Observable — não adicione @Observable 2. Use @Bindable para bindings de formulários: @Bindable var item: GroceryItem 3. Use @Query nas views para dados reativos: @Query var items: [GroceryItem] 4. Use modelContext.fetch() em código que não pertence a uma view 5. Exclusões de relacionamentos precisam de regras explícitas: .cascade, .nullify, .deny

Concorrência do Swift 6.2

Para novos projetos, use a concorrência estrita do Swift 6.2. Essa é uma escolha do modo da linguagem, não da versão do toolchain — tanto o compilador Swift 6.3 no Xcode 26.6 estável quanto o Swift 6.4 no beta do Xcode 27 compilam esses padrões sem alterações:¹⁷¹⁸

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

Orientações para agentes sobre concorrência: - Marque todos os view models com @MainActor (evita avisos de data race) - Use async/await para todo trabalho assíncrono (sem completion handlers) - Faça com que tipos por valor sejam Sendable para transferências entre actors - Use Task { } nas views para inicialização assíncrona - Use nonisolated somente quando você tiver identificado uma necessidade de desempenho por meio de medições

Sistema de design Liquid Glass (iOS 26+)

O iOS 26 introduziu o sistema de design Liquid Glass. Os agentes trabalham bem com ele quando recebem orientações explícitas:

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

Inclua no CLAUDE.md: “Use .glassEffect() nos planos de fundo das seções e nos contêineres de cards. As barras de navegação adotam automaticamente o material de vidro no iOS 26. Não recrie manualmente efeitos de vidro com materiais personalizados — use o modificador do sistema.”

Contexto específico de cada framework

Cada framework da Apple tem particularidades para o uso com agentes. Esta seção aborda os frameworks usados nos 8 apps.

HealthKit

Apps que o utilizam: Return, Water

O HealthKit exige um tratamento cuidadoso das permissões e verificações de plataforma:

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

Regras para agentes que trabalham com HealthKit: - Sempre verifique com HKHealthStore.isHealthDataAvailable() - Nunca presuma que há autorização — verifique-a em cada gravação - Use #if canImport(HealthKit) em código multiplataforma (o HealthKit não está disponível no tvOS) - Nunca armazene dados de saúde localmente além do que o HealthKit fornece - Inclua NSHealthShareUsageDescription e NSHealthUpdateUsageDescription no Info.plist

SpriteKit

Apps que o utilizam: TappyColor, Starfield Destroyer

O modelo de grafo de cenas do SpriteKit exige orientações explícitas para o agente:

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

Pontos fortes dos agentes com SpriteKit: - Criar sequências e grupos de SKAction - Configurar corpos físicos e detecção de contatos - Implementar máquinas de estados de jogos - Criar overlays de HUD

Pontos fracos dos agentes com SpriteKit: - Loops de jogo sensíveis ao desempenho (o agente adiciona trabalho desnecessário a cada frame) - Simulações físicas complexas (uma implementação física personalizada supera o SKPhysicsBody em precisão) - Ajuste de efeitos de partículas (é visual e exige iteração)

Metal

Apps que o utilizam: amp97, Water, Starfield Destroyer

Metal é o framework com o qual os agentes enfrentam mais dificuldades. O modelo de programação GPU é fundamentalmente diferente do Swift executado na CPU, e os agentes não conseguem verificar o resultado visual.

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

O que incluir no CLAUDE.md de projetos Metal: - A definição da struct Uniforms (compartilhada entre Swift e MSL) - O padrão de configuração do estado do pipeline de renderização - Os índices dos buffers e suas finalidades - Quais shaders existem e o que cada um faz - Problemas de precisão conhecidos (half vs. float)

Live Activities

Apps que o utilizam: Return

Live Activities exigem configurações específicas que os agentes executam bem depois que elas são documentadas:

## Live Activities

- ActivityAttributes defined in `TimerActivityAttributes.swift`
- ActivityKit framework: `import ActivityKit`
- Widget extension: `ReturnWidgets/ReturnLiveActivity.swift`
- Start: `Activity<TimerActivityAttributes>.request(attributes:content:)`
- Update: `activity.update(ActivityContent(state:staleDate:))`
- End: `activity.end(ActivityContent(state:staleDate:), dismissalPolicy:)`
- Push token: register for updates via `activity.pushTokenUpdates`

Game Center

Apps que o utilizam: 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)

Padrões multiplataforma

Return abrange iOS, watchOS e tvOS. O desenvolvimento multiplataforma com agentes exige documentação explícita dos limites entre plataformas.

Organização de código compartilhado

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

Regra para agentes: “Se um arquivo estiver em Shared/, as alterações afetarão todas as plataformas. Se um arquivo estiver em um diretório de plataforma, as alterações serão isoladas. Sempre verifique em qual diretório um arquivo está antes de modificá-lo.”

Proteções de disponibilidade por plataforma

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

Orientação para agentes: “Sempre use proteções #if canImport() ou #if os() ao utilizar frameworks específicos de uma plataforma. Não presuma que um framework está disponível em todos os targets.”

Adaptação da UI por plataforma

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

Fluxos de trabalho avançados

Ciclos autônomos de build-teste-correção

O padrão mais poderoso: forneça ao agente uma especificação de recurso e deixe que ele itere autonomamente por ciclos de build-teste-correção.

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.

O agente escreve código, faz o build via MCP, lê erros estruturados, corrige-os e repete o processo. Um recurso que exigiria de 5 a 10 ciclos humanos de build-erro-correção é concluído em um único ciclo autônomo.

Quando isso funciona: Recursos bem definidos com critérios de aceitação claros.

Quando isso falha: Recursos abertos (“deixe mais bonito”), código sensível a desempenho ou qualquer coisa que exija verificação visual.

Delegação para subagentes no iOS

O sistema de subagentes do Claude Code funciona em projetos 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.

O subagente explora a documentação e os padrões de código em uma janela de contexto separada, retorna um resumo, e a sessão principal implementa a recomendação. Isso evita que a pesquisa consuma seu contexto principal.

Aplicação de padrões entre apps

Ao manter vários apps iOS com padrões consistentes, os agentes podem aplicar padrões de um app a outro:

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.

O agente lê o padrão de origem, entende a estrutura e cria uma implementação consistente no projeto de destino.

Revisão com dois agentes (Claude + Codex)

Para alterações críticas, use dois agentes de famílias de modelos diferentes:

1. Claude Code escreve a implementação
2. Codex CLI a revisa em uma etapa separada

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

Famílias de modelos diferentes identificam classes de erros diferentes. Isso é especialmente valioso para shaders Metal e padrões de concorrência, nos quais bugs sutis são fáceis de introduzir.

O que a revisão dupla detecta que uma revisão única não detecta:

A revisão dupla não se trata de encontrar mais bugs — trata-se de encontrar bugs diferentes. Cada família de modelos tem modos de falha distintos em seu reconhecimento de padrões.

Operações em lote em vários apps

Quando uma alteração de framework ou padrão afeta vários 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

Use com cautela. A flag --dangerously-skip-permissions é necessária para o modo não interativo, mas ignora todas as verificações de segurança. Garanta que seus hooks PreToolUse estejam configurados para proteger arquivos .pbxproj.

Apps que usam o LLM no dispositivo da Apple

Se o seu app chama o framework Foundation Models da Apple (por exemplo, para sumarização offline, classificação ou geração de saída estruturada), os agentes precisam conhecer o orçamento de prompt. O iOS 26.4 adicionou duas APIs do API a SystemLanguageModel que substituíram a estimativa anterior de 4096 tokens: contextSize (o máximo de tokens que o modelo aceita em uma única conversa) e tokenCount(for:) (async throws, retorna quantos tokens um determinado prompt realmente custa).³¹ Ambas são @backDeployed(before: iOS 26.4), portanto estão disponíveis em todas as versões de SO compatíveis com FM sem uma sequência de #available.

O padrão que um agente deve seguir ao gerar código de construção de prompts:

import FoundationModels

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

Adicione esse padrão ao seu CLAUDE.md caso o app use SystemLanguageModel. Sem ele, os agentes recorrem ao hardcode antigo de 4096 e truncam prompts silenciosamente em dispositivos que vêm com janelas de contexto maiores. A assinatura async throws em tokenCount(for:) é essencial — agentes que colarem uma versão síncrona não conseguirão compilar.

Estudos de caso reais

Conselhos abstratos são fáceis. Aqui estão cenários específicos dos 8 apps que mostram como o desenvolvimento iOS assistido por agentes funciona na prática — inclusive as falhas.

Estudo de caso 1: adicionar um app para TV ao Return (sucesso)

A tarefa: Adicionar um target tvOS ao Return, um timer de meditação que já tinha versões para iOS e watchOS. O app para TV precisava de navegação com Siri Remote, UI para tela grande e sincronização de configurações com o app iOS.

O que o agente fez bem: - Leu o TimerManager existente no iOS e criou um TVTimerManager que omitia Live Activities e HealthKit (indisponíveis no tvOS) - Criou estilos de botão personalizados para navegação por foco com Siri Remote (TVCapsuleButtonStyle, TVCircleButtonStyle) - Criou um componente TVStepper que substitui seletores em roda (não usáveis com Siri Remote) por botões +/- - Implementou sincronização de configurações via App Groups (group.com.941apps.Return) - Adicionou proteções #if os(tvOS) em todo o código compartilhado - Compilou e testou via MCP com platform=tvOS Simulator,name=Apple TV

O que precisei fazer manualmente: - Criar o target tvOS no Xcode (File > New > Target > tvOS App) - Adicionar o novo target ao projeto Xcode (alterações no .pbxproj) - Configurar o entitlement de App Groups para o target da TV - Adicionar o target da TV ao scheme existente ou criar um novo - Adicionar manualmente todos os arquivos Swift criados pelo agente ao target da TV - Testar manualmente a navegação com Siri Remote (o agente não consegue avaliar o comportamento de foco)

Resultado: 15 novos arquivos Swift, app para TV totalmente funcional, em aproximadamente 3 horas de trabalho assistido por agente. Pela minha estimativa, o agente cuidou de cerca de 80% do trabalho de implementação; eu cuidei das partes que exigiam interação com a UI do Xcode (entitlements, configuração de target, flags de capabilities) e testes manuais de foco em uma Apple TV real. O trabalho solo equivalente neste codebase — com base em recursos parecidos que já lancei sem agentes — teria levado vários dias.

Estudo de caso 2: depuração de shader Metal no amp97 (falha parcial)

A tarefa: Adicionar um sistema de intensidade baseado em energia ao shader de osciloscópio. A visualização deveria pulsar com a energia do áudio.

O que aconteceu: 1. O agente escreveu uma modificação válida no shader Metal adicionando um uniform uEnergy e tonemapping HDR 2. O código compilou sem erros 3. No dispositivo, a visualização ficou completamente branca — o coeficiente de intensidade estava 10x alto demais (3,5 em vez de 0,30) 4. O agente não conseguia ver a tela branca, então não tinha sinal de feedback 5. Identifiquei o problema visualmente e pedi ao agente para reduzir o coeficiente 6. O agente reduziu, mas a máquina de estados de energia como um todo estava complexa demais e quebrou o visualizador de outras formas 7. Revertido por completo — dois commits (67959ed e cda4830) revertidos em 869d914

A lição: Shaders Metal são o domínio mais difícil para desenvolvimento assistido por agentes porque o loop de feedback é quebrado. O agente consegue verificar sintaxe (compila) e semântica (tipos corretos), mas não consegue verificar o resultado (se parece certo). Qualquer modificação de shader que altere o comportamento visual exige verificação humana no dispositivo.

O que adicionei ao CLAUDE.md depois disso: “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.”

Estudo de caso 3: migração SwiftData no Banana List (sucesso)

A tarefa: Migrar o modelo de dados da V1 para a V2, adicionando um campo quantity a GroceryItem e um novo modelo Category com relacionamentos.

O que o agente fez: 1. Leu as definições existentes do modelo V1 2. Criou definições do modelo V2 com os novos campos e relacionamentos 3. Escreveu um GroceryMigrationPlan com conformidade ao protocolo SchemaMigrationPlan 4. Implementou o estágio de migração V1toV2: adicionou quantity: 1 e category: nil como padrões 5. Atualizou todas as views para dar suporte aos novos campos 6. Atualizou SampleData.swift para previews 7. Compilou e executou testes via MCP — todos passaram 8. Criou testes unitários específicos para a migração

O ponto-chave: O agente teve sucesso porque migrações SwiftData seguem um padrão de protocolo bem definido, amplamente representado na documentação da Apple e nos dados de treinamento. O CLAUDE.md documentava explicitamente o modelo V1, então o agente entendeu de onde estava migrando.

Estudo de caso 4: sincronização de sessões via iCloud no Return (sucesso com complexidade)

A tarefa: Implementar registro de sessões de meditação entre dispositivos. Sessões concluídas na Apple TV ou no Mac deveriam sincronizar com o iPhone para registro no HealthKit.

O que o agente produziu:

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

O agente: 1. Criou o modelo de dados MeditationSession com UUID, datas, duração, dispositivo de origem e status de sincronização com HealthKit 2. Criou um singleton SessionStore gerenciando NSUbiquitousKeyValueStore para sincronização via iCloud 3. Implementou resolução de conflitos de merge (desduplicação baseada em UUID) 4. Adicionou SessionHistoryView com adaptações específicas por plataforma (deslizar para excluir no iOS, baseado em foco no tvOS) 5. Conectou a sincronização com HealthKit no lado do iPhone para sessões vindas de outros dispositivos

O que exigiu iteração: A implementação inicial não lidava com o caso em que o app do iPhone inicia em segundo plano (sem notificação de foreground para sincronização). O agente precisou de orientação específica: “Use NSUbiquitousKeyValueStore.didChangeExternallyNotification to trigger sync on background KV changes.” Depois dessa dica, a implementação ficou correta.

A lição: Agentes lidam bem com padrões arquiteturais multiplataforma quando a arquitetura é descrita com clareza. O padrão de sincronização via iCloud não é trivial, mas segue um padrão documentado da Apple que o agente entendeu. O caso de borda (sincronização em segundo plano) exigiu conhecimento humano de domínio porque não é bem documentado.

Estudo de caso 5: integração com Game Center no Starfield Destroyer (sucesso)

A tarefa: Adicionar leaderboards e achievements do Game Center ao shooter espacial.

O que o agente fez bem: - Implementou GKLocalPlayer.local.authenticateHandler no ponto de entrada do app - Criou um GameCenterManager com métodos para envio de pontuação e relatório de achievements - Adicionou verificação de estado de autenticação antes de todas as operações do Game Center - Lidou bem com o caso offline (o jogo funciona sem Game Center e envia quando reconecta) - Criou definições de achievements correspondentes ao sistema de progressão de 8 naves

O que exigiu trabalho manual: - Criar os leaderboards e achievements no App Store Connect (portal web, inacessível ao agente) - Configurar o entitlement de Game Center no Xcode - Testar com uma conta sandbox do Game Center (exige login manual no dispositivo)

Ciclo de vida do projeto com agentes

Iniciando um novo projeto iOS

O fluxo de trabalho ideal para iniciar um novo projeto com ajuda de agentes:

Fase 1: configuração humana (15-30 minutos) 1. Crie o projeto no Xcode (File > New > Project) 2. Configure signing e capabilities 3. Defina o deployment target e os destinos compatíveis 4. Adicione qualquer entitlement necessário (HealthKit, Game Center etc.) 5. Crie o CLAUDE.md inicial com a identidade e as regras do projeto

Fase 2: implementação pelo agente (horas a dias) 1. O agente cria o modelo de dados (SwiftData, Core Data ou structs simples) 2. O agente cria views seguindo seus padrões documentados 3. O agente implementa a lógica de negócio em classes manager/service 4. O agente escreve testes unitários 5. Loop de build-test-fix via MCP (autônomo)

Fase 3: integração humana (30-60 minutos) 1. Adicione os arquivos criados pelo agente aos targets do Xcode 2. Verifique signing e entitlements 3. Teste em um dispositivo físico 4. Revise o layout visual e a UX 5. Envie para o App Store Connect

Mantendo um projeto existente

Para desenvolvimento contínuo em apps já estabelecidos:

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]

A eficácia do agente aumenta conforme o seu CLAUDE.md reflete bem o estado atual do projeto. Atualize o CLAUDE.md quando você adicionar recursos novos importantes, mudar padrões arquiteturais ou introduzir novos frameworks.

Quando envolver o agente ou não

Configurando definições de agentes

Se você usa o sistema de definição de agentes do Claude Code (.claude/agents/), crie um agente específico para 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

Referencie esse agente com @ios-developer em sessões do Claude Code.

Padrões de teste para iOS assistido por agentes

Agentes escrevem ótimos testes unitários quando recebem orientação clara. Estes são os padrões que produzem os melhores resultados.

Organização de arquivos de teste

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

Prompt de teste eficaz:

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.

Por que isso funciona: Critérios de aceite numerados dão ao agente uma checklist. Referenciar um arquivo de teste existente estabelece o padrão. Especificar o uso de setUp() evita que o agente crie estado de teste emaranhado.

Prompt de teste ineficaz:

Write tests for TimerManager.

Isso produz testes genéricos e superficiais, que deixam passar casos de borda e podem não seguir os padrões do seu projeto.

Padrões de teste async

Para testar código baseado em timers e código async:

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

Principais padrões que os agentes precisam ser lembrados de seguir: - @MainActor em métodos de teste que testam classes @MainActor - async throws para testes que usam Task.sleep ou operações async - Tolerância em assertions baseadas em tempo (1,1 segundo, não exatamente 1,0) - setUp() / tearDown() limpos para isolamento dos testes

Snapshot testing

Para detecção de regressão visual, considere adicionar 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.

Agentes configuram snapshot tests corretamente, mas não conseguem revisar as imagens de referência. Você revisa os snapshots iniciais; depois, os testes do agente detectam regressões visuais em mudanças futuras.

Gerenciamento da janela de contexto para projetos iOS

A janela de contexto de 1M (Opus 5) é grande, mas não infinita. Projetos iOS têm necessidades específicas de gerenciamento de contexto.

Custo de tokens dos arquivos iOS

Para um projeto com 50 arquivos: Ler todos os arquivos consome aproximadamente 50.000-100.000 tokens — bem dentro da janela de 1M. O agente consegue manter o projeto inteiro no contexto.

Para um projeto com mais de 100 arquivos: A leitura seletiva se torna necessária. O agente lê primeiro o CLAUDE.md (para consultar as anotações da estrutura de arquivos) e depois lê arquivos específicos conforme necessário. Por isso, as anotações de arquivos no CLAUDE.md são essenciais — elas direcionam o agente aos arquivos certos sem que ele precise ler tudo.

Estratégias para projetos grandes

1. Anotações detalhadas de arquivos no CLAUDE.md — O agente lê o mapa de arquivos e navega diretamente até os arquivos relevantes
2. Delegação para subagentes — Encaminhe a exploração e a pesquisa para subagentes (contexto limpo, retornam resumos)
3. Prompts específicos — “Modifique SettingsView.swift para adicionar um novo toggle” é melhor do que “atualize as configurações”
4. Limites entre sessões — Inicie novas sessões para recursos não relacionados em vez de prolongar uma sessão extensa
5. Use /compact — O comando de compactação do Claude Code resume a conversa e libera espaço no contexto

Eficiência de tokens do MCP

Um dos argumentos mais fortes a favor do MCP: as respostas estruturadas do JSON consomem muito menos tokens do que a saída bruta do xcodebuild.

Ao longo de uma sessão típica de desenvolvimento com 10-20 ciclos de build, o MCP economiza de 30.000 a 150.000 tokens em comparação com o xcodebuild bruto — tokens que continuam disponíveis para o raciocínio sobre o código.

Solução de problemas

“build_sim falhou — scheme não encontrado”

O agente está tentando adivinhar o nome do scheme. Corrija assim:

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

Ou adicione explicitamente o nome do scheme ao seu CLAUDE.md:

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

“xcrun mcpbridge — comando não encontrado”

Você precisa do Xcode 26.3 ou posterior. Verifique com xcodebuild -version. Se você tiver o Xcode 26.3 ou posterior, mas o comando ainda falhar:

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

# Verify
xcrun mcpbridge --help

“As ferramentas do MCP não aparecem no Claude Code”

As ferramentas do MCP registradas durante uma sessão podem não aparecer até que você reinicie. Saia do Claude Code e inicie uma nova sessão:

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

Depois, verifique:

You: List all available MCP tools from XcodeBuildMCP.

“O agente continua usando xcodebuild via Bash em vez do MCP”

O agente não está encontrando as ferramentas do MCP por meio do Tool Search. Há duas soluções:

1. Adicione instruções explícitas ao CLAUDE.md (consulte Como ensinar o agente a usar o MCP)
2. Instrua diretamente no prompt: “Use a ferramenta build_sim do MCP, não o xcodebuild via Bash”

“O build é bem-sucedido, mas o agente informa uma falha”

O XcodeBuildMCP analisa a saída do xcodebuild. Se o build gerar avisos que pareçam erros (algo comum com avisos de descontinuação), o agente poderá interpretar o resultado incorretamente. Verifique o campo de status real na resposta do MCP.

“O simulador trava durante a inicialização”

Encerre todos os simuladores e reinicie:

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

Ou peça ao agente:

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

“O agente tentou modificar o .pbxproj apesar das regras do CLAUDE.md”

As regras do CLAUDE.md são sugestões. Hooks garantem que elas sejam cumpridas. Se você não tiver o hook PreToolUse bloqueando gravações no .pbxproj, em algum momento o agente tentará modificá-lo. Instale o 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'"
      }
    ]
  }
}

As regras dizem “por favor, não faça isso”. Os hooks dizem “você não pode fazer isso”.

Perguntas frequentes

Com qual runtime de agente devo começar?

Claude Code CLI com XcodeBuildMCP. Ele oferece a integração mais profunda com MCP, o sistema de hooks mais maduro e a janela de contexto de 1 milhão de tokens (Opus 5), capaz de manter projetos iOS inteiros na memória de trabalho. Comece por ele e, conforme seu fluxo de trabalho amadurecer, adicione o Codex para revisão e os agentes nativos do Xcode para edições rápidas diretamente no código.

Preciso dos dois servidores MCP?

Para a maioria dos desenvolvedores, apenas o XcodeBuildMCP atende a 90% das necessidades (builds, testes, simuladores e depuração). Adicione o Xcode MCP da Apple se quiser pesquisar na documentação, verificar código com o Swift REPL ou renderizar previews do SwiftUI. Você sempre poderá adicioná-lo depois — os dois servidores são independentes.

Os agentes podem criar um novo projeto do Xcode do zero?

O XcodeBuildMCP inclui ferramentas de scaffolding (scaffold_ios_project, scaffold_macos_project) que criam novos projetos do Xcode a partir de templates. Contudo, para apps em produção, recomendo criar o projeto no Xcode (para configurar corretamente a assinatura, os recursos e o target) e depois usar os agentes para implementar todo o código. Os 5 minutos que você dedica ao assistente de criação de projetos do Xcode evitam horas corrigindo problemas na configuração de projetos gerados por agentes.

Como os agentes lidam com dependências do Swift Package Manager?

Muito bem. Package.swift é um arquivo Swift padrão que os agentes conseguem ler e editar de forma confiável. É possível adicionar dependências, atualizar intervalos de versões e configurar targets sem problemas. A limitação está no gerenciamento de dependências baseado em .xcodeproj (a interface de resolução de pacotes do Xcode) — essa parte é gerenciada pelo Xcode e não deve ser editada por agentes.

Os agentes podem enviar um app para a App Store?

Não. O envio para a App Store envolve o Organizer do Xcode, perfis de provisionamento, capturas de tela, metadados e o portal App Store Connect. Nenhum desses recursos pode ser acessado via MCP ou ferramentas de linha de comando de uma forma que os agentes consigam operar de maneira útil. Os agentes cuidam de tudo até a criação do archive — implementação, testes, correção de bugs e documentação. A etapa final do envio ainda precisa ser realizada por uma pessoa.

Porém, os agentes podem ajudar com os metadados da App Store. Peça ao agente para escrever a descrição do app, as palavras-chave e o texto das novidades com base nas alterações mais recentes. Esse é um trabalho de geração de texto no qual os agentes se destacam.

Como lidar com segredos e chaves de API no desenvolvimento iOS assistido por agentes?

Nunca faça commit de segredos. Para apps iOS que se conectam a APIs de backend:

1. Use arquivos .xcconfig para configurações específicas de cada ambiente
2. Adicione os arquivos .xcconfig ao .gitignore
3. Referencie os valores de configuração por meio das configurações de build do Info.plist
4. Documente os segredos necessários no CLAUDE.md sem incluir os valores reais

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

O agente sabe que as chaves existem e onde são usadas, mas nunca vê os valores reais.

E quanto às animações do SwiftUI — os agentes conseguem escrevê-las?

Os agentes escrevem código de animação corretamente do ponto de vista sintático, mas não conseguem verificar o resultado visualmente. Animações simples (.animation(.spring()), .transition(.slide), withAnimation { }) produzem resultados corretos. Animações complexas, com várias etapas e temporização precisa, exigem iteração visual, algo que os agentes não conseguem fazer.

Eficaz: “Adicione uma animação de mola quando o timer alternar entre os estados.”

Ineficaz: “Faça a animação do timer parecer satisfatória.” (É subjetivo e exige ajustes visuais.)

Como os agentes lidam com padrões de tratamento de erros?

Muito bem. Os agentes entendem os padrões do/catch, Result e async throws do 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

Os agentes produzem um tratamento de erros estruturado, com mensagens adequadas para o usuário. Às vezes, eles tratam erros em excesso (capturando exceções que deveriam ser propagadas), portanto revise os blocos catch.

Posso usar agentes para implementar acessibilidade?

Parcialmente. Os agentes adicionam corretamente labels, dicas e traits de acessibilidade:

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

O que os agentes não conseguem fazer: verificar se a ordem de navegação do VoiceOver está correta, testar o dimensionamento do Dynamic Type ou avaliar as taxas de contraste das cores. Use o Accessibility Inspector do Xcode para fazer essas verificações.

Como os agentes lidam com a migração do Core Data (quando não se usa SwiftData)?

Os agentes escrevem mapeamentos de migração e versões de modelos do Core Data, mas as etapas manuais no Xcode (criar novas versões de modelo e selecionar a versão atual) não podem ser automatizadas. Se você ainda usa Core Data em vez de SwiftData, documente o histórico de versões do modelo no CLAUDE.md:

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

Como os agentes lidam com previews do SwiftUI?

De duas formas: 1. A ferramenta RenderPreview do Apple Xcode MCP renderiza previews sem interface gráfica e retorna o resultado. O agente consegue verificar se um preview compila e é renderizado sem erros, mas não consegue avaliar se o resultado visual está correto. 2. Verificação baseada em build via build_sim confirma que os providers de preview compilam. Se um preview falhar durante a execução, o build ainda será concluído — a falha só aparecerá quando o Xcode tentar renderizar o preview.

Para verificar visualmente os previews, você ainda precisa manter o Xcode aberto.

E quanto ao visionOS e ao Apple Vision Pro?

Os mesmos padrões se aplicam. O XcodeBuildMCP oferece suporte a simuladores do visionOS, e os padrões de arquitetura (@Observable, NavigationStack, SwiftData) são idênticos. O código específico do RealityKit (conteúdo 3D, espaços imersivos e rastreamento de mãos) tem as mesmas limitações do Metal — os agentes conseguem escrever código correto, mas não verificar o resultado espacial.

Qual pode ser o tamanho de um projeto antes que os agentes comecem a ter dificuldades?

O tamanho da janela de contexto é o fator limitante. Com a janela de 1 milhão de tokens do Opus 5, o Claude Code consegue manter aproximadamente de 50 a 70 arquivos Swift simultaneamente na memória de trabalho ativa. Em projetos maiores, o agente usa a pesquisa de arquivos e a leitura seletiva para trabalhar com partes da base de código. Projetos com mais de 100 arquivos funcionam bem — o agente simplesmente lê os arquivos conforme necessário, em vez de manter tudo no contexto.

Na prática, o limite não é a quantidade de arquivos, mas a coerência da base de código. Um projeto bem documentado com 200 arquivos e um CLAUDE.md detalhado produz resultados melhores do que um projeto sem documentação com 30 arquivos.

Preciso saber Swift para usar agentes no desenvolvimento iOS?

Você precisa conseguir revisar o que o agente produz e tomar decisões de arquitetura. Não precisa escrever cada linha por conta própria, mas deve entender Swift o suficiente para perceber quando o agente toma decisões incorretas — especialmente em relação a concorrência, gerenciamento de memória e padrões específicos de frameworks. Um agente multiplica sua habilidade atual por 10; ele não a substitui.

Como os agentes lidam com conflitos de merge em arquivos Swift?

Os agentes resolvem conflitos de merge em arquivos de código-fonte Swift de forma confiável. Os marcadores de conflito padrão (<<<<<<<, =======, >>>>>>>) são bem compreendidos por todos os runtimes de agentes. Contudo, conflitos de merge em arquivos .pbxproj ainda precisam ser resolvidos manualmente — não peça aos agentes para resolver conflitos em .pbxproj.

Qual é o custo de executar agentes para desenvolvimento iOS?

Com o plano Max do Anthropic (Opus 5, contexto de 1 milhão de tokens), uma sessão típica de desenvolvimento iOS dura de 30 a 120 minutos e processa de 200 mil a 800 mil tokens. As chamadas de ferramentas do MCP acrescentam uma sobrecarga mínima (as respostas estruturadas em JSON usam tokens de forma eficiente em comparação com a saída bruta do build). O custo é comparável ao de executar o Claude Code em qualquer outra base de código — o desenvolvimento iOS não é significativamente mais nem menos caro do que o desenvolvimento web.

Posso usar agentes em projetos UIKit?

Sim, mas os agentes são mais eficazes com SwiftUI. O UIKit exige mais código repetitivo, tem uma estrutura menos declarativa e geralmente envolve arquivos do Interface Builder que os agentes não conseguem editar. Se você tem um projeto UIKit, considere usar agentes para a camada de modelos e a lógica de negócios enquanto cuida da interface manualmente, ou migre as views para SwiftUI de forma gradual.

Como os agentes lidam com localização?

Os agentes criam e editam arquivos .xcstrings (catálogos de strings do Xcode) com eficiência. Eles conseguem adicionar novas chaves de localização, fornecer traduções e manter a consistência entre idiomas. O formato estruturado em JSON dos arquivos .xcstrings é fácil de trabalhar para os agentes. Eles também têm bom desempenho com arquivos .strings (formato legado) — o formato de chave e valor é simples.

Erros comuns de agentes no iOS (e como evitá-los)

Estes são os erros recorrentes que observei em milhares de interações com agentes em 8 projetos iOS. Cada um deles tem uma estratégia de prevenção.

Erro 1: misturar padrões observáveis

O que acontece: O agente usa @Observable em um arquivo e ObservableObject em outro ou adiciona @Observable a uma classe @Model (que já é Observable).

Prevenção: Regras explícitas no 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

Erro 2: criar ciclos de retenção em closures

O que acontece: O agente cria closures que capturam self com referência forte, especialmente em Timer.publish, NotificationCenter e handlers de conclusão.

Prevenção: Inclua um padrão de closure no 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

Erro 3: ignorar os requisitos de @MainActor

O que acontece: O agente cria classes @Observable sem isolamento de @MainActor, causando avisos de concorrência do Swift 6.2 ou falhas em tempo de execução quando as atualizações da interface ocorrem fora da thread principal.

Prevenção:

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

Erro 4: usar NavigationLink com closure de destino

O que acontece: O agente usa o padrão obsoleto NavigationLink(destination:label:) em vez do padrão type-safe NavigationLink(value:) + .navigationDestination(for:).

Prevenção:

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

Erro 5: fixar nomes de simuladores no código

O que acontece: O agente escreve comandos de build com nomes específicos de simuladores (“iPhone 16 Pro”) que talvez não existam no seu sistema.

Prevenção: MCP cuida disso — list_sims descobre os simuladores disponíveis. No 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.

Erro 6: criar arquivos nas pastas erradas

O que acontece: O agente cria um novo arquivo de view na raiz do projeto em vez de colocá-lo na subpasta Views/ ou insere um model no grupo errado.

Prevenção: As anotações da estrutura de arquivos no CLAUDE.md orientam onde cada arquivo deve ficar. Além disso:

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

Erro 7: não considerar a disponibilidade da plataforma

O que acontece: O agente usa HealthKit em código compartilhado compilado para tvOS (onde HealthKit não está disponível) ou usa ActivityKit em código do watchOS.

Prevenção:

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

Erro 8: complicar demais recursos simples

O que acontece: O agente cria um protocolo, uma extensão de protocolo, uma implementação concreta, uma factory e um contêiner de injeção de dependência para algo que deveria ser uma função utilitária de 20 linhas.

Prevenção: Inclua um princípio de simplicidade:

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

Uma avaliação honesta

Depois de lançar 8 apps para iOS com agentes de IA, este é o resumo:

O que os agentes transformaram: A velocidade de implementação. O que antes levava dias agora leva horas. Views do SwiftUI, models do SwiftData, testes unitários e refatoração — tudo isso agora é produzido principalmente por agentes e revisado por humanos.

O que os agentes não transformaram: Decisões de arquitetura, design visual, otimização de desempenho ou envio para a App Store. Essas atividades continuam sendo conduzidas por humanos.

O ganho é real, mas tem limites. Minha estimativa subjetiva considerando o portfólio de 8 apps: uma melhoria de 3 a 5 vezes no tempo de entrega de recursos em projetos bem documentados, com configuração adequada de MCP e hooks. Isso não foi medido em relação a um grupo de controle; é uma comparação do tempo decorrido entre recursos desenvolvidos com o auxílio de agentes e trabalhos equivalentes feitos individualmente nas mesmas bases de código. Projetos sem documentação e sem hooks talvez tenham uma melhoria de 1,5 a 2 vezes — o agente passa tempo demais tentando adivinhar em vez de desenvolver.³³

O investimento que vale a pena: O tempo dedicado ao CLAUDE.md, aos hooks e à configuração de MCP. Cada hora de configuração economiza muitas horas corrigindo erros dos agentes. A configuração é o produto — o agente é o mecanismo de execução.

O que me surpreendeu: O quanto os servidores MCP mudaram a dinâmica. Antes de MCP, os agentes eram editores de texto sofisticados que, por acaso, entendiam Swift. Depois de MCP, eles se tornaram parceiros de desenvolvimento que escrevem, compilam, testam, depuram e iteram. O ciclo estruturado de feedback é o que diferencia um agente que escreve código de um que entrega código.

O que eu diria ao meu eu do passado: Comece pelo menor app (Reps, 14 arquivos), configure corretamente o MCP e os hooks, escreva um CLAUDE.md completo e depois aplique esses padrões a projetos maiores. Não comece pelo app multiplataforma com 63 arquivos. O investimento em infraestrutura é o mesmo, independentemente do tamanho do projeto — faça isso uma vez em um projeto pequeno e depois copie para todos os outros.

O futuro: A integração nativa de agentes do Xcode 26.3 é o começo, não o fim. O suporte a MCP oferecido pela Apple significa que a cadeia de ferramentas está avançando para um desenvolvimento centrado em agentes. Os desenvolvedores que investirem agora em estruturas de projeto compatíveis com agentes — arquivos CLAUDE.md bem organizados, arquiteturas testáveis e hooks automatizados — ampliarão o retorno desse investimento à medida que as ferramentas evoluírem.

Cartão de referência rápida

Instalação (configuração única)

# 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

Seções essenciais do 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 essenciais

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

Regras de arquitetura

@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+)

Prioridades das ferramentas de 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)

Registro de alterações

Referências