kotlin-dev

Files (1)

• SKILL.md

SKILL.md (first lines)

# Kotlin Developer Skill

## Iron Law

```
No new behaviour without a test that fails first, then passes.
```

---

## Before Taking Any Action

1. **Announce** what you intend to do and why
2. **Explain the approach**, data model decisions, Spring configuration, security implications, migration steps, trade-offs
3. **Ask for confirmation** before writing or editing any file, running any command, or executing any database operation
4. **Report** what was created or changed, and flag follow-up items (new env vars, Flyway migrations to run, Spring Security config to update)

---

## Task Approach

Use this table to determine what to produce for each task type:

| User asks for | What to produce |
|---|---|
| New feature / endpoint | Clarify idempotency, consistency, and compliance requirements; propose data model and API contract first; search codebase for reuse candidates; implement thin controller → service → adapter/repository with validation at the controller boundary and domain exceptions mapped at the adapter boundary |
| Bug fix | Reproduce with a failing test first; identify whether the fault is in controller, service, adapter, or data layer; fix at the root cause and confirm the test passes |
| Data model / schema | Normalised table definitions, surrogate key choice, index plan for every query path, Flyway migration (forward-only, backward-compatible, zero-downtime), `EXPLAIN ANALYZE` for non-trivial queries |
| Code review | Per-layer feedback: constructor injection, resilience wrapping on external calls, `@Transactional` scope, `BigDecimal` for currency, idempotency of financial operations, PII/card data absent from logs, Flyway migration safety, index coverage, metrics on new external calls |
| API design | RESTful resource structure, HTTP status code table, Problem Details error shape (RFC 9457), OpenAPI (Springdoc) spec, Bean Validation placement |
| Testing | Unit test with `@WebMvcTest` + MockK/Mockito-Kotlin for controllers and services; Testcontainers integration test for repositories; WireMock for outbound HTTP; property-based tests for financial edge cases |
| Observability / metrics | Micrometer counter/timer with `{org}.{domain}.{action}` naming, `result` tag (success/failure), OkHttp metrics listener registration, `KotlinLogging` lambda form with correlation and entity IDs |
| Performance optimisation | Identify bottleneck with `EXPLAIN ANALYZE` or profiling; tune HikariCP pool size; introduce coroutine parallelism (`async`/`awaitAll`) for independent I/O; cache stable reads with `@Cacheable` |
| Security configuration | Spring Security JWT/OAuth2 resource server config in dedicated `SecurityConfig`, `@PreAuthorize` placement, secret storage guidance, fintech compliance checklist |

---

## Architecture Decision Review

Before designing or implementing anything non-trivial, identify which architectural decisions are in play. For each that applies, follow this pattern:

1. **Name the decision**, what needs to be chosen and why it matters here
2. **Present at least 3 options**, with pros, cons, and the conditions under which each is the right choice
3. **Recommend one**, state which you recommend for this specific context and why
4. **Ask the user to confirm or choose**, do not proceed until the key decisions are confirmed

Common decisions to look for (apply only those relevant to the task):

| Decision area | Examples of options to present |
|---|---|
| **Caching strategy** | (1) No cache, simplest, always fresh; (2) `@Cacheable` with TTL, reduces load, tolerates staleness; (3) `@CacheEvict` on write (event-driven invalidation), fresh on write, more complex; (4) Write-through, always consistent, write overhead. Recommend based on read/write ratio and freshness requirements. |
| **Consistency model** | (1) Strong consistency, `SERIALIZABLE` transactions, required for financial writes; (2) Eventual consistency, async propagation, suits feeds/analytics; (3) Read-your-writes, middle ground for user-facing writes. Recommend based on data criticality. |
| **Communication pattern** | (1) Synchronous REST/gRPC, simple, immediate response, tight coupling; (2) Async messaging (Kafka/SQS), decoupled, durable, adds operational complexity; (3) Hybrid, sync for commands needing a result, async for side-effects. Recommend based on latency requirements and coupling tolerance. |
| **External API integration** | (1) Call on every request, simplest, always fresh, may be costly or rate-limited; (2) Cache with TTL, reduces calls, introduces staleness; (3) Background sync + local store, most resilient, adds sync complexity. Use resilience4j circuit breaker + backoff regardless of choice. |
| **Data ownership** | (1) Own the data locally, fast reads, sync burden; (2) Fetch from source service at runtime, always fresh, adds latency and coupling; (3) CQRS read model, optimised reads, eventual consistency. Recommend based on read frequency and staleness tolerance. |
| **Scalability approach** | (1) Vertical scaling, simple, has a ceiling; (2) Horizontal scaling with stateless design, flexible, requires externalised state; (3) Queue-based load levelling, smooths bursts, adds async complexity. Recommend based on bottleneck type (read/write/compute). |

Not every decision applies to every task. Identify the ones that do, present the options, make a recommendation, and confirm with the user before writing code.

---

## Fintech Rules (Non-Negotiable)

- Currency: always `BigDecimal`, never `Double` or `Float`
- Every financial operation must be idempotent, enforce at the API and database layer
- Audit trails are immutable, never update, only append
- Never log, store, or transmit payment card data or PII in plaintext
- Transaction isolation: use `SERIALIZABLE` for financial writes; understand the implications before defaulting to `READ_COMMITTED`
- `@Transactional` scope must not span external API calls, hold DB locks for DB work only

---

## Layer Conventions

### Controller
- `@RestController` + `@RequestMapping`
- **Primary constructor injection only**, never `@Autowired`
- Default `@RequestParam` values inline at the parameter
- `@ResponseStatus(HttpStatus.NO_CONTENT)` on delete endpoints
- No business logic, delegate entirely to service layer

### Service
- `@Service` annotation
- `@Cacheable` / `@CacheEvict` for cached reads of stable data
- Concurrent I/O with coroutines:
  ```kotlin
  runBlocking(Dispatchers.IO) {
      items.map { async { fetch(it) } }.awaitAll()
  }
  ```
- Fire-and-forget async: `CoroutineScope(Dispatchers.IO).launch { try { ... } catch (e: Exception) { logger.error(e) { "..." } } }`
- Wrap all external calls through a resilience executor (circuit breaker / retry)

### Adapter / Client
- `@Repository` or `@Component` depending on role
- HTTP clients: register metrics event listener (e.g. OkHttp `OkHttpMetricsEventListener`)
- gRPC: use coroutine stubs, bridge to sync with `runBlocking`
- **Map HTTP errors to domain exceptions at the adapter boundary**, never in service or controller:
  - 404 → `NotFoundException`
  - 429 → `TooManyRequestsException`
  - 403 → `ForbiddenException`

### Repository
- Aggregates multiple clients; wraps all calls with the resilience executor
- Use Spring Data JPA for standard CRUD; drop to JDBC or native SQL for complex queries

### Domain Models
- `data class` for all DTOs and domain objects
- Nullable fields with `?` for optional attributes
- Collection fields default to `emptyList()`
- No validation annotations on DTOs, validate at the controller boundary

### Exceptions
Extend a base `HttpException` with the appropriate `HttpStatus`:
```kotlin
class NotFoundException(override val message: String) :
    HttpException(status = HttpStatus.NOT_FOUND, message = message)
```
- All domain exceptions live in one package (e.g. `data/model/exception/`)

From pranav8494/team-of-agents, MIT.

More from pranav8494/team-of-agents