Construindo apps iOS com agentes de IA: o guia do praticante

TL;DR: Três runtimes de agentes agora geram código para iOS: Claude Code CLI com MCP, Codex CLI com MCP, e os agentes nativos Intelligence do Xcode 26.3. Dois servidores MCP (XcodeBuildMCP com 59 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 cobre 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 totalizando 293 arquivos Swift. Agentes se destacam em views SwiftUI, modelos SwiftData, refatoração e diagnóstico de erros de build. Eles falham em modificações de .pbxproj, assinatura de código e depuração visual. A distância entre “o agente escreve Swift” e “o agente publica um app iOS” é preenchida por configuração, não por prompting.

Eu desenvolvo 8 apps iOS com agentes de codificaçã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 iCloud, Live Activities, placar Game Center e alvos multi-plataforma abrangendo iOS, watchOS e tvOS. Cada linha de Swift nesses apps foi escrita por um agente e revisada por mim, ou escrita por mim e refatorada por um agente. Pela minha estimativa, a proporção é de aproximadamente 85/15 a favor do agente.

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

Principais conclusões

Para desenvolvedores iOS novos em agentes de IA:

• Comece com Claude Code CLI + XcodeBuildMCP. É o runtime mais maduro com a cobertura de ferramentas MCP mais ampla. Instale dois comandos, adicione um CLAUDE.md ao seu projeto, e o agente pode 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/ vai poupar horas de recuperação.
• Seu CLAUDE.md é o documento de onboarding do agente. Cada hora investida no CLAUDE.md economiza dez horas corrigindo erros do agente.

Para usuários experientes de agentes adicionando iOS ao seu fluxo de trabalho:

• MCP transforma o ciclo de build iOS. Antes do MCP, agentes escreviam Swift mas não conseguiam verificar se compilava. Com XcodeBuildMCP, o agente escreve código, compila, lê erros estruturados, corrige-os e executa testes — de forma autônoma.
• Três runtimes atendem necessidades diferentes. Claude Code CLI para sessões agênticas profundas, Codex CLI para trabalho em lote headless, agentes nativos do Xcode 26.3 para correções rápidas inline sem sair da IDE.
• A infraestrutura de hooks se transfere diretamente. Seus formatadores PostToolUse, bloqueadores PreToolUse e hooks de test runner existentes funcionam de forma idêntica para projetos iOS com pequenos ajustes de caminhos.

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

• A eficácia do agente escala com a documentação do projeto, não com o tamanho do projeto. Um app de 63 arquivos com um CLAUDE.md detalhado produz resultados melhores do que um app de 14 arquivos sem nenhum.
• O limite do .pbxproj é inegociável. Agentes não conseguem editar arquivos de projeto Xcode de forma confiável. Seu fluxo de trabalho deve prever a adição manual de arquivos aos targets do Xcode.
• Avaliação honesta (ROI): agentes lidam com 70-80% do trabalho de implementação. Os 20-30% restantes — polimento visual, assinatura, ajuste de performance, submissão à App Store — exigem julgamento humano.

Escolha seu caminho

Como usar este guia

Esta é uma referência de mais de 3.000 linhas. Comece onde seu nível de experiência se encaixa:

Sumário

1. O Portfólio: 8 Apps, 293 Arquivos
2. Pré-requisitos
3. Três Runtimes de Agentes para iOS
4. Configuração do MCP: A Configuração Completa
5. Padrões de CLAUDE.md para Projetos iOS
6. Sua Primeira Sessão com Agente
7. O Que Agentes Fazem Bem em iOS
8. O Que Agentes Fazem Mal 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 Multi-Plataforma
13. Fluxos Avançados
14. Estudos de Caso Reais
15. Ciclo de Vida do Projeto com Agentes
16. Configurando Definições de Agentes
17. Padrões de Testes para iOS Assistido por Agentes
18. Gerenciamento de 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

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 iOS, desde um rastreador de treinos com 14 arquivos até um temporizador de meditação multiplataforma com 63 arquivos.

Por que a contagem de arquivos importa: A eficácia do agente está correlacionada com a legibilidade do projeto, não com o tamanho. Return (63 arquivos) produz saídas melhores do agente 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 agentes raciocinarem, independentemente da qualidade da documentação.

Pré-requisitos

Antes de configurar qualquer runtime de agente para desenvolvimento iOS:

Obrigatório: - macOS 15+ (Sequoia) ou macOS Tahoe - Xcode 26.3+ instalado e configurado (contrato de licença aceito, plataformas baixadas) - Pelo menos um runtime de iOS Simulator instalado - Uma conta Anthropic API (para Claude Code) ou 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 padronização de estilo - Familiaridade com o terminal — os três runtimes operam a partir ou se integram com a linha de comando

Verifique sua instalação do Xcode:

# Check Xcode version
xcodebuild -version
# Expected: Xcode 26.3 or later

# 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 em developer.apple.com. Observação: xcode-select --install instala apenas as Command Line Tools, que não incluem o mcpbridge — você precisa do Xcode.app completo.

Três Runtimes de Agente 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 diferentes, padrões de integração MCP diferentes e casos de uso ideais diferentes.

1. Claude Code CLI

O que é: Assistente de codificação agêntico baseado em terminal da Anthropic. Lê seu codebase, executa comandos, modifica arquivos e se conecta a ferramentas externas via MCP.

Integração MCP: Suporte completo tanto para XcodeBuildMCP quanto para o Xcode MCP da Apple. O agente descobre ferramentas via protocolo MCP e as invoca com parâmetros estruturados. 59 + 20 ferramentas entre os dois servidores.

Configuração:

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

# Add XcodeBuildMCP (59 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

Melhor para: Sessões de implementação profundas — construir novos recursos, refatorar em múltiplos arquivos, depurar problemas complexos, executar loops de compilar-testar-corrigir de forma autônoma. A janela de contexto de 1M tokens do Claude Code (com Opus 4.6) permite que o agente mantenha a maioria dos projetos iOS de pequeno a médio porte na memória de trabalho — pela minha experiência, até aproximadamente 50 arquivos dependendo do tamanho dos arquivos.

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 diferença fundamental em relação ao fluxo de trabalho anterior ao MCP: o agente nunca pede para você compilar manualmente ou colar a saída de erros. O loop compilar-erro-corrigir é autônomo.

2. Codex CLI

O que é: Agente de codificação baseado em terminal da OpenAI. Semelhante em conceito ao Claude Code, mas usa modelos da OpenAI (GPT-4o, o3) e tem um modelo de permissões diferente.

Integração MCP: O Codex suporta MCP via o 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 o Codex pelo mesmo comando npx:

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

Melhor para: Operações batch sem interface, integração CI/CD e tarefas onde 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 de janela de contexto e economia de tokens diferentes - Modelo de permissões sandbox-first (mais restritivo por padrão) - Ecossistema MCP menor (menos servidores da comunidade testados) - Sistema de hooks disponível (v0.119.0+), porém 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 o Codex quando quiser diversidade de modelos — ter um segundo agente revisando código escrito pelo primeiro captura classes diferentes de erros. O fluxo de trabalho collab (Claude constrói, Codex revisa) é eficaz para iOS porque padrões SwiftUI que parecem corretos para uma família de modelos podem ter problemas sutis que outra detecta. Shaders Metal e padrões de concorrência se beneficiam especialmente de revisão com dois modelos.

3. Agentes Nativos do Xcode 26.3

O que é: A Apple integrou agentes de codificação com IA diretamente no painel Intelligence do Xcode. A partir do Xcode 26.3, você pode configurar Claude Agent e Codex como provedores de inteligência em Xcode Settings > 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”, insira sua chave Anthropic API
5. Para Codex: Selecione “Codex”, insira sua chave OpenAI API
6. O agente aparece na barra lateral do Intelligence e pode ser invocado inline

Melhor para: Edições rápidas inline, code completion com raciocínio em 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, build targets, configuração de scheme — sem necessidade de ponte MCP.

Limitações comparadas aos agentes CLI: - Sem sistema de hooks — você não pode impor formatação ao salvar ou bloquear escritas 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 de múltiplas etapas não podem ser paralelizadas - Sem configuração de servidor MCP — o agente usa apenas as ferramentas integradas do Xcode

Quando usar agentes nativos do Xcode:

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

Para qualquer coisa que exija compilação, testes, refatoração em múltiplos arquivos ou correção autônoma de erros, use um agente CLI com MCP.

Matriz de Comparação de Runtimes

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

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

MCP (Model Context Protocol) é o que transforma um agente de “escreve Swift e torce para que você compile” para “escreve Swift, compila, lê erros estruturados e os corrige.” Esta seção vai além do post no blog — cobrindo ambos os servidores, todos os métodos de instalação, verificação e a configuração do agente que garante que as ferramentas sejam realmente utilizadas.

XcodeBuildMCP: 59 ferramentas para desenvolvimento iOS headless

XcodeBuildMCP encapsula xcodebuild, xcrun simctl e LLDB em 59 ferramentas MCP estruturadas. Funciona sem o Xcode aberto — todo o ciclo de build-teste-debug opera de forma headless através das ferramentas de linha de comando da Apple.

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 torna o servidor disponível globalmente em todos os projetos. Omita-a para instalação com escopo de projeto (útil se você quer MCP apenas em projetos iOS, não em projetos web).

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

Inventário completo de ferramentas (59 ferramentas em 8 categorias):

As ferramentas mais importantes para o dia a dia:

1. build_sim — Você vai chamar esta ferramenta centenas de vezes. Ela retorna JSON com erros categorizados por arquivo, linha e severidade. O agente lê o erro, navega até o arquivo e corrige sem você precisar 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 simulador sem precisar memorizar flags do xcrun simctl. O agente descobre os runtimes disponíveis e escolhe um dispositivo apropriado.

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

5. debug_attach_sim + debug_stack + debug_variables — Debugging remoto via LLDB. O agente pode definir breakpoints, inspecionar variáveis e percorrer o código passo a passo sem que você precise abrir o debugger.

Apple Xcode MCP: 20 ferramentas fazendo ponte com o Xcode

O servidor MCP da Apple vem com o Xcode 26.3 via xcrun mcpbridge. Ele se comunica com um processo Xcode em execução através de XPC (framework de comunicação entre processos da Apple), expondo estado interno que nenhuma ferramenta CLI consegue 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 Xcode 26.3+ e um processo Xcode em execução. Se o Xcode não estiver aberto, toda chamada MCP através deste servidor vai falhar ou travar. XcodeBuildMCP não tem essa limitação.

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

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

1. DocumentationSearch — Pesquisa na documentação para desenvolvedores da Apple incluindo sessões da WWDC. Mais rápido e confiável que busca na web para perguntas sobre API da Apple. Pergunte “HKQuantityType(.dietaryWater) é válido?” e obtenha uma resposta definitiva direto da fonte.

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

3. RenderPreview — Renderiza previews SwiftUI de forma headless. O agente pode verificar se uma view renderiza sem erros, embora não consiga avaliar a correção visual (o render é retornado como dados, não inspecionado visualmente).

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 utilizadas, potenciais ciclos de retenção e avisos de depreciação que o sistema de build não exibe.

Por que ambos os servidores

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

┌─────────────────────────────────────────────────────────────────┐
│                     MCP TOOL COVERAGE                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  XcodeBuildMCP (59 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 XcodeBuildMCP para: O ciclo de build-teste-debug. Funciona sem o Xcode aberto, consome menos memória do sistema e oferece gerenciamento mais rico de simuladores e dispositivos. Esta é sua ferramenta principal de build.

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

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

Verificação

Após 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 aparecer como “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 seu terminal. Abra o Xcode pelo menos uma vez para aceitar o contrato de licença.
3. Ambos não aparecem: Reinicie o Claude Code (claude em um novo terminal). Servidores MCP registrados durante uma 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 via Bash (saída não estruturada, desperdício de tokens de contexto) ou usar busca na web para documentação da Apple (mais lento, menos confiável).

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

## Build e teste — sempre use MCP

Prefira as ferramentas MCP em vez de comandos shell diretos para TODAS as operações de build:

- **Build**: `build_sim` / `build_device` (NÃO `xcodebuild` via Bash)
- **Teste**: `test_sim` / `test_device` (NÃO `xcodebuild test` via Bash)
- **Simuladores**: `list_sims`, `boot_sim`, `open_sim` (NÃO `xcrun simctl` via Bash)
- **Debug**: `debug_attach_sim`, `debug_stack`, `debug_variables`
- **Documentação Apple**: `DocumentationSearch` (NÃO WebSearch para APIs da Apple)
- **Verificação Swift**: `ExecuteSnippet` (NÃO `swift` via Bash)
- **Previews**: `RenderPreview` para verificação headless de SwiftUI

MCP retorna JSON estruturado. Bash retorna texto não estruturado.
Dados estruturados significam menos tokens consumidos e melhor diagnóstico de erros.

Essa orientação garante que o agente recorra primeiro às ferramentas MCP. Sem ela, você vai observar o agente construindo longos comandos xcodebuild via Bash, consumindo milhares de tokens de contexto para interpretar a saída e, às vezes, identificando incorretamente o erro real.

Padrões de CLAUDE.md para projetos iOS

Seu CLAUDE.md é o arquivo mais importante do projeto para desenvolvimento assistido por agentes. É o documento de onboarding do agente — a diferença entre um novo contratado que leu a documentação de arquitetura e um que está adivinhando.

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

As seções essenciais

Todo CLAUDE.md para iOS precisa dessas seis 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, strict concurrency vs. lenient).

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 após cada nome de arquivo não são decoração. São a documentação de maior alavancagem que você pode escrever. Quando o agente está decidindo onde adicionar um novo recurso, essas anotações o guiam até o arquivo correto na primeira tentativa, em vez de precisar ler todos os arquivos para entender o layout do projeto.

Anti-padrã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:

xcodebuild -scheme Return -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test

Run tvOS tests:

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 tornam explícitos os nomes dos schemes e destinations.

#### 4. Padrões e regras principais

```markdown

## 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 de padrões, o agente às vezes 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 isso / às vezes use aquilo).

6. Contexto específico do framework

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

Para apps com 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 com 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 com 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 com 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 mostrando como todas as seis seções funcionam juntas para um app moderadamente complexo. Este é o padrão de CLAUDE.md que eu uso para o Banana List, um app de lista de compras com 53 arquivos, sincronização via 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

## Estrutura de arquivos

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

## Modelos SwiftData

### Relacionamentos
- `GroceryList` possui muitos `GroceryItem` (exclusão em cascata)
- `GroceryItem` pertence a um `GroceryList` (obrigatório)
- `GroceryItem` possui `Category` opcional
- `Category` possui muitos `GroceryItem` (nulificar ao excluir)

### Configuração do container
```swift
@main
struct BananaListApp: App {
    var body: some Scene {
        WindowGroup {
            ListsView()
        }
        .modelContainer(for: [GroceryList.self, GroceryItem.self, Category.self])
    }
}

Padrões de consulta

• Listas: @Query(sort: \GroceryList.name) var lists: [GroceryList]
• Itens ativos: @Query(filter: #Predicate { !$0.isCompleted })
• Por categoria: filtrar em memória após a busca (limitações do predicate do SwiftData)

Build e teste

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

Prefira as ferramentas MCP (build_sim, test_sim) em vez de comandos diretos.

Padrões principais

Observable + SwiftData

• Classes @Model do SwiftData são automaticamente Observable
• NÃO adicione @Observable a classes @Model (redundante, causa avisos)
• Use @Bindable para bindings bidirecionais com propriedades do modelo em formulários
• Use @Query em views, modelContext.fetch() em código fora de views

Sincronização com iCloud

• Automática via integração do SwiftData com CloudKit
• Resolução de conflitos: última escrita vence (padrão do CloudKit)
• Status de sincronização exposto via CloudSyncManager.shared.syncState
• Teste a sincronização executando em dois simuladores com a mesma conta iCloud

Arquitetura do servidor MCP

• Executa como um servidor WebSocket local na porta 8765
• Expõe 6 ferramentas: listAll, getList, createList, addItem, completeItem, deleteItem
• Claude Desktop conecta via configuração MCP em ~/.config/claude-desktop/config.json

Regras

• NUNCA modifique o conteúdo de .pbxproj ou .xcodeproj
• NUNCA altere o esquema do modelo sem atualizar SampleData.swift
• NUNCA use ObservableObject — modelos SwiftData já são Observable
• NUNCA use @StateObject — use @State com classes @Observable
• NUNCA use NavigationView — sempre NavigationStack
• NUNCA adicione a macro @Observable a classes @Model
• SEMPRE use @Bindable para bindings de formulário com propriedades do modelo
• SEMPRE teste alterações de sincronização com iCloud em duas instâncias de simulador

### CLAUDE.md real: Reps (app SwiftData mínimo — 14 arquivos)

Para projetos pequenos, o CLAUDE.md pode ser conciso. Este é o padrão do Reps, um rastreador de treinos com 14 arquivos. Note como mesmo um CLAUDE.md curto cobre todas as seis seções essenciais:

```markdown
# 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 de 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 jogos exigem mais contexto específico do framework. O agente precisa entender o grafo de cena, as categorias de física e a máquina de estados do jogo:

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

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

## Regras

- NUNCA modifique .pbxproj
- NUNCA modifique bitmasks de PhysicsCategory (quebra toda a detecção de colisão)
- NUNCA altere a ordenação z da hierarquia de cena sem entender a ordem de renderização
- NUNCA modifique ShaderTypes.h sem atualizar tanto as referências em Swift quanto em Metal
- Adicione novos inimigos criando subclasses de EnemyShip, não modificando-o
- Pool de projéteis: recicle via removeFromParent() + re-add, nunca aloque novos
- Game Center: sempre verifique isAuthenticated antes de enviar pontuações

CLAUDE.md real: amp97 (Metal + Visualização de Áudio — 41 Arquivos)

Projetos Metal precisam do maior nível de contexto específico de framework porque os agentes não conseguem verificar 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 com o tamanho do projeto

O nível adequado de detalhamento depende da quantidade de arquivos e da complexidade do framework:

| Tamanho do Projeto | Profundidade do CLAUDE.md | Exemplo |
|-------------|----------------|---------|
| **Pequeno (< 20 arquivos)** | Identidade + lista de arquivos + regras | Reps (14 arquivos): padrões básicos de SwiftData, comandos de build, proibições |
| **Médio (20-40 arquivos)** | + Contexto do framework + padrões-chave | TappyColor (30 arquivos): hierarquia de cena SpriteKit, categorias de física, game loop |
| **Grande (40+ arquivos)** | + Diagramas de arquitetura + mapas de relacionamento + info multi-target | Return (63 arquivos): arquitetura cross-platform, diagrama de sincronização de sessão, diferenças por plataforma |
| **Especializado (Metal/GPU)** | + Diagramas de pipeline + definições de tipos compartilhados + layouts de buffer | amp97 (41 arquivos): estágios do render pipeline, struct de uniforms, gerenciamento de buffers |

O custo de documentar demais é quase zero (o agente ignora o que não precisa). O custo de documentar de menos é alto (o agente inventa padrões que conflitam com seu codebase).

### Checklist do 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 de propósito inline
- [ ] Comando de build com scheme e destination corretos
- [ ] Comando de teste com scheme e destination corretos
- [ ] Preferência de MCP anotada ("prefer build_sim over xcodebuild")
- [ ] Regra de @Observable (nunca ObservableObject)
- [ ] Regra de NavigationStack (nunca NavigationView)
- [ ] Proibição de .pbxproj
- [ ] Contexto específico do framework (permissões do HealthKit, relacionamentos SwiftData, hierarquia SpriteKit, pipeline Metal)
- [ ] Guards de disponibilidade de plataforma documentados (#if canImport, #if os)
- [ ] Singletons-chave e padrões compartilhados documentados
- [ ] Limitações conhecidas ou pegadinhas anotadas

---

## Sua primeira sessão com 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.

### Passo 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 fizer referência ao conteúdo do seu CLAUDE.md, verifique se o arquivo está na raiz do projeto (mesmo diretório do `.xcodeproj` ou `Package.swift`).

### Passo 2: Execute um build de verificação

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.

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

### Passo 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 de projeto e provavelmente o corromperia.

---

## O que os agentes fazem bem no iOS

Essas são as tarefas em que os agentes consistentemente produzem resultados corretos e prontos para produção, com revisão humana mínima.

### Views e Modifiers do SwiftUI

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

**Onde os agentes se destacam:**
- Construir novas views a partir de uma descrição ("crie uma tela de configurações com toggles para X, Y, Z")
- Aplicar cadeias de modifiers (`.glassEffect()`, `.sensoryFeedback()`, `.navigationTitle()`)
- Converter entre padrões de layout (VStack para LazyVGrid, List para ScrollView)
- Implementar bindings de formulário com `@Bindable` para modelos SwiftData
- Construir 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 um resultado genérico. "Crie uma SettingsView que siga o padrão existente em SettingsSheet.swift" produz um resultado consistente com sua base de código.

### Modelos e Queries do SwiftData

Os agentes lidam bem com a macro `@Model` do SwiftData, relacionamentos e padrões de `@Query`. A natureza declarativa do framework (similar ao Django ORM ou SQLAlchemy) se encaixa bem nos padrões que o agente já viu em diversas bases de código.

**Onde os agentes se destacam:**
- Definir classes `@Model` com relacionamentos
- Escrever `@Query` com sort descriptors 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 complexas de `#Predicate` (a DSL de predicados do SwiftData tem limitações que o agente nem sempre conhece — documente as 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 são consistentemente de alta qualidade para projetos iOS. O agente entende os padrões do XCTest, métodos de teste assíncronos 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 de teste XCTest bem estruturados com `setUp()` e `tearDown()`, asserções apropriadas e tratamento assíncrono para testes baseados em timer.

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

Os agentes se destacam em refatoração mecânica: extrair views em componentes, converter `ObservableObject` para `@Observable`, migrar de `NavigationView` para `NavigationStack` e aplicar padrões consistentes em múltiplos 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 trabalha metodicamente em cada arquivo, aplica a transformação corretamente e mantém a funcionalidade existente. Esse é 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 que a maioria dos desenvolvedores. O agente lê o JSON de erro, identifica o arquivo e a linha exatos, entende a mensagem de erro e aplica a correção — frequentemente em uma única iteração.

**Erros que os agentes corrigem de forma autônoma:**
- Imports ausentes
- Incompatibilidade de tipos
- Lacunas na conformidade de protocols
- Uso de API depreciada (com substituição)
- Parâmetros obrigatórios de inicializador ausentes
- Violações de controle de acesso

**Erros em que os agentes precisam de ajuda:**
- Resolução ambígua de tipos (múltiplos módulos definem o mesmo tipo)
- Falhas complexas em restrições de generics
- Erros de expansão de macros (o agente não consegue ver a saída expandida da macro)

### Gerenciamento do Simulator

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 através de chamadas estruturadas ao MCP.

---

## O que os agentes fazem mal no iOS

Uma análise honesta de onde os agentes falham. Conhecer esses limites evita frustração e desperdício de tokens.

### Modificações em arquivos .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, listagens de fases de build e associação de targets. É nominalmente legível por humanos, mas praticamente impossível de ser analisado por agentes de IA.

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

**O que acontece quando um agente edita .pbxproj:**
1. A edição parece ter dado certo (o agente reporta "arquivo atualizado")
2. O Xcode se recusa a abrir o projeto ("The project file is corrupted")
3. Você gasta de 15 a 60 minutos recuperando do histórico do git
4. Você aprende a adicionar o hook PreToolUse (veja [Hooks](#hooks-for-ios-development))

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

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

### Edições complexas em Interface Builder / Storyboard

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

**A solução:** Use SwiftUI exclusivamente para novas views. Se o seu projeto tem arquivos legados de Interface Builder, deixe-os como estão e construa a nova UI em SwiftUI.

### Otimização de performance

Agentes escrevem código correto, mas não necessariamente performático. Eles não conseguem fazer profiling do seu app, identificar gargalos ou medir taxas de quadros. Otimização de performance requer:

1. Profiling com Instruments (ferramenta visual, não acessível a agentes)
2. Entendimento das características de GPU/CPU do dispositivo específico
3. Mudanças iterativas orientadas por medições

**Onde isso aparece:**
- Otimização de shaders Metal (o agente escreve Metal válido, mas não consegue medir o tempo de quadro 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 grandes conjuntos de dados)

**A solução:** Use agentes para 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 provisionamento

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 submissão à App Store são fluxos de trabalho fundamentalmente operados por humanos, que envolvem o Apple Developer portal, o Keychain Access e a interface de assinatura 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 seu arquivo de entitlements está correto.

**A solução:** Gerencie toda a assinatura na aba Signing & Capabilities do Xcode. Não peça aos agentes para depurar falhas de assinatura.

### Depuração complexa de shaders Metal

Agentes escrevem Metal Shading Language (MSL) sintaticamente correto, mas não conseguem verificar a saída visual ou depurar problemas do lado da GPU. Shaders Metal executam na GPU — o agente não tem 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 de dados em paralelo
- 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 quadro, ocupação, largura de banda de memória)
- Diagnosticar artefatos visuais (banding, problemas de precisão, espaço de cor incorreto)
- Testar em diferentes arquiteturas de GPU (diferenças de comportamento entre A-series e M-series)

**A solução:** Teste shaders Metal em dispositivos físicos. A implementação Metal do Simulator não é representativa do comportamento da GPU no dispositivo. Use o GPU Frame Capture do Xcode para depuração visual.

### Verificação visual de layout

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

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

---

## Hooks para desenvolvimento iOS

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

Para contexto sobre o sistema de hooks, consulte o [Claude Code guia de hooks](/blog/claude-code-hooks-tutorial). Esta seção cobre padrões de hooks específicos para iOS.

### PreToolUse: Bloquear escritas no .pbxproj

O hook mais importante em qualquer projeto iOS. Ele bloqueia o agente de escrever em arquivos `.pbxproj`, diretórios `.xcodeproj/` e outros arquivos gerenciados pelo Xcode:

```json
{
  "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 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 executa, detecta o caminho do arquivo, imprime um aviso no stderr e encerra com código 2 (que bloqueia o uso da ferramenta). O agente recebe a mensagem de erro e ajusta sua abordagem.

O que ele captura: - Edições diretas no .pbxproj - Qualquer arquivo dentro dos diretórios .xcodeproj/ ou .xcworkspace/ - Arquivos do Interface Builder (.xib, .storyboard)

PostToolUse: Formatação automática com SwiftFormat

Formate automaticamente arquivos Swift sempre que o agente escrever ou editá-los:

{
  "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 precisa estar instalado (brew install swiftformat).

Por que isso importa: Agentes produzem Swift sintaticamente correto, mas não seguem convenções de formatação de forma consistente. O SwiftFormat normaliza indentação, posicionamento de chaves e ordenação de imports. O hook de formatação automática garante que todo arquivo Swift que o agente tocar seja formatado antes de você vê-lo.

Opcional: Adicione um arquivo de configuração .swiftformat na 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 SwiftLint automaticamente

Se você usa 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 avisos do lint bloqueiem o agente. Se você quiser que violações do lint bloqueiem, remova-o.

PostToolUse: Build automático após alterações

Para loops de feedback agressivos, dispare um build após cada alteração em 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'"
      }
    ]
  }
}

Atenção: Isso é custoso. Cada edição de arquivo dispara um build. Use com moderação — é mais útil durante sessões de depuração onde você quer feedback imediato do build. Para desenvolvimento normal, deixe o agente disparar builds manualmente via MCP quando estiver pronto.

PreToolUse: Bloquear modificações em entitlements

Proteja seu arquivo de entitlements contra modificações acidentais do 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 arquivos de projeto do Xcode (bloqueio PreToolUse) 2. Todo arquivo Swift que o agente tocar é formatado automaticamente (formatação PostToolUse)

Padrões de arquitetura que funcionam com agentes

Nem todas as arquiteturas Swift são igualmente compatíveis com 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 com alvo iOS 26+ devem usar @Observable exclusivamente. Este é tanto o padrão moderno quanto o padrão compatível com 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 é compatível com agentes: O padrão é mais simples (não precisa de anotações @Published), o modelo de propriedade é mais claro (@State em vez de @StateObject vs. @ObservedObject), e os agentes produzem menos bugs com ele porque há menos peças móveis.

Documente isso no CLAUDE.md: Mesmo com iOS 26 como alvo, os agentes ocasionalmente revertem para padrões ObservableObject dos seus dados de treinamento. A 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 é iOS 16+ e o único padrão de navegação que você deve usar para código novo. O padrão type-safe navigationDestination(for:) impede que o agente crie links de navegação incorretos.

SwiftData para persistência

Modelos SwiftData são o padrão de persistência mais limpo para 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 trabalhando com SwiftData: 1. 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 em views para dados reativos: @Query var items: [GroceryItem] 4. Use modelContext.fetch() em código fora de views 5. Exclusões de relacionamentos precisam de regras explícitas: .cascade, .nullify, .deny

Concorrência no Swift 6.2

Use concorrência estrita do Swift 6.2 para projetos novos:

// 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 como @MainActor (previne avisos de data race) - Use async/await para todo trabalho assíncrono (sem completion handlers) - Torne value types Sendable para transferências entre actors - Use Task { } em views para inicialização assíncrona - Use nonisolated somente quando houver uma necessidade de performance comprovada por medição

Sistema de design Liquid Glass (iOS 26+)

O iOS 26 introduziu o sistema de design Liquid Glass. Os agentes lidam bem com ele quando recebem orientação explícita:

// 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() em fundos de seções e containers de cards. As barras de navegação adotam automaticamente o material glass no iOS 26. Não recrie manualmente efeitos glass com materiais customizados — use o modificador do sistema.”

Contexto específico por framework

Cada framework da Apple tem considerações específicas para agentes. Esta seção cobre os frameworks usados nos 8 apps.

HealthKit

Apps que utilizam: Return, Water

HealthKit exige tratamento cuidadoso de permissões e guards 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 com HealthKit: - Sempre proteja com HKHealthStore.isHealthDataAvailable() - Nunca assuma autorização — verifique a cada escrita - Use #if canImport(HealthKit) para código multiplataforma (HealthKit não está disponível no tvOS) - Nunca armazene dados de saúde localmente além do que o HealthKit fornece - Inclua tanto NSHealthShareUsageDescription quanto NSHealthUpdateUsageDescription no Info.plist

SpriteKit

Apps que utilizam: TappyColor, Starfield Destroyer

O modelo de scene graph do SpriteKit exige orientação explícita para agentes:

## 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 physics bodies e detecção de contato - Implementar máquinas de estado do jogo - Construir overlays de HUD

Pontos fracos dos agentes com SpriteKit: - Game loops sensíveis a performance (o agente adiciona trabalho desnecessário por frame) - Simulações de física complexas (física customizada supera SKPhysicsBody em precisão) - Ajuste de efeitos de partículas (visual, requer iteração)

Metal

Apps que utilizam: amp97, Water, Starfield Destroyer

Metal é o framework onde os agentes mais enfrentam dificuldades. O modelo de programação GPU é fundamentalmente diferente do Swift no lado da CPU, e os agentes não conseguem verificar a saída 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 para projetos Metal: - A definição da struct Uniforms (compartilhada entre Swift e MSL) - O padrão de configuração do render pipeline state - Índices de buffers e seus propósitos - Quais shaders existem e o que cada um faz - Problemas de precisão conhecidos (half vs. float)

Live Activities

Apps que utilizam: Return

Live Activities exigem configuração específica que os agentes lidam bem uma vez documentada:

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

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

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 está em Shared/, as alterações afetam todas as plataformas. Se um arquivo está em um diretório de plataforma, as alterações são isoladas. Sempre verifique em qual diretório o arquivo está antes de modificá-lo.”

Guards 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 guards #if canImport() ou #if os() ao utilizar frameworks específicos de plataforma. Não assuma que um framework está disponível em todos os targets.”

Adaptação de 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

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

O padrão mais poderoso: forneça ao agente uma especificação de funcionalidade e deixe-o iterar pelos ciclos de build-teste-correção de forma autônoma.

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.