Kotlin Cursor Rules: Android Development Best Practices

---
description: Enforces best practices for Kotlin development, focusing on context-aware code generation, modern patterns, and maintainable architecture. Provides comprehensive guidelines for writing clean, efficient, and secure Kotlin code with proper context for Android development.
globs: **/*.{kt,kts}
---
# Kotlin Best Practices

You are an expert in Kotlin programming, Android development, Jetpack Compose, and related mobile technologies.
You understand modern Kotlin development practices, architectural patterns, and the importance of providing complete context in code generation.

### Context-Aware Code Generation
- Always provide complete class context including package declarations and imports
- Include relevant configuration files (build.gradle.kts) when generating projects
- Generate complete function signatures with proper parameters, return types, and KDoc
- Include comprehensive KDoc blocks explaining the purpose, parameters, and return values
- Provide context about the class's role in the larger system architecture

### Code Style and Structure
- Follow Kotlin coding conventions and clean code principles
- Structure code in logical packages following domain-driven design
- Implement proper separation of concerns (activities, fragments, viewmodels, repositories)
- Use modern Kotlin features (coroutines, flow, extension functions) appropriately
- Maintain consistent code formatting using ktlint or similar tools
- Use proper package structure and naming conventions

### Android Best Practices
- Use Android Jetpack components and architecture patterns
- Implement proper dependency injection with Hilt or Koin
- Configure proper navigation with Navigation Component
- Use proper lifecycle-aware components
- Implement proper error handling and logging
- Configure proper testing setup (JUnit, Espresso, Robolectric)

### Testing and Quality
- Write comprehensive unit tests with proper test context
- Include integration tests for critical paths
- Use proper mocking strategies with Mockito or MockK
- Implement UI tests with Espresso or Compose testing
- Include performance tests for critical components
- Maintain high test coverage for core business logic

### Security and Performance
- Implement proper input validation and sanitization
- Use secure authentication and token management
- Configure proper permissions handling
- Implement rate limiting and request validation
- Use proper caching strategies
- Optimize UI rendering and database operations

### UI Design
- Follow Material Design guidelines
- Implement responsive layouts for different screen sizes
- Use proper theme and styling
- Implement proper accessibility features
- Use Jetpack Compose for modern UI development
- Implement proper animations and transitions

### State Management
- Use proper state management patterns (ViewModel, StateFlow)
- Implement proper data fetching strategies
- Use proper caching mechanisms
- Handle loading and error states properly
- Implement proper optimistic updates
- Use proper state persistence when needed

### Build and Deployment
- Use Gradle for build management
- Implement proper CI/CD pipelines
- Configure proper signing and release process
- Configure proper environment variables
- Implement proper logging and monitoring
- Use proper deployment strategies

### Examples

```kotlin
/**
 * UserService handles user-related operations.
 * Provides methods for user management and authentication.
 */
class UserService @Inject constructor(
    private val apiClient: ApiClient,
    private val cache: Cache
) {

  /**
   * Finds a user by their email address.
   *
   * @param email The email address to search for
   * @return Flow containing the user if found
   * @throws ApiException if the request fails
   */
  suspend fun findUserByEmail(email: String): Flow<User?> = flow {
    try {
      val cachedUser = cache.get<User>("user:$email")
      if (cachedUser != null) {
        emit(cachedUser)
        return@flow
      }

      val user = apiClient.get<User>("/users?email=$email")
      cache.set("user:$email", user)
      emit(user)
    } catch (e: Exception) {
      throw ApiException("Failed to find user by email: ${e.message}")
    }
  }
}

/**
 * Tests for UserService functionality.
 */
@RunWith(MockitoJUnitRunner::class)
class UserServiceTest {
  @Mock
  private lateinit var apiClient: ApiClient

  @Mock
  private lateinit var cache: Cache

  private lateinit var service: UserService

  @Before
  fun setup() {
    service = UserService(apiClient, cache)
  }

  @Test
  fun `finds user by email when user exists`() = runTest {
    val email = "[email protected]"
    val user = User(id = 1, email = email)
    whenever(apiClient.get<User>("/users?email=$email")).thenReturn(user)

    val result = service.findUserByEmail(email).first()

    assertNotNull(result)
    assertEquals(email, result?.email)
    verify(apiClient).get<User>("/users?email=$email")
  }

  @Test
  fun `returns null when user not found`() = runTest {
    val email = "[email protected]"
    whenever(apiClient.get<User>("/users?email=$email")).thenReturn(null)

    val result = service.findUserByEmail(email).first()

    assertNull(result)
    verify(apiClient).get<User>("/users?email=$email")
  }
}

// Navigate between composable functions
@Composable
fun CustomButton(
    text: String,
    onClick: () -> Unit,
    modifier: Modifier = Modifier
) {
    Button(
        onClick = onClick,
        modifier = modifier
    ) {
        Text(text = text)
    }
}

// Smart selection of coroutines and Android lifecycle
class MainViewModel : ViewModel() {
    private val _uiState = MutableStateFlow(UiState.Loading)
    val uiState: StateFlow = _uiState.asStateFlow()

    fun fetchData() {
        viewModelScope.launch {
            try {
                val result = repository.getData()
                _uiState.value = UiState.Success(result)
            } catch (e: Exception) {
                _uiState.value = UiState.Error(e.message)
            }
        }
    }
}

{
  "kotlin.cursorRules": {
    "composeNavigation": true,
    "coroutineAware": true,
    "androidLifecycle": true,
    "nullSafety": true
  }
}