AI 에이전트로 iOS 앱 만들기: 실무자 가이드

TL;DR: 이제 3개의 에이전트 런타임으로 iOS용 코드를 출시할 수 있습니다. MCP를 사용하는 Claude Code CLI, MCP를 사용하는 Codex CLI, 그리고 Xcode의 기본 Intelligence 에이전트인 Claude Agent, Codex, 그리고 Xcode 26.6부터는 Google Gemini 또는 모든 Agent Client Protocol (ACP) 에이전트입니다.¹⁷ 두 개의 MCP 서버(82개 도구를 제공하는 XcodeBuildMCP, 20개 도구를 제공하는 Apple의 xcrun mcpbridge)는 에이전트에 빌드, 테스트, 시뮬레이터, 디버깅에 대한 구조화된 접근 권한을 제공합니다. 이 가이드는 실제 CLAUDE.md 패턴, hook 구성, 그리고 작동하는 부분과 깨지는 부분에 대한 솔직한 평가를 다룹니다. 이는 총 293개의 Swift 파일로 구성된 8개의 프로덕션 iOS 앱에서 얻은 내용입니다.³² 에이전트는 SwiftUI 뷰, SwiftData 모델, 리팩터링, 빌드 오류 진단에 뛰어납니다. .pbxproj 수정, 코드 서명, 시각적 디버깅에는 취약합니다. “에이전트가 Swift를 작성하는 것”과 “에이전트가 iOS 앱을 출시하는 것” 사이의 간극은 프롬프트가 아니라 구성으로 메웁니다. WWDC 2026(6월 8일) 기준 iOS 27은 beta 상태입니다. 8월 10일 기준 beta 5(24A5408d)이며, 2026년 6월 이전에 학습된 모델은 알지 못할 에이전트 관련 프레임워크(Foundation Models tool-calling 제어, App Intents 백그라운드 실행, 새로운 Core AI 및 Evaluations 프레임워크)를 추가하므로 에이전트의 컨텍스트에 이름을 명시해 둘 가치가 있습니다. Xcode 26.6(2026-06-25, Swift 6.3)은 현재 안정적인 toolchain이며, Xcode 27 beta(Swift 6.4, iOS 27 SDKs)는 iOS 27 주기를 따릅니다.¹⁷¹⁸

저는 AI 코딩 에이전트로 8개의 iOS 앱을 만들었습니다. 프로토타입이 아닙니다. HealthKit 통합, Metal shader, SpriteKit 물리, iCloud 동기화, Live Activities, Game Center 리더보드, iOS, watchOS, tvOS에 걸친 멀티플랫폼 타깃을 갖추고 App Store에 출시된 앱입니다. 이 앱의 모든 Swift 코드는 에이전트가 작성하고 제가 검토했거나, 제가 작성하고 에이전트가 리팩터링했습니다. 제 추정으로는 에이전트가 줄 단위 코드 작성의 대부분을 담당했고, 저는 검토, 범위 설정, 그리고 사람의 판단이 필요한 부분(시각적 완성도, 서명, 성능 튜닝, App Store 제출)을 맡았습니다.

이 가이드는 제가 시작할 때 있었으면 했던 레퍼런스입니다. 어떤 에이전트 런타임을 사용할지, 구조화된 빌드 접근을 위해 MCP 서버를 어떻게 구성할지, CLAUDE.md에 무엇을 넣을지, 에이전트가 Xcode 프로젝트를 망가뜨리지 않도록 하는 hook은 무엇인지, 그리고 결정적으로 에이전트가 실패해 직접 조작해야 하는 지점까지 전체 스택을 다룹니다.

핵심 요점

AI 에이전트를 처음 사용하는 iOS 개발자를 위한 내용:

• Claude Code CLI + XcodeBuildMCP로 시작하세요. 가장 성숙한 런타임이며, 가장 폭넓은 MCP 도구 범위를 제공합니다. 명령어 2개를 설치하고 프로젝트에 CLAUDE.md를 추가하면, 오류 메시지를 복사하지 않아도 에이전트가 빌드, 테스트, 디버깅할 수 있습니다.
• 에이전트가 .pbxproj를 수정하게 두지 마세요. 이것이 가장 중요한 규칙입니다. .pbxproj 및 .xcodeproj/에 대한 쓰기를 차단하는 PreToolUse hook은 복구에 드는 시간을 몇 시간이나 아껴 줍니다.
• CLAUDE.md는 에이전트의 온보딩 문서입니다. 여기에 투자한 시간은 프로젝트를 다루는 모든 에이전트 세션에서 다시 돌아옵니다.

워크플로에 iOS를 추가하는 숙련된 에이전트 사용자를 위한 내용:

• MCP는 iOS 빌드 루프를 바꿉니다. MCP 이전에는 에이전트가 Swift를 작성해도 컴파일되는지 검증할 수 없었습니다. XcodeBuildMCP를 사용하면 에이전트가 코드를 작성하고, 빌드하고, 구조화된 오류를 읽어 수정하고, 테스트까지 실행합니다. 자율적으로 말입니다.
• 3개의 런타임은 서로 다른 요구를 충족합니다. 심층 에이전트 세션에는 Claude Code CLI, headless 일괄 작업에는 Codex CLI, 그리고 Xcode 자체 에이전트를 사용하세요. Xcode 자체 에이전트는 Xcode 27에서 plug-in, MCP 서버, 시뮬레이터 조작 기능을 얻으며 인라인 수정 도구에서 벗어났습니다.²²
• hook 인프라는 그대로 이어집니다. 기존 PostToolUse formatter, PreToolUse blocker, 테스트 러너 hook은 경로를 약간 조정하면 iOS 프로젝트에서도 동일하게 작동합니다.

AI 지원 iOS 개발을 평가하는 팀 리드를 위한 내용:

• 에이전트의 효과는 프로젝트 규모가 아니라 프로젝트 문서화 수준에 따라 커집니다. 상세한 CLAUDE.md가 있는 63파일 앱은 CLAUDE.md가 없는 14파일 앱보다 더 나은 에이전트 결과를 만듭니다.
• .pbxproj 경계는 타협할 수 없습니다. 에이전트는 Xcode 프로젝트 파일을 안정적으로 편집할 수 없습니다. 워크플로에는 Xcode 타깃에 파일을 수동으로 추가하는 과정을 포함해야 합니다.
• 솔직한 ROI: 에이전트는 문서화가 잘된 프로젝트에서 구현의 대부분을 처리합니다 — 아래 사례 연구의 15파일 TV 앱은 에이전트 지원 작업 3시간 만에 출시되었습니다. 남은 작업인 시각적 완성도, 서명, 성능 튜닝, App Store 제출에는 사람의 판단이 필요합니다.

경로 선택

이 가이드 사용 방법

이 문서는 3,000줄이 넘는 레퍼런스입니다. 현재 경험 수준에 맞는 곳에서 시작하세요.

목차

1. 포트폴리오: 8개 앱, 293개 파일
2. 사전 요구 사항
3. iOS용 3개 에이전트 런타임
4. MCP 설정: 전체 구성
5. iOS 프로젝트를 위한 CLAUDE.md 패턴
6. 첫 에이전트 세션
7. iOS에서 에이전트가 잘하는 일
8. iOS에서 에이전트가 잘하지 못하는 일
9. iOS 개발을 위한 Hooks
10. 에이전트와 잘 작동하는 아키텍처 패턴
11. 프레임워크별 컨텍스트
12. 멀티플랫폼 패턴
13. 고급 워크플로
14. 실제 사례 연구
15. 에이전트를 활용한 프로젝트 수명 주기
16. 에이전트 정의 구성하기
17. 에이전트 지원 iOS를 위한 테스트 패턴
18. iOS 프로젝트를 위한 컨텍스트 윈도우 관리
19. 문제 해결
20. iOS에서 흔히 발생하는 에이전트 실수와 예방 방법
21. 솔직한 평가
22. FAQ
23. 빠른 참조 카드
24. 참고 자료

관련 리소스

Apple 생태계 시리즈. Apple Intelligence, MCP, Foundation Models, Vision, Core ML, iOS 26 프레임워크 스택과 통합되는 SwiftUI 앱에 관한 21개의 프로덕션 글입니다. Water, Get Bananas, Return 및 나머지 941 포트폴리오에서 얻은 내용입니다.

시리즈 허브: Apple 생태계 시리즈

Agentic Apple (E4):

프레임워크(E2/E3):

출시된 코드(E1):

종합(E5):

iOS 27 및 WWDC 2026: 이제 에이전트가 빌드하는 대상

WWDC 2026(2026년 6월 8일)에서 iOS 27 베타가 공개됐어요. 이 가이드의 에이전트 개발 워크플로는 바뀌지 않아요. 여전히 Claude Code, Codex 또는 Xcode Intelligence 에이전트를 MCP를 통해 사용하고, CLAUDE.md를 작성하며, hooks로 파괴적인 작업을 제한해요. 달라지는 점은 에이전트가 코드를 작성할 대상 범위예요. iOS 27에는 에이전트와 관련된 새로운 프레임워크가 여러 개 추가됐고, 2026년 6월 이전에 학습된 모델은 이를 알지 못하므로 코딩 에이전트가 이 프레임워크를 명시적으로 사용하도록 안내해야 해요. 현재 출시 버전은 여전히 iOS 26이므로, 아래 항목은 iOS 27 베타 SDK을 대상으로 빌드할 때 사용할 대상으로 보세요.

에이전트와 관련된 iOS 27 기능과 각각의 심층 참고 자료는 다음과 같아요.

• Foundation Models에 tool-calling 제어 기능이 추가됐어요. GenerationOptions.ToolCallingMode를 사용하면 요청별로 온디바이스 모델이 도구를 호출하는 적극성을 조절할 수 있고, 프레임워크는 첫 호출 후 모드를 전환해 요청의 도구 활동을 제한할 수 있어요. 이제 Vision 프레임워크는 인식 코드를 직접 작성하지 않아도 LanguageModelSession에 연결할 수 있는 OCRTool 및 BarcodeReaderTool을 제공해요. iOS 27의 Foundation Models: Tool-Calling 제어를 참고하세요.¹²
• App Intents가 30초 제한을 넘었어요. 진행 상황 보고가 필요한 performBackgroundTask(options:operation:)를 통한 LongRunningIntent는 동기화, 파일 작업, 온디바이스 추론을 위한 intent의 백그라운드 실행 시간을 연장해요. SyncableEntity는 AppEntity에 기기 간 식별성을 제공하고, IndexedEntityQuery는 시스템이 Spotlight 인덱스를 복구하도록 쿼리에 요청할 수 있게 해요. iOS 27의 App Intents: 백그라운드, 동기화, Spotlight를 참고하세요.¹³
• Core AI는 Apple Silicon에서 모델을 실행하기 위한 새 프레임워크예요. Apple 시스템 모델 대신 자체 모델을 가져오는 경우에 Foundation Models보다 하위 계층에서 사용해요. Core AI: Apple Silicon에서 모델 실행하기를 참고하세요.¹⁴
• Evaluations는 모델 품질을 위한 XCTest예요. 테스트 모음의 일부로 모델 출력 품질을 측정하는 새로운 프레임워크(macOS 27)로, 에이전트가 빌드하는 데 도움을 준 AI 기능을 출시하는 데 빠져 있던 부분이에요. Evaluations: 모델 품질을 위한 XCTest를 참고하세요.¹⁵
• SwiftData, HealthKit, SwiftUI도 함께 발전했어요. SwiftData에는 iOS 27에서 관찰 및 기록 기능이 추가됐고, HealthKit에는 운동 구간과 새 유형이 추가됐으며, SwiftUI의 iOS 27 추가 기능은 평소처럼 폭넓어요. iOS 27의 SwiftData, iOS 27의 HealthKit, iOS 27용 SwiftUI의 새로운 기능을 참고하세요.¹⁶

iOS 27 작업용 도구 체인은 Xcode 27 베타예요. Xcode 27은 WWDC 첫날(6월 8일, build 27A5194q)에 베타로 출시됐고, 8월 10일 기준 베타 5(27A5237l)예요. Swift 6.4와 iOS 27 / iPadOS 27 / tvOS 27 / watchOS 27 / macOS 27 / visionOS 27 SDK을 포함하며, macOS Tahoe 26.4 이상이 필요해요.¹⁸ 에이전트 워크플로에 중요한 릴리스 노트 항목은 4개예요. Coding Intelligence에 plan mode가 추가됐어요. 릴리스 노트는 “Implement the plan?” 확인 표시줄과 관련된 알려진 문제(178673449)를 통해 이를 안내하므로, 계획을 확인하거나 닫기 전에 에이전트가 스트리밍을 마칠 때까지 기다리세요. RenderPreview MCP 도구는 이제 Preview 그룹을 렌더링하고(174692209), 다른 현지화 환경에서 UI를 미리 볼 수 있어요(181040291). 에이전트용 “Prepare Project for Localization” 도구는 이제 소스에 더 이상 나타나지 않아 제거된 String Catalog 키를 보고해요(179755385). 또한 앱을 Xcode 26.4 이하로 빌드한 경우 27.0 대상에서 Address Sanitizer가 실행되지 않을 수 있으므로 ASan 실행에는 Xcode 26.5+를 사용하세요(178072780).¹⁸ 베타 5에는 여기서 중요한 항목이 2개 더 추가됐어요. 이제 에이전트는 watchOS 앱을 검증할 수 있으며, “Digital Crown을 돌리고 누르며, 측면 버튼과 Action 버튼(Apple Watch Ultra)을 누르는 작업”도 포함해요(181147968). 이는 Apple의 에이전트가 처음으로 watch 앱의 물리적 입력을 조작할 수 있게 된 것으로, 이 가이드에서 다루는 시각적 검증 공백의 일부를 메워요. 또한 Apple은 Xcode를 열지 않아도 되는 MCP 서버를 미리 공개했어요. 아래 Apple의 MCP 서버 섹션을 참고하세요.²² MCP 도구도 베타를 따라잡았어요. XcodeBuildMCP v2.7.0(2026-07-23)은 Device Hub를 통해 Xcode 27 simulator에서 UI 자동화 도구가 완전히 작동하도록 했으며, simulator 창 실행과 키보드 제어도 포함해요. 이 릴리스 전에는 런타임 UI 자동화가 Xcode 26 simulator에서만 안정적이어서, iOS 27 베타에서 에이전트 주도 UI 검증은 수동 작업이었어요.²¹

운영 측면의 교훈은 이 가이드 전체에서 말하는 것과 같아요. 에이전트는 코드를 작성하지만, 부족한 지식은 사용자가 제공해야 해요. iOS 27 베타에서는 프롬프트나 CLAUDE.md에 이 프레임워크를 명시하고 Apple 문서로 연결해야 해요. 그렇지 않으면 모델은 각 API의 iOS 26 형태를 사용하려 할 거예요. 이 가이드의 나머지 내용(runtime, MCP, hooks, 실패 모드)은 iOS 27 작업에도 그대로 적용돼요.

포트폴리오: 8개 앱, 293개 파일

설정을 살펴보기 전에, 이 가이드가 어떤 프로젝트에서 비롯됐는지 소개할게요. 장난감 프로젝트가 아니에요. Apple 프레임워크 5개, 플랫폼 3개, 파일 14개짜리 운동 추적기부터 파일 63개짜리 멀티플랫폼 명상 타이머까지 iOS 복잡성의 전체 범위를 아울러요.

파일 수가 중요한 이유: 에이전트의 효과는 프로젝트 크기가 아니라 프로젝트의 이해 가능성과 관련이 있어요. Return(63개 파일)은 상세한 CLAUDE.md에 파일 주석, 아키텍처 다이어그램, 명시적 패턴이 있으므로 amp97(41개 파일)보다 더 나은 에이전트 출력을 만들어요. amp97의 Metal shaders는 문서 품질과 관계없이 에이전트가 본질적으로 추론하기 더 어려워요.

사전 요구 사항

iOS 개발용 에이전트 runtime을 설정하기 전에 다음을 확인하세요.

App Store Connect 마감일: 2026-04-28부터 App Store Connect에 앱을 업로드하려면 iOS 26, iPadOS 26, tvOS 26, visionOS 26 또는 watchOS 26용 SDK을 사용해 Xcode 26 이상으로 빌드해야 해요.²⁶ (macOS 제출에는 이 요구 사항이 적용되지 않아요.) 팀에서 아직 Xcode 16.x를 사용 중이라면 이 가이드의 에이전트 지원 도구 체인은 전환을 유도하는 계기가 돼요. 아래의 MCP server는 어차피 Xcode 26.3+ 없이는 작동하지 않아요.

필수: - macOS 15+(Sequoia) 또는 macOS Tahoe(Xcode 26.6에는 macOS Tahoe 26.2+가 필요하고, Xcode 27 베타에는 Tahoe 26.4+가 필요해요) - Xcode 26.3+ 설치 및 구성(xcrun mcpbridge 최소 버전), Xcode 26.6+ 권장. Xcode 26.6(2026-06-25, build 17F113)은 최신 안정 버전이며, 에이전트와 관련된 Coding Intelligence 변경 사항 3가지를 제공해요. 코딩 보조 제공자로서의 Google Gemini, Agent Client Protocol(ACP) 지원, preview MCP 도구의 변형 렌더링(라이트/다크, 방향, 글자 크기)이에요. 또한 에이전트 turn 중 발생하는 충돌 2건과 에이전트가 질문할 때 멈추는 문제를 해결하고, iOS 26.5 세대 SDK과 함께 Swift 6.3을 제공해요.¹⁷ 코딩 보조의 메시지 큐잉과 명확화 질문 지원을 포함한 26.5 워크플로 업그레이드, Swift Testing 이미지 첨부, 기록된 issue 심각도, crashlog가 포함된 UI-test 충돌 경고, String Catalog 편집기 개선을 포함한 26.4 변경 사항도 모두 이어져요.²⁷²⁸ 이전 안정 버전은 26.5(2026-05-11, build 17F42)와 26.4.1(2026-04-16, build 17E202)이에요.²⁹ - iOS Simulator runtime을 최소 1개 설치 - Claude Code용 Anthropic API 계정 또는 Codex용 OpenAI 계정

권장: - SwiftFormat 설치(brew install swiftformat) — 저장 시 포맷 hooks에서 사용해요 - SwiftLint 설치(brew install swiftlint) — 선택 사항이지만 스타일 적용에 유용해요 - 터미널 사용에 익숙할 것 — 세 가지 runtime 모두 명령줄에서 작동하거나 명령줄과 통합돼요

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

xcrun mcpbridge가 “command not found”를 반환하면 Xcode 26.3 이상이 필요해요. App Store 또는 developer.apple.com을 통해 Xcode를 설치하거나 업데이트하세요. 참고로 xcode-select --install은 Command Line Tools만 설치하며, 여기에는 mcpbridge가 포함되지 않아요. 전체 Xcode.app이 필요해요.

iOS용 세 가지 에이전트 런타임

서로 다른 3가지 런타임이 iOS 코드를 작성하고, 빌드하고, 테스트할 수 있습니다. 이들은 서로 대체할 수 없으며, 각각 강점과 MCP 통합 방식, 적합한 사용 사례가 다릅니다.

1. Claude Code CLI

무엇인가요: Anthropic의 터미널 기반 에이전틱 코딩 어시스턴트입니다. 코드베이스를 읽고, 명령을 실행하고, 파일을 수정하며, MCP를 통해 외부 도구에 연결합니다.⁷

MCP 통합: XcodeBuildMCP와 Apple의 Xcode MCP를 모두 완전히 지원합니다. 에이전트는 MCP 프로토콜로 도구를 검색하고 구조화된 매개변수로 호출합니다. 두 서버에 걸쳐 82 + 20개의 도구를 제공합니다.

설정:

# 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

대안 — xcodebuildmcp init 자동 설치 프로그램(v2.1.0+, 2026-02-23):

수동 MCP 연결 설정을 건너뛰고 싶다면, XcodeBuildMCP v2.1.0+에는 Claude Code, Cursor 또는 Codex를 자동 감지하고 에이전트 스킬과 MCP 설정을 한 번에 설치하는 init 하위 명령이 포함되어 있습니다.

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

플래그: --print(지원되지 않는 클라이언트용으로 설정을 stdout에 출력), --uninstall(제거). 연결할 MCP 서버와 적용 범위를 명시적으로 제어하고 싶다면 이 방법은 건너뛰세요. 위의 수동 claude mcp add 호출을 사용하면 이를 제어할 수 있습니다.³⁰

가장 적합한 용도: 심층 구현 세션입니다. 새 기능 구축, 여러 파일에 걸친 리팩터링, 복잡한 문제 디버깅, 빌드-테스트-수정 루프의 자율 실행에 적합합니다. Claude Code의 1M 컨텍스트 윈도우(Opus 5 사용)는 에이전트가 대부분의 소규모~중간 규모 iOS 프로젝트를 작업 메모리에 유지할 수 있음을 의미합니다. 제 경험상 파일 크기에 따라 대략 50개 파일까지 가능합니다.²⁵

일반적인 세션:

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]

MCP 이전 워크플로와의 핵심 차이점은 에이전트가 수동 빌드나 오류 출력 붙여넣기를 요청하지 않는다는 것입니다. 빌드-오류-수정 루프가 자율적으로 실행됩니다.

2. Codex CLI

무엇인가요: OpenAI의 터미널 기반 코딩 에이전트입니다. 개념적으로는 Claude Code와 비슷하지만 OpenAI의 Codex 모델을 실행하며 권한 모델이 다릅니다. 현재 라인업은 GPT-5.6 Sol(플래그십, 복잡한 코딩에 가장 강력), GPT-5.6 Terra(균형 잡힌 일상용 기본값), GPT-5.6 Luna(빠르고 가장 저렴함)이며, GPT-5.3 Codex Spark는 텍스트 전용 리서치 프리뷰입니다. GPT-5.4와 GPT-5.4-mini는 2026년 8월 31일에 Codex에서 지원 종료되므로, 해당 설정은 각각 Terra와 Luna로 옮기세요.²³

MCP 통합: Codex는 codex mcp add 명령을 통해 MCP를 지원합니다. Apple의 Xcode MCP는 바로 작동합니다.

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

XcodeBuildMCP도 같은 npx 명령을 통해 Codex와 함께 작동합니다.

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

가장 적합한 용도: 헤드리스 일괄 작업, CI/CD 통합, 다른 모델 계열의 두 번째 의견이 필요한 작업입니다. Codex의 샌드박스 모드는 격리된 환경에서 코드를 실행하므로, 상태를 수정하는 테스트 스위트 실행처럼 파괴적일 수 있는 작업에 유용합니다.

Claude Code와의 주요 차이점: - Claude 모델 대신 OpenAI 모델을 사용합니다 - 컨텍스트 윈도우 크기와 토큰 비용 구조가 다릅니다 - 샌드박스 우선 권한 모델을 사용합니다(기본적으로 더 제한적) - MCP 생태계가 더 작습니다(테스트된 커뮤니티 서버가 더 적음) - Hooks 시스템을 사용할 수 있습니다(v0.119.0+). 다만 Claude Code보다 성숙도가 낮으며 이벤트 유형이 더 적고 조건부 if 필드도 없습니다

iOS에서 Claude Code 대신 Codex를 사용할 때:

모델 다양성이 필요할 때 Codex를 사용하세요. 첫 번째 에이전트가 작성한 코드를 두 번째 에이전트가 검토하면 서로 다른 유형의 오류를 잡아낼 수 있습니다. collab workflow(Claude가 구축하고 Codex가 검토)는 한 모델 계열에는 올바르게 보이는 SwiftUI 패턴이 다른 모델 계열에서는 미묘한 문제로 드러날 수 있기 때문에 iOS 작업에 효과적입니다. Metal 셰이더와 동시성 패턴은 특히 두 모델을 활용한 검토의 이점을 얻습니다.

3. Xcode Native Agents

무엇인가요: Apple은 AI 코딩 에이전트를 Xcode의 Intelligence 패널에 직접 통합했습니다. Xcode 26.3부터 Xcode Settings > Intelligence에서 Claude Agent와 Codex를 인텔리전스 제공자로 설정할 수 있습니다.¹⁰ Xcode 26.6에서는 제공자 목록이 확대됩니다. 이제 코딩 어시스턴트에서 Google Gemini를 사용할 수 있고(171990272), Xcode에 Agent Client Protocol(ACP) 지원도 추가됩니다(178294840). 즉, 처음에는 2개 제공자 통합으로 시작했지만 이제는 3개 제공자와 ACP 호환 에이전트를 Intelligence 패널에 연결할 수 있는 개방형 프로토콜을 제공합니다.¹⁷

설정:

1. Xcode 26.3+를 엽니다
2. Settings > Intelligence로 이동합니다
3. 새 제공자를 추가합니다.
4. Claude의 경우: “Claude Agent”를 선택하고 Anthropic API 키를 입력합니다
5. Codex의 경우: “Codex”를 선택하고 OpenAI API 키를 입력합니다
6. Gemini의 경우: “Google Gemini”를 선택합니다(Xcode 26.6+)
7. 그 밖의 경우: ACP 호환 에이전트를 연결합니다(Xcode 26.6+)
8. 에이전트가 Intelligence 사이드바에 나타나며 인라인으로 호출할 수 있습니다

가장 적합한 용도: 빠른 인라인 수정, 에이전트 수준의 추론을 활용한 코드 완성, Xcode를 벗어나고 싶지 않은 개발자에게 적합합니다. 네이티브 통합 덕분에 에이전트는 MCP 브리지 없이 열린 파일, 빌드 타깃, 스킴 설정 등 Xcode 프로젝트 컨텍스트에 직접 접근할 수 있습니다.

CLI 에이전트와 비교한 제한 사항 — Xcode 26.x 기준: - Hooks 시스템이 없습니다. 저장 시 포맷을 강제하거나 .pbxproj 쓰기를 차단할 수 없습니다 - CLAUDE.md를 로드하지 않습니다. 에이전트는 프로젝트 수준 설정 파일을 읽지 않습니다 - 자율성이 제한적입니다. 에이전트는 전체 프로젝트가 아니라 현재 파일 또는 선택 영역에서 작동합니다 - 하위 에이전트 위임이 없습니다. 복잡한 여러 단계 작업을 병렬화할 수 없습니다 - MCP 서버 설정이 없습니다. 에이전트는 Xcode 내장 도구만 사용합니다

Xcode 27은 이 목록 대부분을 무효화합니다. 베타 1(6월 8일)부터 Xcode의 에이전트는 인라인 어시스턴트가 아니라 확장 플랫폼이 되었습니다.²²

• 플러그인: “이제 Xcode의 에이전트는 스킬, MCP 서버, ACP 에이전트 설정을 포함하는 플러그인으로 확장할 수 있습니다. 스킬은 자동 완성 지원이 있는 슬래시 명령으로 호출할 수 있습니다.”(178289210) 따라서 “내장 도구만 사용” 및 “MCP 설정 없음” 제한은 사라졌습니다.
• Simulator 제어: 에이전트는 “이제 Simulator를 부팅하고, 앱을 설치 및 실행하고, 터치 이벤트를 합성하고, UI 동작을 검증하기 위한 스크린샷을 캡처할 수 있습니다”(175179787). 베타 5에서는 watchOS 하드웨어 입력도 제어할 수 있습니다(181147968).
• 디버거 접근: Xcode MCP 서버에는 실행 상태 조작, 디버거 콘솔 읽기, 스킴 및 실행 대상 전환, “빌드 설정, 컴파일러 플래그, entitlements, Info.plist 키” 검사 또는 수정 도구가 추가되었습니다(176935844).
• 파일 시스템 보안 계층: “코딩 에이전트와 이들이 생성하는 모든 프로세스의 파일 시스템 접근을 모니터링하고 제어하는” 계층(178289431)에 더해, 일급 계획 기능(172857081)과 크래시, 멈춤, 에너지, 실행 문제를 다루는 프로젝트 인사이트(177568662)가 제공됩니다.

176935844에서 직접 따라오는 경고 한 가지: 이제 Xcode의 에이전트는 빌드 설정, entitlements, Info.plist 키를 수정할 수 있습니다. 이 가이드가 PreToolUse hook으로 구성하는 .pbxproj 보호 기능은 Xcode 내부에서는 적용되지 않습니다. hook은 Apple이 아니라 CLI 에이전트의 설정에 있기 때문입니다. 이 hook을 안전망으로 사용한다면 Intelligence 패널에는 적용 권한이 없다는 점을 알아두세요.

Xcode 네이티브 에이전트를 사용할 때:

터미널로 전환하는 것이 오버헤드인 빠르고 범위가 제한된 수정에 사용하세요. “이 모델에 계산 프로퍼티를 추가해 줘.” “이 함수의 단위 테스트를 작성해 줘.” “이 뷰를 @Observable을 사용하도록 리팩터링해 줘.” 파일 1~2개만 수정하고 빌드-테스트 주기가 필요하지 않은 작업에 적합합니다.

빌드, 테스트, 여러 파일 리팩터링 또는 자율적인 오류 수정이 필요한 작업에는 MCP와 함께 CLI 에이전트를 사용하세요.

런타임 비교 매트릭스

권장 사항: Claude Code CLI를 기본 런타임으로 사용하세요. 빠른 인라인 수정에는 Xcode 네이티브 에이전트를 사용하세요. 검토 단계와 일괄 작업에는 Codex CLI를 사용하세요. 이 3가지는 경쟁하기보다 서로를 보완합니다.

MCP 설정: 전체 구성

MCP (Model Context Protocol)은 에이전트를 “Swift를 작성하고 빌드되기를 바라는” 수준에서 “Swift를 작성하고, 빌드하고, 구조화된 오류를 읽고, 수정하는” 수준으로 바꿉니다.² 이 섹션에서는 블로그 게시물¹¹보다 더 깊이 다룹니다. 두 서버, 모든 설치 방법, 검증 방법, 그리고 도구가 실제로 사용되도록 보장하는 에이전트 구성까지 설명합니다.

XcodeBuildMCP: 헤드리스 iOS 개발을 위한 82개 도구

XcodeBuildMCP는 xcodebuild, xcrun simctl, LLDB를 82개의 구조화된 MCP 도구로 감쌉니다(v2.6.2부터 v2.7.0까지 광고된 도구 목록이 변경되지 않았음을 확인). 도구는 12개의 워크플로 카테고리로 나뉩니다.³¹⁹²¹ 이 프로젝트의 공식 홈은 getsentry GitHub 조직입니다. Sentry가 유지 관리하며, 원래의 cameroncooke/XcodeBuildMCP URL은 이제 이곳으로 리디렉션됩니다. 오래된 글에서 이전 주소를 인용할 때 이 점이 중요합니다.²¹ Xcode를 실행하지 않아도 작동합니다. 전체 빌드-테스트-디버그 사이클이 Apple의 명령줄 도구를 통해 헤드리스로 실행됩니다. 알아둘 만한 도구 목록 관련 사항은 2가지입니다. 기본 stdio 세션은 시뮬레이터 워크플로의 24개 도구를 노출하고 나머지는 에이전트 컨텍스트에 넣지 않습니다. 더 많은 도구를 로드하려면 XCODEBUILDMCP_ENABLED_WORKFLOWS를 설정하세요(아래 표의 카테고리 이름을 쉼표로 구분). 또한 같은 엔진은 CLI로도 제공됩니다(xcodebuildmcp tools는 100개 명령, 72개 정식 명령을 보고함). MCP 없이 동일한 작업을 원할 때 사용할 수 있습니다.⁹

설치 옵션:

# 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

-s user 플래그를 사용하면 모든 프로젝트에서 서버를 전역으로 사용할 수 있습니다. 프로젝트 범위 설치를 원한다면 생략하세요(MCP를 웹 프로젝트가 아닌 iOS 프로젝트에서만 사용하려는 경우 유용합니다).

-e XCODEBUILDMCP_SENTRY_DISABLED=true 환경 변수는 크래시 보고 텔레메트리를 비활성화합니다. XcodeBuildMCP에는 기본적으로 Sentry가 포함되어 있으며, 파일 경로를 포함한 오류 데이터를 전송합니다. 프로젝트에 진단 정보를 제공하려는 것이 아니라면 옵트아웃하세요.¹

도구 목록(12개 워크플로 카테고리의 82개 도구 — 카테고리별 대표 도구):

일상 작업에서 가장 중요한 도구:

1. build_sim — 수백 번 호출하게 됩니다. 파일, 줄, 심각도별로 분류된 오류와 함께 JSON을 반환합니다. 에이전트는 오류를 읽고, 파일로 이동해 사용자가 아무것도 건드리지 않아도 수정합니다.

2. test_sim — 테스트 메서드별 결과를 반환합니다. 에이전트는 단순히 “테스트 실패”가 아니라 어떤 테스트가 왜 실패했는지 정확히 파악합니다.

3. list_sims + boot_sim — xcrun simctl 플래그를 외우지 않고 시뮬레이터를 관리할 수 있습니다. 에이전트가 사용 가능한 런타임을 찾고 적절한 기기를 선택합니다.

4. discover_projs + list_schemes — 프로젝트 검사 도구입니다. 에이전트는 scheme 이름이나 workspace 구조를 추측할 필요가 없습니다.

5. debug_attach_sim + debug_stack + debug_variables — 원격 LLDB 디버깅입니다. 에이전트는 디버거를 열지 않고도 중단점을 설정하고, 변수를 검사하며, 코드를 단계별로 실행할 수 있습니다.

v2.6.0에서 변경된 사항(2026-06-01) — 런타임 UI 자동화:

v2.6.0 릴리스는 UI 자동화를 일회성 스크린샷 대신 재사용 가능한 컨텍스트 중심으로 재구축했습니다.¹⁹ 이제 snapshot_ui는 안정적인 요소 참조와 화면 해시를 반환하며, sinceScreenHash를 받아 화면이 바뀌지 않았을 때 전체 스냅샷을 건너뛸 수 있습니다. 3개의 새 도구가 루프를 완성합니다. wait_for_ui는 에이전트가 sleep을 추측하는 대신 조건이 충족될 때까지 폴링합니다(존재, 활성 상태, 포커스, 보이는 텍스트, 안정화된 레이아웃). batch는 요소 참조 작업 시퀀스를 한 번의 호출로 수행합니다. drag는 sheet와 목록 스크롤을 위한 요소 참조 드래그 제스처를 수행합니다. type_text에는 필드 값에 덧붙이는 대신 교체하는 replaceExisting이 추가되었고, 후보 컨트롤은 접근성 데이터에 따라 순위가 매겨지며, 구조화된 결과에는 이제 nextSteps 힌트가 포함됩니다(이 릴리스에서 결과 스키마는 v2로 버전이 지정되었고, 이후 v2.7.0에서는 빌드/테스트 결과가 schemaVersion: 3으로 변경되었습니다. 아래를 참조하세요). XCODEBUILDMCP_HEADLESS_LAUNCH=true를 설정하면 macOS 포커스를 빼앗지 않고 백그라운드에서 앱을 실행합니다. 계속 Simulator 창을 앞으로 끌어오는 세션과 그대로 실행해 둘 수 있는 에이전트 세션의 차이를 만듭니다. 결정론적인 Weather 앱 작업에서 프로젝트 자체 벤치마크는 v2.6 이전 흐름과 비교해 실제 경과 시간이 약 70% 줄고, 토큰은 68% 줄며, 도구 호출은 76% 줄었다고 주장합니다. 이는 독립적인 측정이 아니라 프로젝트 측 수치이지만, 변경되지 않은 스냅샷 건너뛰기와 같은 화면 작업 일괄 처리가 UI 자동화 토큰 소모가 발생하는 정확한 지점입니다.¹⁹

v2.7.0에서 변경된 사항(2026-07-23) — Xcode 27 시뮬레이터, 스키마 v3, scheme 설정을 따르는 빌드:

v2.7.0 릴리스는 2.6.0보다 작지만, 업그레이드 전에 알아둘 만한 호환성 변경 1개와 동작 변경 1개를 포함합니다.²¹ 핵심은 다음과 같습니다. 이제 UI 자동화 도구가 Device Hub를 통해 Xcode 27 시뮬레이터에서 완전히 작동합니다. 여기에는 시뮬레이터 창 실행과 키보드 제어가 포함되어, 런타임 UI 자동화가 Xcode 26 시뮬레이터에서만 안정적이던 격차를 해소합니다. 호환성 변경: 빌드 및 테스트 도구는 이제 schemaVersion: 3 구조화된 결과를 반환합니다(2.6.0부터 v2였습니다). 버전 2에 고정된 결과 검증이나 파싱 코드는 업데이트해야 합니다. 동작 변경: configuration을 생략하면 이제 빌드, 테스트, 정리, 앱 경로 도구는 항상 Debug로 기본 설정하는 대신 scheme 작업의 구성을 따릅니다. scheme의 Test 작업이 Release로 설정되어 있다면, 구성을 지정하지 않은 test_sim은 이제 Release를 빌드합니다. 워크플로가 특정 구성에 의존한다면 configuration을 명시적으로 전달하세요. 작지만 유용한 변경으로는 재사용 가능한 .xctestproducts 테스트 준비 패키지를 통해 매번 새 .xcresult를 만들면서 재빌드 없이 테스트를 다시 실행할 수 있게 된 점, session_set_defaults의 extraArgs로 공통 xcodebuild 플래그를 호출마다 반복하지 않고 세션당 한 번 설정할 수 있는 점, XcodeBuildMCP의 workspace 저장소를 보고 정리하는 새 xcodebuildmcp purge CLI 명령(기본값은 dry-run이며 삭제하려면 명시적으로 옵트인해야 함), 그리고 도구가 사용 가능해질 때까지 10~17초 기다리던 MCP 클라이언트 문제 수정이 있습니다. 이 문제는 짧은 상태 확인에서 연결 실패가 보고될 수 있었습니다.²¹

Apple Xcode MCP: Xcode로 연결되는 20개 도구

Apple의 MCP 서버는 xcrun mcpbridge를 통해 Xcode 26.3과 함께 제공됩니다.⁴ XPC(Apple의 프로세스 간 통신 프레임워크)를 통해 실행 중인 Xcode 프로세스와 통신하며, 어떤 CLI 도구도 접근할 수 없는 내부 상태를 노출합니다.⁵

설치:

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

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

Xcode 26.3 이상과 실행 중인 Xcode 프로세스가 필요합니다. Xcode가 열려 있지 않으면 이 서버를 통한 모든 MCP 호출이 실패하거나 멈춥니다. XcodeBuildMCP에는 이런 제한이 없습니다.

Xcode 27 beta 5는 이 제약에서 벗어날 방법을 미리 보여 줍니다. Apple은 sudo xcrun mcp-server enable로 활성화하고 xcrun mcp-server status로 검사할 수 있는 “열린 Xcode workspace 없이 실행되는 새로운 MCP 서버 환경”을 추가했습니다. 이 미리보기에서는 코드 서명된 에이전트에 디렉터리 트리 내부에서 작업할 지속적인 권한을 부여하여 매번 다시 승인하지 않아도 됩니다. 무인 실행을 위해 sudo xcrun mcp-server enable --unsafe-always-allow-all-agents를 사용하면 모든 것을 미리 승인합니다. Apple은 이를 “책상 앞에서 사용할 때 권장되는 구성이 아님”이라고 명시하며, 저도 마찬가지로 권장하지 않습니다. 에이전트가 노출할 의도가 없던 디렉터리에 접근하지 못하게 하는 승인 단계를 제거하기 때문입니다. 전체 기능을 초기 미리보기로 보고, 미리보기를 벗어날 때까지 XcodeBuildMCP를 헤드리스 경로로 유지하세요.²²

도구 목록(5개 카테고리의 20개 도구):

Apple MCP에만 있는 도구(XcodeBuildMCP에서는 사용할 수 없음):

1. DocumentationSearch — WWDC 세션을 포함한 Apple 개발자 문서를 검색합니다. Apple API 관련 질문에는 웹 검색보다 빠르고 신뢰할 수 있습니다. “is HKQuantityType(.dietaryWater) valid?”라고 물으면 출처에서 확정적인 답을 얻습니다.

2. ExecuteSnippet — 프로젝트 컨텍스트 내에서 Swift REPL을 실행합니다. 에이전트는 전체 앱을 빌드하지 않고도 API 동작을 검증하고, 타입 변환을 테스트하며, 표현식을 확인할 수 있습니다.

3. RenderPreview — SwiftUI 미리보기를 헤드리스로 렌더링합니다. 에이전트는 뷰가 오류 없이 렌더링되는지 확인할 수 있지만, 시각적 정확성을 평가할 수는 없습니다(렌더링은 시각적으로 검사되는 것이 아니라 데이터로 반환됨). Xcode 26.6부터 미리보기 MCP 도구(26.6 릴리스 노트에서는 “Preview Snapshot”이라고 부름)는 라이트/다크 외관, 세로/가로 방향, 글자 크기 재정의를 포함한 variant를 렌더링합니다(178831772). 따라서 에이전트는 한 번에 여러 외관에서 뷰를 검증할 수 있습니다.¹⁷ Xcode 27 beta에서는 Preview 그룹 렌더링과 다른 localization으로 미리보기까지 확장됩니다.¹⁸

4. XcodeListNavigatorIssues — 빌드 오류만이 아니라 Xcode analyzer의 실시간 진단을 반환합니다. 빌드 시스템이 노출하지 않는 미사용 변수, 잠재적 retain cycle, 사용 중단 경고 같은 문제를 포착합니다.

두 서버가 모두 필요한 이유

두 서버는 빌드와 테스트 기능이 겹치지만 근본적으로 다릅니다.

┌─────────────────────────────────────────────────────────────────┐
│                     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를 사용할 때: 빌드-테스트-디버그 사이클에 사용하세요. Xcode를 열지 않아도 작동하고, 시스템 메모리를 덜 사용하며, 더 풍부한 시뮬레이터 및 기기 관리 기능을 제공합니다. 이것이 기본 빌드 도구입니다.

Apple Xcode MCP를 사용할 때: 문서 조회, Swift REPL 검증, SwiftUI 미리보기 렌더링, 실시간 진단에 사용하세요. 이런 기능이 필요한 세션에서는 Xcode를 열어 두세요.

실제로는: 저는 MCP 호출의 약 90%에 XcodeBuildMCP를 사용하고, 문서 및 REPL 검증에는 Apple Xcode MCP를 사용합니다. 에이전트는 빌드와 테스트에 XcodeBuildMCP를 기본으로 사용합니다. 더 빠르고(Xcode 프로세스 오버헤드 없음) 신뢰성이 더 높기 때문입니다(XPC 의존성 없음).

두 서버라는 구분은 약해지고 있습니다. XcodeBuildMCP 2.6.x에는 xcode-ide 프록시 카테고리가 추가되었습니다. xcode_ide_list_tools는 Xcode-IDE 전용 MCP 기능을 검색하고, xcode_ide_call_tool은 이를 호출합니다(xcode_tools_documentationsearch처럼 xcode_tools_* 이름으로 표시됨). 따라서 이제 XcodeBuildMCP 등록 하나로 Apple의 IDE 측 도구에도 접근할 수 있습니다.¹⁹ 중요한 제약은 바뀌지 않습니다. 직접 xcrun mcpbridge 등록과 마찬가지로, 프록시 호출에도 실행 중인 Xcode 프로세스가 필요합니다. Apple 도구를 에이전트 도구 목록에 일급으로 표시하고 싶다면 두 서버를 모두 등록해 두세요. 프록시는 서버 항목 하나만 두고 가끔 IDE 읽기 작업을 수행하려는 경우에 가장 유용합니다.

검증

두 서버를 설치한 후 연결되었는지 확인하세요.

# List all configured MCP servers
claude mcp list

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

서버가 “Disconnected”로 표시되거나 보이지 않는 경우:

1. XcodeBuildMCP가 연결되지 않는 경우: Node.js가 설치되어 있는지 확인하세요(node --version). npx 명령에는 Node.js 18 이상이 필요합니다.
2. Apple Xcode MCP가 연결되지 않는 경우: Xcode 26.3 이상이 설치되어 있고, 터미널에서 xcrun mcpbridge 명령이 작동하는지 확인하세요. 라이선스 계약에 동의하려면 Xcode를 최소 한 번 열어야 합니다.
3. 둘 다 보이지 않는 경우: Claude Code를 재시작하세요(새 터미널에서 claude 실행). 세션 중간에 등록한 MCP 서버는 재시작 전까지 나타나지 않을 수 있습니다.

에이전트에게 MCP 사용법 가르치기

MCP 서버 설치는 필요하지만 충분하지는 않습니다. 명시적인 안내가 없으면 에이전트는 Bash로 xcodebuild를 실행하는 방식(구조화되지 않은 출력, 컨텍스트 토큰 낭비)으로 돌아가거나 Apple 문서에 웹 검색을 사용할 수 있습니다(더 느리고 신뢰성도 낮음).

CLAUDE.md 또는 에이전트 정의에 다음을 추가하세요.

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

이 안내를 추가하면 에이전트가 먼저 MCP 도구를 사용하도록 합니다. 안내가 없으면 에이전트가 Bash를 통해 긴 xcodebuild 명령을 구성하고, 출력 파싱에 수천 개의 컨텍스트 토큰을 소비하며, 때로 실제 오류를 잘못 식별하는 모습을 보게 됩니다.⁶

XcodeBuildMCP v2.7.0의 한 동작 변경은 이 섹션의 사고 모델에 포함해야 합니다. configuration을 생략하면 이제 빌드, 테스트, 정리, 앱 경로 도구가 항상 Debug를 사용하는 대신 scheme 작업의 구성을 따릅니다.²¹ 대부분의 scheme은 Debug에서 실행 및 테스트하므로 대부분의 프로젝트에서는 아무 변화도 느끼지 못합니다. 그러나 scheme 작업이 Release로 설정되어 있다면(프로파일링 scheme이나 archive 인접 설정에서 흔함), 구성을 지정하지 않은 build_sim 또는 test_sim은 이제 Release를 빌드합니다. CLAUDE.md 또는 hook이 Debug 산출물을 전제로 한다면 도구 호출에서 명시적으로 지정하거나 session_set_defaults로 세션마다 한 번 설정하세요.

장시간 빌드: Claude Code는 이제 백그라운드에서 실행합니다

Claude Code의 두 릴리스가 세션 안에서 장시간 빌드가 보이는 방식을 바꿨습니다. v2.1.212(2026-07-16)부터 2분 이상 실행되는 모든 MCP 도구 호출은 세션을 계속 사용할 수 있도록 자동으로 백그라운드로 이동합니다. CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS를 통해 임계값을 구성하거나 동작을 비활성화할 수 있습니다.²⁰ 실제 프로젝트에서는 build_sim / test_sim을 통한 clean build와 전체 테스트 실행이 2분을 자주 넘습니다. 따라서 빌드가 백그라운드에서 끝나는 동안 턴을 차단하지 않고, 에이전트가 파일을 읽고 다음 편집을 계획하며 계속 작업할 것으로 예상하세요. 함께 적용된 수정도 똑같이 중요합니다. v2.1.206(2026-07-09) 이전에는 --mcp-config 또는 .mcp.json으로 설정한 서버별 request_timeout_ms가 새 세션에서 무시되었습니다. 따라서 장시간 MCP 호출은 기본 60초에서 시간 초과되었습니다. 전형적인 증상은 첫 clean build가 시간 초과되었다가 재시도 시 “저절로 해결되는” 것이었습니다.²⁰ wrapper script나 사전 예열 빌드로 이 동작을 우회했다면, 이제 그 우회책은 삭제할 수 있습니다.

iOS 프로젝트를 위한 CLAUDE.md 패턴

CLAUDE.md는 에이전트 지원 개발에서 프로젝트에서 가장 중요한 파일입니다. 에이전트의 온보딩 문서이며, 아키텍처 문서를 읽은 신입과 추측으로 일하는 신입을 가르는 차이입니다.

제가 관리하는 모든 iOS 프로젝트에는 CLAUDE.md가 있습니다. 8개 앱에서 얻은, 실제로 효과가 있었던 패턴을 소개합니다.

필수 섹션

모든 iOS CLAUDE.md에는 다음 6개 섹션이 필요합니다. 나머지는 선택 사항입니다.

1. 프로젝트 정체성

# 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

이것이 중요한 이유: 에이전트는 코드를 작성하기 전에 deployment target을 알아야 합니다. iOS 17을 대상으로 하는 에이전트는 NavigationView와 @ObservedObject를 사용합니다. iOS 26을 대상으로 하는 에이전트는 NavigationStack과 @Observable을 사용합니다. bundle ID는 entitlements와 HealthKit 설정에 중요합니다. Swift 버전은 동시성 모델(async/await와 completion handler, 엄격한 동시성과 느슨한 동시성)을 결정합니다.

2. 목적 주석이 있는 파일 구조

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

각 파일명 뒤의 인라인 주석은 장식이 아닙니다. 작성할 수 있는 문서 중 가장 효과가 큰 문서입니다. 에이전트가 새 기능을 어디에 추가할지 결정할 때, 이 주석은 프로젝트 구조를 이해하려고 모든 파일을 읽는 대신 첫 시도에 올바른 파일로 안내합니다.

안티 패턴: 주석 없이 파일만 나열하는 방식입니다. TimerManager.swift만으로는 해당 파일이 상태를 다루는지, UI를 다루는지, 둘 다 다루는지 에이전트가 알 수 없습니다. TimerManager.swift # Timer state, logic, and repeat handling는 그 파일에 무엇이 속하고 무엇이 속하지 않는지 정확히 알려줍니다.

3. 빌드 및 테스트 명령

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

에이전트가 MCP를 우선해야 하더라도 원본 명령을 포함하세요. 원본 명령은 fallback 문서 역할을 하며 scheme 이름과 destination을 명확히 보여줍니다.

4. 핵심 패턴과 규칙

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

이 패턴은 에이전트가 일관성 없는 코드를 도입하지 않도록 막아줍니다. 명시적인 패턴 문서가 없으면 에이전트가 한 파일에서는 ObservableObject를 사용하고 다른 파일에서는 @Observable을 사용하거나, 기존 Settings.shared singleton을 쓰는 대신 새로운 설정 메커니즘을 만들 때가 있습니다.

5. 에이전트가 절대 해서는 안 되는 일

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

명시적인 금지는 암묵적인 기대보다 효과적입니다. 에이전트는 긍정적 제안보다 부정적 제약을 더 안정적으로 따릅니다. 부정적 제약은 이진적이기 때문입니다(하라 / 하지 마라). 반면 긍정적 제안은 휴리스틱입니다(이것을 선호하라 / 때로는 저것을 사용하라).

6. 프레임워크별 컨텍스트

이 섹션은 앱마다 달라집니다. 설정이 직관적이지 않은 프레임워크가 있다면 포함하세요.

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

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

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

Metal 앱의 경우:

## Metal Pipeline

- Render pipeline: `MetalView` → `Renderer` → `ShaderLibrary`
- Compute pipeline: `AudioAnalyzer` → compute shader → texture output
- Shared uniforms struct: `Uniforms` in `ShaderTypes.h` (bridged to Swift)
- Frame timing: `CADisplayLink` drives render loop
- Buffer triple-buffering: 3 in-flight frames with semaphore

### Shader Files
- `Shaders.metal` — Main render shaders (vertex + fragment)
- `Compute.metal` — Audio analysis compute kernel
- `PostProcess.metal` — Bloom and color grading

### DO NOT modify Metal shaders without testing on device.
Simulator Metal is not representative of device GPU behavior.

실제 CLAUDE.md: Banana List (SwiftUI + SwiftData + iCloud + MCP Server)

다음은 중간 정도 복잡한 앱에서 6개 섹션이 어떻게 함께 작동하는지 보여주는 주석付き 예시입니다. 이것은 제가 Banana List에 사용하는 CLAUDE.md 패턴입니다. Banana List는 iCloud 동기화와 앱 데이터를 Claude Desktop에 노출하는 커스텀 MCP 서버를 갖춘 53개 파일의 장보기 목록 앱입니다.

# Banana List - Grocery List App

**Bundle ID:** `com.941apps.BananaList`
**Target:** iOS 26+
**Architecture:** SwiftUI + SwiftData + iCloud Drive sync
**Swift version:** 6.2
**Minimum deployment:** iOS 26.0

## Core Features

- Grocery lists with items, categories, and quantities
- iCloud Drive sync via SwiftData CloudKit integration
- Custom MCP server exposing list data to Claude Desktop
- Liquid Glass design system
- Haptic feedback on interactions
- Share sheets for list sharing

## File Structure

```
BananaList/
├── BananaListApp.swift           # App entry, model container setup
├── Models/
│   ├── GroceryList.swift         # @Model: list with name, items, color
│   ├── GroceryItem.swift         # @Model: item with name, quantity, category, isCompleted
│   ├── Category.swift            # @Model: user-defined categories
│   └── SampleData.swift          # Preview and test data
├── Views/
│   ├── ListsView.swift           # Main list of grocery lists
│   ├── ListDetailView.swift      # Items within a list
│   ├── ItemRow.swift             # Single item row with swipe actions
│   ├── AddItemSheet.swift        # New item form
│   ├── CategoryPicker.swift      # Category selection with create-new
│   └── SettingsView.swift        # App settings
├── Managers/
│   ├── CloudSyncManager.swift    # iCloud Drive sync status and conflict resolution
│   └── HapticManager.swift       # UIImpactFeedbackGenerator wrapper
├── MCP/
│   ├── MCPServer.swift           # MCP server for Claude Desktop integration
│   ├── ListTools.swift           # MCP tools: list CRUD operations
│   └── ItemTools.swift           # MCP tools: item CRUD operations
└── Extensions/
    ├── Color+Extensions.swift    # Custom color definitions
    └── View+Extensions.swift     # Reusable view modifiers
```

## SwiftData Models

### Relationships
- `GroceryList` has many `GroceryItem` (cascade delete)
- `GroceryItem` belongs to one `GroceryList` (required)
- `GroceryItem` has optional `Category`
- `Category` has many `GroceryItem` (nullify on delete)

### Container Setup
```swift
@main
struct BananaListApp: App {
    var body: some Scene {
        WindowGroup {
            ListsView()
        }
        .modelContainer(for: [GroceryList.self, GroceryItem.self, Category.self])
    }
}
```

### Query Patterns
- Lists: `@Query(sort: \GroceryList.name) var lists: [GroceryList]`
- Active items: `@Query(filter: #Predicate { !$0.isCompleted })`
- By category: filter in-memory after fetch (SwiftData predicate limitations)

## Build & Test

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

Prefer MCP tools (`build_sim`, `test_sim`) over raw commands.

## Key Patterns

### Observable + SwiftData
- SwiftData `@Model` classes are automatically Observable
- DO NOT add `@Observable` to `@Model` classes (redundant, causes warnings)
- Use `@Bindable` for two-way bindings to model properties in forms
- Use `@Query` in views, `modelContext.fetch()` in non-view code

### iCloud Sync
- Automatic via SwiftData CloudKit integration
- Conflict resolution: last-write-wins (CloudKit default)
- Sync status exposed via `CloudSyncManager.shared.syncState`
- Test sync by running on two simulators with same iCloud account

### MCP Server Architecture
- Runs as a local WebSocket server on port 8765
- Exposes 6 tools: listAll, getList, createList, addItem, completeItem, deleteItem
- Claude Desktop connects via MCP config in `~/.config/claude-desktop/config.json`

## Rules

- NEVER modify .pbxproj or .xcodeproj contents
- NEVER change the model schema without updating SampleData.swift
- NEVER use `ObservableObject` — SwiftData models are already Observable
- NEVER use `@StateObject` — use `@State` with `@Observable` classes
- NEVER use `NavigationView` — always `NavigationStack`
- NEVER add `@Observable` macro to `@Model` classes
- ALWAYS use `@Bindable` for form bindings to model properties
- ALWAYS test iCloud sync changes on two simulator instances

실제 CLAUDE.md: Reps (최소 SwiftData 앱 — 14개 파일)

작은 프로젝트에서는 CLAUDE.md를 간결하게 작성할 수 있습니다. 다음은 14개 파일로 구성된 운동 기록 앱 Reps의 패턴입니다. 짧은 CLAUDE.md도 6개 필수 섹션을 모두 다룬다는 점에 주목하세요.

# 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

14개 파일 프로젝트에 40줄짜리 CLAUDE.md입니다. 작성에는 10분이 걸리고, 에이전트가 혼란스러워하며 낭비할 몇 시간을 줄여줍니다.

실제 CLAUDE.md: Starfield Destroyer (SpriteKit + Metal — 32개 파일)

게임 프로젝트에는 더 많은 프레임워크별 컨텍스트가 필요합니다. 에이전트는 scene graph, physics category, game state machine을 이해해야 합니다.

# Starfield Destroyer - Space Shooter

**Bundle ID:** `com.941apps.StarfieldDestroyer`
**Target:** iOS 26+
**Architecture:** SpriteKit + Metal post-processing + Game Center
**Swift version:** 6.2

## Game Overview

99 levels across 3 galaxies. 8 unlockable ships with different stats.
Game Center leaderboards and achievements. Metal shader post-processing
for bloom and screen effects.

## File Structure

```
StarfieldDestroyer/
├── StarfieldDestroyerApp.swift    # App entry, Game Center auth
├── GameScene.swift                # Main game scene, update loop
├── MenuScene.swift                # Title screen, ship selection
├── Entities/
│   ├── PlayerShip.swift           # Player node with physics, weapons, shields
│   ├── EnemyShip.swift            # Enemy base class with AI behaviors
│   ├── Bullet.swift               # Bullet pool node
│   ├── PowerUp.swift              # Collectible power-ups
│   └── Boss.swift                 # Boss enemies (levels 33, 66, 99)
├── Systems/
│   ├── LevelManager.swift         # Level progression, wave spawning
│   ├── PhysicsCategory.swift      # UInt32 bitmask categories
│   ├── CollisionHandler.swift     # Contact delegate methods
│   ├── ScoreManager.swift         # Score tracking, multipliers
│   ├── ParticleManager.swift      # Explosion, trail, shield emitters
│   └── AudioManager.swift         # Sound effects, background music
├── UI/
│   ├── HUDNode.swift              # Score, health, level display
│   ├── ShipSelectView.swift       # SwiftUI ship selection (UIHostingController)
│   ├── GameOverView.swift         # Game over screen with score submission
│   └── PauseMenu.swift            # Pause overlay
├── Metal/
│   ├── MetalRenderer.swift        # Post-processing render pipeline
│   ├── BloomShader.metal          # Bloom post-process effect
│   └── ShaderTypes.h              # Shared uniforms (bridging header)
├── Data/
│   ├── ShipData.swift             # 8 ship definitions (speed, damage, shields)
│   ├── LevelData.swift            # 99 level configurations
│   └── AchievementData.swift      # Game Center achievement definitions
└── GameCenterManager.swift        # Leaderboard/achievement submission
```

## SpriteKit Scene Hierarchy

```
GameScene (SKScene)
├── backgroundLayer (zPosition: -100)
│   └── StarfieldNode (parallax scrolling, 3 layers)
├── gameLayer (zPosition: 0)
│   ├── playerShip (zPosition: 10)
│   ├── enemyContainer (zPosition: 5)
│   ├── bulletPool (zPosition: 8) — pre-allocated 50 bullets
│   └── powerUpContainer (zPosition: 3)
├── effectsLayer (zPosition: 50)
│   └── ParticleManager (explosion + trail emitters)
└── hudLayer (zPosition: 100)
    ├── scoreLabel (SKLabelNode)
    ├── healthBar (custom SKShapeNode)
    └── levelLabel (SKLabelNode)
```

## Physics Categories

```swift
struct PhysicsCategory {
    static let none:      UInt32 = 0
    static let player:    UInt32 = 0b1        // 1
    static let enemy:     UInt32 = 0b10       // 2
    static let bullet:    UInt32 = 0b100      // 4
    static let powerUp:   UInt32 = 0b1000     // 8
    static let shield:    UInt32 = 0b10000    // 16
    static let bossBullet:UInt32 = 0b100000   // 32
}

// Contact pairs:
// player + enemy → damage
// player + powerUp → collect
// bullet + enemy → destroy
// player + bossBullet → damage
```

## Game State Machine

```
.menu → .playing → .paused → .playing
                 → .gameOver → .menu
                 → .bossIntro → .playing
                 → .levelComplete → .playing (next level)
```

## Metal Post-Processing

- Bloom shader: `BloomShader.metal` — multi-pass Gaussian blur + additive blend
- Uniforms: `PostProcessUniforms { float intensity; float threshold; float2 resolution; }`
- Applied after SpriteKit renders each frame via `SKView.presentScene(:transition:)`
- DO NOT modify Metal shaders without testing on device

## Build & Test

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

## Rules

- NEVER modify .pbxproj
- NEVER modify PhysicsCategory bitmasks (breaks all collision detection)
- NEVER change the scene hierarchy z-ordering without understanding render order
- NEVER modify ShaderTypes.h without updating both Swift and Metal references
- Add new enemies by subclassing EnemyShip, not by modifying it
- Bullet pooling: recycle via removeFromParent() + re-add, never allocate new
- Game Center: always check isAuthenticated before submitting scores

실제 CLAUDE.md: amp97 (Metal + Audio Visualization — 41개 파일)

Metal 프로젝트에는 가장 많은 프레임워크별 컨텍스트가 필요합니다. 에이전트가 시각적 출력을 검증할 수 없기 때문입니다.

# 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

프로젝트 규모에 맞춰 CLAUDE.md 확장하기

적절한 상세 수준은 파일 수와 프레임워크 복잡도에 따라 달라집니다.

과하게 문서화하는 비용은 거의 0에 가깝습니다(에이전트는 필요 없는 부분을 건너뜁니다). 문서화가 부족할 때의 비용은 큽니다(에이전트가 코드베이스와 충돌하는 패턴을 만들어냅니다).

CLAUDE.md 체크리스트

iOS 프로젝트용 CLAUDE.md를 만들거나 검토할 때 이 체크리스트를 사용하세요.

• [ ] bundle ID와 deployment target이 명시되어 있음
• [ ] Swift 버전과 아키텍처 패턴이 이름으로 명시되어 있음
• [ ] 인라인 목적 주석이 있는 파일 구조
• [ ] 올바른 scheme과 destination이 포함된 빌드 명령
• [ ] 올바른 scheme과 destination이 포함된 테스트 명령
• [ ] MCP 선호 사항 명시(“xcodebuild보다 build_sim 선호”)
• [ ] @Observable 규칙(ObservableObject는 절대 사용하지 않음)
• [ ] NavigationStack 규칙(NavigationView는 절대 사용하지 않음)
• [ ] .pbxproj 금지
• [ ] 프레임워크별 컨텍스트(HealthKit 권한, SwiftData 관계, SpriteKit hierarchy, Metal pipeline)
• [ ] 플랫폼 가용성 guard가 문서화되어 있음(#if canImport, #if os)
• [ ] 핵심 singleton과 공유 패턴이 문서화되어 있음
• [ ] 알려진 제한 사항이나 주의점이 명시되어 있음

첫 Agent Session

MCP 설정을 마치고 프로젝트에 CLAUDE.md가 있다면, 효과적인 첫 session을 이렇게 진행할 수 있습니다. 여기서는 Claude Code CLI를 사용하지만, workflow는 어떤 runtime에도 적용됩니다.

1단계: Agent가 프로젝트를 볼 수 있는지 확인하세요

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.

agent가 CLAUDE.md 내용을 언급하지 않는다면, 파일이 project root(.xcodeproj 또는 Package.swift와 같은 디렉터리)에 있는지 확인하세요.

2단계: 상태 확인 Build를 실행하세요

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.

3단계: Test를 실행하세요

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.

4단계: 기능을 구현하세요

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

.pbxproj를 수정하지 않겠다는 agent의 메모는 CLAUDE.md의 규칙이 적용된 결과입니다. 이 규칙이 없으면 agent는 project file 수정을 시도하고, 높은 확률로 파일을 손상시킵니다.

iOS에서 Agents가 잘하는 일

다음은 agents가 최소한의 사람 검토만으로도 일관되게 정확하고 production-ready한 결과물을 만들어내는 작업들입니다.

SwiftUI Views와 Modifiers

agents는 SwiftUI의 선언형 문법 패턴을 깊이 인식합니다. View 구성, modifier chain, state binding, layout은 agent의 training data와 잘 맞습니다. SwiftUI의 API 영역이 문서화가 잘 되어 있고 패턴도 매우 일관적이기 때문입니다.

agents가 뛰어난 영역: - 설명을 바탕으로 새 view 만들기(“X, Y, Z용 toggle이 있는 settings sheet를 만들어 주세요”) - modifier chain 적용하기(.glassEffect(), .sensoryFeedback(), .navigationTitle()) - layout pattern 변환하기(VStack에서 LazyVGrid로, List에서 ScrollView로) - SwiftData model에 @Bindable form binding 구현하기 - sample data로 preview provider 만들기

훌륭한 결과를 만드는 prompt 예시:

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.

구체성이 중요합니다. “settings view를 만들어 주세요”라고 하면 일반적인 결과물이 나옵니다. “SettingsSheet.swift의 기존 pattern과 맞는 SettingsView를 만들어 주세요”라고 하면 codebase와 일관된 결과물이 나옵니다.

SwiftData Models와 Queries

agents는 SwiftData의 @Model macro, relationship, @Query pattern을 안정적으로 처리합니다. framework의 선언적인 성격(Django ORM 또는 SQLAlchemy와 비슷함)은 agent가 여러 codebase에서 본 pattern과 잘 맞습니다.

agents가 뛰어난 영역: - relationship이 있는 @Model class 정의하기 - sort descriptor와 predicate를 사용해 @Query 작성하기 - modelContext를 통한 CRUD 작업 구현하기 - schema version 간 migration plan 만들기 - preview data와 test fixture 만들기

agents에게 지침이 필요한 영역: - 복잡한 #Predicate expression(SwiftData의 predicate DSL에는 agent가 항상 알지는 못하는 제한이 있습니다. 알려진 제한은 CLAUDE.md에 문서화하세요) - CloudKit sync 설정(SwiftData를 통해 자동으로 처리되지만, agent가 manual sync를 구현하려 할 수 있습니다)

Unit Tests

agent가 작성한 unit test는 iOS project에서 일관되게 품질이 높습니다. agent는 XCTest pattern, async test method, setup/teardown lifecycle을 이해합니다.

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는 setUp()과 tearDown(), 적절한 assertion, timer 기반 test를 위한 async 처리를 갖춘 잘 구조화된 XCTest case를 만들어냅니다.

Refactoring과 Pattern 적용

agents는 기계적인 refactoring에 뛰어납니다. view를 component로 추출하고, ObservableObject를 @Observable로 변환하고, NavigationView에서 NavigationStack으로 migration하고, 여러 파일에 걸쳐 일관된 pattern을 적용하는 작업입니다.

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는 각 파일을 체계적으로 처리하고, 변환을 정확히 적용하며, 기존 기능을 유지합니다. 이는 높은 leverage를 가진 작업입니다. 사람이 직접 편집하면 1시간 걸릴 refactoring도 몇 분 안에 거의 완벽한 정확도로 끝납니다.

MCP를 통한 Build Error 진단

구조화된 MCP output이 있으면 agents는 대부분의 개발자보다 build error를 더 빠르게 진단합니다. agent는 error JSON를 읽고, 정확한 file과 line을 찾고, error message를 이해한 뒤 fix를 적용합니다. 많은 경우 한 번의 turn으로 끝납니다.

agents가 자율적으로 고치는 error: - 누락된 import - type mismatch - protocol conformance 누락 - deprecated API 사용(대체 항목 포함) - 누락된 required initializer parameter - access control 위반

agents에게 도움이 필요한 error: - 모호한 type resolution(여러 module이 같은 type을 정의하는 경우) - 복잡한 generic constraint 실패 - macro expansion error(agent는 expanded macro output을 볼 수 없습니다)

Simulator 관리

agents는 MCP를 통해 simulator lifecycle을 잘 처리합니다.

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

agent는 list_sims를 호출해 사용 가능한 runtime을 찾고, boot_sim으로 simulator를 시작하고, build_sim으로 build와 install을 수행하며, screenshot으로 capture합니다. 모두 구조화된 MCP call을 통해 처리합니다.

iOS에서 Agents가 잘하지 못하는 것

Agents가 어디에서 실패하는지 솔직하게 정리합니다. 이 경계를 알아두면 좌절과 토큰 낭비를 줄일 수 있습니다.

.pbxproj 파일 수정 — 절대 금지

iOS agent 개발에서 가장 중요한 규칙입니다. .pbxproj 파일은 Xcode의 프로젝트 설정입니다. UUID 참조, 빌드 단계 목록, 타깃 멤버십이 들어 있는 구조화된 텍스트 파일입니다. 겉으로는 사람이 읽을 수 있어 보이지만, 실제로는 AI agents가 파싱하기 거의 불가능합니다.

Agents가 .pbxproj에서 실패하는 이유: - 이 파일은 위치가 중요한 커스텀 형식을 사용합니다(JSON도 아니고, YAML도 아니며, XML도 아닙니다) - 모든 항목이 UUID로 교차 참조됩니다. 파일 하나를 추가하려면 보통 3-5개의 서로 다른 섹션을 일관되게 업데이트해야 합니다 - 문자 하나만 잘못 들어가도 전체 프로젝트 파일이 손상됩니다 - Xcode의 .pbxproj 병합 충돌 해결은 원래도 취약합니다. agent가 편집하면 더 나빠집니다

Agent가 .pbxproj를 편집하면 벌어지는 일: 1. 편집은 성공한 것처럼 보입니다(agent가 “file updated”라고 보고합니다) 2. Xcode가 프로젝트 열기를 거부합니다(“The project file is corrupted”) 3. git 기록에서 복구하느라 15-60분을 씁니다 4. PreToolUse hook을 추가해야 한다는 사실을 배우게 됩니다(Hooks 참조)

작업 흐름: Agent는 Swift 파일을 만듭니다. 사용자는 그 파일을 Xcode 프로젝트에 직접 추가합니다(Xcode로 드래그하거나 File > Add Files 사용). 파일당 5초면 충분하며, 몇 시간짜리 복구 작업을 막아줍니다.

Swift Package Manager 프로젝트의 경우: 이 제한은 덜 심각합니다. Package.swift는 agents가 안정적으로 편집할 수 있는 표준 Swift 파일입니다. 프로젝트가 SPM만 사용한다면(.xcodeproj 없음), agent가 전체 프로젝트 구조를 관리할 수 있습니다.

복잡한 Interface Builder / Storyboard 편집

프로젝트가 Interface Builder(.xib 파일)나 Storyboards(.storyboard 파일)를 사용한다면, agents는 이를 의미 있게 편집할 수 없습니다. 이들은 자동 생성 UUID, 제약 조건 참조, outlet 연결을 포함한 XML 파일이며, 텍스트 편집이 아니라 시각적 편집을 위해 설계되었습니다.

완화 방법: 새 view에는 SwiftUI만 사용하세요. 프로젝트에 기존 Interface Builder 파일이 있다면 그대로 두고, 새 UI는 SwiftUI로 만드세요.

성능 최적화

Agents는 올바른 코드는 작성하지만, 반드시 성능이 좋은 코드를 작성하지는 않습니다. Agents는 앱을 프로파일링하거나 병목을 찾거나 프레임 속도를 측정할 수 없습니다. 성능 최적화에는 다음이 필요합니다.

1. Instruments 프로파일링(시각적 도구이며 agent가 접근할 수 없습니다)
2. 특정 기기의 GPU/CPU 특성에 대한 이해
3. 측정 기반의 반복적인 변경

이 문제가 드러나는 곳: - Metal shader 최적화(agent는 유효한 Metal을 작성하지만 GPU 프레임 시간을 측정할 수 없습니다) - SwiftUI view body 복잡도(agent는 다시 그리기 오버헤드를 유발하는 깊게 중첩된 views를 만듭니다) - Core Data / SwiftData fetch 최적화(agent는 올바른 query를 작성하지만 큰 dataset에서는 느릴 수 있습니다)

완화 방법: 구현에는 agents를 사용하고, Instruments로 직접 프로파일링한 다음, 직접 식별한 구체적인 최적화를 agent에게 적용하게 하세요.

코드 서명과 프로비저닝

Agents는 오류 메시지를 읽는 것 이상으로 코드 서명 문제를 디버깅할 수 없습니다. 프로비저닝 프로파일 관리, 인증서 생성, entitlement 설정, App Store 제출은 근본적으로 Apple Developer portal, Keychain Access, Xcode의 signing UI를 사용하는 사람이 수행해야 하는 작업 흐름입니다.

Agent가 보는 것: “Signing for ‘Return’ requires a development team.”

Agent가 볼 수 없는 것: 인증서가 만료되었는지, 프로비저닝 프로파일에 기기가 포함되어 있는지, bundle ID가 App ID와 일치하는지, entitlements 파일이 올바른지 여부입니다.

완화 방법: 모든 signing은 Xcode의 Signing & Capabilities 탭에서 처리하세요. Signing 실패를 agents에게 디버깅해 달라고 요청하지 마세요.

복잡한 Metal Shader 디버깅

Agents는 문법적으로 올바른 Metal Shading Language(MSL)를 작성하지만, 시각적 출력이나 GPU 쪽 문제를 검증할 수 없습니다. Metal shaders는 GPU에서 실행됩니다. Agent에게는 shader가 올바른 시각적 결과를 내는지 확인할 피드백 메커니즘이 없습니다.

Agents가 Metal로 할 수 있는 일: - 설명을 바탕으로 vertex와 fragment shaders 작성 - Swift에서 Metal render pipeline 설정 - 데이터 병렬 작업용 compute shaders 생성 - .metal 파일의 컴파일 오류 수정

Agents가 Metal로 할 수 없는 일: - Shader 출력의 시각적 정확성 검증 - GPU 성능 디버깅(프레임 시간, occupancy, memory bandwidth) - 시각적 artifacts 진단(banding, precision issues, 잘못된 color space) - 서로 다른 GPU 아키텍처에서 테스트(A-series와 M-series의 동작 차이)

완화 방법: Metal shaders는 실제 기기에서 테스트하세요. Simulator의 Metal 구현은 기기 GPU 동작을 대표하지 않습니다. 시각적 디버깅에는 Xcode의 GPU Frame Capture를 사용하세요.

시각적 레이아웃 검증

Agents는 앱의 UI를 볼 수 없습니다. SwiftUI layout 코드를 작성하고 컴파일 여부는 확인할 수 있지만, 결과 화면이 올바르게 보이는지는 판단할 수 없습니다. 10픽셀 어긋나게 렌더링되거나, 잘못된 font weight를 사용하거나, 요소가 겹치는 view도 빌드 오류를 내지 않으며 모든 로직 테스트를 통과합니다.

완화 방법: UI 변경은 직접 시각적으로 검토하세요. Xcode의 SwiftUI Previews(또는 headless 렌더링용 Apple MCP를 통한 RenderPreview)로 layout을 확인하세요. 자동화된 시각적 회귀 감지를 위해 swift-snapshot-testing 같은 라이브러리로 snapshot testing을 고려하세요.

iOS 개발을 위한 Hooks

Hooks는 에이전트 워크플로의 특정 지점에서 정해진 방식으로 실행되는 셸 명령어예요. 이는 규칙을 강제하는 장치로, “.pbxproj를 편집하지 마세요”(에이전트가 무시할 수 있는 권고)와 “.pbxproj를 편집할 수 없습니다”(강제 차단)의 차이를 만들어요.

Hook 시스템의 배경은 Claude Code Hooks 가이드를 참고하세요. 이 섹션에서는 iOS에 특화된 Hook 패턴을 다뤄요.

PreToolUse: .pbxproj 쓰기 차단

모든 iOS 프로젝트에서 가장 중요한 Hook이에요. 이 Hook은 에이전트가 .pbxproj 파일, .xcodeproj/ 디렉터리 및 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'"
      }
    ]
  }
}

프로젝트 루트의 .claude/settings.json에 추가하거나, 모든 프로젝트를 보호하려면 ~/.claude/settings.json에 추가하세요.

작동 방식: 에이전트가 패턴과 일치하는 파일에 Edit 또는 Write 도구를 사용하려고 하면 Hook이 실행돼요. Hook은 파일 경로를 감지하고 표준 오류에 경고를 출력한 뒤 코드 2로 종료해 도구 사용을 차단해요. 에이전트는 오류 메시지를 전달받고 접근 방식을 조정해요.

차단 대상: - .pbxproj 직접 편집 - .xcodeproj/ 또는 .xcworkspace/ 디렉터리 내부의 모든 파일 - Interface Builder 파일 (.xib, .storyboard)

PostToolUse: SwiftFormat으로 저장 시 자동 포맷

에이전트가 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 swiftformat \"$FP\" --quiet 2>/dev/null; fi'"
      }
    ]
  }
}

요구 사항: SwiftFormat이 설치되어 있어야 해요 (brew install swiftformat).

중요한 이유: 에이전트는 문법상 올바른 Swift 코드를 생성하지만 포맷 규칙을 일관되게 따르지는 않아요. SwiftFormat은 들여쓰기, 중괄호 위치, import 순서를 통일해요.⁸ 저장 시 자동 포맷 Hook을 사용하면 에이전트가 수정한 모든 Swift 파일이 사용자에게 표시되기 전에 자동으로 포맷돼요.

선택 사항: 프로젝트 루트에 .swiftformat 설정 파일을 추가해 포맷 규칙을 맞춤 설정할 수 있어요.

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

PostToolUse: SwiftLint 자동 실행

SwiftLint를 사용한다면 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'"
      }
    ]
  }
}

|| true는 린트 경고가 에이전트 작업을 차단하지 않도록 해요. 린트 위반 시 작업을 차단하려면 이를 제거하세요.

PostToolUse: 변경 후 자동 빌드

빠르고 적극적으로 피드백을 받으려면 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'"
      }
    ]
  }
}

경고: 비용이 많이 드는 방식이에요. 파일을 편집할 때마다 빌드가 실행돼요. 신중하게 사용하세요. 즉각적인 빌드 피드백이 필요한 디버깅 세션에서 가장 유용해요. 일반적인 개발에서는 에이전트가 준비됐을 때 MCP를 통해 직접 빌드를 실행하도록 하세요.

PreToolUse: Entitlement 수정 차단

에이전트가 실수로 Entitlement 파일을 수정하지 못하도록 보호하세요.

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

통합 iOS Hook 설정

다음은 제가 모든 iOS 프로젝트에서 사용하는 전체 .claude/settings.json이에요.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash -c 'INPUT=$(cat); FP=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if echo \"$FP\" | grep -qE \"\\.(pbxproj|xcworkspace|xib|storyboard|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'"
      }
    ]
  }
}

이 설정은 2가지를 보장해요. 1. 에이전트가 Xcode 프로젝트 파일을 손상할 수 없어요(PreToolUse 차단) 2. 에이전트가 수정한 모든 Swift 파일이 자동으로 포맷돼요(PostToolUse 포맷)

에이전트와 잘 맞는 아키텍처 패턴

모든 Swift 아키텍처가 에이전트와 똑같이 잘 맞는 것은 아니에요. 다음 패턴은 명시적이고 일관적이며 학습 데이터에도 충분히 포함되어 있어 가장 좋은 결과를 얻을 수 있어요.

@Observable 사용하기(ObservableObject는 사용하지 않기)

iOS 26 이상을 대상으로 한다면 @Observable만 사용해야 해요. 최신 패턴인 동시에 에이전트와도 잘 맞는 패턴이에요.

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

@Observable이 에이전트와 잘 맞는 이유: 패턴이 더 단순하고(@Published 주석이 필요하지 않아요), 소유권 모델도 더 명확해요(@StateObject와 @ObservedObject 대신 @State를 사용해요). 구성 요소가 적기 때문에 에이전트가 만드는 버그도 줄어들어요.

CLAUDE.md에 명시하세요: iOS 26을 대상으로 하더라도 에이전트는 학습 데이터에 있는 ObservableObject 패턴으로 되돌아갈 때가 있어요. 사용을 명시적으로 금지하면 이를 방지할 수 있어요.

NavigationStack 사용하기(NavigationView는 사용하지 않기)

// CORRECT
NavigationStack {
    List(items) { item in
        NavigationLink(value: item) {
            ItemRow(item: item)
        }
    }
    .navigationDestination(for: Item.self) { item in
        ItemDetailView(item: item)
    }
}

// WRONG
NavigationView {
    List(items) { item in
        NavigationLink(destination: ItemDetailView(item: item)) {
            ItemRow(item: item)
        }
    }
}

NavigationStack은 iOS 16 이상에서 사용할 수 있으며, 새 코드에 사용해야 하는 유일한 내비게이션 패턴이에요. 타입 안전성을 갖춘 navigationDestination(for:) 패턴을 사용하면 에이전트가 잘못된 내비게이션 링크를 만들지 않도록 방지할 수 있어요.

데이터 유지에 SwiftData 사용하기

SwiftData 모델은 에이전트 지원 개발에 가장 깔끔한 데이터 유지 패턴이에요.

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

SwiftData를 다루는 에이전트의 핵심 규칙: 1. @Model 클래스에는 Observable이 자동으로 적용되므로 @Observable을 추가하지 마세요 2. 폼 바인딩에는 @Bindable을 사용하세요: @Bindable var item: GroceryItem 3. 뷰의 반응형 데이터에는 @Query를 사용하세요: @Query var items: [GroceryItem] 4. 뷰가 아닌 코드에서는 modelContext.fetch()를 사용하세요 5. 관계 삭제에는 명시적인 규칙이 필요해요: .cascade, .nullify, .deny

Swift 6.2 동시성

새 프로젝트는 Swift 6.2 엄격한 동시성을 대상으로 하세요. 이는 도구 체인 버전이 아니라 언어 모드 선택이에요. 정식 Xcode 26.6의 Swift 6.3 컴파일러와 Xcode 27 베타의 Swift 6.4 모두 이 패턴을 변경 없이 빌드해요.¹⁷¹⁸

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

동시성에 관한 에이전트 지침: - 모든 뷰 모델에 @MainActor를 표시하세요(데이터 경합 경고를 방지해요) - 모든 비동기 작업에는 async/await를 사용하세요(완료 핸들러는 사용하지 마세요) - 액터 사이에서 전달되는 값 타입은 Sendable로 만드세요 - 뷰의 비동기 초기화에는 Task { }를 사용하세요 - 성능상 필요하다는 사실을 측정으로 확인한 경우에만 nonisolated를 사용하세요

Liquid Glass 디자인 시스템(iOS 26 이상)

iOS 26에는 Liquid Glass 디자인 시스템이 도입되었어요. 명확한 지침을 제공하면 에이전트도 이를 잘 다룰 수 있어요.

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

CLAUDE.md에 포함하세요: “섹션 배경과 카드 컨테이너에 .glassEffect()를 사용하세요. 내비게이션 바에는 iOS 26에서 유리 소재가 자동으로 적용돼요. 사용자 지정 소재로 유리 효과를 직접 재현하지 말고 시스템 수정자를 사용하세요.”

프레임워크별 맥락

각 Apple 프레임워크에는 에이전트별로 고려해야 할 사항이 있어요. 이 섹션에서는 8개 앱에서 사용한 프레임워크를 다뤄요.

HealthKit

사용하는 앱: Return, Water

HealthKit은 권한 처리와 플랫폼 보호 조건을 신중하게 다뤄야 해요.

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

HealthKit을 위한 에이전트 규칙: - 항상 HKHealthStore.isHealthDataAvailable()로 보호하세요 - 권한이 있다고 가정하지 말고 쓸 때마다 확인하세요 - 여러 플랫폼을 지원하는 코드에는 #if canImport(HealthKit)을 사용하세요(HealthKit은 tvOS에서 사용할 수 없어요) - HealthKit에서 제공하는 범위를 넘어 건강 데이터를 로컬에 저장하지 마세요 - Info.plist에 NSHealthShareUsageDescription과 NSHealthUpdateUsageDescription을 모두 포함하세요

SpriteKit

사용하는 앱: TappyColor, Starfield Destroyer

SpriteKit의 장면 그래프 모델을 다루려면 에이전트에 명확한 지침을 제공해야 해요.

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

SpriteKit에서 에이전트가 잘하는 작업: - SKAction 시퀀스와 그룹 만들기 - 물리 바디와 접촉 감지 설정하기 - 게임 상태 머신 구현하기 - HUD 오버레이 만들기

SpriteKit에서 에이전트가 어려워하는 작업: - 성능에 민감한 게임 루프(에이전트가 프레임마다 불필요한 작업을 추가해요) - 복잡한 물리 시뮬레이션(정밀도가 필요하다면 SKPhysicsBody보다 사용자 지정 물리 처리가 더 나아요) - 파티클 효과 조정(시각적 확인과 반복 작업이 필요해요)

Metal

사용하는 앱: amp97, Water, Starfield Destroyer

Metal은 에이전트가 가장 어려워하는 프레임워크예요. GPU 프로그래밍 모델은 CPU 쪽 Swift와 근본적으로 다르며, 에이전트는 시각적 출력을 검증할 수 없어요.

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

Metal 프로젝트의 CLAUDE.md에 포함할 내용: - Uniforms 구조체 정의(Swift와 MSL에서 공유) - 렌더 파이프라인 상태 설정 패턴 - 버퍼 인덱스와 각 인덱스의 용도 - 존재하는 셰이더와 각 셰이더의 역할 - 알려진 정밀도 문제(half와 float)

Live Activities

사용하는 앱: Return

Live Activities에는 구체적인 설정이 필요하지만, 문서화한 뒤에는 에이전트가 이를 잘 처리해요.

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

사용하는 앱: 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)

멀티 플랫폼 패턴

Return은 iOS, watchOS, tvOS를 지원해요. 에이전트를 활용한 멀티 플랫폼 개발에서는 플랫폼 경계를 명확하게 문서화해야 해요.

공유 코드 구성

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

에이전트 규칙: “Shared/에 있는 파일을 변경하면 모든 플랫폼에 영향을 줍니다. 플랫폼 디렉터리에 있는 파일을 변경하면 영향이 해당 플랫폼으로 제한됩니다. 파일을 수정하기 전에 항상 어느 디렉터리에 있는지 확인하세요.”

플랫폼 가용성 가드

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

에이전트 가이드: “플랫폼별 프레임워크를 사용할 때는 항상 #if canImport() 또는 #if os() 가드를 사용하세요. 프레임워크가 모든 타깃에서 사용할 수 있다고 가정하지 마세요.”

플랫폼별 UI 적응

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

고급 워크플로

자율 빌드-테스트-수정 루프

가장 강력한 패턴은 에이전트에 기능 명세를 제공하고 빌드-테스트-수정 사이클을 자율적으로 반복하게 하는 것이에요.

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.

에이전트는 코드를 작성하고 MCP를 통해 빌드한 뒤, 구조화된 오류를 읽고 수정하며 이 과정을 반복해요. 사람이 5~10번의 빌드-오류-수정 사이클을 거쳐야 하는 기능도 하나의 자율 루프에서 완성할 수 있어요.

이 방식이 효과적인 경우: 승인 기준이 명확하게 정의된 기능이에요.

이 방식이 실패하는 경우: 범위가 열려 있는 기능(“보기 좋게 만들어 주세요”), 성능에 민감한 코드, 또는 시각적 검증이 필요한 모든 작업이에요.

iOS용 서브에이전트 위임

Claude Code의 서브에이전트 시스템은 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.

서브에이전트는 별도의 컨텍스트 창에서 문서와 코드 패턴을 탐색하고 요약을 반환하며, 메인 세션은 추천 사항을 구현해요. 이렇게 하면 조사 작업이 기본 컨텍스트를 소모하지 않아요.

앱 간 패턴 적용

일관된 패턴을 사용하는 여러 iOS 앱을 유지 관리한다면, 에이전트가 한 앱의 패턴을 다른 앱에 적용할 수 있어요.

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.

에이전트는 원본 패턴을 읽고 구조를 이해한 다음 대상 프로젝트에 일관된 구현을 만들어요.

듀얼 에이전트 검토 (Claude + Codex)

중요한 변경에는 서로 다른 모델 계열의 에이전트 2개를 사용하세요.

1. Claude Code이 구현을 작성합니다
2. Codex CLI이 별도의 단계에서 이를 검토합니다

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

서로 다른 모델 계열은 서로 다른 유형의 오류를 찾아내요. 미묘한 버그가 쉽게 생기는 Metal 셰이더와 동시성 패턴에서는 특히 가치가 커요.

듀얼 검토가 단일 검토에서 놓치는 문제:

듀얼 검토의 목적은 더 많은 버그를 찾는 것이 아니라 서로 다른 버그를 찾는 것이에요. 각 모델 계열은 패턴 인식에서 서로 다른 실패 모드를 보여요.

여러 앱에 걸친 일괄 작업

프레임워크 또는 패턴 변경이 여러 앱에 영향을 미칠 때는 다음과 같이 진행하세요.

# 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

주의해서 사용하세요. --dangerously-skip-permissions 플래그는 비대화형 모드에 필요하지만 모든 안전 검사를 우회해요. .pbxproj 파일을 보호할 수 있도록 PreToolUse hooks가 마련되어 있는지 확인하세요.

Apple의 온디바이스 LLM을 사용하는 앱

앱에서 Apple의 Foundation Models 프레임워크를 호출한다면(예: 오프라인 요약, 분류 또는 구조화된 출력 생성), 에이전트는 프롬프트 예산을 알아야 해요. iOS 26.4에서는 이전의 4096토큰 추정을 대체하는 SystemLanguageModel용 API 2개가 추가되었어요. contextSize는 모델이 하나의 대화에서 받을 수 있는 최대 토큰 수이고, tokenCount(for:)는 주어진 프롬프트의 실제 비용 토큰 수를 반환하는 async throws API예요.³¹ 두 API 모두 @backDeployed(before: iOS 26.4)이므로 #available 사다리 없이 모든 FM 지원 OS 버전에서 사용할 수 있어요.

프롬프트 구성 코드를 생성할 때 에이전트가 따라야 하는 패턴은 다음과 같아요.

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
}

앱에서 SystemLanguageModel을 사용한다면 이 패턴을 CLAUDE.md에 추가하세요. 그렇지 않으면 에이전트는 이전의 4096 하드코드로 되돌아가 더 큰 컨텍스트 창을 제공하는 기기에서 프롬프트를 조용히 잘라낼 수 있어요. tokenCount(for:)의 async throws 시그니처는 핵심이에요. 동기 버전을 붙여 넣는 에이전트는 컴파일에 실패해요.

실제 사례 연구

추상적인 조언은 쉬워요. 여기서는 실패 사례까지 포함해, agent가 도와주는 iOS 개발이 실제로 어떻게 작동하는지 보여주는 8개 앱의 구체적인 시나리오를 소개해요.

사례 연구 1: Return에 TV 앱 추가하기 (성공)

작업: 이미 iOS와 watchOS 버전이 있던 명상 타이머 Return에 tvOS 타깃을 추가하는 일이었어요. TV 앱에는 Siri Remote 내비게이션, 대형 화면 UI, iOS 앱과의 설정 동기화가 필요했어요.

agent가 잘한 것: - 기존 iOS TimerManager를 읽고, tvOS에서 사용할 수 없는 Live Activities와 HealthKit을 제외한 TVTimerManager를 만들었어요 - Siri Remote 포커스 내비게이션용 커스텀 버튼 스타일(TVCapsuleButtonStyle, TVCircleButtonStyle)을 만들었어요 - Siri Remote로 사용할 수 없는 wheel picker를 +/- 버튼으로 대체하는 TVStepper 컴포넌트를 만들었어요 - App Groups(group.com.941apps.Return)를 통해 설정 동기화를 구현했어요 - 공유 코드 전반에 #if os(tvOS) guard를 추가했어요 - MCP에서 platform=tvOS Simulator,name=Apple TV로 빌드하고 테스트했어요

제가 직접 해야 했던 것: - Xcode에서 tvOS 타깃 만들기(File > New > Target > tvOS App) - 새 타깃을 Xcode 프로젝트에 추가하기(.pbxproj 변경) - TV 타깃의 App Groups entitlement 설정하기 - TV 타깃을 기존 scheme에 추가하거나 새 scheme 만들기 - agent가 만든 모든 Swift 파일을 TV 타깃에 직접 추가하기 - Siri Remote 내비게이션을 직접 테스트하기(agent는 포커스 동작을 평가할 수 없어요)

결과: agent가 도와준 약 3시간의 작업으로 15개의 새 Swift 파일과 완전히 작동하는 TV 앱이 만들어졌어요. 제 추정으로는 agent가 구현 작업의 약 80%를 처리했고, 저는 Xcode UI 상호작용이 필요한 부분(entitlements, target setup, capability flags)과 실제 Apple TV에서의 수동 포커스 테스트를 맡았어요. 이 코드베이스에서 비슷한 기능을 agent 없이 출시해 본 경험에 비추면, 같은 작업을 혼자 했다면 며칠이 걸렸을 거예요.

사례 연구 2: amp97의 Metal Shader 디버깅 (부분 실패)

작업: oscilloscope shader에 energy 기반 intensity 시스템을 추가하는 일이었어요. 시각화가 오디오 energy에 맞춰 pulse해야 했어요.

일어난 일: 1. agent는 uEnergy uniform과 HDR tonemapping을 추가하는 유효한 Metal shader 수정을 작성했어요 2. 코드는 오류 없이 컴파일됐어요 3. 기기에서는 시각화가 완전히 흰색으로 보였어요. intensity 계수가 너무 높았어요(0.30이 아니라 3.5) 4. agent는 흰 화면을 볼 수 없어서 피드백 신호가 없었어요 5. 제가 눈으로 문제를 확인하고 agent에게 계수를 낮추라고 요청했어요 6. agent는 계수를 낮췄지만, 전체 energy state machine이 너무 복잡해서 visualizer를 다른 방식으로 망가뜨렸어요 7. 전부 되돌렸어요. 두 커밋(67959ed, cda4830)이 869d914에서 revert됐어요

교훈: Metal shader는 agent 지원 개발에서 가장 어려운 영역이에요. 피드백 루프가 끊겨 있기 때문이에요. agent는 문법(컴파일됨)과 의미(올바른 타입)는 검증할 수 있지만, 출력(제대로 보이는지)은 검증할 수 없어요. 시각 동작을 바꾸는 shader 수정은 반드시 기기에서 사람이 확인해야 해요.

이후 CLAUDE.md에 추가한 내용: “DO NOT attempt energy state modifications to the oscilloscope shader without extremely careful coefficient testing. Previous attempt broke the visualizer with coefficients 10x too high.”

사례 연구 3: Banana List의 SwiftData 마이그레이션 (성공)

작업: 데이터 모델을 V1에서 V2로 마이그레이션하면서 GroceryItem에 quantity 필드를 추가하고, 관계가 있는 새 Category 모델을 추가하는 일이었어요.

agent가 한 일: 1. 기존 V1 모델 정의를 읽었어요 2. 새 필드와 관계가 포함된 V2 모델 정의를 만들었어요 3. SchemaMigrationPlan protocol conformance가 있는 GroceryMigrationPlan을 작성했어요 4. V1toV2 마이그레이션 단계를 구현했어요. 기본 quantity: 1과 category: nil을 추가했어요 5. 새 필드를 지원하도록 모든 view를 업데이트했어요 6. preview용 SampleData.swift를 업데이트했어요 7. MCP로 빌드하고 테스트를 실행했어요. 모두 통과했어요 8. 마이그레이션 전용 unit test를 만들었어요

핵심: SwiftData 마이그레이션은 Apple 문서와 학습 데이터에 충분히 반영된, 잘 정의된 protocol 패턴을 따르기 때문에 agent가 성공했어요. CLAUDE.md에 V1 모델이 명시적으로 문서화되어 있어서 agent는 무엇을 기준으로 마이그레이션하는지 이해했어요.

사례 연구 4: Return의 iCloud 세션 동기화 (복잡했지만 성공)

작업: 여러 기기 간 명상 세션 기록을 구현하는 일이었어요. Apple TV나 Mac에서 완료한 세션은 HealthKit 기록을 위해 iPhone으로 동기화되어야 했어요.

agent가 만든 것:

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

agent는 다음을 수행했어요. 1. UUID, 날짜, duration, source device, HealthKit sync status를 포함한 MeditationSession 데이터 모델을 만들었어요 2. iCloud 동기화를 위해 NSUbiquitousKeyValueStore를 관리하는 SessionStore singleton을 만들었어요 3. merge conflict resolution을 구현했어요(UUID 기반 중복 제거) 4. 플랫폼별 적응이 포함된 SessionHistoryView를 추가했어요(iOS에서는 swipe-to-delete, tvOS에서는 focus 기반) 5. 다른 기기에서 온 세션을 iPhone 쪽 HealthKit 동기화에 연결했어요

반복이 필요했던 부분: 초기 구현은 iPhone 앱이 background에서 실행되는 경우를 처리하지 못했어요(sync를 위한 foreground notification이 없음). agent에게 구체적인 지침이 필요했어요. “NSUbiquitousKeyValueStore.didChangeExternallyNotification을 사용해 background KV 변경 시 sync를 트리거하세요.” 이 힌트 이후 구현은 올바르게 작동했어요.

교훈: architecture가 명확히 설명되어 있으면 agent는 멀티 플랫폼 architecture 패턴을 잘 처리해요. iCloud sync 패턴은 사소하지 않지만, agent가 이해한 문서화된 Apple 패턴을 따릅니다. edge case(background sync)는 문서화가 충분하지 않아 사람이 가진 domain 지식이 필요했어요.

사례 연구 5: Starfield Destroyer의 Game Center 통합 (성공)

작업: space shooter에 Game Center leaderboards와 achievements를 추가하는 일이었어요.

agent가 잘한 것: - 앱 entry point에 GKLocalPlayer.local.authenticateHandler를 구현했어요 - score submission과 achievement reporting 메서드가 있는 GameCenterManager를 만들었어요 - 모든 Game Center 작업 전에 authentication state checking을 추가했어요 - offline case를 자연스럽게 처리했어요(Game Center 없이도 게임은 플레이되고, 재연결되면 제출됨) - 8-ship progression system에 맞는 achievement 정의를 만들었어요

수동 작업이 필요했던 것: - App Store Connect에서 leaderboards와 achievements 만들기(웹 포털이라 agent가 접근할 수 없음) - Xcode에서 Game Center entitlement 설정하기 - sandbox Game Center 계정으로 테스트하기(기기에서 수동 sign-in 필요)

Agent를 활용한 프로젝트 라이프사이클

새 iOS 프로젝트 시작하기

Agent의 도움을 받아 새 프로젝트를 시작할 때 가장 좋은 워크플로는 다음과 같습니다.

1단계: 사람이 설정하기 (15-30분) 1. Xcode 프로젝트를 만듭니다 (File > New > Project) 2. 서명과 capabilities를 설정합니다 3. 배포 대상과 지원 대상을 설정합니다 4. 필요한 entitlements를 추가합니다 (HealthKit, Game Center 등) 5. 프로젝트 정체성과 규칙을 담은 초기 CLAUDE.md를 만듭니다

2단계: Agent 구현 (몇 시간에서 며칠) 1. Agent가 데이터 모델을 만듭니다 (SwiftData, Core Data 또는 일반 structs) 2. Agent가 문서화된 패턴에 따라 views를 만듭니다 3. Agent가 manager/service classes에 비즈니스 로직을 구현합니다 4. Agent가 unit tests를 작성합니다 5. MCP를 통한 build-test-fix 루프를 실행합니다 (자율)

3단계: 사람이 통합하기 (30-60분) 1. Agent가 만든 파일을 Xcode targets에 추가합니다 2. 서명과 entitlements를 확인합니다 3. 실제 기기에서 테스트합니다 4. 시각적 레이아웃과 UX를 검토합니다 5. App Store Connect에 제출합니다

기존 프로젝트 유지 관리하기

이미 자리 잡은 앱을 계속 개발할 때는 다음을 사용합니다.

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]

Agent의 효과는 CLAUDE.md가 프로젝트의 현재 상태를 얼마나 잘 반영하느냐에 따라 커집니다. 중요한 새 기능을 추가하거나, 아키텍처 패턴을 바꾸거나, 새 frameworks를 도입할 때는 CLAUDE.md를 업데이트하세요.

Agent를 사용할 때와 사용하지 않을 때

Agent 정의 설정하기

Claude Code의 agent definition system(.claude/agents/)을 사용한다면 iOS 전용 Agent를 만드세요.

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

Claude Code 세션에서 @ios-developer로 이 Agent를 참조하세요.

Agent 지원 iOS 테스트 패턴

명확한 지침을 주면 Agent는 훌륭한 unit tests를 작성합니다. 가장 좋은 결과를 내는 패턴은 다음과 같습니다.

테스트 파일 구성

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

테스트 요청하기

효과적인 테스트 프롬프트:

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.

이 방식이 잘 작동하는 이유: 번호가 매겨진 acceptance criteria는 Agent에게 체크리스트를 제공합니다. 기존 테스트 파일을 참조하면 따라야 할 패턴이 정해집니다. setUp() 사용 방식을 지정하면 Agent가 얽힌 테스트 상태를 만들지 않게 됩니다.

효과적이지 않은 테스트 프롬프트:

Write tests for TimerManager.

이런 요청은 edge cases를 놓치고 프로젝트 패턴을 따르지 않을 수 있는 일반적이고 얕은 테스트를 만들어 냅니다.

Async 테스트 패턴

Timer 기반 코드와 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)
    }
}

Agent에게 다시 알려줘야 하는 핵심 패턴: - @MainActor classes를 테스트하는 test methods에는 @MainActor를 붙입니다 - Task.sleep 또는 async operations를 사용하는 tests에는 async throws를 사용합니다 - 시간 기반 assertions에는 tolerance를 둡니다 (정확히 1.0초가 아니라 1.1초) - 테스트 격리를 위해 깔끔한 setUp() / tearDown()을 사용합니다

Snapshot Testing

시각적 regression 감지를 위해 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.

Agent는 snapshot tests를 올바르게 설정하지만 reference images를 검토할 수는 없습니다. 초기 snapshots는 사람이 검토하고, 이후 변경에서는 Agent의 tests가 시각적 regressions를 잡아냅니다.

iOS 프로젝트의 컨텍스트 창 관리

1M 컨텍스트 창(Opus 5)은 크지만 무한하지는 않아요. iOS 프로젝트에서는 컨텍스트 관리와 관련해 특별히 고려할 점이 있어요.

iOS 파일의 토큰 비용

파일이 50개인 프로젝트: 모든 파일을 읽는 데 약 50,000-100,000개의 토큰이 사용되므로 1M 창에 충분히 들어가요. 에이전트는 전체 프로젝트를 컨텍스트에 담을 수 있어요.

파일이 100개 이상인 프로젝트: 필요한 파일만 골라 읽어야 해요. 에이전트는 먼저 CLAUDE.md에서 파일 구조 설명을 확인한 다음, 필요에 따라 특정 파일을 읽어요. 그래서 CLAUDE.md의 파일 설명이 매우 중요해요. 모든 파일을 읽지 않아도 에이전트가 필요한 파일을 바로 찾도록 안내하기 때문이에요.

대규모 프로젝트를 위한 전략

1. CLAUDE.md에 자세한 파일 설명 작성 — 에이전트가 파일 지도를 읽고 관련 파일로 바로 이동해요
2. 서브에이전트에 위임 — 탐색과 조사를 깨끗한 컨텍스트를 가진 서브에이전트에 맡기고 요약을 받아요
3. 구체적인 프롬프트 작성 — “설정을 업데이트해 줘”보다 “SettingsView.swift에 새 토글을 추가해 줘”가 더 좋아요
4. 세션 구분 — 관련 없는 기능은 긴 세션을 계속 이어 가기보다 새 세션에서 시작하세요
5. /compact 사용 — Claude Code의 압축 명령은 대화를 요약하고 컨텍스트 공간을 확보해요

MCP의 토큰 효율성

MCP를 사용해야 하는 가장 강력한 이유 중 하나는 구조화된 JSON 응답이 원시 xcodebuild 출력보다 훨씬 적은 토큰을 사용한다는 점이에요.

일반적인 개발 세션에서 빌드를 10-20회 반복하면 MCP는 원시 xcodebuild를 사용할 때보다 30,000-150,000개의 토큰을 절약해요. 이렇게 아낀 토큰은 실제 코드 추론에 사용할 수 있어요.

문제 해결

“build_sim 실패 — 스킴을 찾을 수 없음”

에이전트가 스킴 이름을 추측하고 있어요. 다음과 같이 해결하세요.

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

또는 CLAUDE.md에 스킴 이름을 명시적으로 추가하세요.

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

“xcrun mcpbridge — 명령을 찾을 수 없음”

Xcode 26.3 이상이 필요해요. xcodebuild -version으로 확인하세요. Xcode 26.3 이상을 사용하지만 명령이 계속 실패한다면 다음을 실행하세요.

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

# Verify
xcrun mcpbridge --help

“Claude Code에 MCP 도구가 표시되지 않음”

세션 도중에 등록한 MCP 도구는 다시 시작하기 전까지 표시되지 않을 수 있어요. Claude Code을 종료하고 새 세션을 시작하세요.

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

그런 다음 확인하세요.

You: List all available MCP tools from XcodeBuildMCP.

“에이전트가 MCP 대신 Bash를 통해 xcodebuild를 계속 사용함”

에이전트가 Tool Search를 통해 MCP 도구를 찾지 못하고 있어요. 다음 2가지 방법으로 해결할 수 있어요.

1. CLAUDE.md에 명시적인 지침 추가(에이전트에게 MCP 사용법 알려 주기 참고)
2. 직접 요청: “Bash를 통한 xcodebuild 대신 build_sim MCP 도구를 사용해 줘”

“빌드는 성공했지만 에이전트가 실패했다고 보고함”

XcodeBuildMCP는 xcodebuild 출력을 파싱해요. 빌드에서 오류처럼 보이는 경고가 발생하면(지원 중단 경고에서 흔함) 에이전트가 결과를 잘못 해석할 수 있어요. MCP 응답의 실제 상태 필드를 확인하세요.

“부팅 중 시뮬레이터가 멈춤”

모든 시뮬레이터를 종료하고 다시 부팅하세요.

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

또는 에이전트에게 요청하세요.

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

“CLAUDE.md 규칙이 있는데도 에이전트가 .pbxproj 수정을 시도함”

CLAUDE.md 규칙은 권고 사항이에요. 실제로 제한하려면 훅을 사용해야 해요. .pbxproj 쓰기를 차단하는 PreToolUse 훅이 없으면 에이전트는 결국 수정을 시도하게 돼요. 다음 훅을 설치하세요.

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

규칙은 “수정하지 말아 주세요”라고 말해요. 훅은 “수정할 수 없어요”라고 강제해요.

자주 묻는 질문

어떤 에이전트 런타임부터 시작해야 하나요?

XcodeBuildMCP와 함께 Claude Code CLI을 사용하세요. MCP 연동이 가장 깊고, 훅 시스템이 가장 성숙했으며, iOS 프로젝트 전체를 작업 메모리에 담을 수 있는 1M 컨텍스트 창(Opus 5)을 제공해요. 여기서 시작한 다음 워크플로가 성숙해지면 검토용 Codex와 빠른 인라인 편집용 Xcode 네이티브 에이전트를 추가하세요.

MCP 서버가 둘 다 필요한가요?

대부분의 개발자에게는 XcodeBuildMCP만으로도 필요한 기능의 90%를 충족해요(빌드, 테스트, 시뮬레이터, 디버깅). 문서 검색, Swift REPL 검증 또는 SwiftUI 미리보기 렌더링이 필요하다면 Apple의 Xcode MCP를 추가하세요. 나중에 언제든 추가할 수 있으며, 두 서버는 서로 독립적이에요.

에이전트가 새 Xcode 프로젝트를 처음부터 만들 수 있나요?

XcodeBuildMCP에는 템플릿으로 새 Xcode 프로젝트를 만드는 스캐폴딩 도구(scaffold_ios_project, scaffold_macos_project)가 포함되어 있어요. 하지만 프로덕션 앱이라면 서명, 기능 및 타깃 구성을 올바르게 설정할 수 있도록 Xcode에서 프로젝트를 만든 다음, 모든 코드 구현에 에이전트를 사용하는 방식을 권장해요. Xcode의 새 프로젝트 마법사에 투자한 5분으로 에이전트가 생성한 프로젝트 구성 문제를 해결하는 데 드는 몇 시간을 아낄 수 있어요.

에이전트는 Swift Package Manager 종속성을 어떻게 처리하나요?

잘 처리해요. Package.swift는 에이전트가 안정적으로 읽고 편집할 수 있는 표준 Swift 파일이에요. 종속성 추가, 버전 범위 업데이트, 타깃 구성 모두 가능해요. 다만 .xcodeproj 기반 종속성 관리(Xcode의 패키지 확인 사용자 인터페이스)는 Xcode가 관리하므로 에이전트가 편집하면 안 돼요.

에이전트가 App Store에 제출할 수 있나요?

아니요. App Store 제출에는 Xcode의 Organizer, 프로비저닝 프로필, 스크린샷, 메타데이터 및 App Store Connect 포털이 필요해요. 에이전트가 실질적으로 조작할 수 있는 방식으로는 MCP나 명령줄 도구에서 이러한 항목에 접근할 수 없어요. 에이전트는 구현, 테스트, 버그 수정, 문서화처럼 아카이브 생성 전까지의 모든 작업을 처리해요. 최종 제출 단계는 여전히 사람이 직접 진행해야 해요.

하지만 에이전트는 App Store 메타데이터 작성을 도울 수 있어요. 최신 변경 사항을 바탕으로 앱 설명, 키워드, 새로운 기능 안내문을 작성해 달라고 요청하세요. 에이전트가 특히 잘하는 텍스트 생성 작업이에요.

에이전트의 도움을 받는 iOS 개발에서 비밀 정보와 API 키를 어떻게 관리하나요?

비밀 정보는 절대 커밋하지 마세요. 백엔드 API에 연결하는 iOS 앱에서는 다음 방식을 사용하세요.

1. 환경별 구성에는 .xcconfig 파일을 사용하세요
2. .xcconfig 파일을 .gitignore에 추가하세요
3. Info.plist 빌드 설정을 통해 구성 값을 참조하세요
4. 실제 값을 포함하지 말고 필요한 비밀 정보를 CLAUDE.md에 문서화하세요

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

에이전트는 키가 존재하고 어디에서 사용되는지는 알지만 실제 값은 절대 볼 수 없어요.

SwiftUI 애니메이션도 에이전트가 작성할 수 있나요?

에이전트는 문법적으로 올바른 애니메이션 코드를 잘 작성하지만 결과를 시각적으로 검증할 수는 없어요. 간단한 애니메이션(.animation(.spring()), .transition(.slide), withAnimation { })은 올바른 결과를 만들어요. 타이밍을 정밀하게 맞춰야 하는 복잡한 다단계 애니메이션은 에이전트가 수행할 수 없는 시각적 반복 조정이 필요해요.

효과적인 요청: “타이머 상태가 전환될 때 스프링 애니메이션을 추가하세요.”

효과적이지 않은 요청: “타이머 애니메이션의 느낌을 만족스럽게 만들어 주세요.” (주관적이며 시각적 조정이 필요해요.)

에이전트는 오류 처리 패턴을 어떻게 다루나요?

아주 잘 다뤄요. 에이전트는 Swift의 do/catch, Result, 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

에이전트는 사용자에게 적절한 메시지를 제공하는 구조화된 오류 처리 코드를 작성해요. 때로는 오류를 지나치게 처리하기도 하므로(상위로 전달해야 할 예외까지 잡는 경우) catch 블록을 검토하세요.

접근성 구현에 에이전트를 사용할 수 있나요?

부분적으로 사용할 수 있어요. 에이전트는 접근성 레이블, 힌트, 특성을 올바르게 추가해요.

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

에이전트는 VoiceOver 탐색 순서가 올바른지 확인하거나, Dynamic Type 크기 조정을 테스트하거나, 색상 대비율을 평가할 수 없어요. 검증에는 Xcode의 Accessibility Inspector를 사용하세요.

SwiftData를 사용하지 않는 경우 에이전트는 Core Data 마이그레이션을 어떻게 처리하나요?

에이전트는 Core Data 마이그레이션 매핑과 모델 버전을 작성하지만, 새 모델 버전을 만들고 현재 버전을 선택하는 Xcode의 수동 단계는 자동화할 수 없어요. SwiftData 대신 Core Data를 계속 사용하고 있다면 모델 버전 기록을 CLAUDE.md에 문서화하세요.

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

에이전트는 SwiftUI 미리보기를 어떻게 처리하나요?

두 가지 방법이 있어요. 1. Apple Xcode MCP의 RenderPreview 도구는 미리보기를 헤드리스 방식으로 렌더링하고 결과를 반환해요. 에이전트는 미리보기가 오류 없이 컴파일되고 렌더링되는지 확인할 수 있지만 시각적으로 올바른지는 평가할 수 없어요. 2. build_sim을 통한 빌드 기반 검증은 미리보기 제공자가 컴파일되는지 확인해요. 미리보기가 런타임에 충돌해도 빌드는 성공하며, 충돌은 Xcode가 미리보기를 렌더링할 때만 나타나요.

미리보기를 시각적으로 검증하려면 여전히 Xcode를 열어야 해요.

visionOS와 Apple Vision Pro는 어떤가요?

동일한 패턴이 적용돼요. XcodeBuildMCP는 visionOS 시뮬레이터를 지원하며, 아키텍처 패턴(@Observable, NavigationStack, SwiftData)도 같아요. RealityKit 전용 코드(3D 콘텐츠, 몰입형 공간, 손 추적)에는 Metal과 동일한 제약이 있어요. 에이전트는 올바른 코드를 작성할 수 있지만 공간 출력은 검증할 수 없어요.

프로젝트가 어느 정도로 커지면 에이전트가 어려움을 겪나요?

컨텍스트 창 크기가 제약 요소예요. Opus 5의 1M 토큰 창을 사용하면 Claude Code은 약 50~70개의 Swift 파일을 작업 메모리에 동시에 담을 수 있어요. 더 큰 프로젝트에서는 에이전트가 파일 검색과 선택적 읽기를 사용해 코드베이스의 일부만 다뤄요. 파일이 100개 이상인 프로젝트도 문제없이 작업할 수 있어요. 모든 파일을 컨텍스트에 담아 두는 대신 필요할 때 읽으면 돼요.

실질적인 한계는 파일 수가 아니라 코드베이스의 일관성이에요. 자세한 CLAUDE.md가 있는 잘 문서화된 200개 파일 규모의 프로젝트가 문서화되지 않은 30개 파일 규모의 프로젝트보다 더 나은 결과를 만들어요.

에이전트로 iOS를 개발하려면 Swift를 알아야 하나요?

에이전트의 결과물을 검토하고 아키텍처를 결정할 수 있어야 해요. 모든 코드를 직접 작성할 필요는 없지만, 특히 동시성, 메모리 관리, 프레임워크별 패턴에서 에이전트가 잘못된 선택을 할 때 이를 알아챌 만큼 Swift를 이해해야 해요. 에이전트는 기존 역량을 10배 증폭하는 도구이지 이를 대체하는 수단은 아니에요.

에이전트는 Swift 파일의 병합 충돌을 어떻게 처리하나요?

에이전트는 Swift 소스 파일의 병합 충돌을 안정적으로 해결해요. 모든 에이전트 런타임은 표준 충돌 표시(<<<<<<<, =======, >>>>>>>)를 잘 이해해요. 하지만 .pbxproj 파일의 병합 충돌은 여전히 수동으로 해결해야 해요. 에이전트에게 .pbxproj 충돌을 해결해 달라고 요청하지 마세요.

iOS 개발에 에이전트를 사용하는 비용은 얼마인가요?

Anthropic의 Max 요금제(Opus 5, 1M 컨텍스트)를 사용할 때 일반적인 iOS 개발 세션은 30~120분 동안 진행되며 200K~800K개의 토큰을 처리해요. MCP 도구 호출로 발생하는 추가 비용은 미미해요. 구조화된 JSON 응답은 원시 빌드 출력보다 토큰 효율이 높아요. 비용은 다른 코드베이스에서 Claude Code을 사용할 때와 비슷해요. iOS 개발은 웹 개발보다 특별히 더 비싸거나 저렴하지 않아요.

UIKit 프로젝트에서도 에이전트를 사용할 수 있나요?

네. 하지만 에이전트는 SwiftUI에서 더 효과적이에요. UIKit은 상용구 코드가 더 많고 선언형 구조가 부족하며, 에이전트가 편집할 수 없는 Interface Builder 파일을 사용하는 경우가 많아요. UIKit 프로젝트가 있다면 모델 계층과 비즈니스 로직에는 에이전트를 사용하고 사용자 인터페이스는 직접 처리하거나, 뷰를 SwiftUI로 점진적으로 마이그레이션하는 방식을 고려하세요.

에이전트는 현지화를 어떻게 처리하나요?

에이전트는 .xcstrings(Xcode 문자열 카탈로그) 파일을 효과적으로 만들고 편집해요. 새 현지화 키를 추가하고, 번역을 제공하며, 여러 언어에서 일관성을 유지할 수 있어요. .xcstrings 파일의 구조화된 JSON 형식은 에이전트가 다루기 좋아요. 이전 형식인 .strings 파일도 잘 처리해요. 키와 값 형식이 단순하기 때문이에요.

iOS에서 흔히 발생하는 에이전트 실수와 예방법

다음은 8개의 iOS 프로젝트에서 수천 번에 걸쳐 에이전트와 상호작용하며 반복적으로 발견한 오류예요. 각 오류에는 예방법이 있어요.

실수 1: Observable 패턴 혼용

발생하는 문제: 에이전트가 한 파일에서는 @Observable을 사용하고 다른 파일에서는 ObservableObject를 사용하거나, 이미 Observable인 @Model 클래스에 @Observable을 추가해요.

예방법: 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

실수 2: 클로저에서 강한 참조 순환 생성

발생하는 문제: 에이전트가 self를 강하게 캡처하는 클로저를 만들어요. 특히 Timer.publish, NotificationCenter, 완료 핸들러에서 자주 발생해요.

예방법: 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

실수 3: @MainActor 요구 사항 무시

발생하는 문제: 에이전트가 @MainActor 격리 없이 @Observable 클래스를 만들어서 Swift 6.2 동시성 경고가 발생하거나, 기본 스레드가 아닌 곳에서 사용자 인터페이스를 업데이트할 때 런타임 충돌이 일어나요.

예방법:

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

실수 4: 대상 클로저가 있는 NavigationLink 사용

발생하는 문제: 에이전트가 타입 안전성을 갖춘 NavigationLink(value:)와 .navigationDestination(for:) 패턴 대신 지원이 중단된 NavigationLink(destination:label:)을 사용해요.

예방법:

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

실수 5: 시뮬레이터 이름을 하드코딩

발생하는 문제: 에이전트가 사용자의 시스템에 없을 수도 있는 특정 시뮬레이터 이름(“iPhone 16 Pro”)을 빌드 명령어에 작성해요.

예방법: MCP에서 이를 처리해요. list_sims는 사용 가능한 시뮬레이터를 찾아요. 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.

실수 6: 잘못된 디렉터리에 파일 생성

발생하는 문제: 에이전트가 새 뷰 파일을 Views/ 하위 디렉터리가 아닌 프로젝트 루트에 만들거나, 모델을 잘못된 그룹에 배치해요.

예방법: CLAUDE.md의 파일 구조 주석을 통해 적절한 위치를 안내하세요. 다음 내용도 추가하세요.

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

실수 7: 플랫폼 지원 여부를 처리하지 않음

발생하는 문제: 에이전트가 HealthKit을 지원하지 않는 tvOS용으로도 컴파일되는 공유 코드에서 HealthKit을 사용하거나, watchOS 코드에서 ActivityKit을 사용해요.

예방법:

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

실수 8: 간단한 기능을 지나치게 복잡하게 설계

발생하는 문제: 20줄짜리 유틸리티 기능이면 충분한데도 에이전트가 프로토콜, 프로토콜 확장, 구체적인 구현, 팩토리, 의존성 주입 컨테이너까지 만들어요.

예방법: 단순성 원칙을 포함하세요.

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

솔직한 평가

AI 에이전트와 함께 8개의 iOS 앱을 출시한 뒤 내린 결론은 다음과 같아요.

에이전트가 바꾼 것: 구현 속도예요. 며칠 걸리던 작업을 몇 시간 만에 끝낼 수 있어요. SwiftUI 뷰, SwiftData 모델, 단위 테스트, 리팩터링은 이제 대부분 에이전트가 만들고 사람이 검토해요.

에이전트가 바꾸지 못한 것: 아키텍처 결정, 시각 디자인, 성능 최적화, App Store 제출이에요. 이러한 작업은 여전히 사람이 주도해요.

생산성 향상 효과는 분명하지만 한계도 있어요. 8개 앱 전체를 경험한 결과를 주관적으로 추산하면, 문서가 잘 갖춰져 있고 MCP와 훅이 제대로 설정된 프로젝트에서는 기능 구현 시간이 3배에서 5배 단축됐어요. 대조군을 두고 측정한 결과는 아니며, 같은 코드베이스에서 에이전트의 도움을 받아 기능을 구현한 시간과 혼자 유사한 작업을 수행한 시간을 실제 소요 시간으로 비교한 값이에요. 문서와 훅이 없는 프로젝트에서는 개선 폭이 1.5배에서 2배 정도에 그쳐요. 에이전트가 개발보다 추측에 너무 많은 시간을 쓰기 때문이에요.³³

효과를 내는 투자: CLAUDE.md, 훅, MCP 설정에 들이는 시간이에요. 설정에 투자한 1시간은 에이전트의 실수를 수정하는 데 필요한 여러 시간을 절약해 줘요. 설정 자체가 제품이고, 에이전트는 이를 실행하는 엔진이에요.

놀라웠던 점: MCP 서버가 작업 방식을 얼마나 크게 바꿨는지예요. MCP를 사용하기 전의 에이전트는 우연히 Swift를 이해하는 정교한 텍스트 편집기와 같았어요. MCP를 사용한 뒤에는 코드를 작성하고 빌드하고 테스트하고 디버깅하며 반복해서 개선하는 개발 파트너가 됐어요. 구조화된 피드백 순환이 단순히 코드를 작성하는 에이전트와 실제로 코드를 출시하는 에이전트를 가르는 차이예요.

과거의 나에게 해주고 싶은 말: 가장 작은 앱인 Reps부터 시작하세요. 파일이 14개뿐인 이 앱에서 MCP와 훅을 제대로 설정하고, 꼼꼼한 CLAUDE.md를 작성한 다음, 그 패턴을 더 큰 프로젝트로 확장하세요. 파일이 63개인 멀티플랫폼 앱부터 시작하지 마세요. 프로젝트 크기와 관계없이 인프라에 필요한 투자는 같아요. 작은 프로젝트에서 한 번 완성한 뒤 다른 모든 프로젝트에 복사하세요.

앞으로의 전망: Xcode 26.3의 네이티브 에이전트 통합은 끝이 아니라 시작이에요. Apple이 MCP 지원을 제공한다는 사실은 도구 체계가 에이전트 우선 개발 방식으로 이동하고 있음을 보여 줘요. 깔끔한 CLAUDE.md 파일, 테스트 가능한 아키텍처, 자동화된 훅처럼 에이전트와 호환되는 프로젝트 구조에 지금 투자하는 개발자는 도구가 발전할수록 그 효과를 더 크게 누리게 될 거예요.

빠른 참조 카드

설치 및 최초 설정

# 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

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

필수 훅

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

아키텍처 규칙

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

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)

변경 로그

참고 자료