Clerk Android (네이티브)은(는) 무엇을 하나요?
이 스킬은 현재 clerk-android SDK 및 문서 패턴을 따라 네이티브 Android 프로젝트에 Clerk을 구현합니다.
활성화 규칙
다음 조건 중 하나라도 참일 때 이 스킬을 활성화하세요:
- 사용자가 Android, Kotlin, Jetpack Compose 또는 Android용 네이티브 모바일 Clerk 구현을 명시적으로 요청한 경우
- 프로젝트가 네이티브 Android로 보이는 경우(예:
build.gradle(.kts)에 Android 플러그인,AndroidManifest.xml,app/src/main/java, Compose UI 파일)
다음 조건 중 하나라도 참일 때 이 스킬을 활성화하지 마세요:
- 프로젝트가 Expo인 경우
- 프로젝트가 React Native인 경우
Expo/React Native 신호가 감지되면 대신 일반 설정 스킬로 라우팅하세요.
무엇이 필요하신가요?
| 작업 | 참고 자료 |
|---|---|
| 미리 빌드된 AuthView / UserButton (가장 빠름) | references/prebuilt.md |
| 커스텀 API 기반 인증 흐름 (완전한 제어) | references/custom.md |
빠른 시작
| 단계 | 작업 |
|---|---|
| 1 | 프로젝트 유형이 네이티브 Android이고 Expo/React Native가 아님을 확인 |
| 2 | 흐름 유형(prebuilt 또는 custom) 결정하고 일치하는 참고 자료 파일 로드 |
| 3 | 실제 Clerk 발행 가능 키가 있는지 확인(또는 개발자에게 요청) |
| 4 | 선택한 흐름에 맞는 올바른 Clerk 아티팩트가 설치되었는지 확인 |
| 5 | 공식 Android 퀵스타트를 읽고 필수 설정(네이티브 API, 최소 SDK/Java, 매니페스트, 초기화)을 확인 |
| 6 | 선택한 흐름과 관련된 clerk-android 소스/샘플 패턴 검사 |
| 7 | 선택한 참고 자료 체크리스트만 따라 흐름 구현 |
의사 결정 트리
사용자가 Android/Kotlin에서 Clerk 요청
|
+-- Expo/React Native 프로젝트 감지?
| |
| +-- 예 -> 이 스킬 사용 안 함
| |
| +-- 아니오 -> 계속 진행
|
+-- 기존 인증 UI 감지?
| |
| +-- 미리 빌드된 뷰 감지 -> references/prebuilt.md 로드
| |
| +-- 커스텀 흐름 감지 -> references/custom.md 로드
| |
| +-- 새 구현 -> 개발자에게 prebuilt/custom 질문 후 일치하는 참고 자료 로드
|
+-- 발행 가능 키 및 SDK 초기화 경로 확인
|
+-- 올바른 Android 아티팩트가 설치되었는지 확인
|
+-- 프로젝트에서 퀵스타트 필수 조건 확인
|
+-- 선택한 흐름 참고 자료를 사용하여 구현
흐름 참고 자료
흐름 유형이 확인된 후 정확히 하나를 로드하세요:
- Prebuilt 흐름: references/prebuilt.md
- 커스텀 흐름: references/custom.md
개발자가 명시적으로 하이브리드 접근 방식을 요청하지 않는 한 두 참고 자료를 단일 구현에 혼합하지 마세요.
상호작용 계약
구현 편집 전에 에이전트는 다음 두 가지를 모두 가지고 있어야 합니다:
- 흐름 선택:
prebuilt또는custom - 실제 Clerk 발행 가능 키
사용자 요청/컨텍스트에서 둘 중 하나라도 누락된 경우:
- 사용자에게 누락된 값을 요청하세요
- 응답을 기다리며 멈추세요
- 아직 파일을 편집하거나 종속성을 설치하지 마세요
사용자가 이 대화에서 이미 해당 값을 명시적으로 제공한 경우에만 질문을 건너뜁니다.
소스 기반 템플릿
이 스킬에 구현 예제를 하드코딩하지 마세요. 구현 전에 설치된 SDK 버전에 대한 현재 clerk-android 소스/문서를 검사하세요.
| 사용 사례 | 진실의 근원 |
|---|---|
SDK 아티팩트 및 종속성 분할(clerk-android-api vs clerk-android-ui) | clerk-android README 및 Android 설치 문서 |
| SDK 초기화 및 발행 가능 키 연결 | Android 퀵스타트 및 source/api/.../Clerk.kt |
| 미리 빌드된 인증 및 프로필 동작 | source/ui/.../AuthView.kt, source/ui/.../UserButton.kt 및 prebuilt 샘플 |
| 커스텀 인증 순서 및 요소 처리 | source/ui/auth/*, source/api/auth/* 및 custom-flows 샘플 |
| 인스턴스 설정에서 기능/특징 게이팅 | Clerk 공개 필드(예: enabledFirstFactorAttributes, socialProviders, isGoogleOneTapEnabled, mfaIsEnabled) 및 환경 모델 소스 |
| 필수 Android 설정 체크리스트 | 공식 Android 퀵스타트(/docs/android/getting-started/quickstart) |
실행 게이트 (건너뛰지 마세요)
-
필수 조건 전에는 구현 편집 금지
- 흐름 유형이 확인되고 유효한 발행 가능 키를 사용할 수 있을 때까지 프로젝트 파일을 편집하지 마세요.
-
누락된 흐름 또는 키는 질문을 트리거해야 함
- 흐름 선택이 누락된 경우 명시적으로 질문: prebuilt 뷰 또는 커스텀 흐름?
- 발행 가능 키가 누락/플레이스홀더/유효하지 않은 경우 실제 키를 명시적으로 요청하세요.
- 두 답변 모두 제공될 때까지 계속 진행하지 마세요.
-
발행 가능 키 연결 방식은 필수
- 기본적으로
Clerk.initialize(...)에서 개발자가 제공한 키를 직접 연결합니다. - 명시적으로 요청되지 않는 한 비밀 관리 간접 참조를 도입하지 마세요.
- 기본적으로
-
아티팩트 설치 정책은 필수
- Prebuilt 흐름:
clerk-android-ui사용(API 포함). - 커스텀 흐름:
clerk-android-api사용(단, prebuilt 구성 요소가 명시적으로 요청되지 않은 경우). - Clerk 아티팩트가 누락된 경우 사용 가능한 최신 안정 릴리스를 추가하세요.
- Prebuilt 흐름:
-
Android 퀵스타트 준수는 필수
- Clerk 앱에 대해 네이티브 API가 활성화되었는지 확인하세요.
- 퀵스타트의 Android 요구 사항(최소 SDK 및 Java 대상, 매니페스트 인터넷 권한, 앱 수준 Clerk 초기화)이 프로젝트에 구현되었는지 확인하세요.
- 앱이 인증 준비 상태를 가정하기 전에 SDK 초기화(
Clerk.isInitialized)를 기다리는지 확인하세요.
-
기능 기반 동작은 필수
- Clerk 런타임 기능/설정 상태(예: 활성화된 요소/소셜 제공자/MFA 플래그)를 사용하여 흐름 동작을 게이팅하세요.
- 대시보드 구성과 충돌할 수 있는 요소 가정을 하드코딩하지 마세요.
-
참고 자료 파일 규율은 필수
- 흐름이 선택되면 구현 및 검증을 위해 해당 흐름 참고 자료 파일만 따르세요.
-
커스텀 흐름 구조 패리티는 필수
custom흐름의 경우 다단계 인증 진행 및 요소별 처리를 유지하세요(기본적으로 단일 모든 필드 양식 사용 안 함).- UI, 상태 오케스트레이션 및 Clerk API 통합을 별도 모듈로 유지하세요.
-
선택된 경우 prebuilt 선호는 필수
prebuilt흐름의 경우 명시적으로 요청되지 않는 한 커스텀 API 호출로 인증 양식을 재구축하지 마세요.- 기본 구성 요소로
AuthView/UserButton을 사용하세요.
워크플로
- 네이티브 Android와 Expo/React Native 구분.
- 흐름 유형이 명시적으로 제공되지 않은 경우 사용자에게
prebuilt또는custom을 물어보세요. - 발행 가능 키가 명시적으로 제공되지 않은 경우 사용자에게 키를 물어보세요.
- 파일을 변경하기 전에 두 답변을 모두 기다리세요.
- 일치하는 흐름 참고 자료 파일을 로드하세요.
Clerk.initialize(...)경로와 발행 가능 키 연결이 유효한지 확인하세요.- 종속성/아티팩트가 선택한 흐름과 일치하는지 확인하세요.
- Android 퀵스타트 요구 사항을 검토하고 프로젝트에 누락된 설정을 적용하세요.
- 선택한 참고 자료 체크리스트를 사용하여 구현하세요.
- 선택한 참고 자료 체크리스트와 공유 게이트를 사용하여 검증하세요.
일반적인 함정
| 수준 | 문제 | 예방 |
|---|---|---|
| 치명적 | 구현 전에 누락된 흐름 선택을 묻지 않음 | prebuilt vs custom을 묻고 편집 전에 기다리기 |
| 치명적 | 구현 전에 누락된 발행 가능 키를 묻지 않음 | 키를 묻고 편집 전에 기다리기 |
| 치명적 | 흐름 유형이 확인되기 전에 구현 시작 | 먼저 흐름을 확인하고 일치하는 참고 자료 로드 |
| 치명적 | Android 퀵스타트 필수 조건 건너뛰기 | 공식 Android 퀵스타트의 필수 설정 확인 및 적용 |
| 치명적 | 앱 수준 Clerk.initialize(...) 호출 누락 | Application 시작 경로에서 Clerk 초기화 |
| 높음 | 선택한 흐름에 잘못된 아티팩트 | Prebuilt: clerk-android-ui, custom: clerk-android-api |
| 높음 | SDK 초기화 완료 전에 인증 UI 렌더링 | Clerk.isInitialized 상태로 UI 게이팅 |
| 높음 | 인증 요소/소셜 제공자 하드코딩 | Clerk 런타임 기능 필드에서 동작 구동 |
| 높음 | Expo/React Native에 이 스킬 사용 | 구현 전에 감지하고 라우팅 전환 |
참고
- 상위 수준 Clerk 라우팅을 위한
clerk스킬 - 프레임워크 간 퀵스타트 설정을 위한
clerk-setup스킬 https://github.com/clerk/clerk-androidhttps://clerk.com/docs/android/getting-started/quickstart