clerk-swift

Clerk Swift（ネイティブ iOS）

このスキルは、インストール済みパッケージのソースを読み取り、現在の ClerkKit／ClerkKitUI の動作を再現することで、ネイティブの Swift／iOS プロジェクトに Clerk を実装します。

有効化ルール

次のいずれかの条件に該当する場合、このスキルを有効にします。

• ユーザーが Swift、SwiftUI、UIKit、またはネイティブ iOS での Clerk 実装を明示的に求めている。
• プロジェクトがネイティブ iOS／Swift プロジェクトと思われる（例：.xcodeproj、.xcworkspace、Package.swift、Swift ターゲット）。

次のいずれかの条件に該当する場合、このスキルを有効にしないでください。

• プロジェクトが Expo である。
• プロジェクトが React Native である。

Expo／React Native の兆候がある場合は、このスキルではなく、一般的なセットアップスキルに案内してください。

何が必要ですか？

タスク	リファレンス
ビルド済みの AuthView / UserButton（最速）	references/prebuilt.md
カスタムの API 駆動型認証フロー（完全な制御）	references/custom.md

クイックスタート

手順	アクション
1	プロジェクトがネイティブ Swift／iOS であり、Expo／React Native ではないことを確認します
2	フローの種類（prebuilt または custom）を決定し、該当するリファレンスファイルを読み込みます
3	有効な publishable key が存在することを確認します（なければ開発者に確認します）。設定に直接指定します
4	選択したフローに適したプロダクトを含めて clerk-ios パッケージがインストールされていることを確認します。未インストールの場合は、up-to-next-major バージョン要件を使用して、利用可能な最新リリースをインストールします
5	インストール済みの ClerkKitUI ソースを調べ、機能やステップの制御に使用される Environment フィールドを特定します
6	手順 5 の後に /v1/environment を呼び出し、ClerkKitUI に対応するフィールドマップのみを使って評価します
7	インストール済みの clerk-ios パッケージの README で iOS クイックスタートの URL を見つけ、.md を追加してから、その Markdown URL にアクセスして読み、必須手順のチェックリストを作成します
8	このプロジェクトでクイックスタートの前提条件（関連ドメインや必要な機能など）をすべて確認し、満たします
9	選択したリファレンスのチェックリストのみに従ってフローを実装します

決定ツリー

User asks for Clerk in Swift/iOS
    |
    +-- Expo/React Native project detected?
    |     |
    |     +-- YES -> Do not use this skill
    |     |
    |     +-- NO -> Continue
    |
    +-- Existing auth UI detected?
    |     |
    |     +-- Prebuilt views detected -> Load references/prebuilt.md
    |     |
    |     +-- Custom flow detected -> Load references/custom.md
    |     |
    |     +-- New implementation -> Ask developer prebuilt/custom, then load matching reference
    |
    +-- Ensure publishable key and direct wiring
    |
    +-- Ensure clerk-ios is installed
    |
    +-- Inspect ClerkKitUI Environment field usage
    |
    +-- Call /v1/environment using that field map
    |
    +-- Visit/read quickstart URL from installed clerk-ios package README
    |
    +-- Verify all quickstart prerequisites are completed
    |
    +-- Implement using selected flow reference

フローのリファレンス

フローの種類が決まったら、次のいずれか 1 つだけを読み込みます。

• ビルド済みフロー：references/prebuilt.md
• カスタムフロー：references/custom.md

開発者が明示的にハイブリッド方式を求めない限り、1 つの実装で両方のリファレンスを組み合わせないでください。

対話のルール

実装に関する編集を行う前に、エージェントは次の両方を確認する必要があります。

• フローの選択：prebuilt または custom
• 実際に使用できる Clerk publishable key

いずれかの値がユーザーのリクエストまたはコンテキストに含まれていない場合：

• 不足している値をユーザーに確認します
• 回答を待ちます
• まだファイルを編集したり、依存関係をインストールしたりしないでください

ユーザーがこの会話ですでに値を明示している場合に限り、確認を省略できます。

ソースに基づくテンプレート

このスキルで実装例をハードコードしないでください。実装前に、現在インストールされているパッケージのソースを調べてください。

用途	インストール済みパッケージにおける信頼できる情報源
SDK パッケージのプロダクト、プラットフォームのサポート、依存関係の制約	ClerkKit と ClerkKitUI のパッケージマニフェストおよびターゲットのプロダクト定義、ならびにパッケージ要件の形式（up-to-next-major）
Publishable key の検証とフロントエンド API の導出	Clerk の設定ロジック（次のシンボルを検索：configure(publishableKey、frontendApiUrl、invalidPublishableKeyFormat）
環境エンドポイントの契約とフィールドの意味	環境リクエストのパスとリクエスト構築処理、および制御に使用する ClerkKitUI の Environment フィールドの使用箇所（次のシンボルを検索：/v1/environment、Request<Clerk.Environment>、ClerkKitUI 内の Environment の使用箇所）
iOS クイックスタートの要件	インストール済みの clerk-ios パッケージ README にあるクイックスタートのリンクと、アクセスして読んだクイックスタートページのチェックリスト手順（プロジェクト設定の前提条件を含む）
ネイティブの Sign in with Apple 実装	選択したフローのリファレンスに記載された Apple の機能とネイティブのサインイン動作

実行ゲート（スキップ禁止）

1. 前提条件を満たす前に実装を変更しない

• フローの種類が確認され、有効な公開可能キーが用意されるまで、プロジェクトファイルを編集しないでください。

2. フローまたはキーが不足している場合は質問する

• フローの選択が不明な場合は、必ず「組み込みビュー」か「カスタムフロー」かを明示的に尋ねてください。
• 公開可能キーが不足している、プレースホルダーである、または無効な場合は、実際のキーを明示的に求めてください。
• 両方の回答がそろうまで作業を続けないでください。

3. 公開可能キーの設定方法は必須

• 開発者から提供された公開可能キーを、Clerk.configure に渡すアプリ設定にそのまま記述してください。
• 明示的に依頼されない限り、plist／ローカルシークレット／環境ファイル／ビルド設定を介した間接的な設定は導入しないでください。

4. パッケージのインストールとバージョンの方針は必須

• clerk-ios がインストールされていない場合は、最新の利用可能なリリースを上限非包含の次のメジャーバージョン要件で追加してください。
• 開発者からバージョンの完全固定を明示的に求められない限り、パッケージのバージョンを正確に固定しないでください。

5. ClerkKitUI の Environment フィールドの調査は必須

• パッケージのインストール後、インストールされた ClerkKitUI のソースを調査し、選択したフローで認証の動作を制御する Environment フィールドを特定してください。
• /v1/environment を呼び出す前に、エージェント内部で使用するフィールドマップを作成してください。

6. Environment の呼び出しは必須（両方のフロー）

• パッケージのインストールと手順 5 のフィールドマップの調査が完了してから、/v1/environment に直接 HTTP リクエストを送信してください。
• ClerkKitUI に準拠したフィールドマップを使って、レスポンスを選択したリファレンスワークフローに渡してください。
  • 組み込み：Apple が有効かどうか、およびケイパビリティの変更が必要かどうかの判断に使用します。
  • カスタム：正規化とマトリックス処理をすべてエージェント内部の分析として行います（マトリックスの成果物をプロジェクトコードに保存してはいけません）。

7. リファレンスファイルの取り扱いは必須

• フローを選択したら、実装と検証にはそのフローのリファレンスファイルだけを使用してください。

8. クイックスタートへの準拠は必須

• インストールされた clerk-ios パッケージの README から iOS クイックスタートの URL を見つけ、末尾に .md を追加して、その Markdown URL にアクセスし、内容を読んでください。
• 完了前に、クイックスタートのすべてのセットアップ手順に照らしてプロジェクトを監査してください。
• 必須のクイックスタート設定が不足している場合は、タスクを完了する前に実装してください。
• これには、不足している Associated Domains エントリーや、クイックスタートで必要とされるその他のアプリケーションケイパビリティの追加が含まれます。
• クイックスタートの手順 Add associated domain capability（https://clerk.com/docs/ios/getting-started/quickstart#add-associated-domain-capability）を明示的に実行し、Associated Domains のエントリーがクイックスタートの要件（webcredentials:{YOUR_FRONTEND_API_URL}）に一致することを確認してください。

9. カスタムフローの AuthView 構造との同等性は必須

• custom フローでは、レイアウトとフロー構造を ClerkKitUI の AuthView のデフォルトに実質的に近い状態に保ってください。
• 開発者が異なる UX を明示的に求めていない場合は、AuthView から大きく構造やレイアウトを逸脱させないでください。
• カスタムの順序、ゲーティング、Environment の使用方法やセマンティクスについて不明または混乱がある場合は、インストールされた ClerkKitUI の動作を優先し、それに沿わせてください。

ワークフロー

1. ネイティブ iOS／Swift か Expo／React Native かを検出します。
2. フローの種類が明示されていない場合は、ユーザーに prebuilt または custom のどちらかを尋ねます。
3. 公開可能キーが明示されていない場合は、ユーザーにそのキーを尋ねます。
4. 両方の回答が得られるまで、ファイルを変更しません。
5. 選択したフローに一致するリファレンスファイルを読み込みます。
6. 公開可能キーが有効で、Clerk.configure に直接設定されていることを確認します。
7. パッケージのインストール内容／プロダクトが選択したフローに一致し、新たに追加するパッケージの要件が最新の次のメジャーバージョンまでのポリシーに従っていることを確認します。
8. インストール済みの ClerkKitUI のソースを調べ、選択したフローでゲーティング／必須動作に使われる Environment フィールドを特定します。
9. /v1/environment を呼び出し、ステップ 8 で作成したフィールド対応表に基づいてレスポンスを解釈します。
10. インストール済みの clerk-ios パッケージの README から iOS クイックスタートの URL を見つけ、末尾に .md を付けてアクセスし、内容を読みます。
11. アクセスした Markdown のクイックスタートからチェックリストを作成し、必須セットアップの不足を検出して、現在のプロジェクトに不足分を適用します。
12. クイックスタートの関連ドメイン機能の手順が完全に適用されていることを確認します。不足している場合は webcredentials:{YOUR_FRONTEND_API_URL} を追加します。
13. 選択したリファレンスのチェックリストに従って実装します。
14. 選択したリファレンスのチェックリストと共通の確認項目に基づいて検証します。

よくある落とし穴

レベル	問題	防止策
重大	実装前にフローの選択を尋ねない	prebuilt と custom のどちらかを尋ね、編集を始める前に回答を待ちます
重大	実装前に公開可能キーを尋ねない	キーを尋ね、編集を始める前に回答を待ちます
重大	フローの種類を確認する前に実装を開始する	まずフローを確認し、一致するリファレンスを読み込みます
重大	指示がないのに、plist／ローカル／環境変数を介して公開可能キーを設定する	デフォルトでは、キーを設定に直接指定します
重大	実装前に /v1/environment の呼び出しを省略する	prebuilt と custom のどちらのフローでも、必ず環境エンドポイントを呼び出します
重大	パッケージのインストールと ClerkKitUI の Environment フィールドの調査より前に /v1/environment を呼び出す	まず clerk-ios をインストールし、ClerkKitUI の Environment の使用方法を調べてから、エンドポイントを呼び出します
高	デフォルトで、clerk-ios を固定バージョン／古いバージョンでインストールする	未インストールの場合は、利用可能な最新リリースを次のメジャーバージョンまでの要件でインストールします
重大	クイックスタートの前提条件の監査を省略する	インストール済みの clerk-ios パッケージの README に記載されたクイックスタート URL にアクセスして内容を読み、必須セットアップがすべて完了していることを確認します
重大	不足しているクイックスタートの機能／ドメインを検出しても適用しない	完了前に、不足している必須のクイックスタート機能と関連ドメインをすべて追加します
重大	クイックスタートの関連ドメイン機能の手順を省略する	クイックスタートの Add associated domain capability を実行し、webcredentials:{YOUR_FRONTEND_API_URL} が存在することを確認します
重大	機能／必須フィールドの対応表をアプリのコードに記述する	対応表はエージェント内部にとどめ、そこから導き出した動作のみを UI／認証フローのコードに適用します
重大	明示的な指示なしに、custom フローのレイアウトを AuthView から大きく逸脱させる	デフォルトでは、custom の画面構成とステップの組み立てを AuthView に十分近づけます
重大	custom 認証を、すべてのフィールドを表示する単一画面にまとめる	AuthView スタイルの複数ステップの進行と、ステップごとのフィールド収集に従います
重大	不確かなまま custom フローの順序付け／ゲーティング／Environment の使用方法を推測する	インストール済みの ClerkKitUI の動作を参照し、最終的な実装に反映します
高	Expo／React Native にこのスキルを使用する	実装前に検出し、適切な別の手順に切り替えます

関連項目

• Clerk のトップレベルの振り分けについては clerk スキル
• ネイティブ以外、またはクロスフレームワークのセットアップについては clerk-setup スキル
• 現行の iOS クイックスタートリンクの参照元は、インストール済みの clerk-ios パッケージの README.md
• https://github.com/clerk/clerk-ios