avgarcia/runcriticon / .claude/skills/backend-feature-dev
backend-feature-dev
VerifiedDesarrollo de una feature (caso de uso) dentro de un módulo backend existente: domain con Either, @ApplicationService con autorización explícita, adaptadores REST/JPA, migración Flyway y pirámide de tests completa, ajustado a ADR-0007/0008/0009/0010 y a los docs de arquitectura. Usar al añadir o modificar casos de uso en un módulo ya creado.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.1 KB |
| referencias/jpa-hibernate.md | markdown | 5.3 KB |
| referencias/jvm-performance.md | markdown | 5.7 KB |
| referencias/kotlin-arrow.md | markdown | 6.5 KB |
| referencias/patrones-disenio.md | markdown | 5.5 KB |
| referencias/spring-boot.md | markdown | 5.1 KB |
referencias/kotlin-arrow.md
View on GitHub# Kotlin y Arrow.kt — idioms del proyecto
Fuente: ADR-0008 D11, `estructura-de-un-modulo.md` §3. El stack es **Spring MVC bloqueante + JPA**: las corrutinas no son el modelo por defecto (ver última sección).
## Either y la Raise DSL
Todo error de negocio fluye como `Either<{Modulo}Error, T>`:
```kotlin
import arrow.core.Either
import arrow.core.raise.either
import arrow.core.raise.ensure
fun publicar(): Either<PlanificacionError, PlanPublicado> = either {
ensure(estado == EstadoPlan.BORRADOR) { PlanificacionError.PlanYaPublicado(id) }
ensure(sesiones.isNotEmpty()) { PlanificacionError.SinSesiones }
estado = EstadoPlan.PUBLICADO
PlanPublicado.from(id, clubId, sesiones.toList())
}
```
Herramientas del builder `either { }`:
- `ensure(condicion) { error }` — valida o corta con Left.
- `ensureNotNull(valor) { error }` — smart-cast a no-nulo o Left.
- `raise(error)` — corta incondicionalmente.
- `otroEither.bind()` — desempaqueta o propaga el Left. Es la composición monádica: una cadena de `bind()` reemplaza el railway de `flatMap`.
```kotlin
fun ejecutar(actor: Principal, planId: PlanId): Either<PlanificacionError, PlanPublicado> = either {
ensure(AuthorizationMatrix.can(actor.role, Resource.PLAN, Action.PUBLISH)) { PlanificacionError.Forbidden }
val plan = repositorio.buscar(ClubId.of(actor.clubId), planId)
?: raise(PlanificacionError.NotFound("PlanSemanal", planId.value.toString()))
plan.publicar().bind()
}
// (En el caso de uso real cada guarda publica además AccesoDenegado — ADR-0009 D7, D15.)
```
## La regla `require`/`check` vs `Either`
| Situación | Mecanismo | Ejemplo |
|-----------|-----------|---------|
| Validación **esperable** de negocio | `Either` | Plan ya publicado, sin sesiones, alumno fuera del snapshot |
| Precondición **imposible** (bug del caller) | `require` / `check` | `sesionId` que no pertenece al plan, ID nulo donde no puede serlo |
`require` lanza `IllegalArgumentException` y eso es correcto: un bug no es un flujo de negocio. Se testea con `shouldThrow<IllegalArgumentException>`.
## Jerarquía de errores: sealed class por módulo
**No hay `DomainError` compartido.** Cada módulo define la suya con variantes comunes de shape estandarizado + variantes propias:
```kotlin
sealed class PlanificacionError {
// shape estandarizado entre módulos
data class Forbidden(val razon: String) : PlanificacionError()
data class NotFound(val recurso: String, val id: String) : PlanificacionError()
data class InvalidInput(val campo: String, val motivo: String) : PlanificacionError()
data object Conflict : PlanificacionError()
data class ProjectionStale(val modulo: String, val lagSeconds: Long) : PlanificacionError()
// específicas del módulo
data class PlanYaPublicado(val planId: PlanId) : PlanificacionError()
data object SinSesiones : PlanificacionError()
}
```
Esta sealed class **es** la "exception hierarchy" del módulo: exhaustiva en `when`, sin herencia abierta, sin stack traces innecesarios.
## Política de excepciones
- Excepciones solo **técnicas** y solo en **infrastructure**. Se capturan en el adaptador y se traducen:
```kotlin
override fun enviarInvitacion(destinatario: Email, magicLink: String): Either<EmailError, Unit> = either {
runCatching { postmarkClient.send(destinatario, "Invitación", html) }
.onFailure { raise(EmailError.EnvioFallido(it.message ?: "desconocido")) }
}
```
- El `@RestControllerAdvice` captura excepciones de framework → 500 neutro.
- Nunca `try/catch` de "excepciones de dominio": no existen.
## Typed IDs: value class + UUID v7
```kotlin
@JvmInline
value class PlanId(val value: UUID) {
companion object {
fun nuevo(): PlanId = PlanId(UuidCreator.getTimeOrderedEpoch())
}
}
```
- Cero coste en runtime (inline), imposible pasar el ID equivocado.
- UUID v7 **generado en aplicación** (ordenable temporalmente → mejor locality de índice).
- MockK los maneja sin fricción; en mappers Konvert requieren custom converter.
## Smart constructors
Cuando la construcción puede fallar de forma esperable, constructor privado + factory que devuelve Either:
```kotlin
class Email private constructor(val valor: String) {
companion object {
fun crear(valor: String): Either<IdentidadError, Email> = either {
ensure(REGEX.matches(valor)) { IdentidadError.InvalidInput("email", "formato inválido") }
Email(valor)
}
}
}
```
Si la invariante es universal e incondicional (no depende de input del usuario), basta `init { require(...) }`.
## Modelado con sealed + data
- **Estados**: sealed class con variantes que portan solo los datos válidos en ese estado (hace irrepresentable lo inválido).
- **Value objects**: `data class` inmutables, o sealed cuando tienen formas alternativas (`Ritmo.Absoluto | Ritmo.Relativo`).
- `when` sobre sealed **sin rama `else`**: el compilador avisa al añadir una variante.
- Colecciones: exponer `List`, no `MutableList`; copiar en defensa (`sesiones.toList()`).
## Null safety como diseño
- `?` en el tipo significa "la ausencia es un caso de negocio" — trátalo, no lo silencies.
- `?:` con `raise(...)` es el patrón estándar para "no encontrado".
- `!!` prohibido salvo justificación en comentario. En la práctica: nunca en domain/application.
## Scope functions con criterio
| Función | Cuándo |
|---------|--------|
| `let` | Transformar un nullable: `evento.traceparent?.let { restore(it) }` |
| `apply` | Configurar un objeto que se devuelve (builders, entidades JPA en tests) |
| `also` | Side-effect sin romper la cadena (logging puntual) |
| `run`/`with` | Agrupación de operaciones sobre un receptor |
Antipatrón: anidar más de dos scope functions — extrae una función con nombre.
## inline / reified
Útiles en helpers de test y en extensiones genéricas (`shouldBeLeft<PlanificacionError.Forbidden>()` funciona gracias a reified). En código de producción del dominio, raramente necesarios — no optimices por reflejo.
## Corrutinas: uso acotado
El stack es **MVC bloqueante**: los casos de uso son funciones síncronas y JPA bloquea el hilo. No introducir `suspend` en puertos ni casos de uso.
Uso legítimo y acotado:
- Jobs programados o trabajos paralelos puntuales (fan-out de emails): `runBlocking` + `coroutineScope` con structured concurrency, en infrastructure.
- Nunca `GlobalScope`. Nunca corrutina que toque la transacción JPA del request.
Si algún día el proyecto migra a WebFlux/corrutinas end-to-end, eso es un ADR nuevo — no una decisión de feature.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |