clerk-swift

Clerk Swift（ネイティブ iOS および macOS）

このスキルは、ネイティブ Swift プロジェクトで Clerk 認証 UI を構築します。事前構築済みの ClerkKitUI ビュー、または ClerkKit を使ったカスタムフローに対応しています。SDK、ケイパビリティ、ネイティブアプリの登録、Clerk の初期化を含むセットアップを最初に行います。セットアップには専用のワークフローがあります。

有効化ルール

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

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

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

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

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

まず Clerk をセットアップする

Clerk がまだセットアップされていない場合（clerk-ios パッケージがない、Clerk.configure の呼び出しがない、または Clerk アプリケーションが選択されていない場合）、UI 作業の前にセットアップ用の iOS プロンプトに従ってください。この手順では Clerk CLI を使って Clerk アプリケーションを選択し、SDK をインストールし、ケイパビリティを設定し、ネイティブアプリを登録して、残りの Swift 統合作業に進みます。また、CLI が publishable key を提供するため、ユーザーにキーの貼り付けを求めないでください。

CLI でプロジェクトをセットアップできない場合（例：Xcode を利用できない、またはプロジェクトがサポート対象外の場合）は、代わりに手動の iOS クイックスタートに従ってください。

ユーザーがカスタムフローなどのサインイン UI をすでに依頼している場合は、セットアップのビルドチェックが通った時点で、ここから続行してください。それ以外の場合は、ユーザーがサインイン UI の追加または変更を希望したときに、このスキルに戻ってください。

何が必要ですか？

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

クイックスタート

手順	アクション
1	プロジェクトがネイティブ Swift であり、Expo／React Native ではないことを確認します
2	Clerk がセットアップされていない場合は、まずセットアップ用の iOS プロンプトに従います（上記を参照）
3	フローの種類（prebuilt または custom）を特定します。未決定の場合はユーザーに尋ね、該当するリファレンスを読み込みます
4	パッケージプロダクトやケイパビリティなど、選択したフローに必要な前提条件を確認し、不足しているものだけを対象として変更します
5	選択したリファレンスに従ってフローを実装します
6	ターゲットをビルドし、未検証の項目を報告します

判断ツリー

User asks for Clerk in Swift
    |
    +-- Expo/React Native project detected?
    |     |
    |     +-- YES -> Do not use this skill
    |     |
    |     +-- NO -> Continue
    |
    +-- Clerk set up in this project?
    |     |
    |     +-- NO -> Follow the iOS setup prompt (manual quickstart if the CLI can't)
    |     |
    |     +-- YES -> 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
    |
    +-- Make targeted prerequisite changes for the selected flow
    |
    +-- Implement using selected flow reference

フローのリファレンス

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

• 事前構築済みフロー：references/prebuilt.md
• カスタムフロー：references/custom.md

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

やり取りの契約

UI 実装を編集する前に、エージェントはフロー（prebuilt または custom）を把握している必要があります。決まっていない場合はユーザーに尋ね、回答を待ってください。この会話ですでにユーザーが選択している場合、または既存の UI から選択が明らかな場合に限り、質問を省略できます。

完了済みのセットアップを保持する

• 既存の Clerk.configure 呼び出しと、plist、ビルド設定、その他のカスタムキー読み込み方法を含む、アプリが publishable key を読み込む仕組みを保持してください。ハードコードされたキーに置き換えないでください。
• 既存のパッケージ要件、ケイパビリティ、エンタイトルメントを保持してください。選択したフローに必要で、かつ不足しているものだけを追加してください。
• 変更を加えずに Clerk とプロジェクトのセットアップを確認するには、npx -y clerk@latest doctor を実行します。SDK のリンク、ケイパビリティ、ネイティブアプリの登録、Apple との接続状況が報告されます。

ソースを基準にした実装

UI の動作、特にカスタムフローでは、インストール済みの clerk-ios パッケージのソースを参照してください。

ユースケース	インストール済みパッケージにおける基準ソース
SDK の製品、プラットフォームのサポート、依存関係の制約	ClerkKit と ClerkKitUI のパッケージマニフェストおよびターゲット製品の定義
認証フローの順序とゲーティング	ClerkKitUI の AuthView 実装と、注入された Clerk インスタンスの environment の読み取り方
ネイティブの Sign in with Apple	選択したフローのリファレンスにおける Apple サインインの動作

ワークフロー

1. ネイティブ Swift か Expo／React Native かを判別します。
2. Clerk がセットアップされていない場合は、iOS セットアッププロンプト（CLI でプロジェクトをセットアップできない場合は手動のクイックスタート）に従ってから、次に進みます。
3. フローの種類が不明な場合は、prebuilt か custom かを尋ねます。
4. 該当するフローのリファレンスを読み込みます。
5. そのフローの前提条件を確認し、完了済みのセットアップとカスタムキーの読み込みを維持しながら、不足している箇所だけを対象に変更します。
6. 選択したリファレンスに沿って実装します。
7. 選択したリファレンスに沿って検証してから、ターゲットをビルドします。

よくある問題

レベル	問題	防止策
CRITICAL	Clerk がセットアップされていないときに手作業でセットアップする	iOS セットアッププロンプトに従ってください。このプロンプトは Clerk CLI を実行します。CLI でプロジェクトをセットアップできない場合に限り、手動のクイックスタートを使用してください
CRITICAL	公開可能なキーをユーザーに貼り付けるよう求める	キーはセットアップ時に CLI が提供します。既存アプリ独自のキー読み込み方法を維持してください
CRITICAL	カスタムキーの読み込みや既存のセットアップを置き換える	既存の Clerk.configure、パッケージ、機能を維持し、不足しているものだけを追加してください
CRITICAL	フローの種類を確認する前に UI の実装を開始する	まずフローを確認してから、該当するリファレンスを読み込んでください
CRITICAL	明示的な依頼なく、カスタムフローのレイアウトを AuthView から大きく逸脱させる	原則として、カスタム画面の構成とステップの組み立ては AuthView に実質的に近づけてください
CRITICAL	カスタム認証を、すべての項目を含む単一画面にまとめる	AuthView 形式の複数ステップの進行と、各ステップに応じた項目の収集に従ってください
CRITICAL	不確かな場合に、カスタムフローの順序やゲーティングを推測する	インストール済みの ClerkKitUI の動作を参照し、それに合わせてください
HIGH	このインスタンスの現在の設定をカスタムフローのコードにハードコードする	AuthView と同様に、注入された Clerk インスタンスの environment に基づいて、実行時にステップをゲートしてください
HIGH	Expo／React Native にこのスキルを使用する	実装を始める前に判別し、別の手順へ振り分けてください

関連項目

• Clerk CLI を使って Clerk をセットアップするには、iOS セットアッププロンプトを参照してください
• Clerk の上位レベルの振り分けについては、clerk スキルを参照してください
• ネイティブ以外のセットアップやクロスフレームワークのセットアップについては、clerk-setup スキルを参照してください
• https://github.com/clerk/clerk-ios