AIエージェントでiOSアプリを開発する：実践者のためのガイド

要約： 現在、iOS向けのコードを出荷できるエージェントランタイムは3つあります。Claude Code CLI と MCP、Codex CLI と MCP、そしてXcodeネイティブのIntelligenceエージェントです。これにはClaude Agent、Codex、さらにXcode 26.6以降ではGoogle Geminiまたは任意のAgent Client Protocol（ACP）エージェントが含まれます。¹⁷ 2つの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はベータです。8月10日時点ではbeta 5（24A5408d）であり、エージェントに関連するフレームワーク（Foundation Modelsのtool-calling制御、App Intentsのバックグラウンド実行、新しいCore AIおよびEvaluationsフレームワーク）が追加されています。2026年6月より前に学習されたモデルはこれらを知らないため、エージェントのコンテキストで明示しておく価値があります。Xcode 26.6（2026-06-25、Swift 6.3）が現在の安定したツールチェーンです。Xcode 27 beta（Swift 6.4、iOS 27 SDKs）はiOS 27サイクルを追っています。¹⁷¹⁸

AIコーディングエージェントを使って、8本のiOSアプリを作ってきました。プロトタイプではありません。HealthKit連携、Metalシェーダー、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、ヘッドレスのバッチ作業にはCodex CLI、そしてXcode独自のエージェントです。Xcode独自のエージェントは、Xcode 27でインライン修正ツールの域を超え、プラグイン、MCPサーバー、シミュレータを操作する能力を獲得しました。²²
• hookインフラはそのまま流用できます。 既存のPostToolUseフォーマッター、PreToolUseブロッカー、テストランナーhookは、パスをわずかに調整するだけでiOSプロジェクトでも同様に機能します。

AI支援iOS開発を評価するチームリード向け：

• エージェントの有効性は、プロジェクト規模ではなくプロジェクトドキュメントに比例します。 詳細なCLAUDE.mdを持つ63ファイルのアプリは、何もない14ファイルのアプリよりも優れたエージェント出力を生みます。
• .pbxprojの境界は譲れません。 エージェントはXcodeプロジェクトファイルを確実に編集できません。ワークフローには、Xcodeターゲットへの手動ファイル追加を組み込む必要があります。
• 率直なROI：十分に文書化されたプロジェクトでは、エージェントが実装の大部分を担います。 これは、エージェント支援による3時間の作業で出荷した15ファイルのTVアプリに表れています（下記ケーススタディ）。残る作業、つまり視覚的な磨き込み、署名、パフォーマンス調整、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 Ecosystemシリーズ。 Apple Intelligence、MCP、Foundation Models、Vision、Core ML、iOS 26フレームワークスタックと統合するSwiftUIアプリに関する、21本の本番向け記事です。Water、Get Bananas、Return、そのほか941ポートフォリオのアプリから得た知見をまとめています。

シリーズハブ： Apple Ecosystemシリーズ

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 が追加されています。Foundation Models in iOS 27: Tool-Calling Control をご覧ください。¹²
• App Intents が 30 秒の壁を突破しました。 進行状況の報告が必要な LongRunningIntent（performBackgroundTask(options:operation:) 経由）により、同期、ファイル操作、オンデバイス推論のために intent のバックグラウンド実行時間を延長できます。SyncableEntity は AppEntity にデバイス間で共有される ID を与え、IndexedEntityQuery は Spotlight インデックスの修復をクエリに要求できるようにします。App Intents in iOS 27: Background, Sync, Spotlight をご覧ください。¹³
• Core AI は Apple Silicon 上でモデルを実行するための新しいフレームワークです。 Apple のシステムモデルではなく独自のモデルを持ち込む場合に、Foundation Models より下位の層として使用します。Core AI: Running Models on Apple Silicon をご覧ください。¹⁴
• Evaluations はモデル品質のための XCTest です。 テストスイートの一部としてモデル出力の品質を測定する、新しいフレームワーク（macOS 27）です。エージェントの支援で構築した AI 機能をリリースするために欠けていた要素を補います。Evaluations: XCTest for Model Quality をご覧ください。¹⁵
• SwiftData、HealthKit、SwiftUI も進化しています。 SwiftData には iOS 27 で観測と履歴が追加され、HealthKit にはワークアウトゾーンと新しい型が追加されます。SwiftUI の iOS 27 における追加機能も、例年どおり幅広い領域に及びます。SwiftData in iOS 27、HealthKit in iOS 27、What’s New in SwiftUI for iOS 27 をご覧ください。¹⁶

iOS 27 開発向けのツールチェーンは Xcode 27 ベータです。 Xcode 27 は WWDC 初日（6月8日、build 27A5194q）にベータ版として公開され、8月10日時点で beta 5（27A5237l）です。Swift 6.4 と、iOS 27 / iPadOS 27 / tvOS 27 / watchOS 27 / macOS 27 / visionOS 27 の SDKs が含まれており、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 以前でビルドされている場合、Address Sanitizer は 27.0 ターゲットで起動に失敗する可能性があります。ASan 実行には Xcode 26.5 以降を使用してください（178072780）。¹⁸ Beta 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 を通じて UI 自動化ツールが Xcode 27 シミュレータで完全に動作するようになりました。シミュレータウィンドウの起動やキーボード操作も含まれます。このリリース以前は、ランタイム UI 自動化は Xcode 26 シミュレータに対してのみ信頼できるものであり、iOS 27 ベータでのエージェント主導 UI 検証は手動作業になっていました。²¹

運用上の教訓は、このガイド全体で述べているものと同じです。エージェントがコードを書きますが、不足している知識を与えるのはあなたです。iOS 27 ベータでは、これらのフレームワークをプロンプトまたは CLAUDE.md で明示し、Apple のドキュメントへエージェントをリンクする必要があります。そうしなければ、モデルは各 API の iOS 26 における形を参照してしまいます。このガイドの他の内容（runtimes、MCP、hooks、failure modes）は、iOS 27 開発でも変わらず適用できます。

ポートフォリオ：8 アプリ、293 ファイル

設定に入る前に、このガイドの基となった内容をご紹介します。これらは玩具的なプロジェクトではありません。5 つの Apple フレームワーク、3 つのプラットフォームにまたがり、14 ファイルのワークアウトトラッカーから 63 ファイルのマルチプラットフォーム瞑想タイマーまで、iOS 開発の複雑さを幅広くカバーしています。

ファイル数が重要な理由： エージェントの有効性は、プロジェクト規模ではなくプロジェクトの可読性と相関します。Return（63 ファイル）は、amp97（41 ファイル）より優れたエージェント出力を生みます。Return にはファイル注釈、アーキテクチャ図、明示的なパターンを含む詳細な CLAUDE.md があるためです。amp97 の Metal shaders は、ドキュメントの品質にかかわらず、エージェントが推論するには本質的により難しいものです。

前提条件

iOS 開発向けのエージェント runtime を設定する前に、以下を確認してください。

App Store Connect の期限： 2026-04-28 以降、App Store Connect へアップロードするアプリは、iOS 26、iPadOS 26、tvOS 26、visionOS 26、または watchOS 26 向けの SDKs を使用し、Xcode 26 以降でビルドする必要があります。²⁶（macOS の提出にはこの要件は適用されません。）チームがまだ Xcode 16.x を使用している場合、このガイドのエージェント支援ツールチェーンは移行を促す契機にもなります。いずれにしても、以下の MCP サーバーはいずれも 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 ツールにおける light/dark、orientation、type sizes のバリアントレンダリングです。また、エージェントのターン中に起きる 2 件のクラッシュと、エージェントが質問した際のハングも修正され、Swift 6.3 と iOS 26.5 世代の SDKs も含まれます。¹⁷ 26.5 のワークフロー強化（コーディングアシスタントのメッセージキューイングと明確化質問のサポート）と、26.4 の Swift Testing 画像添付、記録済み issue の重大度、crashlog を伴う UI テストクラッシュ警告、String Catalog エディタの改善もすべて引き継がれています。²⁷²⁸ 以前の安定版は、26.5（2026-05-11、build 17F42）と 26.4.1（2026-04-16、build 17E202）です。²⁹ - 少なくとも 1 つの iOS Simulator runtime をインストール済みであること - Claude Code 用の Anthropic API アカウント、または Codex 用の OpenAI アカウント

推奨： - SwiftFormat をインストール済みであること（brew install swiftformat）— format-on-save hooks で使用します - SwiftLint をインストール済みであること（brew install swiftlint）— 任意ですが、スタイルの強制に役立ちます - ターミナルに慣れていること — 3 つの 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コードの作成、ビルド、テストを行えるランタイムは3種類あります。これらは互換ではありません。それぞれに異なる強み、異なるMCP統合パターン、そして最適な用途があります。

1. Claude Code CLI

概要： Anthropicのターミナルベースのエージェント型コーディングアシスタントです。コードベースを読み取り、コマンドを実行し、ファイルを変更し、MCPを介して外部ツールに接続します。⁷

MCP統合： XcodeBuildMCPとAppleのXcode MCPの両方を完全にサポートしています。エージェントはMCPプロトコル経由でツールを検出し、構造化されたパラメータで呼び出します。2つのサーバーを合わせて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年2月23日）：

手動でのMCP設定を省きたい場合、XcodeBuildMCP v2.1.0+にはinitサブコマンドが含まれています。Claude Code、Cursor、またはCodexを自動検出し、エージェントスキルとMCP設定を1ステップでインストールします。

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を使ってください。1つ目のエージェントが書いたコードを2つ目のエージェントでレビューすると、異なる種類のエラーを見つけられます。collab workflow（Claudeが実装し、Codexがレビュー）は、1つのモデルファミリーでは正しく見えるSwiftUIパターンにも、別のモデルが見つけられる微妙な問題があるため、iOSで効果的です。Metalシェーダーと並行処理パターンは、特にデュアルモデルレビューの恩恵を受けます。

3. Xcodeネイティブエージェント

概要： AppleはXcodeのIntelligenceパネルにAIコーディングエージェントを直接統合しました。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では、このリストの大半が無効になります。 beta 1（6月8日）以降、Xcodeのエージェントはインラインアシスタントではなく拡張プラットフォームです。²²

• プラグイン：「Xcodeのエージェントは、スキル、MCPサーバー、ACPエージェント設定を含むプラグインで拡張できるようになりました。スキルは補完サポート付きのスラッシュコマンドとして呼び出せます。」（178289210）— つまり、「組み込みツールのみ」と「MCP設定なし」という制限は解消されました。
• Simulator制御：エージェントは「Simulatorの起動、アプリのインストールと起動、タッチイベントの合成、UI動作を検証するスクリーンショットのキャプチャ」が可能になりました（175179787）。beta 5ではwatchOSハードウェア入力も操作できます（181147968）。
• デバッガーアクセス：Xcode MCPサーバーには、実行状態の操作、デバッガーコンソールの読み取り、スキームと実行先の切り替え、「ビルド設定、コンパイラフラグ、エンタイトルメント、Info.plistキー」の検査・変更を行うツールが追加されました（176935844）。
• コーディングエージェントとそのエージェントが起動するプロセスによるファイルシステムアクセスを「監視・制御するファイルシステムセキュリティ層」（178289431）に加え、ファーストクラスの計画機能（172857081）、クラッシュ、ハング、エネルギー、起動の問題を対象としたプロジェクトインサイト（177568662）が提供されます。

176935844から直接導かれる1つの警告： Xcodeのエージェントは、ビルド設定、エンタイトルメント、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 フラグを使うと、すべてのプロジェクトでサーバーをグローバルに利用できます。プロジェクト単位でインストールする場合は省略してください（WebプロジェクトではなくiOSプロジェクトでだけMCPを使いたい場合に便利です）。

-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 — プロジェクトの調査です。エージェントはスキーム名やワークスペース構造を推測する必要がありません。

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 は要素参照による一連の操作を1回の呼び出しで実行します。drag はシートやリストスクロール向けに、要素参照のドラッグジェスチャーを実行します。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、スキーム設定を尊重するビルド：

v2.7.0のリリースは2.6.0より小規模ですが、アップグレード前に知っておくべき破壊的変更と動作変更が1つずつあります。²¹ 主な変更点は、UI自動化ツールがDevice Hubを通じてXcode 27シミュレーターで完全に動作するようになったことです。シミュレーターウィンドウの起動やキーボード操作にも対応し、実行時UI自動化がXcode 26シミュレーターでしか信頼できなかった差を埋めます。破壊的変更： ビルドおよびテストツールは schemaVersion: 3 の構造化結果を返すようになりました（2.6.0以降はv2でした）。バージョン2に固定して結果を検証・解析するものを作成している場合は更新が必要です。動作変更： configuration を省略した場合、ビルド、テスト、クリーン、アプリパス取得ツールは常にDebugをデフォルトにするのではなく、スキームアクションの設定を尊重するようになりました。スキームのTestアクションがReleaseに設定されている場合、指定なしのtest_simはReleaseをビルドするため、ワークフローが特定の設定に依存する場合は configuration を明示的に渡してください。小さいながら有用な変更として、再利用可能な .xctestproducts テスト準備パッケージにより、毎回新しい .xcresult を生成しつつ再ビルドなしでテストを再実行できます。セッションデフォルトの extraArgs では、共通の xcodebuild フラグを呼び出しごとに繰り返さず、セッションごとに一度設定できます。新しい xcodebuildmcp purge CLIコマンドは、XcodeBuildMCPのワークスペースストレージを報告・クリーンアップします（デフォルトではdry-runで、削除には明示的なオプトインが必要です）。また、ツールが利用可能になるまでMCPクライアントが10〜17秒待機する問題も修正されました。この問題により、短いヘルスチェックで接続失敗と報告される場合がありました。²¹

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は「開いているXcodeワークスペースを必要とせずに動作する新しいMCPサーバーエクスペリエンス」を追加しました。sudo xcrun mcp-server enable で有効化し、xcrun mcp-server status で確認できます。同じプレビューでは、コード署名されたエージェントに対して、都度再承認するのではなく、ディレクトリツリー内で作業する持続的な権限を付与できます。無人実行では、sudo xcrun mcp-server enable --unsafe-always-allow-all-agents によってすべてを事前承認できます。Appleはこれを「デスクで使用する際に推奨される設定ではない」と明言しています。私も同意します。意図せず公開したディレクトリからエージェントを守る承認ステップがなくなるためです。全体を初期プレビューとして扱い、プレビューが終了するまではヘッドレスの経路としてXcodeBuildMCPを維持してください。²²

ツール一覧（5カテゴリ、全20ツール）：

Apple MCPに固有のツール（XcodeBuildMCPでは利用不可）：

1. DocumentationSearch — WWDCセッションを含むAppleの開発者向けドキュメントを検索します。Apple APIに関する質問では、Web検索より高速かつ信頼できます。「HKQuantityType(.dietaryWater)は有効ですか？」と尋ねれば、ソースから確実な回答を得られます。

2. ExecuteSnippet — プロジェクトのコンテキスト内でSwift REPLを実行します。フルアプリをビルドせずに、エージェントはAPIの動作確認、型変換のテスト、式の検証を行えます。

3. RenderPreview — SwiftUIプレビューをヘッドレスでレンダリングします。ビューがエラーなくレンダリングされるかを確認できますが、視覚的な正しさは評価できません（レンダリング結果は視覚的に確認されるのではなくデータとして返されます）。Xcode 26.6以降、プレビューMCPツール（26.6のリリースノートでは「Preview Snapshot」と呼ばれます）は、ライト／ダーク外観、縦／横方向、文字サイズのオーバーライドというバリアントをレンダリングします（178831772）。そのため、エージェントは1回で複数の外観にわたってビューを検証できます。¹⁷ Xcode 27 betaではさらに拡張され、Previewグループのレンダリングと別ローカリゼーションでのプレビューにも対応しています。¹⁸

4. XcodeListNavigatorIssues — ビルドエラーだけでなく、Xcodeのアナライザーによるリアルタイム診断を返します。未使用変数、潜在的な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を使い、Apple Xcode MCPはドキュメントとREPLの検証に使っています。ビルドとテストでは、Xcodeプロセスのオーバーヘッドがなく高速で、XPC依存もなく信頼性が高いため、エージェントはXcodeBuildMCPをデフォルトにします。

2サーバーという枠組みは緩和されつつあります。 XcodeBuildMCP 2.6.xでは、xcode-ide プロキシカテゴリが追加されています。xcode_ide_list_tools はXcode-IDE専用のMCP機能を検出し、xcode_ide_call_tool はそれらを呼び出します（xcode_tools_documentationsearch のように xcode_tools_* 名で公開されます）。そのため、XcodeBuildMCPの登録1つからAppleのIDE側ツールにもアクセスできるようになりました。¹⁹ 重要な制約は変わりません。プロキシ経由の呼び出しにも、直接のxcrun mcpbridge登録とまったく同じく、実行中のXcodeプロセスが必要です。Appleのツールをエージェントのツール一覧で第一級に扱いたい場合は両方のサーバーを登録しておいてください。プロキシは、サーバー登録を1つにし、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ドキュメントにWeb検索を使うこともあります。こちらは低速で信頼性も下がります。

これを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の動作変更のうち1つは、このセクションの考え方に含めるべきです。configuration を省略すると、ビルド、テスト、クリーン、アプリパス取得ツールは常にDebugを使用する代わりに、スキームアクションの設定を尊重します。²¹ ほとんどのスキームはDebugで実行・テストするため、大半のプロジェクトでは何も変わりません。ただし、スキームのアクションがReleaseに設定されている場合（プロファイリング用スキームやアーカイブに近い設定で一般的です）、指定なしのbuild_simまたはtest_simはReleaseをビルドします。CLAUDE.mdやフックがDebug成果物を前提としている場合は、ツール呼び出しで明示するか、session_set_defaults でセッションごとに一度設定してください。

長時間ビルド：Claude Codeはバックグラウンドで実行するようになりました

Claude Codeの2つのリリースにより、セッション内での長時間ビルドの扱いが変わりました。v2.1.212（2026-07-16）以降、2分を超えて実行されるMCPツール呼び出しは、セッションを使い続けられるように自動でバックグラウンドへ移行します。このしきい値は CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS で設定でき、動作自体を無効にすることもできます。²⁰ 実際のプロジェクトでは、build_sim / test_sim を使ったクリーンビルドや全テスト実行は通常2分を超えます。そのため、ビルド完了を待ってターンをブロックする代わりに、エージェントはバックグラウンドでビルドを完了させながら、ファイルを読み、次の編集を計画し続けます。付随する修正も同じくらい重要です。v2.1.206（2026-07-09）より前は、--mcp-config または .mcp.json 経由で設定したサーバーごとの request_timeout_ms が新しいセッションで無視されていました。そのため、長時間のMCP呼び出しは60秒のデフォルトでタイムアウトしていました。典型的な症状は、最初のクリーンビルドがタイムアウトし、再試行すると「自然に直る」ことでした。²⁰ ラッパースクリプトや事前ウォームアップしたビルドでこれらの挙動を回避していた場合は、その回避策を削除できます。

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

これが重要な理由: エージェントはコードを書く前に、デプロイメントターゲットを知る必要があります。iOS 17を対象にするエージェントはNavigationViewと@ObservedObjectを使います。iOS 26を対象にするエージェントはNavigationStackと@Observableを使います。Bundle IDはentitlementsやHealthKit設定に関係します。Swiftのバージョンは並行処理モデル（async/awaitかcompletion handlerか、strict concurrencyかlenientか）を決めます。

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を優先すべきですが、生のコマンドも含めてください。生のコマンドはフォールバック用ドキュメントとして機能し、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 syncと、アプリのデータをClaude Desktopへ公開するカスタムMCP serverを備えた、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ファイルのプロジェクトに対して、CLAUDE.mdは40行です。書くのに10分しかかからず、エージェントの混乱を何時間分も減らせます。

実際のCLAUDE.md: Starfield Destroyer（SpriteKit + Metal — 32ファイル）

ゲームプロジェクトでは、より多くのフレームワーク固有コンテキストが必要です。エージェントはscene graph、physics category、ゲーム状態マシンを理解する必要があります。

# 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の調整

適切な詳細度は、ファイル数とフレームワークの複雑さによって変わります。

ドキュメントを書きすぎるコストはほぼゼロです（エージェントは不要な部分を読み飛ばします）。一方、ドキュメント不足のコストは高くなります（エージェントがコードベースと衝突するパターンを作り出します）。

CLAUDE.mdチェックリスト

iOSプロジェクト向けCLAUDE.mdを作成または監査するときは、このチェックリストを使ってください。

• [ ] Bundle IDとデプロイメントターゲットを明記している
• [ ] Swiftバージョンとアーキテクチャパターンを明記している
• [ ] ファイル構成にインラインの目的注釈がある
• [ ] 正しいschemeとdestinationを使ったビルドコマンドがある
• [ ] 正しいschemeとdestinationを使ったテストコマンドがある
• [ ] MCPの優先方針を明記している（”prefer build_sim over xcodebuild”）
• [ ] @Observableルールがある（ObservableObjectは使わない）
• [ ] NavigationStackルールがある（NavigationViewは使わない）
• [ ] .pbxprojの禁止事項がある
• [ ] フレームワーク固有のコンテキストがある（HealthKit権限、SwiftData relationships、SpriteKit hierarchy、Metal pipeline）
• [ ] プラットフォーム可用性ガードを記載している（#if canImport、#if os）
• [ ] 主要なsingletonと共有パターンを記載している
• [ ] 既知の制限や注意点を記載している

初めてのエージェントセッション

MCP を設定し、プロジェクトに CLAUDE.md を置いたら、効果的な初回セッションの流れは次のようになります。ここでは Claude Code CLI を使いますが、このワークフローはどのランタイムにも適用できます。

ステップ 1: エージェントがプロジェクトを認識できることを確認する

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.

エージェントが CLAUDE.md の内容に触れない場合は、ファイルがプロジェクトルート（.xcodeproj または Package.swift と同じディレクトリ）にあることを確認してください。

ステップ 2: ヘルスチェックビルドを実行する

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: テストを実行する

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 を変更しないというエージェントの注記は、CLAUDE.md のルールによるものです。このルールがなければ、エージェントはプロジェクトファイルを変更しようとして、高い確率で壊してしまいます。

iOS でエージェントが得意なこと

ここでは、エージェントが最小限の人間によるレビューで、一貫して正しく本番品質の出力を出せるタスクを紹介します。

SwiftUI ビューとモディファイア

エージェントは、SwiftUI の宣言的な構文パターンを深く認識できます。ビュー構成、モディファイアチェーン、状態バインディング、レイアウトは、エージェントの学習データと相性が良い領域です。SwiftUI の API サーフェスはドキュメントが充実しており、パターンの一貫性も高いためです。

エージェントが得意な領域: - 説明から新しいビューを作る（「X、Y、Z のトグルを持つ設定シートを作成して」） - モディファイアチェーンを適用する（.glassEffect()、.sensoryFeedback()、.navigationTitle()） - レイアウトパターンを変換する（VStack から LazyVGrid、List から ScrollView など） - SwiftData モデルへの @Bindable フォームバインディングを実装する - サンプルデータ付きのプレビュープロバイダーを作る

優れた結果を生むプロンプト例:

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.

具体性が重要です。「設定ビューを作成して」では汎用的な出力になります。「SettingsSheet.swift の既存パターンに合わせて SettingsView を作成して」と指定すると、コードベースと一貫した出力になります。

SwiftData モデルとクエリ

エージェントは、SwiftData の @Model マクロ、リレーション、@Query パターンを安定して扱えます。このフレームワークの宣言的な性質（Django ORM や SQLAlchemy に近いもの）は、多くのコードベースでエージェントが見てきたパターンとよく対応します。

エージェントが得意な領域: - リレーションを持つ @Model クラスを定義する - ソート記述子と述語を使って @Query を書く - modelContext 経由で CRUD 操作を実装する - スキーマバージョン間のマイグレーション計画を作る - プレビューデータとテストフィクスチャを作る

エージェントにガイダンスが必要な領域: - 複雑な #Predicate 式（SwiftData の述語 DSL には制限があり、エージェントが常に把握しているとは限りません。既知の制限は CLAUDE.md に記載してください） - CloudKit 同期設定（SwiftData 経由で自動化されますが、エージェントが手動同期を実装しようとする場合があります）

ユニットテスト

エージェントが書くユニットテストは、iOS プロジェクトで一貫して高品質です。エージェントは XCTest のパターン、async テストメソッド、setUp/tearDown のライフサイクルを理解しています。

Write unit tests for TimerManager covering:
1. Initial state is .stopped
2. start() transitions to .running
3. pause() transitions to .paused
4. reset() returns to .stopped with original duration
5. Timer counts down correctly (test with 3-second duration)

エージェントは、setUp() と tearDown()、適切なアサーション、タイマーベースのテストに対する async 処理を備えた、よく構造化された XCTest ケースを生成します。

リファクタリングとパターン適用

エージェントは機械的なリファクタリングを得意としています。ビューをコンポーネントに抽出する、ObservableObject を @Observable に変換する、NavigationView から NavigationStack に移行する、複数ファイルに一貫したパターンを適用する、といった作業です。

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.

エージェントは各ファイルを順に処理し、変換を正しく適用し、既存の機能を維持します。これはレバレッジの高い作業です。手作業なら 1 時間かかるリファクタリングが、ほぼ完璧な精度で数分で完了します。

MCP によるビルドエラー診断

構造化された MCP 出力があれば、エージェントはほとんどの開発者より速くビルドエラーを診断できます。エージェントはエラーの JSON を読み、正確なファイルと行を特定し、エラーメッセージを理解して修正します。多くの場合、1 ターンで完了します。

エージェントが自律的に修正できるエラー: - 不足している imports - 型の不一致 - プロトコル準拠の不足 - 非推奨の API 使用（置き換えを含む） - 必須イニシャライザーパラメータの不足 - アクセス制御違反

エージェントに支援が必要なエラー: - あいまいな型解決（複数のモジュールが同じ型を定義している場合） - 複雑なジェネリック制約の失敗 - マクロ展開エラー（エージェントは展開後のマクロ出力を確認できません）

シミュレーター管理

エージェントは MCP 経由でシミュレーターのライフサイクルをうまく扱えます。

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

エージェントは list_sims を呼び出して利用可能なランタイムを探し、boot_sim でシミュレーターを起動し、build_sim でビルドとインストールを行い、screenshot でキャプチャします。すべて構造化された MCP 呼び出しを通じて実行します。

iOSでエージェントが苦手なこと

エージェントがどこで失敗するのかを正直に整理します。この境界を知っておくと、フラストレーションや無駄なトークン消費を防げます。

.pbxprojファイルの変更 — 絶対にしない

これはiOSエージェント開発で最も重要なルールです。.pbxprojファイルはXcodeのプロジェクト設定です。UUID参照、ビルドフェーズの一覧、ターゲットメンバーシップを含む構造化テキストファイルです。名目上は人間が読めますが、AIエージェントにとっては実質的に解析不能です。

エージェントが.pbxprojで失敗する理由: - ファイルは独自形式（JSONでもYAMLでもXMLでもありません）を使っており、位置に意味があります - すべてのエントリがUUIDで相互参照されています。ファイルを追加するには、3〜5個の異なるセクションを一貫して更新する必要があります - 1文字でも場所を誤ると、プロジェクトファイル全体が壊れます - Xcodeの.pbxprojマージコンフリクト解決はもともと脆弱です。エージェントによる編集はそれをさらに悪化させます

エージェントが.pbxprojを編集すると起きること: 1. 編集は成功したように見えます（エージェントは「file updated」と報告します） 2. Xcodeがプロジェクトを開けなくなります（「The project file is corrupted」） 3. git履歴から復旧するのに15〜60分かかります 4. PreToolUseフックを追加する必要性を学びます（フックを参照）

ワークフロー: エージェントがSwiftファイルを作成します。Xcodeプロジェクトへの追加は手動で行います（Xcodeへドラッグするか、File > Add Filesを使います）。1ファイルあたり5秒で済み、何時間もの復旧作業を防げます。

Swift Package Managerプロジェクトの場合: この制限はそれほど深刻ではありません。Package.swiftは標準的なSwiftファイルなので、エージェントでも安定して編集できます。プロジェクトがSPMのみを使用している場合（.xcodeprojなし）、エージェントがプロジェクト構造全体を管理できます。

複雑なInterface Builder / Storyboard編集

プロジェクトでInterface Builder（.xibファイル）やStoryboard（.storyboardファイル）を使っている場合、エージェントはそれらを意味のある形で編集できません。これらは自動生成UUID、制約参照、アウトレット接続を含むXMLファイルであり、テキスト編集ではなくビジュアル編集を前提に設計されています。

対策: 新しいビューにはSwiftUIだけを使います。プロジェクトにレガシーなInterface Builderファイルがある場合は触らず、新しいUIはSwiftUIで構築しましょう。

パフォーマンス最適化

エージェントは正しいコードを書けますが、必ずしも高性能なコードを書けるわけではありません。アプリをプロファイルしたり、ボトルネックを特定したり、フレームレートを測定したりすることはできません。パフォーマンス最適化には次が必要です。

1. Instrumentsによるプロファイリング（視覚的なツールであり、エージェントからはアクセスできません）
2. 特定デバイスのGPU/CPU特性の理解
3. 測定に基づく反復的な変更

この問題が現れる場所: - Metalシェーダー最適化（エージェントは有効なMetalを書けますが、GPUフレーム時間は測定できません） - SwiftUIのview bodyの複雑さ（エージェントが深くネストしたビューを作成し、再描画オーバーヘッドを引き起こすことがあります） - Core Data / SwiftDataのフェッチ最適化（エージェントは正しいクエリを書けますが、大規模データセットでは遅い場合があります）

対策: 実装にはエージェントを使い、Instrumentsで手動プロファイリングします。そのうえで、特定した最適化をエージェントに適用させます。

コード署名とプロビジョニング

エージェントは、エラーメッセージを読む以上のコード署名問題のデバッグはできません。プロビジョニングプロファイル管理、証明書作成、エンタイトルメント設定、App Store提出は、Apple Developer portal、Keychain Access、Xcodeの署名UIを使う、人間が行うワークフローです。

エージェントに見えるもの: “Signing for ‘Return’ requires a development team.”

エージェントに見えないもの: 証明書が期限切れかどうか、プロビジョニングプロファイルにデバイスが含まれているか、bundle IDがApp IDと一致しているか、エンタイトルメントファイルが正しいかどうかです。

対策: 署名はすべてXcodeのSigning & Capabilitiesタブで処理します。署名失敗のデバッグをエージェントに依頼しないでください。

複雑なMetalシェーダーのデバッグ

エージェントは構文的に正しいMetal Shading Language（MSL）を書けますが、視覚出力の検証やGPU側の問題のデバッグはできません。MetalシェーダーはGPU上で実行されます。シェーダーが正しい視覚結果を生成しているかどうかについて、エージェントにはフィードバック手段がありません。

エージェントがMetalでできること: - 説明に基づいてvertexシェーダーとfragmentシェーダーを書く - SwiftでMetalレンダーパイプラインを設定する - データ並列処理用のcomputeシェーダーを作成する - .metalファイルのコンパイルエラーを修正する

エージェントがMetalでできないこと: - シェーダー出力の視覚的な正しさを検証する - GPUパフォーマンスをデバッグする（フレーム時間、occupancy、メモリ帯域幅） - 視覚的なアーティファクトを診断する（バンディング、精度の問題、誤った色空間） - 異なるGPUアーキテクチャでテストする（A-seriesとM-seriesの挙動差）

対策: Metalシェーダーは実機でテストします。SimulatorのMetal実装は、デバイスのGPU挙動を代表するものではありません。視覚デバッグにはXcodeのGPU Frame Captureを使います。

ビジュアルレイアウト検証

エージェントにはアプリのUIが見えません。SwiftUIレイアウトコードを書き、コンパイルできることは検証できますが、結果の画面が正しく見えるかどうかは判断できません。10ピクセル中心からずれているビュー、誤ったフォントウェイト、要素の重なりは、ビルドエラーを出さず、すべてのロジックテストにも合格します。

対策: UI変更は目視でレビューします。XcodeのSwiftUI Previews（またはヘッドレスレンダリング用のApple MCP経由のRenderPreview）を使ってレイアウトを検証します。自動のビジュアル回帰検出には、swift-snapshot-testingのようなライブラリを使ったスナップショットテストも検討してください。

iOS 開発向けの Hooks

Hooks は、エージェントのワークフローにおける特定のタイミングで確実に実行されるシェルコマンドです。ルールを強制する仕組みであり、「.pbxproj を編集しないでください」（エージェントが無視する可能性のある提案）と「.pbxproj は編集できません」（強制的なブロック）の違いを生みます。

hook システムの背景については、Claude Code hooks ガイドをご覧ください。このセクションでは、iOS 固有の hook パターンを取り上げます。

PreToolUse：.pbxproj への書き込みをブロックする

あらゆる iOS プロジェクトで最も重要な 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 が実行されます。ファイルパスを検出して stderr に警告を出力し、終了コード 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 により、lint の警告でエージェントの処理がブロックされるのを防げます。lint 違反をブロックしたい場合は削除してください。

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：Entitlements の変更をブロックする

エージェントによる意図しない変更から entitlements ファイルを保護します。

{
  "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 フックが設定されていることを確認してください。

Apple のオンデバイス LLM を使用するアプリ

アプリが Apple の Foundation Models フレームワークを呼び出す場合（たとえば、オフライン要約、分類、構造化出力の生成）、エージェントはプロンプト予算を把握する必要があります。iOS 26.4 では、以前の 4096 トークンという推測に代わる SystemLanguageModel の API が 2 つ追加されました。contextSize（モデルが単一の会話で受け入れる最大トークン数）と、tokenCount(for:)（async throws で、指定したプロンプトの実際のトークン消費量を返します）です。³¹ どちらも @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 シグネチャは重要です。同期バージョンを貼り付けたエージェントは、コンパイルに失敗します。

実世界のケーススタディ

抽象的なアドバイスを書くのは簡単です。ここでは、8つのアプリから、agent支援によるiOS開発が実際にどう機能するのかを示す具体的なシナリオを紹介します。失敗例も含めています。

ケーススタディ 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では使いにくいホイールピッカーを、+/-ボタンに置き換えるTVStepperコンポーネントを構築しました - App Groups（group.com.941apps.Return）経由で設定同期を実装しました - 共有コード全体に#if os(tvOS)ガードを追加しました - MCPでplatform=tvOS Simulator,name=Apple TVを指定し、ビルドとテストを実行しました

手動で行う必要があったこと: - XcodeでtvOSターゲットを作成する（File > New > Target > tvOS App） - 新しいターゲットをXcodeプロジェクトに追加する（.pbxprojの変更） - TVターゲット向けにApp Groupsエンタイトルメントを設定する - 既存のスキームにTVターゲットを追加する、または新しいスキームを作成する - agentが作成したすべてのSwiftファイルを、TVターゲットに手動で追加する - Siri Remoteナビゲーションを手動でテストする（agentはフォーカス挙動を評価できません）

結果: 約3時間のagent支援作業で、15個の新しいSwiftファイルと、完全に動作するTVアプリができました。私の見積もりでは、実装作業のおよそ80%をagentが担当し、Xcode UI操作が必要な部分（エンタイトルメント、ターゲット設定、機能フラグ）と、実機のApple TVでのフォーカステストを私が担当しました。このコードベースで同等の作業を1人で行う場合、過去にagentなしで出荷した類似機能を基準にすると、数日かかる作業だったはずです。

ケーススタディ 2: amp97のMetalシェーダーデバッグ（一部失敗）

タスク: オシロスコープシェーダーに、エネルギーベースの強度システムを追加することでした。ビジュアライゼーションが音声エネルギーに合わせて脈動する必要がありました。

起きたこと: 1. agentは、uEnergy uniformとHDRトーンマッピングを追加する、有効なMetalシェーダー変更を書きました 2. コードはエラーなくコンパイルされました 3. 実機では、ビジュアライゼーションが完全に白く表示されました。強度係数が10倍高すぎたのです（0.30ではなく3.5） 4. agentには白い画面が見えないため、フィードバック信号がありませんでした 5. 私が視覚的に問題を特定し、係数を下げるようagentに依頼しました 6. agentは係数を下げましたが、全体のエネルギーステートマシンが複雑すぎて、別の形でビジュアライザーを壊しました 7. 完全にrevertしました。2つのコミット（67959edとcda4830）を869d914でrevertしました

教訓: Metalシェーダーは、agent支援開発で最も難しい領域です。フィードバックループが切れているからです。agentは構文（コンパイルできること）と意味論（型が正しいこと）は検証できますが、出力（見た目が正しいこと）は検証できません。視覚的挙動を変えるシェーダー変更には、必ず実機での人間による検証が必要です。

この後CLAUDE.mdに追加したこと: 「極めて慎重な係数テストなしに、オシロスコープシェーダーのエネルギーステート変更を試みないこと。前回の試みでは係数が10倍高すぎて、ビジュアライザーが壊れた。」

ケーススタディ 3: Banana ListのSwiftDataマイグレーション（成功）

タスク: データモデルをV1からV2へマイグレーションし、GroceryItemにquantityフィールドを追加し、リレーションを持つ新しいCategoryモデルを追加することでした。

agentが行ったこと: 1. 既存のV1モデル定義を読みました 2. 新しいフィールドとリレーションを含むV2モデル定義を作成しました 3. SchemaMigrationPlanプロトコルに準拠したGroceryMigrationPlanを書きました 4. V1toV2マイグレーションステージを実装しました。デフォルトのquantity: 1とcategory: nilを追加しました 5. 新しいフィールドに対応するよう、すべてのビューを更新しました 6. プレビュー向けにSampleData.swiftを更新しました 7. MCP経由でビルドとテストを実行し、すべて合格しました 8. マイグレーション専用のユニットテストを作成しました

要点: SwiftDataマイグレーションは、Appleのドキュメントと学習データに十分含まれている、明確なプロトコルパターンに従うため、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、日付、継続時間、ソースデバイス、HealthKit同期ステータスを持つMeditationSessionデータモデルを作成しました 2. iCloud同期向けにNSUbiquitousKeyValueStoreを管理するSessionStoreシングルトンを構築しました 3. マージ競合解決（UUIDベースの重複排除）を実装しました 4. プラットフォーム別の調整を含むSessionHistoryViewを追加しました（iOSではスワイプ削除、tvOSではフォーカスベース） 5. 他デバイスからのセッションに対して、iPhone側のHealthKit同期を接続しました

反復が必要だったこと: 初期実装では、iPhoneアプリがバックグラウンドで起動するケースを扱えていませんでした（同期のためのフォアグラウンド通知がありません）。agentには具体的な指示が必要でした。「バックグラウンドのKV変更で同期をトリガーするために、NSUbiquitousKeyValueStore.didChangeExternallyNotificationを使う」。このヒントの後、実装は正しくなりました。

教訓: アーキテクチャが明確に説明されていれば、agentはマルチプラットフォームのアーキテクチャパターンをうまく扱えます。iCloud同期パターンは単純ではありませんが、Appleのドキュメント化されたパターンに従っており、agentはそれを理解しました。エッジケース（バックグラウンド同期）には、人間のドメイン知識が必要でした。十分に文書化されていないためです。

ケーススタディ 5: Starfield DestroyerのGame Center統合（成功）

タスク: 宇宙シューティングにGame Centerのリーダーボードと実績を追加することでした。

agentがうまくできたこと: - アプリのエントリーポイントにGKLocalPlayer.local.authenticateHandlerを実装しました - スコア送信と実績報告のメソッドを持つGameCenterManagerを作成しました - すべてのGame Center操作の前に、認証状態チェックを追加しました - オフライン時のケースを適切に扱いました（Game Centerなしでもゲームはプレイでき、再接続時に送信されます） - 8機の機体進行システムに合わせた実績定義を作成しました

手動作業が必要だったこと: - App Store Connectでリーダーボードと実績を作成する（Webポータルであり、agentはアクセスできません） - XcodeでGame Centerエンタイトルメントを設定する - サンドボックスのGame Centerアカウントでテストする（実機での手動サインインが必要です）

エージェントを使ったプロジェクトライフサイクル

新しい iOS プロジェクトを始める

エージェント支援で新しいプロジェクトを始める場合の最適なワークフローは次のとおりです。

フェーズ 1: 人間によるセットアップ（15〜30分） 1. Xcode プロジェクトを作成します（File > New > Project） 2. 署名とCapabilitiesを設定します 3. デプロイメントターゲットと対応する実行先を設定します 4. 必要なエンタイトルメントを追加します（HealthKit、Game Center など） 5. プロジェクトの識別情報とルールを含む最初の CLAUDE.md を作成します

フェーズ 2: エージェントによる実装（数時間〜数日） 1. エージェントがデータモデルを作成します（SwiftData、Core Data、またはプレーンな構造体） 2. エージェントが、文書化されたパターンに従ってビューを構築します 3. エージェントが manager/service クラスにビジネスロジックを実装します 4. エージェントがユニットテストを書きます 5. MCP による build-test-fix ループを実行します（自律）

フェーズ 3: 人間による統合（30〜60分） 1. エージェントが作成したファイルを Xcode ターゲットに追加します 2. 署名とエンタイトルメントを確認します 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]

エージェントの有効性は、CLAUDE.md がプロジェクトの現在の状態をどれだけ正確に反映しているかに比例します。重要な新機能を追加したとき、アーキテクチャパターンを変更したとき、新しいフレームワークを導入したときは、CLAUDE.md を更新してください。

エージェントに関与させるべき場合とそうでない場合

エージェント定義を設定する

Claude Code のエージェント定義システム（.claude/agents/）を使う場合は、iOS 専用エージェントを作成します。

---
name: ios-developer
description: iOS development agent with MCP build tools and SwiftUI expertise
tools:
  - XcodeBuildMCP
  - xcode
---

# iOS Developer Agent

You are an iOS development agent for apps targeting iOS 26+ with SwiftUI.

## Architecture Rules
- @Observable for all view models (NEVER ObservableObject)
- NavigationStack for all navigation (NEVER NavigationView)
- SwiftData for persistence
- Swift 6.2 strict concurrency
- @MainActor on all Observable classes

## Build & Test — Always Use MCP

Prefer MCP tools over raw shell commands for ALL build operations:

- **Build**: `build_sim` / `build_device` (NOT `xcodebuild` via Bash)
- **Test**: `test_sim` / `test_device` (NOT `xcodebuild test` via Bash)
- **Simulators**: `list_sims`, `boot_sim`, `open_sim`
- **Debug**: `debug_attach_sim`, `debug_stack`, `debug_variables`
- **Apple docs**: `DocumentationSearch` (NOT WebSearch for Apple APIs)
- **Swift verification**: `ExecuteSnippet` (NOT `swift` via Bash)

MCP returns structured JSON. Bash returns unstructured text.

## File Management Rules
- NEVER modify .pbxproj, .xcodeproj/, .xcworkspace/, .xib, .storyboard
- Create Swift files in the correct directory
- Report files that need manual addition to Xcode targets

## SwiftData Rules
- @Model classes are automatically Observable — do not add @Observable
- Use @Bindable for form bindings to model properties
- Use @Query in views, modelContext.fetch() elsewhere
- Document relationship delete rules

## When You Get Stuck
- Build errors: use `build_sim` via MCP for structured output
- API questions: use `DocumentationSearch` via Apple MCP
- Swift verification: use `ExecuteSnippet` via Apple MCP
- Never guess — verify with tools

Claude Code セッションでは、このエージェントを @ios-developer で参照します。

エージェント支援 iOS のテストパターン

明確なガイダンスを与えると、エージェントは優れたユニットテストを書けます。最も良い結果につながるパターンを紹介します。

テストファイルの構成

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

これが機能する理由: 番号付きの受け入れ条件により、エージェントにチェックリストを渡せます。既存のテストファイルを参照することで、パターンを確立できます。setUp() の使い方を指定すると、エージェントが絡み合ったテスト状態を作るのを防げます。

効果の低いテストプロンプト:

Write tests for TimerManager.

これでは汎用的で浅いテストになり、エッジケースを見逃しやすく、プロジェクトのパターンに従わない可能性があります。

Async テストパターン

タイマー ベースや 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)
    }
}

エージェントに再確認させるべき重要なパターン: - @MainActor クラスをテストするテストメソッドには @MainActor を付ける - Task.sleep や async 処理を使うテストには async throws を使う - 時間ベースのアサーションには許容誤差を持たせる（正確に 1.0 秒ではなく、1.1 秒など） - テスト分離のために、クリーンな setUp() / tearDown() を用意する

Snapshot Testing

ビジュアルリグレッション検出には、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.

エージェントは snapshot テストを正しくセットアップできますが、参照画像をレビューすることはできません。最初のスナップショットは人間がレビューし、その後はエージェントのテストが将来の変更でビジュアルリグレッションを検出します。

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を採用する大きな理由の1つは、構造化されたJSONレスポンスが、生のxcodebuild出力よりはるかに少ないトークンしか消費しないことです。

一般的な開発セッションで10〜20回ビルドする場合、生のxcodebuildと比べてMCPでは30,000〜150,000トークンを節約できます。その分を、実際のコード推論に利用できます。

トラブルシューティング

「build_sim failed — scheme not found」

エージェントがスキーム名を推測しています。次のように修正します。

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 — command not found」

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

「MCPツールがClaude Codeに表示されない」

セッションの途中で登録した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'"
      }
    ]
  }
}

ルールが伝えるのは「変更しないでください」です。フックが強制するのは「変更できません」です。

FAQ

最初に使うべきエージェントランタイムはどれですか？

XcodeBuildMCPを備えたClaude Code CLIから始めましょう。MCPとの統合が最も深く、フックシステムも最も成熟しています。さらに、1Mのコンテキストウィンドウ（Opus 5）により、iOSプロジェクト全体を作業メモリに保持できます。まずはここから始め、ワークフローが成熟したら、レビュー用のCodexと、手早いインライン編集用のXcodeネイティブエージェントを追加してください。

MCPサーバーは両方必要ですか？

ほとんどの開発者にとって、XcodeBuildMCPだけでニーズの90%（ビルド、テスト、シミュレーター、デバッグ）を満たせます。ドキュメント検索、Swift REPLによる検証、SwiftUIプレビューのレンダリングが必要なら、AppleのXcode MCPを追加してください。後から追加することもでき、2つのサーバーはそれぞれ独立しています。

エージェントは新しいXcodeプロジェクトをゼロから作成できますか？

XcodeBuildMCPには、テンプレートから新しいXcodeプロジェクトを作成するスキャフォールディングツール（scaffold_ios_project、scaffold_macos_project）が含まれています。ただし、本番アプリでは、署名、Capabilities、ターゲット設定を正しく構成するため、Xcodeでプロジェクトを作成し、その後のコード実装をすべてエージェントに任せることをおすすめします。Xcodeの新規プロジェクトウィザードに費やす5分で、エージェントが生成したプロジェクト設定に起因する何時間もの問題を防げます。

エージェントはSwift Package Managerの依存関係をどのように扱いますか？

適切に扱えます。Package.swiftは標準的なSwiftファイルなので、エージェントが確実に読み書きできます。依存関係の追加、バージョン範囲の更新、ターゲットの設定はいずれも可能です。制限があるのは、.xcodeprojベースの依存関係管理（Xcodeのパッケージ解決UI）です。これは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ブロックを確認してください。

アクセシビリティの実装にエージェントを利用できますか？

部分的には利用できます。アクセシビリティのラベル、ヒント、traitsは正しく追加できます。

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を使用してください。

エージェントはCore Dataのマイグレーション（SwiftDataを使用していない場合）をどのように扱いますか？

エージェントは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プレビューをどのように扱いますか？

方法は2つあります。 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開発は、Web開発と比べて特に高価でも安価でもありません。

UIKitプロジェクトでもエージェントを使用できますか？

はい。ただし、エージェントはSwiftUIのほうが効果的に作業できます。UIKitはボイラープレートが多く、宣言的な構造が少ないうえ、エージェントが編集できないInterface Builderファイルを扱うこともよくあります。UIKitプロジェクトでは、モデル層とビジネスロジックにエージェントを使用し、UIは手動で扱う方法を検討してください。または、ビューを段階的にSwiftUIへ移行することもできます。

エージェントはローカライズをどのように扱いますか？

エージェントは.xcstrings（Xcode String Catalog）ファイルを効果的に作成、編集できます。新しいローカライズキーの追加、翻訳の提供、言語間の一貫性維持が可能です。.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：クロージャで循環参照を作る

発生すること： 特にTimer.publish、NotificationCenter、完了ハンドラーで、selfを強参照するクロージャを作成します。

防止策： 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の並行処理に関する警告や、メインスレッド外でUIが更新された際のランタイムクラッシュを引き起こします。

防止策：

## 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人で行った場合の実時間を比較したものです。文書化されておらずフックもないプロジェクトでは、改善はおそらく1.5〜2倍にとどまります。エージェントが構築するよりも推測することに時間を使いすぎるためです。³³

効果のある投資： CLAUDE.md、フック、MCPの設定に費やす時間です。セットアップに1時間かけるごとに、エージェントのミスを修正するための何時間もの作業を削減できます。設定そのものがプロダクトであり、エージェントはその実行エンジンです。

意外だったこと： MCPサーバーによって、開発の進め方が大きく変わったことです。MCPを導入する前のエージェントは、たまたまSwiftを理解している高機能なテキストエディターでした。導入後は、コードの作成、ビルド、テスト、デバッグ、反復改善まで行う開発パートナーになりました。この構造化されたフィードバックループこそが、コードを書くエージェントとコードをリリースまで導けるエージェントを分ける要素です。

過去の自分に伝えたいこと： まず最小のアプリ（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)

変更履歴

参照