Kotlin Idioms skill for Claude Code

Done well means: no !! in production paths, domain states are sealed types matched by exhaustive when, every coroutine is launched in a scope with an owner, cancellation propagates, flows are cold until collected by a lifecycle-aware collector, and detekt/ktlint pass.

Ground rules

• Nullability is part of the type. Resolve it at the boundary (?: return, ?: error()), not with !! deep in logic.
• val by default; var only for local accumulation. Expose read-only collection types (List, Map), keep MutableList private.
• Never use GlobalScope. Never launch a coroutine without knowing which scope cancels it.
• Never swallow CancellationException. Catching Exception in a suspend function must rethrow it.
• Prefer expression bodies and when expressions where they read naturally; stop when a chain needs a comment to follow.

Inspect before changing

grep -rnE 'kotlin\("jvm"\)|org.jetbrains.kotlin|kotlinx-coroutines' build.gradle* gradle/libs.versions.toml 2>/dev/null
grep -rn "!!" --include=*.kt src | wc -l
grep -rn "GlobalScope\|runBlocking" --include=*.kt src

runBlocking belongs only in main and tests (and even there runTest is preferred).

Null safety

fun shippingLabel(order: Order): String {
    val address = order.customer?.address ?: return "NO ADDRESS"
    val zip = requireNotNull(address.zip) { "address ${address.id} missing zip" }
    return "${address.line1}, $zip"
}

Situation	Idiom
Default value	name ?: "anonymous"
Early exit	val x = y ?: return / ?: continue
Invariant violated	requireNotNull(x) { msg } (argument) / checkNotNull (state)
Optional transform	user?.email?.lowercase()
Run block if non-null	x?.let { use(it) } (only when it replaces an if cleanly)
Platform type from Java	Annotate Java side or assign to an explicit String? immediately

lateinit only for DI/test setup fields that are always set before use; never for values that may legitimately be absent.

Modeling

sealed interface UiState<out T> {
    data object Loading : UiState<Nothing>
    data class Success<T>(val data: T) : UiState<T>
    data class Error(val message: String, val retryable: Boolean) : UiState<Nothing>
}

fun render(state: UiState<List<Item>>) = when (state) {   // exhaustive, no else
    UiState.Loading -> showSpinner()
    is UiState.Success -> showItems(state.data)
    is UiState.Error -> showError(state.message)
}

@JvmInline value class UserId(val value: String)          // zero-cost type safety

• Data classes for values; avoid var properties in them (breaks hashCode in sets/maps).
• Omit else in when over sealed types and enums so new cases fail to compile.
• data object for stateless cases (readable toString).
• Guard conditions in when (is Error if state.retryable ->) are stable from Kotlin 2.2; check the project’s Kotlin version first.

Scope functions

Function	Receiver as	Returns	Use for
let	it	lambda result	null-check + transform
apply	this	receiver	configuring a new object
also	it	receiver	side effects (logging) in a chain
run	this	lambda result	compute from an object’s members
with	this	lambda result	several calls on one non-null object

Rule: one scope function per expression. Nested let { ... let { } } or it that shadows an outer it must be rewritten with named lambdas or plain if.

Extension functions

• Use for genuinely general helpers on types you do not own (fun String.toSlug()), or to keep a class small by moving optional conveniences out.
• Do not use them to reach into another module’s internals or as a substitute for a member that needs private state.
• Keep them in a file named for the receiver (StringExt.kt) or next to the only caller.

Coroutines: structure

class OrderRepository(private val api: Api, private val io: CoroutineDispatcher = Dispatchers.IO) {
    suspend fun loadDashboard(id: String): Dashboard = coroutineScope {
        val order = async { api.order(id) }        // both run concurrently
        val history = async { api.history(id) }
        Dashboard(order.await(), history.await()) // one failure cancels the other
    }

    suspend fun export(file: File, rows: List<Row>) = withContext(io) {
        file.bufferedWriter().use { w -> rows.forEach { w.appendLine(it.csv()) } }
    }
}

Need	Use
Parallel subtasks, fail together	coroutineScope { async {}; async {} }
Parallel subtasks, failures independent	supervisorScope + handle each result
Switch thread for blocking I/O	withContext(Dispatchers.IO) inside the suspend fun
Fire-and-forget tied to a screen	viewModelScope.launch / lifecycleScope.launch
App-wide background work	Injected CoroutineScope(SupervisorJob() + dispatcher) owned by the app
Limit parallelism	Dispatchers.IO.limitedParallelism(4) or Semaphore(4).withPermit {}
Timeout	withTimeout(5.seconds) { } / withTimeoutOrNull

• Suspend functions must be main-safe: callers should never need to wrap them in withContext.
• Inject dispatchers so tests can replace them.
• Make long CPU loops cancellable with ensureActive() or yield().

Cancellation-safe error handling:

try {
    api.sync()
} catch (e: CancellationException) {
    throw e
} catch (e: IOException) {
    log.warn("sync failed", e)
}

runCatching { } catches CancellationException too; do not use it around suspend calls unless you rethrow cancellation.

Flow

Type	Hot/cold	Use
Flow<T>	cold	Streams from DB/network, recomputed per collector
StateFlow<T>	hot, has value, conflated	UI state; always has a current value
SharedFlow<T>	hot, no value	Events broadcast to many collectors
Channel<T>	hot, single consumer	One-shot events consumed exactly once

class SearchViewModel(repo: Repo) : ViewModel() {
    private val query = MutableStateFlow("")
    val results: StateFlow<UiState<List<Item>>> = query
        .debounce(300)
        .distinctUntilChanged()
        .mapLatest { q -> UiState.Success(repo.search(q)) as UiState<List<Item>> }  // cancels stale searches
        .catch { emit(UiState.Error(it.message ?: "error", retryable = true)) }
        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), UiState.Loading)

    fun onQuery(q: String) { query.value = q }
}

• flowOn(Dispatchers.IO) changes the upstream context; never withContext inside flow { } around emit.
• On Android collect with repeatOnLifecycle(Lifecycle.State.STARTED) or collectAsStateWithLifecycle() in Compose.
• catch only handles upstream errors; place it after the operators it should guard.
• Update StateFlow atomically with _state.update { it.copy(...) }, not read-modify-write.

Testing coroutines and flows

@Test fun `emits success after search`() = runTest {
    val vm = SearchViewModel(FakeRepo(listOf(item)))
    vm.results.test {                                  // Turbine
        assertEquals(UiState.Loading, awaitItem())
        vm.onQuery("shoe")
        advanceTimeBy(301)
        assertEquals(UiState.Success(listOf(item)), awaitItem())
        cancelAndIgnoreRemainingEvents()
    }
}

• runTest skips delay with virtual time; pass StandardTestDispatcher(testScheduler) into classes that take a dispatcher.
• For code using Dispatchers.Main, call Dispatchers.setMain(testDispatcher) in setup and resetMain() in teardown.

Java to Kotlin conversion checklist

- [ ] Run the IDE converter, then remove every !! it introduced
- [ ] Replace getters/setters + equals/hashCode classes with data classes
- [ ] Replace static utils with top-level functions or extensions
- [ ] Replace builders with named/default arguments
- [ ] Replace callbacks/Futures with suspend functions at the boundary
- [ ] Add @JvmStatic / @JvmOverloads only where Java callers remain

Verification

./gradlew ktlintCheck detekt test     # task names depend on applied plugins; check build files
grep -rn "!!" --include=*.kt src/main | wc -l   # should not increase
grep -rn "GlobalScope" --include=*.kt src/main  # should be empty

Tests that involve time use runTest virtual time, not real delay or Thread.sleep.