Android Kotlin Compose 개발
Kotlin, Jetpack Compose, MVVM, Hilt, Room 3, DataStore, Paging 3 또는 멀티 모듈 프로젝트로 Android 앱을 구축할 때 사용하세요. Android 프로젝트, 화면, ViewModel, 리포지토리, 기능 모듈을 생성하거나 Android 아키텍처 패턴에 대한 질문이 있을 때 트리거됩니다.
빠른 참조
| 작업 | 참조 파일 |
|---|---|
| 프로젝트 구조 및 모듈 | modularization.md |
| 아키텍처 계층 (도메인, 데이터, UI, 공통 등) | architecture.md |
| Compose 패턴, Material 모션, 애니메이션, Modifier, 안정성 | compose-patterns.md |
| 접근성, TalkBack, 레이블 복사본, 실시간 영역, Espresso 접근성 검사 | android-accessibility.md |
| 알림, 포그라운드 서비스, 미디어/오디오, PiP, 공유 시트 | android-notifications.md |
| 데이터 동기화 및 오프라인 우선 패턴 | android-data-sync.md |
| Material 3 테마, 간격 토큰, 카테고리 적합성, 동적 색상 | android-theming.md |
| Navigation3, 적응형 탐색, 대형 화면 품질 계층 | android-navigation.md |
| Kotlin 모범 사례, View 생명주기 상호 운용 | kotlin-patterns.md |
| 코루틴 모범 사례 | coroutines-patterns.md |
| Gradle, 제품 플레이버, BuildConfig, 빌드 성능 | gradle-setup.md |
| 테스트 접근 방식 | testing.md |
| 국제화 및 지역화 | android-i18n.md |
| 아이콘, 적응형 런처 사양, 사용자 정의 그리기 | android-graphics.md |
| 런타임 권한 | android-permissions.md |
| Kotlin 위임 패턴 | kotlin-delegation.md |
| 충돌 보고 | crashlytics.md |
| StrictMode 가드레일 | android-strictmode.md |
| 멀티 모듈 의존성 | dependencies.md |
| 코드 품질 (Detekt) | code-quality.md |
| 코드 커버리지 (JaCoCo) | android-code-coverage.md |
보안, Play Integrity (Standard/Classic), 서버 디코드, requestHash/nonce, 계층화된 정책, 해결; Credential Manager; 보조적인 로컬 루트 검사 | android-security.md |
| 디자인 패턴 | design-patterns.md |
| 성능, Play Vitals, 선택적 CI 보고 (Play Developer Reporting API), 시작, 재구성, 지연, 배터리 | android-performance.md |
| 디버깅, Logcat 수준, ANR, Gradle 오류 패턴, R8, 메모리 누수 | android-debugging.md |
| 마이그레이션 가이드 (XML, RxJava, Navigation, Compose, Room 2→3) | migration.md |
워크플로우 의사 결정 트리
새 프로젝트를 생성 중인가요?
→ 설정 및 모듈 포함을 위해 assets/settings.gradle.kts.template로 시작하세요.
→ 버전 카탈로그를 위해 assets/libs.versions.toml.template로 시작하세요.
→ assets/convention/의 모든 파일을 build-logic/convention/src/main/kotlin/에 복사하세요.
→ build-logic/settings.gradle.kts를 생성하세요 (assets/convention/QUICK_REFERENCE.md 참조).
→ 루트 settings.gradle.kts에 includeBuild("build-logic")을 추가하세요.
→ gradle/libs.versions.toml에 플러그인 항목을 추가하세요 (assets/convention/QUICK_REFERENCE.md 참조).
→ assets/proguard-rules.pro.template를 app/proguard-rules.pro에 복사하세요.
→ 구조 및 모듈 유형을 위해 modularization.md를 읽으세요.
→ 빌드 파일 및 빌드 로직을 위해 gradle-setup.md를 사용하세요.
Gradle/빌드 파일을 구성 중인가요?
→ 모듈 build.gradle.kts 패턴을 위해 gradle-setup.md를 사용하세요.
→ 최적화 워크플로우, 진단 및 병목 현상 해결을 위해 gradle-setup.md → "빌드 성능"을 사용하세요.
→ 프로젝트의 build-logic/에 assets/convention/의 컨벤션 플러그인을 복사하세요.
→ 설정 지침 및 예제는 assets/convention/QUICK_REFERENCE.md를 참조하세요.
→ R8 규칙을 위해 assets/proguard-rules.pro.template를 app/proguard-rules.pro에 복사하세요.
코드 품질 / Detekt를 설정 중인가요?
→ Detekt 컨벤션 플러그인 설정을 위해 code-quality.md를 사용하세요.
→ 규칙을 위해 assets/detekt.yml.template에서 시작하고 Compose 규칙을 활성화하세요.
의존성을 추가하거나 업데이트 중인가요?
→ dependencies.md를 따르세요.
→ 의존성이 누락된 경우 assets/libs.versions.toml.template를 업데이트하세요.
새 기능/모듈을 추가 중인가요? → modularization.md의 모듈 명명 규칙을 따르세요. → 기능 모듈에서 프레젠테이션 계층을 구현하세요. → 의존성 흐름을 따르세요: 기능 → 코어/도메인 → 코어/데이터
UI 화면/컴포넌트를 구축 중인가요?
→ 화면 아키텍처, 상태, 컴포넌트, Modifier를 위해 compose-patterns.md를 읽으세요.
→ 로딩 및 새로 고침 중 안정적인 레이아웃을 위해 compose-patterns.md -> 상태 관리 -> "로딩 및 새로 고침 UX"를 사용하세요 (컨텍스트를 지우는 전체 화면 스피너를 피하세요).
→ Material 3 색상, 타이포그래피 및 모양을 위해 android-theming.md를 사용하세요.
→ 항상 Kotlin 코드를 kotlin-patterns.md에 맞추세요.
→ 기능 모듈에서 Screen + ViewModel + UiState를 생성하세요.
→ 가능하면 core/ui의 공유 컴포넌트를 사용하세요.
상태 및 이벤트를 처리 중인가요?
→ 상태에는 StateFlow를 사용하고, 엄격한 일회성 UI 명령에는 Channel + receiveAsFlow()를 사용하며, 멀티캐스트 또는 재생 의도 이벤트에는 SharedFlow를 사용하세요 (coroutines-patterns.md 참조).
→ SavedStateHandle로 프로세스 종료를 처리하세요 (compose-patterns.md 참조).
앱 테마(색상, 타이포그래피, 모양)를 설정 중인가요?
→ Material 3 테마 및 동적 색상을 위해 android-theming.md를 따르세요.
→ MaterialTheme.colorScheme의 의미론적 색상 역할을 사용하세요 (하드코딩된 색상 사용 금지); 모든 채우기에는 on* 파트너를 짝지으세요 - 색상 짝짓기 규칙 참조.
→ Color.kt에서 전체 M3 색상 세트를 선언하세요 (표면 컨테이너, 어둡게/밝게, *Fixed/*FixedDim) - 전체 색상 역할 참조 및 표면 컨테이너 계층 구조 참조.
→ 깊이는 먼저 컨테이너 톤으로 표현하고, 그림자는 임의의 콘텐츠 위에 떠 있는 컴포넌트에만 사용하세요 - 톤 높이 vs 그림자 참조.
→ 대화형 테두리/포커스에는 outline을, 장식적 구분선에는 outlineVariant를 사용하세요 - outline vs outlineVariant 참조.
→ 사용자 기본 설정 토글로 밝은/어두운 테마를 지원하세요.
→ API 31+에서 동적 색상 (Material You)을 활성화하고, 브랜드/확장 색상을 primary에 맞게 조화시키세요 - 브랜드 색상 조화 참조.
→ Android 14+(API 34)의 시스템 대비 슬라이더를 준수하려면 중간/높은 대비 색상표 변형을 제공하고 UiModeManager.getContrast()를 읽으세요 - 사용자 대비 기본 설정 참조.
→ 지역별 팔레트 재정의(파괴적 범위, 미디어 툴바 등)의 경우 colorScheme.copy(...)와 함께 중첩된 MaterialTheme를 사용하세요 - 범위 테마 참조.
→ Card / OutlinedCard / ElevatedCard는 중요도가 아닌 표면 분리에 따라 선택하고, 토큰 수준에서 모양을 재정의하세요 - 카드 변형 및 컴포넌트 모양 기본값 참조.
Kotlin 코드를 작성 중인가요? → 항상 kotlin-patterns.md를 따르세요. → architecture.md, modularization.md 및 compose-patterns.md의 모범 사례와 일치하는지 확인하세요.
데이터/도메인 계층을 설정 중인가요?
→ architecture.md를 읽으세요.
→ Hilt @Binds, 범위 및 DI 안티 패턴: architecture.md -> 도메인 계층 -> "의존성 주입 설정"
→ core/domain에 리포지토리 인터페이스를 생성하세요.
→ core/data에서 Room 3/Retrofit/DataStore를 사용하여 구현체를 생성하세요.
→ 간단한 키-값 쌍에는 DataStore를 사용하고, 복잡한 관계형 데이터에는 Room 3 (suspend / Flow DAO, SQLiteDriver)를 사용하세요.
목록 및 스크롤을 구현 중인가요?
→ 안정적인 키와 contentType과 함께 LazyColumn/LazyRow를 사용하세요 (compose-patterns.md 참조).
→ 대규모 데이터 세트에는 Paging 3를 사용하세요 (compose-patterns.md -> "Paging 3" 참조).
탐색을 처리 중인가요? → 적응형 탐색을 위해 Navigation3를 사용하세요 (android-navigation.md 참조). → 탐색 안티 패턴을 피하세요 (android-navigation.md -> "탐색 안티 패턴" 참조).
성능을 최적화 중인가요?
→ android-performance.md의 성능 체크리스트를 따르세요.
→ 사용자가 자동화된 Play Console Vitals (CI/Slack, Play Console UI 없음)을 요청하는 경우 android-performance.md → 선택 사항: Play Vitals 관찰 가능성 (Play Developer Reporting API) 을 사용하세요.
→ 고주파 텍스트 입력에는 BasicTextField2를 사용하세요.
테스트 중인가요? → testing.md를 읽어 테스트 철학과 패턴을 확인하세요. → Flow 방출 테스트를 위해 Turbine을 사용하세요 (testing.md -> "Turbine을 사용한 Flow 방출 테스트" 참조). → 리포지토리 테스트를 위한 데이터베이스 로직 및 MockK를 만드세요.