Tworzenie aplikacji iOS z agentami AI: przewodnik dla praktyków

TL;DR: Trzy środowiska uruchomieniowe agentów dostarczają obecnie kod dla iOS: Claude Code CLI z MCP, Codex CLI z MCP oraz natywne agenty Intelligence w Xcode — Agent Claude, Codex, a od Xcode 26.6 także Google Gemini lub dowolny agent Agent Client Protocol (ACP).¹⁷ Dwa serwery MCP (XcodeBuildMCP z 82 narzędziami oraz xcrun mcpbridge firmy Apple z 20 narzędziami) zapewniają agentom ustrukturyzowany dostęp do kompilacji, testów, symulatorów i debugowania. Ten przewodnik omawia rzeczywiste wzorce CLAUDE.md, konfiguracje hooków oraz uczciwie ocenia, co działa, a co się psuje — na podstawie 8 produkcyjnych aplikacji iOS obejmujących łącznie 293 pliki Swift.³² Agenci doskonale radzą sobie z widokami SwiftUI, modelami SwiftData, refaktoryzacją i diagnozowaniem błędów kompilacji. Zawodzą przy modyfikacjach .pbxproj, podpisywaniu kodu i debugowaniu wizualnym. Lukę między „agent pisze Swift” a „agent publikuje aplikację iOS” wypełnia konfiguracja, a nie promptowanie. Od WWDC 2026 (8 czerwca) iOS 27 jest w wersji beta — 10 sierpnia dostępna była beta 5 (24A5408d) — i dodaje frameworki istotne dla agentów (kontrolę wywoływania narzędzi przez Foundation Models, wykonywanie w tle przez App Intents oraz nowe frameworki Core AI i Evaluations), które warto wymienić w kontekście agenta, ponieważ model wytrenowany przed czerwcem 2026 nie będzie ich znał. Xcode 26.6 (2026-06-25, Swift 6.3) jest aktualnym stabilnym toolchainem; beta Xcode 27 (Swift 6.4, SDKy iOS 27) podąża za cyklem iOS 27.¹⁷¹⁸

Zbudowałem 8 aplikacji iOS z użyciem agentów AI do programowania. Nie prototypów — aplikacji dostępnych w App Store, z integracjami HealthKit, shaderami Metal, fizyką SpriteKit, synchronizacją iCloud, Live Activities, rankingami Game Center oraz targetami wieloplatformowymi obejmującymi iOS, watchOS i tvOS. Każda linia Swift w tych aplikacjach została albo napisana przez agenta i przeze mnie sprawdzona, albo napisana przeze mnie i zrefaktoryzowana przez agenta. Według moich szacunków agenci wykonali większość pracy związanej z tworzeniem kodu linia po linii; ja zajmowałem się przeglądem, zakresem oraz elementami wymagającymi ludzkiego osądu (dopracowaniem wizualnym, podpisywaniem, strojeniem wydajności i zgłoszeniem do App Store).

Ten przewodnik jest punktem odniesienia, którego brakowało mi na początku. Obejmuje cały stos: jakiego środowiska uruchomieniowego agenta użyć, jak skonfigurować serwery MCP dla ustrukturyzowanego dostępu do kompilacji, co umieścić w CLAUDE.md, które hooki chronią projekt Xcode przed zniszczeniem przez agenta oraz — co kluczowe — gdzie agenci zawodzą i trzeba przejąć stery.

Najważniejsze wnioski

Dla programistów iOS nowych w świecie agentów AI:

• Zacznij od Claude Code CLI + XcodeBuildMCP. To najbardziej dojrzałe środowisko uruchomieniowe z najszerszym zakresem narzędzi MCP. Wystarczy zainstalować dwa polecenia, dodać CLAUDE.md do projektu, a agent będzie mógł kompilować, testować i debugować bez ręcznego kopiowania komunikatów o błędach.
• Nigdy nie pozwalaj agentowi modyfikować .pbxproj. To najważniejsza zasada. Hook PreToolUse blokujący zapis do .pbxproj i .xcodeproj/ zaoszczędzi wiele godzin odzyskiwania projektu.
• CLAUDE.md jest dokumentem wdrożeniowym dla agenta. Godziny poświęcone na jego przygotowanie zwracają się w każdej sesji agenta pracującej nad projektem.

Dla doświadczonych użytkowników agentów, którzy dodają iOS do swojego workflow:

• MCP zmienia pętlę kompilacji iOS. Przed MCP agenci pisali Swift, ale nie mogli zweryfikować, czy kod się kompiluje. Dzięki XcodeBuildMCP agent pisze kod, kompiluje go, odczytuje ustrukturyzowane błędy, naprawia je i uruchamia testy — autonomicznie.
• Trzy środowiska uruchomieniowe odpowiadają różnym potrzebom. Claude Code CLI do głębokich sesji agentowych, Codex CLI do bezobsługowej pracy wsadowej oraz własne agenty Xcode — które w Xcode 27 przestały być narzędziem do poprawek w linii kodu, zyskując wtyczki, serwery MCP i możliwość sterowania symulatorami.²²
• Infrastruktura hooków jest przenośna. Istniejące formatery PostToolUse, blokery PreToolUse i hooki uruchamiające testy działają identycznie w projektach iOS po niewielkich korektach ścieżek.

Dla liderów zespołów oceniających rozwój iOS wspomagany przez AI:

• Skuteczność agentów skaluje się wraz z dokumentacją projektu, a nie jego rozmiarem. Aplikacja z 63 plikami i szczegółowym CLAUDE.md generuje lepsze wyniki agenta niż aplikacja z 14 plikami bez takiej dokumentacji.
• Granica .pbxproj jest nienegocjowalna. Agenci nie potrafią niezawodnie edytować plików projektu Xcode. Workflow musi uwzględniać ręczne dodawanie plików do targetów Xcode.
• Uczciwy ROI: agenci realizują większość implementacji w dobrze udokumentowanych projektach — co widać na przykładzie 15-plikowej aplikacji TV wydanej po 3 godzinach pracy wspomaganej agentami (studium przypadku poniżej). Pozostała praca — dopracowanie wizualne, podpisywanie, strojenie wydajności i zgłoszenie do App Store — wymaga ludzkiego osądu.

Wybierz swoją ścieżkę

Jak korzystać z tego przewodnika

To materiał referencyjny liczący ponad 3 000 wierszy. Zacznij od miejsca odpowiadającego poziomowi doświadczenia:

Spis treści

1. Portfolio: 8 aplikacji, 293 pliki
2. Wymagania wstępne
3. Trzy środowiska uruchomieniowe agentów dla iOS
4. Konfiguracja MCP: kompletna konfiguracja
5. Wzorce CLAUDE.md dla projektów iOS
6. Pierwsza sesja z agentem
7. W czym agenci są dobrzy w iOS
8. Z czym agenci radzą sobie słabo w iOS
9. Hooki dla rozwoju iOS
10. Wzorce architektury, które działają z agentami
11. Kontekst specyficzny dla frameworków
12. Wzorce wieloplatformowe
13. Zaawansowane workflow
14. Studia przypadków z rzeczywistego świata
15. Cykl życia projektu z agentami
16. Konfigurowanie definicji agentów
17. Wzorce testowania iOS wspomaganego przez agentów
18. Zarządzanie oknem kontekstu w projektach iOS
19. Rozwiązywanie problemów
20. Typowe błędy agentów w iOS i sposoby ich zapobiegania
21. Uczciwa ocena
22. FAQ
23. Karta szybkiej referencji
24. Źródła

Powiązane zasoby

Seria Apple Ecosystem. 21 produkcyjnych wpisów o aplikacjach SwiftUI integrujących się z Apple Intelligence, MCP, Foundation Models, Vision, Core ML oraz stosem frameworków iOS 26. Materiały powstały na podstawie Water, Get Bananas, Return i pozostałej części portfolio 941:

Centrum serii: Apple Ecosystem Series

Agentic Apple (E4):

Frameworki (E2/E3):

Dostarczony kod (E1):

Synteza (E5):

iOS 27 i WWDC 2026: Z czego może teraz korzystać agent

WWDC 2026 (8 czerwca 2026 r.) wprowadziło iOS 27 do wersji beta. Przepływ pracy związany z tworzeniem aplikacji przez agenta opisany w tym przewodniku się nie zmienia: nadal korzysta się z Claude Code, Codex lub agentów Intelligence w Xcode za pośrednictwem MCP, nadal tworzy się plik CLAUDE.md i nadal zabezpiecza operacje destrukcyjne za pomocą hooków. Zmienia się natomiast zakres, względem którego agent tworzy kod. iOS 27 udostępnia kilka nowych frameworków istotnych dla agentów, a praktycznym krokiem jest celowe wskazanie ich agentowi kodującemu, ponieważ model wytrenowany przed czerwcem 2026 r. nie będzie wiedział o ich istnieniu. iOS 26 pozostaje wersją produkcyjną; poniższe elementy należy traktować jako cele podczas tworzenia aplikacji z użyciem wersji beta iOS 27 SDK.

Zakres iOS 27 istotny dla agentów wraz z odnośnikami do szczegółowych omówień:

• Foundation Models zyskał kontrolę nad wywoływaniem narzędzi. GenerationOptions.ToolCallingMode pozwala sterować dla każdego żądania tym, jak agresywnie model działający na urządzeniu wywołuje narzędzia, a framework może zmienić tryb po pierwszym wywołaniu, aby ograniczyć aktywność narzędzi dla żądania. Framework Vision zawiera teraz gotowe OCRTool i BarcodeReaderTool, które można dołączyć do LanguageModelSession bez pisania kodu rozpoznawania. Zobacz Foundation Models w iOS 27: kontrola wywoływania narzędzi.¹²
• App Intents przełamał barierę 30 sekund. LongRunningIntent (za pośrednictwem performBackgroundTask(options:operation:), co wymaga raportowania postępu) wydłuża czas działania intentu w tle dla synchronizacji, pracy z plikami i wnioskowania na urządzeniu; SyncableEntity nadaje AppEntity tożsamość między urządzeniami; IndexedEntityQuery pozwala systemowi poprosić zapytanie o naprawę indeksu Spotlight. Zobacz App Intents w iOS 27: działanie w tle, synchronizacja, Spotlight.¹³
• Core AI to nowy framework do uruchamiania modeli na Apple Silicon. Znajduje się poniżej Foundation Models w przypadkach, gdy korzysta się z własnego modelu zamiast modelu systemowego Apple. Zobacz Core AI: uruchamianie modeli na Apple Silicon.¹⁴
• Evaluations to XCTest dla jakości modeli. To nowy framework (macOS 27) do mierzenia jakości wyników modelu jako części zestawu testów — brakujący element potrzebny do wdrażania funkcji AI, które pomógł stworzyć agent. Zobacz Evaluations: XCTest dla jakości modeli.¹⁵
• SwiftData, HealthKit i SwiftUI również się zmieniły. SwiftData dodaje obserwację i historię w iOS 27; HealthKit dodaje strefy treningowe i nowe typy; dodatki SwiftUI w iOS 27 to, jak zwykle, szeroki zakres zmian. Zobacz SwiftData w iOS 27, HealthKit w iOS 27 i Co nowego w SwiftUI dla iOS 27.¹⁶

Narzędziem dla pracy z iOS 27 jest wersja beta Xcode 27. Xcode 27 wydano w wersji beta pierwszego dnia WWDC (8 czerwca, build 27A5194q), a 10 sierpnia dostępna była beta 5 (27A5237l). Zawiera Swift 6.4 oraz SDKy iOS 27 / iPadOS 27 / tvOS 27 / watchOS 27 / macOS 27 / visionOS 27, a także wymaga macOS Tahoe 26.4 lub nowszego.¹⁸ Cztery elementy informacji o wydaniu mają znaczenie dla przepływów pracy agentów: Coding Intelligence zyskuje tryb planu — informacje o wydaniu opisują go poprzez znany problem z paskiem potwierdzenia „Implement the plan?” (178673449), dlatego przed potwierdzeniem lub odrzuceniem planu należy poczekać, aż agent zakończy przesyłanie strumieniowe; narzędzie MCP RenderPreview renderuje teraz grupy Preview (174692209) i może wyświetlać podgląd UI w innej lokalizacji (181040291); narzędzie „Prepare Project for Localization” przeznaczone dla agentów raportuje teraz klucze String Catalog usunięte, ponieważ nie występują już w kodzie źródłowym (179755385); a Address Sanitizer może nie uruchomić się dla celów 27.0, gdy aplikację zbudowano za pomocą Xcode 26.4 lub starszego — do uruchomień ASan należy używać Xcode 26.5+ (178072780).¹⁸ Beta 5 dodaje jeszcze dwa istotne tutaj elementy. Agenci mogą teraz weryfikować aplikacje watchOS, „w tym obracanie i naciskanie Digital Crown oraz naciskanie przycisków bocznego i Action (Apple Watch Ultra)” (181147968) — po raz pierwszy agenci Apple mogą obsługiwać fizyczne elementy sterujące aplikacji zegarka, co częściowo zamyka lukę w weryfikacji wizualnej udokumentowaną w tym przewodniku. Apple zaprezentowało również serwer MCP, który nie wymaga już otwartego Xcode; zobacz poniższą sekcję dotyczącą serwera MCP Apple.²² Narzędzia MCP nadrobiły też zaległości wobec wersji beta: XcodeBuildMCP v2.7.0 (2026-07-23) sprawiło, że jego narzędzia automatyzacji UI działają w pełni z symulatorami Xcode 27 poprzez Device Hub, w tym z uruchamianiem okien symulatora i sterowaniem klawiaturą — przed tym wydaniem automatyzacja UI w czasie działania była niezawodna tylko w przypadku symulatorów Xcode 26, przez co weryfikacja UI sterowana przez agenta w wersji beta iOS 27 wymagała ręcznej pracy.²¹

Wniosek dla operatora jest taki sam jak w pozostałej części tego przewodnika: agent pisze kod, ale to Pan/Pani dostarcza wiedzę, której mu brakuje. W przypadku wersji beta iOS 27 oznacza to wskazanie tych frameworków w promptcie lub pliku CLAUDE.md oraz podlinkowanie agentowi dokumentacji Apple, ponieważ w przeciwnym razie model sięgnie po kształt każdego API z iOS 26. Wszystko pozostałe w tym przewodniku (środowiska uruchomieniowe, MCP, hooki, tryby awarii) pozostaje bez zmian dla pracy z iOS 27.

Portfolio: 8 aplikacji, 293 pliki

Zanim przejdziemy do konfiguracji, warto wyjaśnić, z czego czerpie ten przewodnik. To nie są projekty zabawkowe — obejmują pięć frameworków Apple, trzy platformy i pełny zakres złożoności iOS: od 14-plikowego trackera treningów po 63-plikowy wieloplatformowy minutnik medytacyjny.

Dlaczego liczba plików ma znaczenie: Skuteczność agentów koreluje z czytelnością projektu, a nie jego rozmiarem. Return (63 pliki) zapewnia lepsze wyniki agenta niż amp97 (41 plików), ponieważ Return ma szczegółowy plik CLAUDE.md z adnotacjami dotyczącymi plików, diagramami architektury i jasno określonymi wzorcami. Shadery Metal w amp97 są z natury trudniejsze dla agentów do analizy, niezależnie od jakości dokumentacji.

Wymagania wstępne

Przed skonfigurowaniem dowolnego środowiska uruchomieniowego agenta do tworzenia aplikacji iOS:

Termin App Store Connect: Od 2026-04-28 przesyłane aplikacje do App Store Connect muszą być zbudowane przy użyciu Xcode 26 lub nowszego oraz SDKów dla iOS 26, iPadOS 26, tvOS 26, visionOS 26 lub watchOS 26.²⁶ (Wymóg nie dotyczy zgłoszeń dla macOS). Jeśli zespół nadal korzysta z Xcode 16.x, wspomagany przez agenta zestaw narzędzi z tego przewodnika stanowi również mechanizm wymuszający zmianę — żaden z poniższych serwerów MCP i tak nie działa bez Xcode 26.3+.

Wymagane: - macOS 15+ (Sequoia) lub macOS Tahoe (Xcode 26.6 wymaga macOS Tahoe 26.2+; wersja beta Xcode 27 wymaga Tahoe 26.4+) - Zainstalowany i skonfigurowany Xcode 26.3+ (minimalna wersja dla xcrun mcpbridge); zalecany jest Xcode 26.6+. Xcode 26.6 (2026-06-25, build 17F113) jest najnowszą wersją stabilną i wprowadza trzy zmiany Coding Intelligence istotne dla agentów: Google Gemini jako dostawcę asystenta kodowania, obsługę Agent Client Protocol (ACP) oraz renderowanie wariantów — jasny/ciemny motyw, orientacje, rozmiary tekstu — w narzędziu podglądu MCP; naprawia też dwa błędy powodujące awarię tury agenta oraz zawieszanie się, gdy agent zada pytanie, i zawiera Swift 6.3 wraz z SDKami generacji iOS 26.5.¹⁷ Ulepszenia przepływu pracy z 26.5 — kolejkowanie wiadomości w asystencie kodowania oraz obsługa pytań doprecyzowujących — a także załączniki obrazów Swift Testing z 26.4, poziom ważności zarejestrowanych problemów, ostrzeżenia o awariach testów UI z crashlogami i ulepszenia edytora String Catalog również pozostają dostępne.²⁷²⁸ Wcześniejsze wersje stabilne: 26.5 (2026-05-11, build 17F42) oraz 26.4.1 (2026-04-16, build 17E202).²⁹ - Co najmniej jedno zainstalowane środowisko uruchomieniowe iOS Simulator - Konto Anthropic API (dla Claude Code) lub konto OpenAI (dla Codex)

Zalecane: - Zainstalowany SwiftFormat (brew install swiftformat) — używany przez hooki formatujące przy zapisie - Zainstalowany SwiftLint (brew install swiftlint) — opcjonalny, ale przydatny do egzekwowania stylu - Znajomość terminala — wszystkie trzy środowiska uruchomieniowe działają z poziomu wiersza poleceń lub integrują się z nim

Zweryfikuj instalację 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")

Jeśli xcrun mcpbridge zwraca „command not found”, potrzebny jest Xcode 26.3 lub nowszy. Należy zainstalować lub zaktualizować Xcode przez App Store albo developer.apple.com. Uwaga: xcode-select --install instaluje wyłącznie Command Line Tools, które nie zawierają mcpbridge — potrzebna jest pełna aplikacja Xcode.app.

Trzy środowiska uruchomieniowe agentów dla iOS

Trzy odrębne środowiska uruchomieniowe mogą pisać, kompilować i testować kod iOS. Nie są wzajemnie wymienne — każde ma inne mocne strony, inne wzorce integracji z MCP oraz inne idealne zastosowania.

1. Claude Code CLI

Czym jest: terminalowy asystent programistyczny oparty na agentach od Anthropic. Odczytuje bazę kodu, wykonuje polecenia, modyfikuje pliki i łączy się z narzędziami zewnętrznymi przez MCP.⁷

**Integracja z MCP: ** Pełna obsługa zarówno XcodeBuildMCP, jak i Apple Xcode MCP. Agent wykrywa narzędzia przez protokół MCP i wywołuje je ze strukturyzowanymi parametrami. Łącznie 82 + 20 narzędzi na obu serwerach.

Konfiguracja:

# 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

Alternatywa — automatyczny instalator xcodebuildmcp init (v2.1.0+, 23 lutego 2026):

Jeśli woli Pan/Pani pominąć ręczne połączenie z MCP, XcodeBuildMCP v2.1.0+ zawiera podpolecenie init, które automatycznie wykrywa Claude Code, Cursor lub Codex i w jednym kroku instaluje umiejętności agenta oraz konfigurację MCP:

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

Flagi: --print (zapisuje konfigurację do stdout dla nieobsługiwanych klientów), --uninstall (usuwa). Proszę pominąć tę opcję, jeśli zależy Panu/Pani na wyraźnej kontroli nad tym, które serwery MCP są podłączone i w jakim zakresie; ręczne wywołania claude mcp add powyżej to umożliwiają.³⁰

Najlepsze zastosowanie: intensywne sesje implementacyjne — tworzenie nowych funkcji, refaktoryzacja obejmująca wiele plików, debugowanie złożonych problemów, autonomiczne uruchamianie pętli kompilacja-test-poprawka. Okno kontekstowe Claude Code o wielkości 1M (z Opus 5) oznacza, że agent może utrzymywać w pamięci roboczej większość małych i średnich projektów iOS — z mojego doświadczenia wynika, że do około 50 plików, zależnie od ich rozmiaru.²⁵

Typowa sesja:

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]

Kluczowa różnica względem przepływu pracy sprzed MCP: agent nigdy nie prosi o ręczne zbudowanie projektu ani wklejenie komunikatów błędów. Pętla kompilacja-błąd-poprawka działa autonomicznie.

2. Codex CLI

Czym jest: terminalowy agent programistyczny OpenAI. Jest podobny koncepcyjnie do Claude Code, ale uruchamia modele Codex OpenAI i ma inny model uprawnień. Obecna oferta obejmuje GPT-5.6 Sol (flagowy, najsilniejszy w złożonym programowaniu), GPT-5.6 Terra (zrównoważony, domyślny model na co dzień) oraz GPT-5.6 Luna (szybki i najtańszy), a także GPT-5.3 Codex Spark jako tekstową wersję zapoznawczą do badań. GPT-5.4 i GPT-5.4-mini przestaną być dostępne w Codex 31 sierpnia 2026 — należy odpowiednio przenieść ich konfiguracje do Terra i Luna.²³

**Integracja z MCP: ** Codex obsługuje MCP przez polecenie codex mcp add. Apple Xcode MCP działa bezpośrednio:

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

XcodeBuildMCP również działa z Codex za pośrednictwem tego samego polecenia npx:

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

Najlepsze zastosowanie: bezobsługowe operacje wsadowe, integracja CI/CD oraz zadania, w których potrzebna jest druga opinia od innej rodziny modeli. Tryb sandbox Codex uruchamia kod w izolowanych środowiskach, co jest przydatne przy destrukcyjnych operacjach, takich jak uruchamianie zestawów testów modyfikujących stan.

Kluczowe różnice względem Claude Code: - Używa modeli OpenAI zamiast modeli Claude - Inne rozmiary okna kontekstowego i ekonomia tokenów - Model uprawnień oparty przede wszystkim na sandboxie (domyślnie bardziej restrykcyjny) - Mniejszy ekosystem MCP (przetestowano mniej serwerów społeczności) - System hooków jest dostępny (v0.119.0+), lecz mniej dojrzały niż w Claude Code — mniej typów zdarzeń i brak warunkowego pola if

Kiedy używać Codex zamiast Claude Code w iOS:

Warto użyć Codex, gdy potrzebna jest różnorodność modeli — drugi agent przeglądający kod napisany przez pierwszego wychwytuje inne klasy błędów. Przepływ pracy collab (Claude buduje, Codex dokonuje przeglądu) jest skuteczny w iOS, ponieważ wzorce SwiftUI, które wyglądają poprawnie dla jednej rodziny modeli, mogą zawierać subtelne problemy wykrywane przez inną. Szczególnie na przeglądzie dwóch modeli zyskują shadery Metal i wzorce współbieżności.

3. Natywne agenty Xcode

Czym są: Apple zintegrowało agentów AI do programowania bezpośrednio z panelem Intelligence w Xcode. Od Xcode 26.3 można skonfigurować Claude Agent i Codex jako dostawców inteligencji w Xcode Settings > Intelligence.¹⁰ Xcode 26.6 rozszerza listę: Google Gemini jest teraz dostępny w asystencie programowania (171990272), a Xcode dodaje obsługę Agent Client Protocol (ACP) (178294840) — integracja, która początkowo obejmowała dwóch dostawców, obejmuje obecnie trzech dostawców oraz otwarty protokół pozwalający każdemu zgodnemu z ACP agentowi podłączyć się do panelu Intelligence.¹⁷

Konfiguracja:

1. Otwórz Xcode 26.3+
2. Przejdź do Settings > Intelligence
3. Dodaj nowego dostawcę:
4. Dla Claude: wybierz „Claude Agent”, wprowadź klucz API Anthropic
5. Dla Codex: wybierz „Codex”, wprowadź klucz OpenAI API
6. Dla Gemini: wybierz „Google Gemini” (Xcode 26.6+)
7. Dla pozostałych: połącz agenta zgodnego z ACP (Xcode 26.6+)
8. Agent pojawi się na pasku bocznym Intelligence i będzie można wywoływać go inline

Najlepsze zastosowanie: szybkie edycje inline, uzupełnianie kodu z rozumowaniem na poziomie agenta oraz praca dla deweloperów, którzy wolą nie opuszczać Xcode. Natywna integracja oznacza, że agent ma bezpośredni dostęp do kontekstu projektu Xcode — otwartych plików, celów kompilacji i konfiguracji schematu — bez mostka MCP.

Ograniczenia względem agentów CLI — w Xcode 26.x: - Brak systemu hooków — nie można wymusić formatowania przy zapisie ani blokować zapisów w .pbxproj - Brak wczytywania CLAUDE.md — agent nie odczytuje plików konfiguracji na poziomie projektu - Ograniczona autonomia — agent działa na bieżącym pliku lub zaznaczeniu, a nie w całym projekcie - Brak delegowania podagentów — złożonych, wieloetapowych zadań nie można zrównoleglić - Brak konfiguracji serwera MCP — agent używa wyłącznie wbudowanych narzędzi Xcode

Xcode 27 unieważnia większość tej listy. Od beta 1 (8 czerwca) agenci Xcode są platformą rozszerzeń, a nie asystentem inline:²²

• Wtyczki: „Agents in Xcode can now be extended with plugins that contain skills, MCP servers, and ACP agent configurations. Skills are invokable as slash commands with completion support.” (178289210) — zatem ograniczenia „wyłącznie wbudowane narzędzia” i „brak konfiguracji MCP” już nie obowiązują.
• Sterowanie symulatorem: agenci „can now boot simulators, install and launch apps, synthesize touch events, and capture screenshots to verify UI behavior” (175179787), a od beta 5 mogą sterować wejściami sprzętowymi watchOS (181147968).
• Dostęp do debuggera: serwer Xcode MCP zyskał narzędzia do manipulowania stanem uruchomienia, odczytywania konsoli debuggera, przełączania schematów i miejsc uruchomienia oraz sprawdzania lub modyfikowania „build settings, compiler flags, entitlements, and Info.plist keys” (176935844).
• Warstwa zabezpieczeń systemu plików, która „monitors and controls filesystem access by coding agents and any processes they spawn” (178289431), a także pierwszorzędne planowanie (172857081) i wgląd w projekt obejmujący awarie, zawieszenia, zużycie energii oraz problemy z uruchomieniem (177568662).

Jedno ostrzeżenie wynikające bezpośrednio z 176935844: agenci Xcode mogą teraz edytować ustawienia kompilacji, uprawnienia i klucze Info.plist. Ochrona .pbxproj, którą ten przewodnik tworzy za pomocą hooka PreToolUse, nie obowiązuje wewnątrz Xcode, ponieważ hook znajduje się w konfiguracji agenta CLI, a nie Apple. Jeśli ten hook stanowi siatkę bezpieczeństwa, należy pamiętać, że nie ma on żadnej kontroli nad panelem Intelligence.

Kiedy używać natywnych agentów Xcode:

Do szybkich, ograniczonych edycji, gdy przełączanie się do terminala stanowi narzut. „Dodaj właściwość obliczaną do tego modelu”. „Napisz test jednostkowy dla tej funkcji”. „Zrefaktoryzuj ten widok, aby używał @Observable”. Są to zadania dotyczące jednego lub dwóch plików i niewymagające cyklu kompilacja-test.

Do wszystkiego, co wymaga kompilowania, testowania, refaktoryzacji wielu plików lub autonomicznego korygowania błędów, należy użyć agenta CLI z MCP.

Macierz porównawcza środowisk uruchomieniowych

Rekomendacja: Claude Code CLI warto używać jako podstawowego środowiska uruchomieniowego. Natywne agenty Xcode sprawdzą się przy szybkich edycjach inline. Codex CLI warto wykorzystywać do przeglądów i operacji wsadowych. Te trzy rozwiązania się uzupełniają, a nie konkurują ze sobą.

Konfiguracja MCP: kompletna konfiguracja

MCP (Model Context Protocol) zmienia agenta z „pisze Swift i liczy, że aplikacja się zbuduje” w agenta, który „pisze Swift, buduje aplikację, odczytuje ustrukturyzowane błędy i je naprawia”.² Ta sekcja omawia temat szerzej niż wpis na blogu¹¹ — obejmuje oba serwery, wszystkie metody instalacji, weryfikację oraz konfigurację agenta, która zapewnia, że narzędzia są rzeczywiście używane.

XcodeBuildMCP: 82 narzędzia do bezgłowego tworzenia aplikacji iOS

XcodeBuildMCP opakowuje xcodebuild, xcrun simctl i LLDB w 82 ustrukturyzowane narzędzia MCP (deklarowany zestaw narzędzi, potwierdzony jako niezmieniony od v2.6.2 do v2.7.0), pogrupowane w 12 kategorii przepływu pracy.³¹⁹²¹ Kanonicznym miejscem projektu jest organizacja GitHub getsentry — Sentry go utrzymuje, a pierwotny adres URL cameroncooke/XcodeBuildMCP przekierowuje teraz tam, co ma znaczenie, gdy starsze opracowania cytują dawny adres.²¹ Działa bez uruchomionego Xcode — cały cykl budowania, testowania i debugowania odbywa się bez interfejsu graficznego za pomocą narzędzi wiersza poleceń Apple. Warto znać dwie kwestie dotyczące zestawu narzędzi: domyślna sesja stdio udostępnia około dwóch tuzinów narzędzi przepływu pracy z symulatorem, a pozostałe pozostawia poza kontekstem agenta — aby załadować więcej, należy ustawić XCODEBUILDMCP_ENABLED_WORKFLOWS (nazwy kategorii rozdzielone przecinkami z tabeli poniżej) — a ten sam silnik jest dostarczany jako CLI (xcodebuildmcp tools zgłasza 100 poleceń, z czego 72 są kanoniczne), jeśli potrzebne są identyczne operacje bez MCP.⁹

Opcje instalacji:

# 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

Flaga -s user udostępnia serwer globalnie we wszystkich projektach. Należy ją pominąć przy instalacji ograniczonej do projektu (przydatne, jeśli MCP ma być dostępny wyłącznie w projektach iOS, a nie webowych).

Zmienna środowiskowa -e XCODEBUILDMCP_SENTRY_DISABLED=true wyłącza telemetrię raportów awarii. XcodeBuildMCP domyślnie zawiera Sentry, które wysyła dane o błędach, w tym ścieżki plików. Należy zrezygnować, chyba że chce się przekazywać diagnostykę do projektu.¹

Zestaw narzędzi (82 narzędzia w 12 kategoriach przepływu pracy — reprezentatywne narzędzia w każdej kategorii):

Narzędzia najważniejsze w codziennej pracy:

1. build_sim — Będzie Pan/Pani wywoływać je setki razy. Zwraca JSON z błędami sklasyfikowanymi według pliku, wiersza i wagi. Agent odczytuje błąd, przechodzi do pliku i go naprawia bez żadnej interwencji.

2. test_sim — Zwraca wyniki dla każdej metody testowej. Agent dokładnie wie, który test nie przeszedł i dlaczego, a nie tylko że „testy nie przeszły”.

3. list_sims + boot_sim — Zarządzanie symulatorem bez zapamiętywania flag xcrun simctl. Agent wykrywa dostępne środowiska wykonawcze i wybiera odpowiednie urządzenie.

4. discover_projs + list_schemes — Analiza projektu. Agent nie musi zgadywać nazwy schematu ani struktury obszaru roboczego.

5. debug_attach_sim + debug_stack + debug_variables — Zdalne debugowanie LLDB. Agent może ustawiać punkty przerwania, sprawdzać zmienne i krokowo wykonywać kod bez otwierania debugera.

Co zmieniło v2.6.0 (2026-06-01) — automatyzacja UI w czasie działania:

Wydanie v2.6.0 przebudowało automatyzację UI wokół kontekstu wielokrotnego użytku zamiast jednorazowych zrzutów ekranu.¹⁹ snapshot_ui zwraca teraz stabilne odwołania do elementów i hash ekranu oraz przyjmuje sinceScreenHash, dzięki czemu agent może pominąć pełny zrzut, gdy ekran się nie zmienił. Trzy nowe narzędzia domykają ten cykl: wait_for_ui odpytyje aż do spełnienia predykatu (istnienie, stan włączenia, fokus, widoczny tekst lub ustalony układ), zamiast aby agent zgadywał za pomocą opóźnień; batch wykonuje sekwencję działań na odwołaniach do elementów w jednym wywołaniu; drag wykonuje gesty przeciągania po odwołaniach do elementów dla arkuszy i przewijania list. type_text zyskało replaceExisting, aby zastępować wartość pola zamiast ją dopisywać, potencjalne kontrolki są klasyfikowane na podstawie danych dostępności, a ustrukturyzowane wyniki zawierają teraz wskazówki nextSteps (schematy wyników zostały w tym wydaniu podniesione do wersji v2; od tego czasu v2.7.0 przeniosło wyniki budowania/testów do schemaVersion: 3 — patrz niżej). Należy ustawić XCODEBUILDMCP_HEADLESS_LAUNCH=true, aby uruchamiać aplikacje w tle bez przejmowania fokusu macOS — to różnica między sesją agenta, którą można pozostawić uruchomioną, a sesją stale wysuwającą okno Simulator na pierwszy plan. W deterministycznym zadaniu aplikacji pogodowej własny benchmark projektu deklaruje około 70% mniej czasu zegarowego, 68% mniej tokenów i 76% mniej wywołań narzędzi niż przepływ sprzed wersji 2.6 — są to wyniki projektu, a nie niezależny pomiar, lecz mechanizm (pomijanie niezmienionych zrzutów, grupowanie działań na tym samym ekranie) dokładnie odpowiada za zużycie tokenów przez automatyzację UI.¹⁹

Co zmieniło v2.7.0 (2026-07-23) — symulatory Xcode 27, schemat v3, budowanie zgodne ze schematem:

Wydanie v2.7.0 jest mniejsze niż 2.6.0, lecz zawiera jedną niekompatybilną zmianę i jedną zmianę zachowania, które warto znać przed aktualizacją.²¹ Najważniejsze: narzędzia automatyzacji UI działają teraz w pełni z symulatorami Xcode 27 przez Device Hub, w tym z uruchamianiem okna symulatora i sterowaniem klawiaturą — zamyka to lukę, w której automatyzacja UI w czasie działania była niezawodna tylko dla symulatorów Xcode 26. Niekompatybilna zmiana: narzędzia budowania i testowania zwracają teraz ustrukturyzowane wyniki schemaVersion: 3 (od 2.6.0 była to wersja v2) — wszystko, co waliduje lub parsuje wyniki przypięte do wersji 2, wymaga aktualizacji. Zmiana zachowania: narzędzia budowania, testowania, czyszczenia i ścieżki aplikacji respektują teraz konfigurację działania schematu, gdy configuration jest pominięte, zamiast zawsze domyślnie używać Debug — jeśli działanie Test schematu jest ustawione na Release, nieokreślone test_sim buduje teraz Release, dlatego tam, gdzie przepływ pracy zależy od konkretnej konfiguracji, należy przekazywać configuration jawnie. Mniejsze, lecz przydatne zmiany: pakiety przygotowania testów .xctestproducts wielokrotnego użytku pozwalają ponownie uruchamiać testy bez przebudowywania, nadal tworząc świeży .xcresult przy każdym uruchomieniu; domyślne dla sesji extraArgs pozwala ustawić wspólne flagi xcodebuild raz na sesję zamiast powtarzać je przy każdym wywołaniu; nowe polecenie CLI xcodebuildmcp purge raportuje i czyści magazyn obszaru roboczego XcodeBuildMCP (domyślnie działa jako dry-run, usunięcie wymaga wyraźnej zgody); a także naprawiono problem klientów MCP oczekujących 10–17 sekund na udostępnienie narzędzi — przez co krótkie kontrole stanu mogły zgłaszać nieudane połączenie.²¹

Apple Xcode MCP: 20 narzędzi łączących z Xcode

Serwer MCP Apple jest dostarczany z Xcode 26.3 przez xcrun mcpbridge.⁴ Komunikuje się z uruchomionym procesem Xcode przez XPC (mechanizm komunikacji międzyprocesowej Apple), udostępniając stan wewnętrzny, do którego nie ma dostępu żadne narzędzie CLI.⁵

Instalacja:

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

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

Wymaga Xcode 26.3+ oraz uruchomionego procesu Xcode. Jeśli Xcode nie jest otwarty, każde wywołanie MCP przez ten serwer zakończy się niepowodzeniem albo zawiesi się. XcodeBuildMCP nie ma tego ograniczenia.

Xcode 27 beta 5 zapowiada odejście od tego ograniczenia. Apple dodało „nowe środowisko serwera MCP, które działa bez konieczności otwierania obszaru roboczego Xcode”, włączane przez sudo xcrun mcp-server enable i sprawdzane poleceniem xcrun mcp-server status. Ta sama wersja zapoznawcza pozwala przyznać podpisanym agentom trwałe uprawnienia do pracy w drzewie katalogów zamiast ponownego zatwierdzania za każdym razem. W przypadku uruchomień bez nadzoru sudo xcrun mcp-server enable --unsafe-always-allow-all-agents zatwierdza wszystko z góry — Apple wyraźnie określa to jako „niezalecaną konfigurację do użycia przy biurku” i ja również: usuwa krok zatwierdzania, który chroni przed dostępem agenta do katalogów, których nie zamierzano udostępniać. Cały ten obszar należy traktować jako wczesną wersję zapoznawczą i zachować XcodeBuildMCP jako bezgłową ścieżkę, dopóki nie opuści fazy preview.²²

Zestaw narzędzi (20 narzędzi w 5 kategoriach):

Narzędzia unikalne dla Apple MCP (niedostępne w XcodeBuildMCP):

1. DocumentationSearch — Przeszukuje dokumentację programistyczną Apple, w tym sesje WWDC. Jest szybsze i bardziej niezawodne niż wyszukiwanie w sieci w przypadku pytań o API Apple. Proszę zapytać „is HKQuantityType(.dietaryWater) valid?”, aby otrzymać jednoznaczną odpowiedź ze źródła.

2. ExecuteSnippet — Wykonywanie Swift REPL w kontekście projektu. Agent może weryfikować zachowanie API, testować konwersje typów i sprawdzać wyrażenia bez budowania całej aplikacji.

3. RenderPreview — Renderuje podglądy SwiftUI bez interfejsu graficznego. Agent może sprawdzić, czy widok renderuje się bez błędów, choć nie może ocenić poprawności wizualnej (render jest zwracany jako dane, a nie oglądany). Od Xcode 26.6 narzędzie MCP do podglądu (w informacjach o wydaniu 26.6 nazwane „Preview Snapshot”) renderuje warianty — jasny/ciemny wygląd, orientację pionową/poziomą oraz nadpisania rozmiaru tekstu (178831772) — więc agent może zweryfikować widok we wszystkich wyglądach w jednym przebiegu.¹⁷ Wersja beta Xcode 27 rozszerza to dalej: renderowanie grup Preview i podgląd w innej lokalizacji.¹⁸

4. XcodeListNavigatorIssues — Zwraca diagnostykę w czasie rzeczywistym z analizatora Xcode, nie tylko błędy budowania. Wykrywa problemy takie jak nieużywane zmienne, potencjalne cykle retain i ostrzeżenia o wycofaniu, których system budowania nie zgłasza.

Dlaczego oba serwery

Pokrywają się w zakresie budowania i testów, ale zasadniczo się różnią:

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

XcodeBuildMCP należy używać do: Cyklu budowania, testowania i debugowania. Działa bez otwartego Xcode, zużywa mniej pamięci systemowej oraz oferuje bogatsze zarządzanie symulatorami i urządzeniami. To podstawowe narzędzie do budowania.

Apple Xcode MCP należy używać do: Wyszukiwania dokumentacji, weryfikacji Swift REPL, renderowania podglądów SwiftUI i diagnostyki w czasie rzeczywistym. Podczas sesji wymagających tych możliwości należy pozostawić Xcode otwarte.

W praktyce: Używam XcodeBuildMCP do około 90% wywołań MCP, a Apple Xcode MCP do dokumentacji i weryfikacji REPL. Agent domyślnie używa XcodeBuildMCP do budowania i testów, ponieważ jest szybszy (bez narzutu procesu Xcode) i bardziej niezawodny (bez zależności XPC).

Model dwóch serwerów zaczyna się zacierać. XcodeBuildMCP 2.6.x dodaje kategorię proxy xcode-ide: xcode_ide_list_tools wykrywa możliwości MCP dostępne wyłącznie w Xcode-IDE, a xcode_ide_call_tool je wywołuje (pojawiają się pod nazwami xcode_tools_*, np. xcode_tools_documentationsearch), dzięki czemu jedna rejestracja XcodeBuildMCP może teraz sięgać również do narzędzi po stronie IDE Apple.¹⁹ Ograniczenie, które ma znaczenie, pozostaje bez zmian: te wywołania przez proxy nadal wymagają uruchomionego procesu Xcode, dokładnie jak bezpośrednia rejestracja xcrun mcpbridge. Warto zachować zarejestrowane oba serwery, jeśli narzędzia Apple mają być pierwszorzędnymi pozycjami na liście narzędzi agenta; proxy jest najbardziej przydatne, gdy potrzebny jest jeden wpis serwera i tylko okazjonalne odczyty IDE.

Weryfikacja

Po zainstalowaniu obu serwerów należy sprawdzić, czy są połączone:

# List all configured MCP servers
claude mcp list

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

Jeśli serwer pokazuje „Disconnected” lub się nie pojawia:

1. XcodeBuildMCP nie łączy się: Należy upewnić się, że Node.js jest zainstalowany (node --version). Polecenie npx wymaga Node.js 18+.
2. Apple Xcode MCP nie łączy się: Należy upewnić się, że zainstalowano Xcode 26.3+ i że polecenie xcrun mcpbridge działa w terminalu. Należy otworzyć Xcode przynajmniej raz, aby zaakceptować umowę licencyjną.
3. Żaden serwer się nie pojawia: Należy ponownie uruchomić Claude Code (claude w nowym terminalu). Serwery MCP zarejestrowane w trakcie sesji mogą nie pojawić się aż do ponownego uruchomienia.

Uczenie agenta korzystania z MCP

Instalacja serwerów MCP jest konieczna, ale niewystarczająca. Bez wyraźnych wskazówek agent może wrócić do uruchamiania xcodebuild przez Bash (nieustrukturyzowane dane wyjściowe, zmarnowane tokeny kontekstu) albo używać wyszukiwania w sieci dla dokumentacji Apple (wolniej, mniej niezawodnie).

Należy dodać to do CLAUDE.md lub definicji agenta:

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

Ta wskazówka zapewnia, że agent najpierw sięga po narzędzia MCP. Bez niej można zaobserwować, że agent konstruuje długie polecenia xcodebuild przez Bash, zużywa tysiące tokenów kontekstu na analizowanie danych wyjściowych i czasami błędnie identyfikuje rzeczywisty błąd.⁶

Jedna zmiana zachowania XcodeBuildMCP v2.7.0 należy do modelu mentalnego tej sekcji: gdy configuration jest pominięte, narzędzia budowania, testowania, czyszczenia i ścieżki aplikacji respektują teraz konfigurację działania schematu, zamiast zawsze używać Debug.²¹ Większość schematów uruchamia się i testuje w Debug, więc większość projektów nie zauważy żadnej różnicy — lecz jeśli działanie schematu jest ustawione na Release (częste w schematach do profilowania lub konfiguracjach zbliżonych do archiwizacji), nieokreślone build_sim albo test_sim buduje teraz Release. Jeśli CLAUDE.md lub hooki zakładają artefakty Debug, należy wskazać to jawnie w wywołaniu narzędzia albo ustawić raz na sesję za pomocą session_set_defaults.

Długotrwałe budowania: Claude Code uruchamia je teraz w tle

Dwa wydania Claude Code zmieniły to, jak długie budowanie wygląda w trakcie sesji. Od v2.1.212 (2026-07-16) każde wywołanie narzędzia MCP, które trwa dłużej niż 2 minuty, automatycznie przechodzi do tła, aby sesja pozostawała użyteczna; próg można skonfigurować — lub wyłączyć to zachowanie — przez CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS.²⁰ Czyste budowania i pełne uruchomienia testów przez build_sim / test_sim regularnie przekraczają granicę 2 minut w rzeczywistych projektach, dlatego należy oczekiwać, że agent będzie kontynuował pracę — czytał pliki, planował kolejną edycję — gdy budowanie zakończy się w tle zamiast blokować turę. Równie istotna jest towarzysząca poprawka: przed v2.1.206 (2026-07-09) wartość request_timeout_ms dla danego serwera, skonfigurowana przez --mcp-config lub .mcp.json, była ignorowana w świeżych sesjach, więc długie wywołania MCP przekraczały domyślny limit 60 sekund — klasycznym objawem był limit czasu przy pierwszym czystym budowaniu, który „naprawiał się” przy ponownej próbie.²⁰ Jeśli stosowano obejścia dla któregokolwiek z tych zachowań za pomocą skryptów opakowujących lub wstępnie rozgrzanych buildów, można je usunąć.

Wzorce CLAUDE.md dla projektów iOS

CLAUDE.md to najważniejszy plik w projekcie przy tworzeniu oprogramowania z pomocą agentów. To dokument onboardingowy agenta — różnica między nową osobą w zespole, która przeczytała dokumentację architektury, a taką, która zgaduje.

Każdy projekt iOS, który utrzymuję, ma CLAUDE.md. Oto wzorce, które działają, wyprowadzone ze wszystkich 8 aplikacji.

Niezbędne sekcje

Każdy iOS CLAUDE.md potrzebuje tych 6 sekcji. Wszystko inne jest opcjonalne.

1. Tożsamość projektu

# 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

Dlaczego to ma znaczenie: agent musi znać docelową wersję wdrożenia, zanim napisze jakikolwiek kod. Agent celujący w iOS 17 użyje NavigationView i @ObservedObject. Agent celujący w iOS 26 użyje NavigationStack i @Observable. Bundle ID ma znaczenie dla uprawnień i konfiguracji HealthKit. Wersja Swift określa model współbieżności (async/await zamiast callbacków completion handler, ścisła współbieżność zamiast łagodnej).

2. Struktura plików z adnotacjami celu

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

Komentarze inline po każdej nazwie pliku nie są ozdobą. To dokumentacja o największym przełożeniu, jaką można napisać. Gdy agent decyduje, gdzie dodać nową funkcję, te adnotacje prowadzą go do właściwego pliku przy pierwszej próbie, zamiast zmuszać do czytania każdego pliku, by zrozumieć układ projektu.

Antywzorzec: lista plików bez adnotacji. TimerManager.swift nie mówi agentowi nic o tym, czy obsługuje stan, UI, czy jedno i drugie. TimerManager.swift # Timer state, logic, and repeat handling mówi dokładnie, co tam należy, a co nie.

3. Polecenia budowania i testowania

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

Należy uwzględnić surowe polecenia, mimo że agent powinien preferować MCP. Surowe polecenia służą jako dokumentacja awaryjna oraz jasno wskazują nazwy scheme i destination.

4. Kluczowe wzorce i zasady

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

Te wzorce zapobiegają wprowadzaniu przez agenta niespójności. Bez jawnej dokumentacji wzorców agent czasem użyje ObservableObject w jednym pliku i @Observable w innym albo utworzy nowy mechanizm ustawień zamiast użyć istniejącego singletona Settings.shared.

5. Rzeczy, których agent nigdy nie może robić

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

Jawne zakazy są skuteczniejsze niż domyślne oczekiwania. Agent pewniej przestrzega ograniczeń negatywnych niż pozytywnych sugestii, ponieważ są binarne (zrób / nie rób), a nie heurystyczne (preferuj to / czasem użyj tamtego).

6. Kontekst specyficzny dla frameworka

Ta sekcja różni się w zależności od aplikacji. Warto ją uwzględnić dla każdego frameworka, który ma nieoczywistą konfigurację:

Dla aplikacji 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)`

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

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

Dla aplikacji 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.

Rzeczywisty CLAUDE.md: Banana List (SwiftUI + SwiftData + iCloud + serwer MCP)

Oto przykład z adnotacjami pokazujący, jak wszystkie 6 sekcji współdziała w umiarkowanie złożonej aplikacji. To wzorzec CLAUDE.md, którego używam dla Banana List, 53-plikowej aplikacji listy zakupów z synchronizacją iCloud oraz niestandardowym serwerem MCP, który udostępnia dane aplikacji dla 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

Rzeczywisty CLAUDE.md: Reps (minimalna aplikacja SwiftData — 14 plików)

W małych projektach CLAUDE.md może być zwięzły. Oto wzorzec dla Reps, 14-plikowego trackera treningów. Warto zauważyć, że nawet krótki CLAUDE.md obejmuje wszystkie 6 niezbędnych sekcji:

# 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

To 40 linii CLAUDE.md dla 14-plikowego projektu. Ich napisanie zajmuje 10 minut i oszczędza godziny dezorientacji agenta.

Rzeczywisty CLAUDE.md: Starfield Destroyer (SpriteKit + Metal — 32 pliki)

Projekty gier wymagają szerszego kontekstu specyficznego dla frameworków. Agent musi rozumieć graf sceny, kategorie fizyki i maszynę stanów gry:

# 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

Rzeczywisty CLAUDE.md: amp97 (Metal + wizualizacja audio — 41 plików)

Projekty Metal potrzebują najwięcej kontekstu specyficznego dla frameworka, ponieważ agenci nie mogą zweryfikować wyniku wizualnego:

# 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

Skalowanie CLAUDE.md wraz z rozmiarem projektu

Właściwy poziom szczegółowości zależy od liczby plików i złożoności frameworków:

Koszt nadmiernej dokumentacji jest bliski zeru (agent pomija to, czego nie potrzebuje). Koszt niedostatecznej dokumentacji jest wysoki (agent wymyśla wzorce sprzeczne z Państwa codebase).

Lista kontrolna CLAUDE.md

Warto używać tej listy kontrolnej podczas tworzenia lub audytu CLAUDE.md dla projektu iOS:

• [ ] Określono Bundle ID i deployment target
• [ ] Podano wersję Swift i nazwę wzorca architektury
• [ ] Struktura plików zawiera adnotacje celu inline
• [ ] Polecenie budowania ma poprawny scheme i destination
• [ ] Polecenie testowania ma poprawny scheme i destination
• [ ] Odnotowano preferencję MCP („prefer build_sim over xcodebuild”)
• [ ] Reguła @Observable (nigdy ObservableObject)
• [ ] Reguła NavigationStack (nigdy NavigationView)
• [ ] Zakaz .pbxproj
• [ ] Kontekst specyficzny dla frameworka (uprawnienia HealthKit, relacje SwiftData, hierarchia SpriteKit, pipeline Metal)
• [ ] Udokumentowano ograniczenia dostępności platform (#if canImport, #if os)
• [ ] Udokumentowano kluczowe singletony i współdzielone wzorce
• [ ] Odnotowano znane ograniczenia lub pułapki

Pierwsza sesja z agentem

Po skonfigurowaniu MCP i dodaniu CLAUDE.md w projekcie poniżej znajduje się przebieg skutecznej pierwszej sesji. W przykładzie użyto Claude Code CLI, ale ten workflow sprawdza się w dowolnym środowisku uruchomieniowym.

Krok 1: sprawdzenie, czy agent widzi projekt

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.

Jeśli agent nie odwołuje się do treści CLAUDE.md, należy sprawdzić, czy plik znajduje się w katalogu głównym projektu (tym samym folderze co .xcodeproj lub Package.swift).

Krok 2: uruchomienie kontrolnego builda

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.

Krok 3: uruchomienie testów

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.

Krok 4: zaimplementowanie funkcji

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

Uwaga agenta o niemodyfikowaniu .pbxproj wynika z reguł w CLAUDE.md. Bez tej reguły agent próbowałby zmodyfikować plik projektu i prawdopodobnie go uszkodził.

W czym agenci dobrze sprawdzają się w iOS

To zadania, w których agenci konsekwentnie dostarczają poprawne, produkcyjnej jakości rezultaty przy minimalnej weryfikacji przez człowieka.

Widoki i modyfikatory SwiftUI

Agenci bardzo dobrze rozpoznają wzorce deklaratywnej składni SwiftUI. Kompozycja widoków, łańcuchy modyfikatorów, wiązania stanu i layout — te elementy dobrze pasują do danych treningowych agenta, ponieważ zakres API w SwiftUI jest dobrze udokumentowany, a wzorce są bardzo spójne.

W czym agenci są szczególnie skuteczni: - Tworzenie nowych widoków na podstawie opisu („utwórz arkusz ustawień z przełącznikami dla X, Y, Z”) - Stosowanie łańcuchów modyfikatorów (.glassEffect(), .sensoryFeedback(), .navigationTitle()) - Konwertowanie między wzorcami layoutu (VStack na LazyVGrid, List na ScrollView) - Implementowanie wiązań formularzy @Bindable z modelami SwiftData - Tworzenie preview providers z przykładowymi danymi

Przykładowy prompt, który daje bardzo dobre wyniki:

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.

Konkretność ma znaczenie. „Utwórz widok ustawień” daje generyczny rezultat. „Utwórz SettingsView zgodny z istniejącym wzorcem w SettingsSheet.swift” daje wynik spójny z bazą kodu projektu.

Modele i zapytania SwiftData

Agenci niezawodnie obsługują makro @Model w SwiftData, relacje oraz wzorce @Query. Deklaratywny charakter frameworka (podobny do Django ORM lub SQLAlchemy) dobrze odpowiada wzorcom, które agent widział w wielu bazach kodu.

W czym agenci są szczególnie skuteczni: - Definiowanie klas @Model z relacjami - Pisanie @Query z deskryptorami sortowania i predykatami - Implementowanie operacji CRUD przez modelContext - Plany migracji między wersjami schematu - Dane do preview i fixtures testowe

Gdzie agenci potrzebują wskazówek: - Złożone wyrażenia #Predicate (DSL predykatów SwiftData ma ograniczenia, których agent nie zawsze jest świadomy — znane ograniczenia warto udokumentować w CLAUDE.md) - Konfiguracja synchronizacji CloudKit (automatyczna przez SwiftData, ale agent może próbować implementować synchronizację ręcznie)

Testy jednostkowe

Testy jednostkowe pisane przez agentów są konsekwentnie wysokiej jakości w projektach iOS. Agent rozumie wzorce XCTest, asynchroniczne metody testowe oraz cykl życia 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)

Agent tworzy dobrze ustrukturyzowane przypadki testowe XCTest z setUp() i tearDown(), odpowiednimi asercjami oraz obsługą async dla testów opartych na timerach.

Refaktoryzacja i stosowanie wzorców

Agenci świetnie radzą sobie z mechaniczną refaktoryzacją: wydzielaniem widoków do komponentów, konwersją ObservableObject na @Observable, migracją z NavigationView do NavigationStack oraz spójnym stosowaniem wzorców w wielu plikach.

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.

Agent metodycznie przechodzi przez każdy plik, poprawnie stosuje transformację i zachowuje istniejącą funkcjonalność. To praca o wysokiej dźwigni — refaktoryzacja, która ręcznie zajęłaby godzinę, z agentem kończy się w kilka minut z niemal idealną dokładnością.

Diagnozowanie błędów builda przez MCP

Dzięki ustrukturyzowanemu wyjściu MCP agenci diagnozują błędy builda szybciej niż większość programistów. Agent odczytuje JSON błędu, identyfikuje dokładny plik i wiersz, rozumie komunikat błędu i stosuje poprawkę — często w jednej turze.

Błędy, które agenci naprawiają autonomicznie: - Brakujące importy - Niezgodności typów - Braki w zgodności z protokołami - Użycie przestarzałego API (z zamiennikiem) - Brakujące wymagane parametry inicjalizatora - Naruszenia kontroli dostępu

Błędy, przy których agenci potrzebują pomocy: - Niejednoznaczne rozwiązywanie typów (wiele modułów definiuje ten sam typ) - Złożone błędy ograniczeń generycznych - Błędy rozwijania makr (agent nie widzi rozwiniętego wyjścia makra)

Zarządzanie symulatorem

Agenci dobrze obsługują cykl życia symulatora przez MCP:

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

Agent wywołuje list_sims, aby znaleźć dostępne środowiska wykonawcze, boot_sim, aby uruchomić symulator, build_sim, aby zbudować i zainstalować aplikację, oraz screenshot, aby wykonać zrzut ekranu — wszystko przez ustrukturyzowane wywołania MCP.

Z czym agenci radzą sobie słabo w iOS

Uczciwe podsumowanie miejsc, w których agenci zawodzą. Znajomość tych granic zapobiega frustracji i marnowaniu tokenów.

Modyfikacje pliku .pbxproj — NIGDY

To najważniejsza zasada w tworzeniu iOS z użyciem agentów. Plik .pbxproj to konfiguracja projektu Xcode — ustrukturyzowany plik tekstowy z odwołaniami UUID, listami faz budowania i przynależnością do targetów. Formalnie jest czytelny dla człowieka, ale w praktyce agenci AI nie są w stanie go niezawodnie parsować.

Dlaczego agenci zawodzą przy .pbxproj: - Plik używa niestandardowego formatu (nie JSON, nie YAML, nie XML) o znaczeniu zależnym od położenia - Każdy wpis jest powiązany przez UUID — dodanie pliku wymaga spójnej aktualizacji 3–5 różnych sekcji - Jeden źle umieszczony znak uszkadza cały plik projektu - Rozwiązywanie konfliktów scalania w .pbxproj przez Xcode i tak jest kruche — edycje agenta tylko to pogarszają

Co się dzieje, gdy agent edytuje .pbxproj: 1. Edycja wygląda na udaną (agent zgłasza „file updated”) 2. Xcode odmawia otwarcia projektu („The project file is corrupted”) 3. Trzeba poświęcić 15–60 minut na odzyskiwanie z historii git 4. Wtedy staje się jasne, że warto dodać hook PreToolUse (zob. Hooki)

Workflow: Agent tworzy pliki Swift. Następnie należy dodać je ręcznie do projektu Xcode (przeciągnąć do Xcode albo użyć File > Add Files). Zajmuje to 5 sekund na plik i zapobiega godzinom odzyskiwania projektu.

W przypadku projektów Swift Package Manager: To ograniczenie jest mniej dotkliwe. Package.swift to standardowy plik Swift, który agenci mogą edytować niezawodnie. Jeśli projekt korzysta wyłącznie z SPM (bez .xcodeproj), agent może zarządzać pełną strukturą projektu.

Złożone edycje Interface Builder / Storyboard

Jeśli projekt używa Interface Builder (pliki .xib) albo Storyboardów (pliki .storyboard), agenci nie potrafią edytować ich w sensowny sposób. Są to pliki XML z automatycznie generowanymi UUID, odwołaniami do constraints i połączeniami outlets, zaprojektowane do edycji wizualnej, a nie tekstowej.

Ograniczenie ryzyka: Do nowych widoków należy używać wyłącznie SwiftUI. Jeśli projekt ma starsze pliki Interface Builder, najlepiej zostawić je bez zmian i budować nowy UI w SwiftUI.

Optymalizacja wydajności

Agenci piszą poprawny kod, ale niekoniecznie kod wydajny. Nie potrafią profilować aplikacji, identyfikować wąskich gardeł ani mierzyć liczby klatek na sekundę. Optymalizacja wydajności wymaga:

1. Profilowania w Instruments (narzędzie wizualne, niedostępne dla agenta)
2. Zrozumienia charakterystyki GPU/CPU konkretnego urządzenia
3. Iteracyjnych zmian opartych na pomiarach

Gdzie to widać: - Optymalizacja shaderów Metal (agent pisze poprawny Metal, ale nie może zmierzyć czasu klatki GPU) - Złożoność body widoku SwiftUI (agent tworzy głęboko zagnieżdżone widoki, które powodują narzut przy ponownym rysowaniu) - Optymalizacja zapytań Core Data / SwiftData (agent pisze poprawne zapytania, które mogą być wolne na dużych zbiorach danych)

Ograniczenie ryzyka: Agenci sprawdzają się przy implementacji, ale profilowanie należy wykonać ręcznie w Instruments, a następnie poprosić agenta o zastosowanie konkretnych, zidentyfikowanych optymalizacji.

Code signing i provisioning

Agenci nie potrafią debugować problemów z code signing poza odczytaniem komunikatu błędu. Zarządzanie provisioning profile, tworzenie certyfikatów, konfiguracja entitlements i wysyłanie do App Store to zasadniczo workflow wykonywane przez człowieka, obejmujące portal Apple Developer, Keychain Access oraz UI podpisywania w Xcode.

Co widzi agent: „Signing for ‘Return’ requires a development team.”

Czego agent nie widzi: Czy certyfikat wygasł, czy provisioning profile obejmuje urządzenie, czy bundle ID pasuje do App ID albo czy plik entitlements jest poprawny.

Ograniczenie ryzyka: Całe podpisywanie należy obsługiwać w karcie Signing & Capabilities w Xcode. Nie należy prosić agentów o debugowanie błędów podpisywania.

Złożone debugowanie shaderów Metal

Agenci piszą składniowo poprawny Metal Shading Language (MSL), ale nie potrafią zweryfikować wyniku wizualnego ani debugować problemów po stronie GPU. Shadery Metal wykonują się na GPU — agent nie ma mechanizmu informacji zwrotnej, który pozwalałby stwierdzić, czy shader daje poprawny wynik wizualny.

Co agenci mogą zrobić z Metal: - Napisać shadery vertex i fragment na podstawie opisów - Skonfigurować pipeline renderowania Metal w Swift - Tworzyć compute shaders do operacji równoległych na danych - Naprawiać błędy kompilacji w plikach .metal

Czego agenci nie mogą zrobić z Metal: - Zweryfikować poprawności wizualnej wyniku shadera - Debugować wydajności GPU (czas klatki, occupancy, przepustowość pamięci) - Diagnozować artefaktów wizualnych (banding, problemy z precyzją, nieprawidłowa przestrzeń kolorów) - Testować na różnych architekturach GPU (różnice zachowania między A-series a M-series)

Ograniczenie ryzyka: Shadery Metal należy testować na fizycznych urządzeniach. Implementacja Metal w Simulatorze nie odzwierciedla zachowania GPU na urządzeniu. Do debugowania wizualnego warto używać GPU Frame Capture w Xcode.

Weryfikacja układu wizualnego

Agenci nie widzą UI aplikacji. Piszą kod układu SwiftUI i mogą sprawdzić, czy się kompiluje, ale nie potrafią ocenić, czy wynikowy ekran wygląda poprawnie. Widok przesunięty o 10 pikseli od środka, używający niewłaściwej grubości fontu albo mający nakładające się elementy nie generuje błędu budowania i przechodzi wszystkie testy logiki.

Ograniczenie ryzyka: Zmiany UI należy sprawdzać wizualnie. Do weryfikacji układu warto używać SwiftUI Previews w Xcode (albo RenderPreview przez Apple MCP do renderowania headless). W przypadku automatycznego wykrywania regresji wizualnych warto rozważyć snapshot testing z bibliotekami takimi jak swift-snapshot-testing.

Hooki w programowaniu na iOS

Hooki to polecenia powłoki wykonywane deterministycznie w określonych momentach przepływu pracy agenta. Stanowią mechanizm egzekwowania reguł — różnicę między „proszę nie edytować pliku .pbxproj” (sugestią, którą agent może zignorować) a „nie można edytować pliku .pbxproj” (bezwzględną blokadą).

Podstawowe informacje o systemie hooków można znaleźć w przewodniku po hookach Claude Code. W tej sekcji omówiono wzorce hooków przeznaczone dla systemu iOS.

PreToolUse: blokowanie zapisu w plikach .pbxproj

Najważniejszy hook w każdym projekcie iOS. Uniemożliwia agentowi zapisywanie zmian w plikach .pbxproj, folderach .xcodeproj/ oraz innych plikach zarządzanych przez 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'"
      }
    ]
  }
}

Należy umieścić go w pliku .claude/settings.json w katalogu głównym projektu lub w pliku ~/.claude/settings.json, aby zapewnić ochronę globalną.

Jak to działa: Gdy agent próbuje użyć narzędzia Edit lub Write na dowolnym pliku pasującym do wzorca, uruchamia się hook, wykrywa ścieżkę pliku, wyświetla ostrzeżenie w standardowym strumieniu błędów i kończy działanie z kodem 2 (co blokuje użycie narzędzia). Agent otrzymuje komunikat o błędzie i odpowiednio dostosowuje swoje podejście.

Co wykrywa: - Bezpośrednie modyfikacje plików .pbxproj - Dowolne pliki w folderach .xcodeproj/ lub .xcworkspace/ - Pliki Interface Builder (.xib, .storyboard)

PostToolUse: formatowanie podczas zapisu za pomocą SwiftFormat

Automatyczne formatowanie plików Swift po każdym ich zapisaniu lub zmodyfikowaniu przez agenta:

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

Wymagania: SwiftFormat musi być zainstalowany (brew install swiftformat).

Dlaczego ma to znaczenie: Agenci tworzą poprawny składniowo kod Swift, ale nie zawsze przestrzegają konwencji formatowania. SwiftFormat ujednolica wcięcia, rozmieszczenie nawiasów klamrowych i kolejność importów.⁸ Dzięki hookowi formatującemu podczas zapisu każdy plik Swift zmodyfikowany przez agenta zostaje automatycznie sformatowany, zanim zostanie wyświetlony.

Opcjonalnie: można dodać plik konfiguracyjny .swiftformat do katalogu głównego projektu, aby dostosować reguły formatowania:

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

PostToolUse: automatyczne uruchamianie SwiftLint

Jeśli używany jest SwiftLint, należy uruchamiać go po każdej modyfikacji pliku 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'"
      }
    ]
  }
}

Fragment || true zapobiega blokowaniu agenta przez ostrzeżenia narzędzia lint. Aby naruszenia reguł lint blokowały agenta, należy go usunąć.

PostToolUse: automatyczne kompilowanie po zmianach

Aby uzyskać intensywną pętlę informacji zwrotnej, można uruchamiać kompilację po każdej zmianie pliku 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'"
      }
    ]
  }
}

Ostrzeżenie: Jest to kosztowne. Każda modyfikacja pliku uruchamia kompilację. Z tej opcji należy korzystać oszczędnie — jest najbardziej przydatna podczas sesji debugowania, gdy potrzebna jest natychmiastowa informacja zwrotna z kompilacji. Podczas zwykłego programowania warto pozwolić agentowi ręcznie uruchamiać kompilacje za pośrednictwem MCP, gdy będzie gotowy.

PreToolUse: blokowanie modyfikacji uprawnień

Należy zabezpieczyć plik uprawnień przed przypadkowymi modyfikacjami dokonywanymi przez agenta:

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

Połączona konfiguracja hooków dla iOS

Poniżej znajduje się pełna zawartość pliku .claude/settings.json, którego używam we wszystkich projektach 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'"
      }
    ]
  }
}

Zapewnia to dwie gwarancje: 1. Agent nie może uszkodzić plików projektu Xcode (blokada PreToolUse) 2. Każdy plik Swift zmodyfikowany przez agenta jest automatycznie formatowany (formatowanie PostToolUse)

Wzorce architektoniczne dobrze współpracujące z agentami

Nie wszystkie architektury Swift są równie przyjazne dla agentów. Poniższe wzorce zapewniają najlepsze rezultaty, ponieważ są jednoznaczne, spójne i dobrze reprezentowane w danych treningowych.

@Observable (nigdy ObservableObject)

W projektach przeznaczonych dla systemu iOS 26 lub nowszego należy używać wyłącznie @Observable. Jest to zarówno nowoczesny wzorzec, jak i wzorzec przyjazny dla agentów:

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

Dlaczego @Observable jest przyjazne dla agentów: Wzorzec jest prostszy (nie wymaga adnotacji @Published), model własności jest bardziej przejrzysty (@State zamiast wyboru między @StateObject a @ObservedObject), a agenci popełniają przy jego stosowaniu mniej błędów, ponieważ obejmuje mniej współdziałających elementów.

Należy udokumentować to w CLAUDE.md: Nawet gdy docelowym systemem jest iOS 26, agenci sporadycznie wracają do wzorców ObservableObject pochodzących z danych treningowych. Wyraźny zakaz temu zapobiega.

NavigationStack (nigdy 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 jest dostępny od iOS 16 i stanowi jedyny wzorzec nawigacji, którego należy używać w nowym kodzie. Bezpieczny pod względem typów wzorzec navigationDestination(for:) zapobiega tworzeniu przez agenta nieprawidłowych łączy nawigacyjnych.

SwiftData do trwałego przechowywania danych

Modele SwiftData stanowią najprostszy wzorzec trwałego przechowywania danych w projektach tworzonych przy wsparciu agentów:

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

Najważniejsze reguły dla agentów pracujących ze SwiftData: 1. Klasy @Model są automatycznie Observable — nie należy dodawać @Observable 2. Do powiązań formularzy należy używać @Bindable: @Bindable var item: GroceryItem 3. Do reaktywnych danych w widokach należy używać @Query: @Query var items: [GroceryItem] 4. W kodzie poza widokami należy używać modelContext.fetch() 5. Usuwanie relacji wymaga jawnych reguł: .cascade, .nullify, .deny

Współbieżność w Swift 6.2

W nowych projektach należy korzystać ze ścisłej współbieżności Swift 6.2. Jest to wybór trybu języka, a nie wersji zestawu narzędzi — zarówno kompilator Swift 6.3 w stabilnej wersji Xcode 26.6, jak i Swift 6.4 w wersji beta Xcode 27 kompilują te wzorce bez zmian:¹⁷¹⁸

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

Wskazówki dla agentów dotyczące współbieżności: - Wszystkie modele widoków należy oznaczać @MainActor (zapobiega to ostrzeżeniom o wyścigach danych) - Do wszystkich operacji asynchronicznych należy używać async/await (bez procedur obsługi zakończenia) - Typy wartości przekazywane między aktorami należy definiować jako Sendable - Do asynchronicznej inicjalizacji w widokach należy używać Task { } - nonisolated należy stosować wyłącznie wtedy, gdy pomiary wykażą potrzebę poprawy wydajności

System projektowania Liquid Glass (iOS 26+)

W systemie iOS 26 wprowadzono system projektowania Liquid Glass. Agenci dobrze sobie z nim radzą, jeśli otrzymają jednoznaczne wskazówki:

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

Należy uwzględnić w CLAUDE.md: „Używać .glassEffect() w tłach sekcji i kontenerach kart. Paski nawigacyjne w systemie iOS 26 automatycznie przyjmują materiał szklany. Nie odtwarzać ręcznie efektów szkła za pomocą niestandardowych materiałów — używać modyfikatora systemowego”.

Kontekst poszczególnych frameworków

Każdy framework Apple wiąże się ze szczególnymi wymaganiami dotyczącymi agentów. W tej sekcji omówiono frameworki używane w 8 aplikacjach.

HealthKit

Aplikacje, które go używają: Return, Water

HealthKit wymaga starannej obsługi uprawnień i zabezpieczeń zależnych od platformy:

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

Reguły dla agentów dotyczące HealthKit: - Zawsze należy stosować zabezpieczenie HKHealthStore.isHealthDataAvailable() - Nigdy nie należy zakładać, że przyznano uprawnienia — trzeba je sprawdzać przed każdym zapisem - W kodzie wieloplatformowym należy używać #if canImport(HealthKit) (HealthKit nie jest dostępny w tvOS) - Nie należy przechowywać lokalnie danych zdrowotnych poza zakresem zapewnianym przez HealthKit - W pliku Info.plist należy uwzględnić zarówno NSHealthShareUsageDescription, jak i NSHealthUpdateUsageDescription

SpriteKit

Aplikacje, które go używają: TappyColor, Starfield Destroyer

Model grafu sceny w SpriteKit wymaga przekazania agentowi jednoznacznych wskazówek:

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

Mocne strony agentów podczas pracy ze SpriteKit: - Tworzenie sekwencji i grup SKAction - Konfigurowanie brył fizycznych oraz wykrywania kontaktów - Implementowanie maszyn stanów gry - Tworzenie nakładek HUD

Słabe strony agentów podczas pracy ze SpriteKit: - Pętle gry wrażliwe na wydajność (agent dodaje zbędne operacje wykonywane w każdej klatce) - Złożone symulacje fizyczne (niestandardowe rozwiązania fizyczne zapewniają większą precyzję niż SKPhysicsBody) - Dostrajanie efektów cząsteczkowych (ma charakter wizualny i wymaga iteracji)

Metal

Aplikacje, które go używają: amp97, Water, Starfield Destroyer

Metal jest frameworkiem, z którym agenci radzą sobie najgorzej. Model programowania GPU zasadniczo różni się od modelu Swift wykonywanego po stronie CPU, a agenci nie mogą zweryfikować efektu wizualnego.

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

Co należy uwzględnić w CLAUDE.md w projektach korzystających z Metal: - Definicję struktury Uniforms (współdzielonej przez Swift i MSL) - Wzorzec konfiguracji stanu potoku renderowania - Indeksy buforów i ich przeznaczenie - Informacje o istniejących shaderach i działaniu każdego z nich - Znane problemy z precyzją (half a float)

Live Activities

Aplikacje, które go używają: Return

Live Activities wymagają określonej konfiguracji, z którą agenci dobrze sobie radzą po jej udokumentowaniu:

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

Aplikacje, które go używają: 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)

Wzorce wieloplatformowe

Return obejmuje iOS, watchOS i tvOS. Tworzenie aplikacji wieloplatformowych z agentami wymaga jawnej dokumentacji granic między platformami.

Organizacja współdzielonego kodu

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

Zasada dla agentów: „Jeśli plik znajduje się w Shared/, zmiany wpływają na wszystkie platformy. Jeśli plik znajduje się w katalogu danej platformy, zmiany są odizolowane. Przed zmodyfikowaniem pliku zawsze należy sprawdzić, w którym katalogu się znajduje.”

Strażnicy dostępności platform

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

Wskazówki dla agentów: „Podczas korzystania z frameworków specyficznych dla platformy zawsze należy używać strażników #if canImport() lub #if os(). Nie należy zakładać, że framework jest dostępny we wszystkich targetach.”

Dostosowanie UI dla poszczególnych platform

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

Zaawansowane przepływy pracy

Autonomiczne pętle kompilowania, testowania i naprawiania

Najbardziej zaawansowany wzorzec: należy przekazać agentowi specyfikację funkcji i pozwolić mu autonomicznie przechodzić przez cykle kompilowania, testowania i naprawiania.

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.

Agent pisze kod, kompiluje za pomocą MCP, odczytuje ustrukturyzowane błędy, naprawia je i powtarza proces. Funkcja, która wymagałaby 5–10 cykli kompilowania, analizy błędów i napraw przez człowieka, zostaje ukończona w jednej autonomicznej pętli.

Kiedy to działa: Dobrze zdefiniowane funkcje z jasnymi kryteriami akceptacji.

Kiedy to zawodzi: Funkcje o otwartym zakresie („niech to dobrze wygląda”), kod wrażliwy na wydajność lub wszystko, co wymaga weryfikacji wizualnej.

Delegowanie zadań podagentom dla iOS

System podagentów Claude Code sprawdza się w projektach 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.

Podagent analizuje dokumentację i wzorce kodu w oddzielnym oknie kontekstu, zwraca podsumowanie, a główna sesja wdraża rekomendację. Dzięki temu badania nie zużywają podstawowego kontekstu.

Stosowanie wzorców między aplikacjami

Gdy utrzymuje się wiele aplikacji iOS o spójnych wzorcach, agenci mogą przenosić wzorce z jednej aplikacji do drugiej:

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.

Agent odczytuje wzorzec źródłowy, rozumie jego strukturę i tworzy spójną implementację w projekcie docelowym.

Podwójna recenzja agentów (Claude + Codex)

W przypadku krytycznych zmian należy użyć dwóch agentów z różnych rodzin modeli:

1. Claude Code tworzy implementację
2. Codex CLI recenzuje ją w osobnym przebiegu

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

Różne rodziny modeli wykrywają różne klasy błędów. Jest to szczególnie wartościowe w przypadku shaderów Metal i wzorców współbieżności, gdzie łatwo wprowadzić subtelne błędy.

Co podwójna recenzja wykrywa, a pojedyncza pomija:

Podwójna recenzja nie polega na znajdowaniu większej liczby błędów — chodzi o znajdowanie innych błędów. Każda rodzina modeli ma inne tryby błędów w rozpoznawaniu wzorców.

Operacje wsadowe w wielu aplikacjach

Gdy zmiana frameworka lub wzorca wpływa na wiele aplikacji:

# 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

Należy używać ostrożnie. Flaga --dangerously-skip-permissions jest wymagana w trybie nieinteraktywnym, ale omija wszystkie kontrole bezpieczeństwa. Należy upewnić się, że hooki PreToolUse są wdrożone, aby chronić pliki .pbxproj.

Aplikacje korzystające z działających na urządzeniu LLM firmy Apple

Jeśli aplikacja wywołuje framework Foundation Models firmy Apple (np. do podsumowywania offline, klasyfikacji lub generowania danych wyjściowych o ustrukturyzowanym formacie), agenci muszą znać budżet promptu. iOS 26.4 dodał dwa APIs do SystemLanguageModel, które zastąpiły wcześniejsze założenie 4096 tokenów: contextSize (maksymalna liczba tokenów akceptowana przez model w pojedynczej rozmowie) oraz tokenCount(for:) (async throws, zwraca liczbę tokenów, jaką faktycznie kosztuje dany prompt).³¹ Oba mają adnotację @backDeployed(before: iOS 26.4), więc są dostępne we wszystkich wersjach systemu operacyjnego obsługujących FM bez drabiny #available.

Wzorzec, którego agent powinien przestrzegać podczas generowania kodu do konstruowania promptów:

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
}

Jeśli aplikacja korzysta z SystemLanguageModel, należy dodać ten wzorzec do CLAUDE.md. Bez niego agenci wracają do starego hardcode’u 4096 i po cichu obcinają prompty na urządzeniach z większymi oknami kontekstu. Sygnatura async throws w tokenCount(for:) jest kluczowa — agenci, którzy wkleją wersję synchroniczną, nie zdołają skompilować kodu.

Studia przypadków z praktyki

Łatwo dawać ogólne rady. Poniżej znajdują się konkretne scenariusze z 8 aplikacji, które pokazują, jak w praktyce działa tworzenie aplikacji iOS z pomocą agentów — także wtedy, gdy coś się nie udaje.

Studium przypadku 1: Dodanie aplikacji TV do Return (sukces)

Zadanie: Dodać target tvOS do Return, czyli timera medytacyjnego, który miał już wersje na iOS i watchOS. Aplikacja TV wymagała nawigacji za pomocą Siri Remote, interfejsu dla dużego ekranu oraz synchronizacji ustawień z aplikacją iOS.

Co agent zrobił dobrze: - Odczytał istniejący iOS TimerManager i utworzył TVTimerManager, który pomijał Live Activities oraz HealthKit (niedostępne na tvOS) - Utworzył niestandardowe style przycisków dla nawigacji fokusem Siri Remote (TVCapsuleButtonStyle, TVCircleButtonStyle) - Zbudował komponent TVStepper, który zastępuje selektory kołowe (nieużywalne z Siri Remote) przyciskami +/- - Zaimplementował synchronizację ustawień przez App Groups (group.com.941apps.Return) - Dodał zabezpieczenia #if os(tvOS) w całym współdzielonym kodzie - Zbudował i przetestował przez MCP z platform=tvOS Simulator,name=Apple TV

Co trzeba było zrobić ręcznie: - Utworzyć target tvOS w Xcode (File > New > Target > tvOS App) - Dodać nowy target do projektu Xcode (zmiany w .pbxproj) - Skonfigurować uprawnienie App Groups dla targetu TV - Dodać target TV do istniejącego schematu albo utworzyć nowy - Ręcznie dodać wszystkie pliki Swift utworzone przez agenta do targetu TV - Ręcznie przetestować nawigację Siri Remote (agent nie potrafi ocenić zachowania fokusu)

Rezultat: 15 nowych plików Swift, w pełni działająca aplikacja TV, po około 3 godzinach pracy z pomocą agenta. Według moich szacunków agent wykonał mniej więcej 80% prac implementacyjnych; po mojej stronie były elementy wymagające interakcji z UI Xcode (uprawnienia, konfiguracja targetu, flagi funkcji) oraz ręczne testowanie fokusu na prawdziwym Apple TV. Równoważna samodzielna praca w tej bazie kodu — na podstawie podobnych funkcji, które wdrażałem bez agentów — zajęłaby kilka dni.

Studium przypadku 2: Debugowanie shadera Metal w amp97 (częściowe niepowodzenie)

Zadanie: Dodać system intensywności oparty na energii do shadera oscyloskopu. Wizualizacja miała pulsować zgodnie z energią dźwięku.

Co się wydarzyło: 1. Agent napisał poprawną modyfikację shadera Metal, dodając uniform uEnergy i tonemapping HDR 2. Kod skompilował się bez błędów 3. Na urządzeniu wizualizacja była całkowicie biała — współczynnik intensywności był 10 razy za wysoki (3,5 zamiast 0,30) 4. Agent nie mógł zobaczyć białego ekranu, więc nie miał sygnału zwrotnego 5. Zidentyfikowałem problem wizualnie i poprosiłem agenta o obniżenie współczynnika 6. Agent go obniżył, ale cały automat stanów energii był zbyt złożony i psuł wizualizator na inne sposoby 7. Całość wycofano — dwa commity (67959ed i cda4830) zostały wycofane w 869d914

Lekcja: Shadery Metal to najtrudniejsza domena dla developmentu wspieranego przez agentów, ponieważ pętla informacji zwrotnej jest przerwana. Agent może zweryfikować składnię (kompiluje się) i semantykę (typy są poprawne), ale nie może zweryfikować wyniku (czy wygląda dobrze). Każda modyfikacja shadera, która zmienia zachowanie wizualne, wymaga ludzkiej weryfikacji na urządzeniu.

Co zostało potem dodane do CLAUDE.md: „NIE podejmować prób modyfikacji stanu energii w shaderze oscyloskopu bez wyjątkowo ostrożnego testowania współczynników. Poprzednia próba zepsuła wizualizator przez współczynniki 10 razy za wysokie.”

Studium przypadku 3: Migracja SwiftData w Banana List (sukces)

Zadanie: Zmigrować model danych z V1 do V2, dodając pole quantity do GroceryItem oraz nowy model Category z relacjami.

Co zrobił agent: 1. Odczytał istniejące definicje modelu V1 2. Utworzył definicje modelu V2 z nowymi polami i relacjami 3. Napisał GroceryMigrationPlan zgodny z protokołem SchemaMigrationPlan 4. Zaimplementował etap migracji V1toV2: dodał domyślne quantity: 1 oraz category: nil 5. Zaktualizował wszystkie widoki tak, aby obsługiwały nowe pola 6. Zaktualizował SampleData.swift dla podglądów 7. Zbudował projekt i uruchomił testy przez MCP — wszystkie przeszły 8. Utworzył testy jednostkowe specyficzne dla migracji

Klucz: Agent odniósł sukces, ponieważ migracje SwiftData podążają za dobrze zdefiniowanym wzorcem protokołu, szeroko opisanym w dokumentacji Apple i danych treningowych. CLAUDE.md jawnie dokumentował model V1, więc agent rozumiał, z czego wykonuje migrację.

Studium przypadku 4: Synchronizacja sesji iCloud w Return (sukces ze złożonością)

Zadanie: Zaimplementować rejestrowanie sesji medytacyjnych między urządzeniami. Sesje ukończone na Apple TV lub Mac powinny synchronizować się z iPhone w celu zapisu w HealthKit.

Co wygenerował agent:

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

Agent: 1. Utworzył model danych MeditationSession z UUID, datami, czasem trwania, urządzeniem źródłowym i statusem synchronizacji HealthKit 2. Zbudował singleton SessionStore, który zarządza NSUbiquitousKeyValueStore na potrzeby synchronizacji iCloud 3. Zaimplementował rozwiązywanie konfliktów scalania (deduplikacja oparta na UUID) 4. Dodał SessionHistoryView z adaptacjami specyficznymi dla platformy (przeciągnięcie, aby usunąć na iOS, obsługa fokusu na tvOS) 5. Połączył synchronizację HealthKit po stronie iPhone dla sesji z innych urządzeń

Co wymagało iteracji: Początkowa implementacja nie obsługiwała przypadku, w którym aplikacja iPhone uruchamia się w tle (brak powiadomienia pierwszoplanowego dla synchronizacji). Agent potrzebował konkretnej wskazówki: „Użyj NSUbiquitousKeyValueStore.didChangeExternallyNotification, aby wyzwolić synchronizację przy zmianach KV w tle.” Po tej podpowiedzi implementacja była poprawna.

Lekcja: Agenci dobrze radzą sobie z wieloplatformowymi wzorcami architektonicznymi, gdy architektura jest jasno opisana. Wzorzec synchronizacji iCloud nie jest trywialny, ale podąża za udokumentowanym wzorcem Apple, który agent rozumiał. Przypadek brzegowy (synchronizacja w tle) wymagał ludzkiej wiedzy domenowej, ponieważ nie jest dobrze udokumentowany.

Studium przypadku 5: Integracja Game Center w Starfield Destroyer (sukces)

Zadanie: Dodać rankingi i osiągnięcia Game Center do strzelanki kosmicznej.

Co agent zrobił dobrze: - Zaimplementował GKLocalPlayer.local.authenticateHandler w punkcie wejścia aplikacji - Utworzył GameCenterManager z metodami do przesyłania wyników i raportowania osiągnięć - Dodał sprawdzanie stanu uwierzytelnienia przed wszystkimi operacjami Game Center - Elegancko obsłużył tryb offline (gra działa bez Game Center, a wyniki są przesyłane po ponownym połączeniu) - Utworzył definicje osiągnięć odpowiadające systemowi progresji 8 statków

Co wymagało ręcznej pracy: - Utworzenie rankingów i osiągnięć w App Store Connect (portal webowy, niedostępny dla agenta) - Skonfigurowanie uprawnienia Game Center w Xcode - Testowanie z kontem sandbox Game Center (wymaga ręcznego zalogowania na urządzeniu)

Cykl życia projektu z agentami

Rozpoczynanie nowego projektu iOS

Optymalny przepływ pracy przy rozpoczynaniu nowego projektu ze wsparciem agenta:

Faza 1: konfiguracja wykonywana przez człowieka (15-30 minut) 1. Utworzenie projektu Xcode (File > New > Project) 2. Skonfigurowanie podpisywania i uprawnień 3. Ustawienie celu wdrożenia i obsługiwanych miejsc docelowych 4. Dodanie wymaganych entitlements (HealthKit, Game Center itp.) 5. Utworzenie początkowego CLAUDE.md z tożsamością projektu i regułami

Faza 2: implementacja przez agenta (od kilku godzin do kilku dni) 1. Agent tworzy model danych (SwiftData, Core Data lub zwykłe struktury) 2. Agent buduje widoki zgodnie z udokumentowanymi wzorcami 3. Agent implementuje logikę biznesową w klasach manager/service 4. Agent pisze testy jednostkowe 5. Pętla build-test-fix przez MCP (autonomicznie)

Faza 3: integracja wykonywana przez człowieka (30-60 minut) 1. Dodanie plików utworzonych przez agenta do targetów Xcode 2. Zweryfikowanie podpisywania i entitlements 3. Przetestowanie na fizycznym urządzeniu 4. Przegląd układu wizualnego i UX 5. Przesłanie do App Store Connect

Utrzymywanie istniejącego projektu

W przypadku bieżącego rozwoju ustabilizowanych aplikacji:

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]

Skuteczność agenta rośnie wraz z tym, jak dobrze CLAUDE.md odzwierciedla aktualny stan projektu. CLAUDE.md należy aktualizować po dodaniu istotnych nowych funkcji, zmianie wzorców architektonicznych lub wprowadzeniu nowych frameworków.

Kiedy angażować agenta, a kiedy nie

Konfigurowanie definicji agentów

Jeśli używany jest system definicji agentów Claude Code (.claude/agents/), należy utworzyć agenta specyficznego dla 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

Do tego agenta można odwoływać się za pomocą @ios-developer w sesjach Claude Code.

Wzorce testowania dla iOS wspomaganego przez agentów

Agenci piszą znakomite testy jednostkowe, gdy otrzymają jasne wytyczne. Poniżej znajdują się wzorce, które dają najlepsze wyniki.

Organizacja plików testowych

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

Promptowanie testów

Skuteczny prompt testowy:

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.

Dlaczego to działa: Numerowane kryteria akceptacji dają agentowi checklistę. Odwołanie do istniejącego pliku testowego ustanawia wzorzec. Określenie użycia setUp() zapobiega tworzeniu przez agenta splątanego stanu testowego.

Nieskuteczny prompt testowy:

Write tests for TimerManager.

To prowadzi do ogólnych, płytkich testów, które pomijają przypadki brzegowe i mogą nie podążać za wzorcami projektu.

Wzorce testów async

Do testowania kodu opartego na timerach i 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)
    }
}

Kluczowe wzorce, o których agentom trzeba przypominać: - @MainActor przy metodach testowych, które testują klasy @MainActor - async throws dla testów używających Task.sleep lub operacji async - Tolerancja w asercjach opartych na czasie (1,1 sekundy, nie dokładnie 1,0) - Czyste setUp() / tearDown() dla izolacji testów

Snapshot testing

Do wykrywania regresji wizualnych warto rozważyć dodanie 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.

Agenci poprawnie konfigurują snapshot tests, ale nie mogą oceniać obrazów referencyjnych. Człowiek sprawdza początkowe snapshoty, a następnie testy agenta wychwytują regresje wizualne w przyszłych zmianach.

Zarządzanie oknem kontekstu w projektach iOS

Okno kontekstu o pojemności 1 mln tokenów (Opus 5) jest duże, ale nie nieskończone. Projekty iOS wymagają uwzględnienia specyficznych aspektów zarządzania kontekstem.

Koszt tokenów plików iOS

W przypadku projektu zawierającego 50 plików: Odczytanie wszystkich plików zużywa około 50 000–100 000 tokenów — znacznie poniżej limitu 1 mln. Agent może przechowywać cały projekt w kontekście.

W przypadku projektu zawierającego ponad 100 plików: Konieczne staje się selektywne odczytywanie. Agent najpierw odczytuje CLAUDE.md (ze względu na adnotacje dotyczące struktury plików), a następnie w razie potrzeby konkretne pliki. Właśnie dlatego adnotacje dotyczące plików w CLAUDE.md są tak istotne — kierują agenta do właściwych plików bez konieczności odczytywania wszystkiego.

Strategie dla dużych projektów

1. Szczegółowe adnotacje dotyczące plików w CLAUDE.md — Agent odczytuje mapę plików i przechodzi bezpośrednio do odpowiednich plików
2. Delegowanie zadań podagentom — Przekazywanie eksploracji i badań podagentom (czysty kontekst, zwracanie podsumowań)
3. Precyzyjne prompty — „Zmodyfikuj SettingsView.swift, aby dodać nowy przełącznik” jest lepsze niż „zaktualizuj ustawienia”
4. Granice sesji — W przypadku niepowiązanych funkcji warto rozpoczynać nowe sesje zamiast przedłużać trwającą już długo sesję
5. Korzystanie z /compact — Polecenie kompresji Claude Code podsumowuje rozmowę i zwalnia miejsce w kontekście

Efektywność wykorzystania tokenów przez MCP

Jeden z najmocniejszych argumentów przemawiających za MCP: ustrukturyzowane odpowiedzi JSON zużywają znacznie mniej tokenów niż nieprzetworzone dane wyjściowe xcodebuild.

Podczas typowej sesji programistycznej obejmującej 10–20 cykli kompilacji MCP pozwala zaoszczędzić 30 000–150 000 tokenów w porównaniu z nieprzetworzonymi danymi wyjściowymi xcodebuild — tokenów, które pozostają dostępne na właściwe analizowanie kodu.

Rozwiązywanie problemów

„build_sim nie powiodło się — nie znaleziono schematu”

Agent zgaduje nazwę schematu. Rozwiązanie:

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

Można też jawnie dodać nazwę schematu do pliku CLAUDE.md:

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

„xcrun mcpbridge — nie znaleziono polecenia”

Wymagany jest Xcode 26.3 lub nowszy. Wersję można sprawdzić za pomocą xcodebuild -version. Jeśli zainstalowano Xcode 26.3 lub nowszy, ale polecenie nadal nie działa:

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

# Verify
xcrun mcpbridge --help

„Narzędzia MCP nie pojawiają się w Claude Code”

Narzędzia MCP zarejestrowane w trakcie sesji mogą pojawić się dopiero po ponownym uruchomieniu. Należy zamknąć Claude Code i rozpocząć nową sesję:

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

Następnie zweryfikować:

You: List all available MCP tools from XcodeBuildMCP.

„Agent nadal używa xcodebuild przez Bash zamiast MCP”

Agent nie wykrywa narzędzi MCP za pośrednictwem Tool Search. Istnieją dwa rozwiązania:

1. Dodać jednoznaczne wskazówki do CLAUDE.md (zob. Jak nauczyć agenta korzystania z MCP)
2. Wydać bezpośrednie polecenie: „Użyj narzędzia build_sim MCP, a nie xcodebuild przez Bash”

„Kompilacja kończy się powodzeniem, ale agent zgłasza niepowodzenie”

XcodeBuildMCP analizuje dane wyjściowe xcodebuild. Jeśli kompilacja generuje ostrzeżenia przypominające błędy (co często zdarza się w przypadku ostrzeżeń o wycofaniu), agent może błędnie zinterpretować wynik. Należy sprawdzić faktyczne pole stanu w odpowiedzi MCP.

„Symulator zawiesza się podczas uruchamiania”

Należy zakończyć działanie wszystkich symulatorów i uruchomić je ponownie:

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

Można też poprosić agenta:

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

„Agent próbował zmodyfikować .pbxproj pomimo reguł w CLAUDE.md”

Reguły w CLAUDE.md są sugestiami. Hooki wymuszają ich przestrzeganie. Jeśli hook PreToolUse blokujący zapis do .pbxproj nie jest zainstalowany, agent w końcu podejmie próbę modyfikacji. Należy zainstalować 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'"
      }
    ]
  }
}

Reguły mówią „proszę tego nie robić”. Hooki mówią „nie można tego zrobić”.

Często zadawane pytania

Od którego środowiska uruchomieniowego agenta najlepiej zacząć?

Claude Code CLI z XcodeBuildMCP. Zapewnia najgłębszą integrację z MCP, najbardziej dojrzały system hooków oraz okno kontekstowe o pojemności 1 mln tokenów (Opus 5), które może pomieścić całe projekty iOS w pamięci roboczej. Warto zacząć od tego rozwiązania, a wraz z rozwojem procesu pracy dodać Codex do przeglądu kodu oraz natywne agenty Xcode do szybkich edycji bezpośrednio w kodzie.

Czy potrzebne są oba serwery MCP?

Większości programistów sam XcodeBuildMCP zapewni 90% potrzebnych funkcji (kompilowanie, testowanie, obsługa symulatorów i debugowanie). Warto dodać Xcode MCP firmy Apple, jeśli potrzebne jest przeszukiwanie dokumentacji, weryfikacja w Swift REPL lub renderowanie podglądów SwiftUI. Można go dodać w dowolnym momencie — oba serwery działają niezależnie.

Czy agenty mogą utworzyć od podstaw nowy projekt Xcode?

XcodeBuildMCP zawiera narzędzia do tworzenia szkieletów projektów (scaffold_ios_project, scaffold_macos_project), które generują nowe projekty Xcode na podstawie szablonów. W przypadku aplikacji produkcyjnych zalecam jednak utworzenie projektu w Xcode (aby prawidłowo skonfigurować podpisywanie, możliwości aplikacji i targety), a następnie wykorzystanie agentów do całej implementacji kodu. 5 minut poświęconych na kreator nowego projektu w Xcode pozwala uniknąć wielogodzinnego rozwiązywania problemów z konfiguracją projektu wygenerowaną przez agenta.

Jak agenty obsługują zależności Swift Package Manager?

Dobrze. Package.swift jest standardowym plikiem Swift, który agenty potrafią niezawodnie odczytywać i edytować. Dodawanie zależności, aktualizowanie zakresów wersji oraz konfigurowanie targetów działa prawidłowo. Ograniczeniem jest zarządzanie zależnościami opartymi na .xcodeproj (interfejs rozwiązywania pakietów w Xcode) — tym obszarem zarządza Xcode i agenty nie powinny go edytować.

Czy agenty mogą przesłać aplikację do App Store?

Nie. Przesłanie aplikacji do App Store wymaga użycia Organizatora Xcode, profili aprowizacji, zrzutów ekranu, metadanych oraz portalu App Store Connect. Żaden z tych elementów nie jest dostępny przez MCP ani narzędzia wiersza poleceń w sposób umożliwiający agentom skuteczną obsługę. Agenty zajmują się wszystkim aż do utworzenia archiwum — implementacją, testowaniem, naprawianiem błędów i dokumentacją. Ostatni etap przesyłania aplikacji nadal wymaga udziału człowieka.

Agenty mogą jednak pomóc w przygotowaniu metadanych App Store. Można poprosić agenta o napisanie opisu aplikacji, słów kluczowych oraz informacji o nowościach na podstawie ostatnich zmian. To zadanie polegające na generowaniu tekstu, z którym agenty radzą sobie znakomicie.

Jak zarządzać sekretami i kluczami API podczas tworzenia aplikacji iOS z pomocą agentów?

Nigdy nie należy umieszczać sekretów w repozytorium. W przypadku aplikacji iOS łączących się z backendowymi API:

1. Używać plików .xcconfig do konfiguracji właściwej dla poszczególnych środowisk
2. Dodać pliki .xcconfig do .gitignore
3. Odwoływać się do wartości konfiguracyjnych za pośrednictwem ustawień kompilacji Info.plist
4. Udokumentować wymagane sekrety w CLAUDE.md bez podawania ich rzeczywistych wartości

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

Agent wie, że klucze istnieją i gdzie są używane, ale nigdy nie poznaje ich rzeczywistych wartości.

A co z animacjami SwiftUI — czy agenty potrafią je pisać?

Agenty dobrze radzą sobie ze składnią kodu animacji, ale nie mogą wizualnie zweryfikować efektu. Proste animacje (.animation(.spring()), .transition(.slide), withAnimation { }) dają prawidłowe rezultaty. Złożone, wieloetapowe animacje o precyzyjnym harmonogramie wymagają iteracji wizualnych, których agenty nie są w stanie przeprowadzić.

Skuteczne: „Proszę dodać animację sprężynową podczas przechodzenia minutnika między stanami”.

Nieskuteczne: „Proszę sprawić, aby animacja minutnika dawała satysfakcjonujące wrażenie”. (To subiektywne i wymaga dostrojenia wizualnego).

Jak agenty radzą sobie ze wzorcami obsługi błędów?

Bardzo dobrze. Agenty rozumieją wzorce Swift oparte na do/catch, Result i async throws:

Implement error handling for the HealthKit authorization flow:
1. Check HKHealthStore.isHealthDataAvailable() — show alert if not
2. Request authorization — handle denial gracefully
3. On write failure — retry once, then show error
4. All errors should be user-facing with localized descriptions

Agenty tworzą uporządkowaną obsługę błędów z odpowiednimi komunikatami dla użytkownika. Czasami obsługują błędy zbyt szeroko (przechwytując wyjątki, które powinny być propagowane), dlatego należy przeglądać bloki catch.

Czy można używać agentów do wdrażania dostępności?

Częściowo. Agenty prawidłowo dodają etykiety, wskazówki i cechy dostępności:

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

Agenty nie mogą natomiast zweryfikować prawidłowej kolejności nawigacji VoiceOver, przetestować skalowania Dynamic Type ani ocenić współczynników kontrastu kolorów. Do weryfikacji należy użyć Inspektora dostępności w Xcode.

Jak agenty obsługują migrację Core Data (jeśli nie jest używany SwiftData)?

Agenty tworzą mapowania migracji i wersje modeli Core Data, ale ręcznych czynności w Xcode (tworzenia nowych wersji modelu i wybierania bieżącej wersji) nie można zautomatyzować. Jeśli nadal używany jest Core Data zamiast SwiftData, historię wersji modelu należy udokumentować w CLAUDE.md:

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

Jak agenty obsługują podglądy SwiftUI?

Na dwa sposoby: 1. Narzędzie RenderPreview w Xcode MCP firmy Apple renderuje podglądy bez interfejsu graficznego i zwraca wynik. Agent może zweryfikować, czy podgląd kompiluje się i renderuje bez błędów, ale nie może ocenić jego poprawności wizualnej. 2. Weryfikacja przez kompilację za pomocą build_sim potwierdza, że dostawcy podglądów się kompilują. Jeśli podgląd ulegnie awarii podczas działania, kompilacja i tak zakończy się powodzeniem — awaria ujawni się dopiero wtedy, gdy Xcode spróbuje wyrenderować podgląd.

Do wizualnej weryfikacji podglądów nadal potrzebny jest otwarty Xcode.

A co z visionOS i Apple Vision Pro?

Obowiązują te same wzorce. XcodeBuildMCP obsługuje symulatory visionOS, a wzorce architektoniczne (@Observable, NavigationStack, SwiftData) są identyczne. Kod właściwy dla RealityKit (treści 3D, przestrzenie immersyjne, śledzenie dłoni) podlega tym samym ograniczeniom co Metal — agenty mogą napisać poprawny kod, ale nie mogą zweryfikować rezultatu przestrzennego.

Jak duży może być projekt, zanim agenty zaczną mieć trudności?

Czynnikiem ograniczającym jest rozmiar okna kontekstowego. Dzięki oknu Opus 5 o pojemności 1 mln tokenów Claude Code może jednocześnie przechowywać w aktywnej pamięci roboczej około 50–70 plików Swift. W większych projektach agent korzysta z wyszukiwania plików i selektywnego odczytu, aby pracować na fragmentach bazy kodu. Projekty zawierające ponad 100 plików działają bez problemu — agent po prostu odczytuje pliki na żądanie, zamiast przechowywać wszystko w kontekście.

W praktyce ograniczeniem nie jest liczba plików, lecz spójność bazy kodu. Dobrze udokumentowany projekt zawierający 200 plików i szczegółowy CLAUDE.md daje lepsze wyniki niż nieudokumentowany projekt złożony z 30 plików.

Czy do tworzenia aplikacji iOS z pomocą agentów trzeba znać Swift?

Trzeba umieć przeglądać wyniki pracy agenta i podejmować decyzje architektoniczne. Nie trzeba samodzielnie pisać każdego wiersza, ale należy rozumieć Swift na tyle dobrze, aby wychwycić błędne decyzje agenta — zwłaszcza w zakresie współbieżności, zarządzania pamięcią i wzorców właściwych dla poszczególnych frameworków. Agent dziesięciokrotnie wzmacnia posiadane umiejętności, ale ich nie zastępuje.

Jak agenty radzą sobie z konfliktami scalania w plikach Swift?

Agenty niezawodnie rozwiązują konflikty scalania w plikach źródłowych Swift. Standardowe znaczniki konfliktów (<<<<<<<, =======, >>>>>>>) są dobrze rozumiane przez wszystkie środowiska uruchomieniowe agentów. Konflikty scalania w plikach .pbxproj nadal wymagają jednak ręcznego rozwiązania — nie należy prosić agentów o rozwiązywanie konfliktów .pbxproj.

Ile kosztuje korzystanie z agentów podczas tworzenia aplikacji iOS?

W planie Max usługi Anthropic (Opus 5, kontekst 1 mln tokenów) typowa sesja tworzenia aplikacji iOS trwa 30–120 minut i przetwarza 200–800 tys. tokenów. Wywołania narzędzi MCP generują minimalny narzut (ustrukturyzowane odpowiedzi JSON są oszczędne pod względem tokenów w porównaniu z surowymi danymi wyjściowymi kompilacji). Koszt jest porównywalny z używaniem Claude Code w dowolnej innej bazie kodu — tworzenie aplikacji iOS nie jest znacząco droższe ani tańsze niż tworzenie aplikacji internetowych.

Czy można używać agentów w projektach UIKit?

Tak, ale agenty są skuteczniejsze w połączeniu ze SwiftUI. UIKit wymaga większej ilości kodu szablonowego, ma mniej deklaratywną strukturę i często korzysta z plików Interface Builder, których agenty nie mogą edytować. W projekcie UIKit warto rozważyć wykorzystanie agentów do warstwy modelu i logiki biznesowej, pozostawiając ręczną obsługę interfejsu użytkownika, lub stopniowo migrować widoki do SwiftUI.

Jak agenty obsługują lokalizację?

Agenty skutecznie tworzą i edytują pliki .xcstrings (katalogi ciągów Xcode). Mogą dodawać nowe klucze lokalizacyjne, przygotowywać tłumaczenia i zachowywać spójność między językami. Ustrukturyzowany format JSON plików .xcstrings jest przyjazny dla agentów. Agenty radzą sobie również dobrze z plikami .strings (starszym formatem) — format klucz-wartość jest prosty.

Typowe błędy agentów w iOS (i sposoby zapobiegania im)

Poniżej przedstawiono powtarzające się błędy zaobserwowane podczas tysięcy interakcji z agentami w 8 projektach iOS. Dla każdego z nich istnieje strategia zapobiegania.

Błąd 1: Mieszanie wzorców obserwowalności

Co się dzieje: Agent używa @Observable w jednym pliku, a ObservableObject w innym, albo dodaje @Observable do klasy @Model (która już jest obserwowalna).

Zapobieganie: Jednoznaczne reguły w 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

Błąd 2: Tworzenie cykli silnych referencji w domknięciach

Co się dzieje: Agent tworzy domknięcia, które przechwytują self przez silną referencję, zwłaszcza w Timer.publish, NotificationCenter i procedurach obsługi zakończenia.

Zapobieganie: Warto umieścić wzorzec domknięcia w 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

Błąd 3: Ignorowanie wymagań @MainActor

Co się dzieje: Agent tworzy klasy @Observable bez izolacji @MainActor, co powoduje ostrzeżenia dotyczące współbieżności w Swift 6.2 lub awarie w czasie działania, gdy interfejs jest aktualizowany poza głównym wątkiem.

Zapobieganie:

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

Błąd 4: Używanie NavigationLink z domknięciem miejsca docelowego

Co się dzieje: Agent używa przestarzałego wzorca NavigationLink(destination:label:) zamiast bezpiecznego typowo połączenia NavigationLink(value:) i .navigationDestination(for:).

Zapobieganie:

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

Błąd 5: Wpisywanie nazw symulatorów na stałe

Co się dzieje: Agent zapisuje polecenia kompilacji z konkretnymi nazwami symulatorów („iPhone 16 Pro”), które mogą nie istnieć w danym systemie.

Zapobieganie: MCP rozwiązuje ten problem — list_sims wykrywa dostępne symulatory. W 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.

Błąd 6: Tworzenie plików w niewłaściwych folderach

Co się dzieje: Agent tworzy nowy plik widoku w katalogu głównym projektu zamiast w podfolderze Views/ albo umieszcza model w niewłaściwej grupie.

Zapobieganie: Adnotacje dotyczące struktury plików w CLAUDE.md wskazują właściwe miejsce. Dodatkowo:

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

Błąd 7: Nieuwzględnianie dostępności na poszczególnych platformach

Co się dzieje: Agent używa HealthKit we współdzielonym kodzie kompilowanym dla tvOS (gdzie HealthKit jest niedostępny) albo używa ActivityKit w kodzie dla watchOS.

Zapobieganie:

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

Błąd 8: Nadmierne komplikowanie prostych funkcji

Co się dzieje: Agent tworzy protokół, rozszerzenie protokołu, konkretną implementację, fabrykę oraz kontener wstrzykiwania zależności dla rozwiązania, które powinno być 20-wierszową funkcją narzędziową.

Zapobieganie: Warto uwzględnić zasadę prostoty:

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

Uczciwa ocena

Po wydaniu 8 aplikacji iOS z pomocą agentów AI podsumowanie wygląda następująco:

Agenci zrewolucjonizowali: Szybkość implementacji. Zadania, które zajmowały dni, teraz zajmują godziny. Widoki SwiftUI, modele SwiftData, testy jednostkowe i refaktoryzacja — obecnie są tworzone przede wszystkim przez agentów i weryfikowane przez człowieka.

Agenci nie zrewolucjonizowali: Decyzji architektonicznych, projektowania wizualnego, optymalizacji wydajności ani procesu publikacji w App Store. Te obszary nadal wymagają kierowania przez człowieka.

Wzrost produktywności jest rzeczywisty, lecz ma swoje granice. Moja subiektywna ocena obejmująca portfolio 8 aplikacji: w dobrze udokumentowanych projektach, z właściwie skonfigurowanymi MCP i hookami, czas potrzebny na wdrożenie funkcji skraca się 3–5 razy. Wyniku tego nie uzyskano w badaniu z grupą kontrolną; jest to porównanie rzeczywistego czasu realizacji funkcji wspomaganych przez agentów z równoważną samodzielną pracą w tych samych bazach kodu. W projektach bez dokumentacji i hooków poprawa wynosi najwyżej 1,5–2 razy — agent poświęca zbyt dużo czasu na zgadywanie zamiast na tworzenie.³³

Inwestycja, która się zwraca: Czas poświęcony na CLAUDE.md oraz konfigurację hooków i MCP. Każda godzina konfiguracji pozwala zaoszczędzić wiele godzin na poprawianiu błędów agentów. To konfiguracja jest produktem — agent stanowi silnik wykonawczy.

Co mnie zaskoczyło: Jak bardzo serwery MCP zmieniły charakter współpracy. Przed wdrożeniem MCP agenci byli zaawansowanymi edytorami tekstu, które przypadkiem rozumiały Swift. Po wdrożeniu MCP stali się partnerami programistycznymi, którzy piszą kod, kompilują, testują, debugują i wprowadzają kolejne poprawki. Ustrukturyzowana pętla informacji zwrotnej odróżnia agenta, który pisze kod, od agenta, który dostarcza działające oprogramowanie.

Co powiedziałbym sobie z przeszłości: Należy zacząć od najmniejszej aplikacji (Reps, 14 plików), prawidłowo skonfigurować MCP i hooki, przygotować szczegółowy plik CLAUDE.md, a następnie zastosować te wzorce w większych projektach. Nie warto zaczynać od wieloplatformowej aplikacji składającej się z 63 plików. Nakład pracy związany z infrastrukturą jest taki sam bez względu na wielkość projektu — najlepiej zrobić to raz w małym projekcie, a następnie skopiować do wszystkich pozostałych.

Przyszłość: Natywna integracja agentów w Xcode 26.3 to początek, a nie koniec. Wprowadzenie przez Apple obsługi MCP oznacza, że zestaw narzędzi zmierza w stronę tworzenia oprogramowania z agentami na pierwszym planie. Programiści, którzy już teraz zainwestują w struktury projektów zgodne z agentami — uporządkowane pliki CLAUDE.md, testowalne architektury i zautomatyzowane hooki — będą czerpać coraz większe korzyści z tej inwestycji wraz z rozwojem narzędzi.

Skrócona karta referencyjna

Instalacja (konfiguracja jednorazowa)

# 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

Najważniejsze sekcje 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

Najważniejsze hooki

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

Reguły architektury

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

Priorytety narzędzi 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)

Dziennik zmian

Odniesienia