| name | kotlin-patterns |
| description | Use when writing or refactoring Kotlin code, implementing coroutines/Flow, designing DSLs, or integrating Kotlin with Spring Boot. Do NOT use for JPA (use jpa-patterns), SQL optimization (use sql-optimization-patterns), or Java patterns (use java-modern-patterns). |
| paths | **/*.kt, **/*.kts, **/build.gradle* |
Kotlin Development Patterns
Idiomatic Kotlin patterns for building robust, type-safe, and concurrent applications.
Quick Start
When to Activate
- Writing new Kotlin code
- Reviewing or refactoring Kotlin code
- Implementing coroutines or Flow-based async operations
- Designing type-safe DSLs or builders
- Using Kotlin with Spring Boot
- Choosing between sealed classes, enums, data classes
CRITICAL Rules
MUST DO
- Null safety — Use
?, ?., ?: consistently. Prefer safe calls over !!
- Structured concurrency — Always use scoped coroutines (
viewModelScope, coroutineScope, supervisorScope)
- Immutability — Prefer
val over var, List over MutableList in public APIs
- Sealed types for state — Use
sealed class/sealed interface for UI state, results, errors
- Flow for reactive streams — Use
Flow for cold streams, StateFlow/SharedFlow for hot streams
- Scope functions correctly —
let for null check + transform, apply for configuration, also for side effects
- Explicit API mode for libraries — Use
explicit API mode in library modules
- KDoc for public APIs — Document public functions and classes
MUST NOT DO
GlobalScope.launch — Leaks coroutines, no structured concurrency
!! without justification — Prefer ?., ?:, or requireNotNull with message
runBlocking in production — Blocks the thread, defeats coroutines purpose
- Block in Flow operators —
Thread.sleep() in map/filter — use delay() + flowOn
- Ignore cancellation — Never catch
CancellationException (rethrow it)
- Forget
awaitClose in callbackFlow — Causes resource leaks
- Mix platform code in common modules (KMP) — Use
expect/actual
Reference Guide
Load detailed guidance based on context:
| Topic | Reference | Load When |
|---|
| Coroutines & Flow | references/coroutines-flow.md | Async operations, structured concurrency, Flow operators, backpressure, testing coroutines |
| Spring Boot + Kotlin | references/kotlin-springboot.md | Spring Boot Kotlin compiler plugins, constructor DI, Router DSL, coroutines in Spring |
| DSL & Idioms | references/dsl-idioms.md | Type-safe builders, scope functions, extension functions, delegated properties, inline/reified |
Pattern Hints
- Value class 적극 활용: UserId, Email 같은 primitive wrapper는
@JvmInline value class로 감싸서 타입 안전성 확보
- SharedFlow for one-shot events: 토스트, 네비게이션 등 일회성 이벤트는
MutableSharedFlow로 (StateFlow는 상태 유지용)
- Multiple sealed interfaces: UiState 외에 Result, Event 등 별도 sealed interface로 관심사 분리
Decision Tree
Writing Kotlin code?
├─ Async operation needed?
│ ├─ Simple suspend function → references/coroutines-flow.md
│ ├─ Reactive stream → Flow API (references/coroutines-flow.md)
│ ├─ Callback to Flow → callbackFlow (references/coroutines-flow.md)
│ └─ Multiple concurrent ops → supervisorScope (references/coroutines-flow.md)
├─ Spring Boot project?
│ ├─ Kotlin-specific setup → references/kotlin-springboot.md
│ └─ JPA entities → jpa-patterns skill
├─ Building DSL or API?
│ ├─ Type-safe builder → references/dsl-idioms.md
│ ├─ Scope functions → references/dsl-idioms.md
│ └─ Operator overloading → references/dsl-idioms.md
└─ Data modeling?
├─ Fixed variants → sealed class/interface
├─ Plain data holder → data class
├─ Type-safe ID/wrapper → value class (@JvmInline)
└─ Platform-specific → expect/actual (KMP)
Output Template
When implementing Kotlin features, provide:
- Data models (sealed classes, data classes, value classes)
- Implementation (suspend functions, Flow, extension functions)
- Test file with coroutine test support
- Brief explanation of Kotlin-specific patterns used