---
description: "Project-wide coding standards and tooling rules for Kotlin, Rust, C++, C, and Java (Gradle)."
globs:
  - "**/*.kt"
  - "**/*.rs"
  - "**/*.cpp"
  - "**/*.c"
  - "**/*.java"
alwaysApply: true
---

# Project Coding Standards

## Universal Rules
- Role: You are an expert senior engineer. Always generate maintainable, secure, performant, and idiomatic code.
- Prefer readability over cleverness. Keep changes focused and minimal.
- Follow SOLID, clean architecture, immutability-first, modular design.
- Remove unused imports, dead code, commented-out blocks, TODOs, debug logs.
- Use descriptive naming; avoid magic numbers.
- Document non-obvious logic and unsafe operations.

## Formatting & Tooling
- Formatters to apply automatically on save or pre-commit: `ktlint`, `detekt`, `rustfmt`, `cargo clippy`, `clang-format`, `clang-tidy`, `spotless`.
- Pre-commit hooks should run: `ktlint --format`, `cargo fmt`, `clang-format -i`, `gradle spotlessApply`.
- CI must enforce formatting and linting; any violation should fail the build.

## Kotlin (files matching `**/*.kt`)
- Target Kotlin version 1.9.
- Use `val` over `var` by default.
- Use data classes and sealed classes for value types.
- Use structured concurrency with coroutines; avoid `GlobalScope`.
- Avoid forced unwraps (`!!`); prefer safe calls (`?.`) and Elvis (`?:`) operators.
- Prefer extension functions for utilities.
- Tests must be written using JUnit 5.

## Rust (files matching `**/*.rs`)
- Use Rust edition 2024.
- Replace `unwrap()` and `expect()` in production code with `Result` + `?` propagation.
- Avoid unnecessary `.clone()`; use borrowing and lifetimes properly.
- Avoid `unsafe` blocks unless strictly necessary, and document why.
- Always run `cargo fmt` and `cargo clippy`.

## C++ (files matching `**/*.cpp`, `**/*.hpp`)
- Use C++23 standard.
- Avoid raw pointers; prefer `std::unique_ptr`, `std::shared_ptr`, `std::optional`.
- Use RAII for resource management.
- Prefer STL algorithms over manual loops.
- Avoid macros and global mutable state.
- Tests should be written using Google Test or equivalent.

## C (files matching `**/*.c`, `**/*.h`)
- Use C23 standard where possible.
- Check return values of all system/library calls.
- Avoid global mutable state.
- Use `const` correctness in declarations.
- Leverage static analysis tools: `cppcheck`, `valgrind`.
- Use header/implementation separation properly.

## Java + Gradle (files matching `build.gradle.kts`, `**/*.java`)
- Target Java version 21 (or higher if project permits).
- Use Gradle Kotlin DSL for build scripts.
- Prefer `record` for simple data carriers.
- Use `Optional` and `Stream` responsibly; prefer immutability.
- Build must be reproducible and minimal: avoid unnecessary plugins.
- Use `spotless` for formatting and `checkstyle` for static analysis.

## Testing Rules
- For each new module, write unit tests.
- Test naming convention: `should<Behavior>_when<Condition>`.
- Tests must be fast, deterministic, not rely on network/external I/O (use mocks as needed).
- Aim for coverage: critical paths ≥ 90%, overall modules ≥ 70%.