Codeando con IA: agentes, skills y buenas prácticas para no morir en el intento

# Ejemplo en modo Ask:
> Explicame como funciona el flujo de autenticacion en este proyecto.
  Cual es la ruta que sigue un request desde que llega hasta que se valida el token?

# La IA va a leer tus archivos, seguir el flujo y darte una explicacion.
# Pero NO va a cambiar ni una linea de codigo.

# Ejemplo en modo Agent:
> Agrega un endpoint GET /api/users/{id} que retorne un usuario por ID.
  Sigue el patron de OrderController. Incluye validacion del ID
  y retorna 404 si no existe.

# La IA va a:
# 1. Leer OrderController.kt para entender el patron
# 2. Leer la entity User.kt
# 3. Crear o editar el UserController.kt
# 4. Registrar la ruta en el controller con @GetMapping
# 5. (Opcionalmente) correr tests para verificar

# Ejemplo en modo Plan:
> Necesito migrar el sistema de autenticacion de sesiones a JWT.
  Planifica como lo harias paso a paso.

# La IA te va a responder algo como:
#
# Plan de migracion: Sesiones -> JWT
#
# Paso 1: Crear el middleware de JWT
#   - Archivo: src/security/JwtAuthFilter.kt
#   - Dependencia: jjwt (ya esta en build.gradle.kts)
#
# Paso 2: Crear el servicio de tokens
#   - Archivo: src/service/TokenService.kt
#   - Funciones: generateToken(), verifyToken(), refreshToken()
#
# Paso 3: Modificar el login
#   - Archivo: src/controller/AuthController.kt
#   - Cambio: retornar JWT en vez de crear sesion
#
# Paso 4: Actualizar los endpoints protegidos
#   - Archivos: todos los controllers que usan @Secured
#   - Cambio: reemplazar filtro de sesion por JwtAuthFilter
#
# Paso 5: Tests
#   - Actualizar tests existentes
#   - Agregar tests para el flujo de JWT
#
# Quieres que proceda con este plan?

# Ejemplo: instrucciones para un agente de exploracion (en CLAUDE.md)

Cuando necesites explorar el codebase para entender la arquitectura:
- Primero lee los archivos de configuracion (build.gradle.kts, application.yml)
- Luego mapea la estructura de carpetas
- Identifica los patrones de diseno usados
- Resume tus hallazgos antes de hacer cambios

# .cursorrules - Agente de migracion de base de datos

Eres un especialista en migraciones de base de datos.

## Tu flujo de trabajo:
1. Lee la migracion anterior mas reciente en src/migrations/
2. Sigue la convencion de naming: YYYYMMDD_HHMMSS_descripcion.sql
3. Siempre incluye un bloque DOWN (rollback)
4. Nunca hagas DROP TABLE sin confirmacion
5. Valida que los tipos de datos son compatibles con PostgreSQL 15

# En Claude Code, puedes pedirle que lance sub-agentes en paralelo:
> Necesito que hagas estas 3 tareas en paralelo:
  1. Agrega tests unitarios para UserService
  2. Agrega tests unitarios para OrderService
  3. Agrega tests unitarios para ProductService
  Cada servicio es independiente. Usa el mismo patron de tests
  que ya tenemos en src/test/kotlin/services/PaymentServiceTest.kt

# En Cursor Composer:
> Necesito actualizar todos los controladores para usar el nuevo middleware de auth.
  Los controladores son independientes entre si:
  - src/controller/UserController.kt
  - src/controller/OrderController.kt
  - src/controller/ProductController.kt
  Aplica el mismo cambio en todos: agregar JwtAuthFilter a la cadena de seguridad para cada ruta.

# Patron "explorador + ejecutor":
> Haz dos cosas en paralelo:
  1. Explora el codebase y hazme un resumen de como funciona
     el sistema de autenticacion actual (archivos involucrados,
     flujo del token, donde se valida)
  2. Mientras tanto, agrega tests para el endpoint GET /api/users
     que ya existe en UserController.kt

# El agente explorador te da contexto mientras el ejecutor avanza
# con trabajo que no depende de esa exploracion.

# Skill: /new-endpoint (ejemplo conceptual)

## Instrucciones
Cuando el usuario pida crear un nuevo endpoint, sigue estos pasos:

### 1. Recopilar informacion
- Pregunta: metodo HTTP, ruta, descripcion de lo que hace

### 2. Crear el DTO de request/response
- Ubicacion: src/dto/{recurso}/
- Naming: {Recurso}Request.kt y {Recurso}Response.kt
- Siempre incluir validaciones con Jakarta Validation (@field:NotBlank, etc.)

### 3. Crear el controller
- Ubicacion: src/controller/{Recurso}Controller.kt
- Seguir el patron de OrderController como referencia
- Incluir decoradores de Swagger/OpenAPI

### 4. Crear el servicio
- Ubicacion: src/service/{Recurso}Service.kt
- Inyeccion por constructor, nunca usar @Autowired

### 5. Crear tests
- Ubicacion: src/test/kotlin/controller/{Recurso}ControllerTest.kt
- Minimo 3 casos: happy path, validacion fallida, recurso no encontrado

### 6. Verificar
- Ejecutar los tests con ./gradlew test
- Verificar que compila sin errores con ./gradlew compileKotlin

# Cursor Notepad: "Nuevo Componente React"

Cuando crees un nuevo componente React en este proyecto:

1. Usa TypeScript con interfaces (no types) para las props
2. Ubicalo en src/components/{NombreComponente}/
3. Crea estos archivos:
   - index.tsx (el componente)
   - {NombreComponente}.test.tsx (tests con Testing Library)
   - {NombreComponente}.stories.tsx (Storybook)
4. Usa Tailwind para estilos, nunca CSS modules
5. Exporta el componente como named export, no default
6. Si tiene estado complejo, usa useReducer, no multiples useState

# CLAUDE.md (Claude Code) / .cursorrules (Cursor) / .github/copilot-instructions.md (Copilot)

## Stack del proyecto
- Backend: Spring Boot 3.2 con Kotlin
- Base de datos: PostgreSQL 15
- ORM: Exposed (no JPA)
- Testing: Kotest + Testcontainers

## Convenciones
- Nombres de endpoints en kebab-case
- Siempre validar DTOs en el controller con @Valid
- Los servicios nunca deben retornar entidades, solo DTOs
- Logs estructurados con logback en formato JSON

## Arquitectura
- Patron: Hexagonal simplificada
- Capas: controller -> service -> repository
- Sin usar @Autowired, solo inyeccion por constructor

# Paso 1: Crea la entity
"Crea la entity User en src/entity/User.kt con campos: id, email, name, createdAt"

# Verificas que la entity se ve bien...

# Paso 2: Crea el repositorio
"Crea el repositorio UserRepository en src/repository/ usando la entity User que acabamos de crear"

# Verificas...

# Paso 3: Crea el servicio
"Crea el servicio UserService con metodos create, findById y findByEmail.
Usa UserRepository por inyeccion de constructor"

# Y asi sucesivamente...

# La IA propone crear un archivo nuevo...
"No, no crees un archivo nuevo. Agrega esa logica al servicio existente en src/service/OrderService.kt"

# La IA usa una libreria que no quieres...
"No uses java.util.Date, usamos kotlinx-datetime en este proyecto. Revisa el build.gradle.kts"

# La IA sobredisena la solucion...
"Eso es demasiado complejo. Solo necesito un when expression, no un patron Strategy"

# Despues de crear tu servicio:
"Genera tests unitarios para UserService.
Usa Kotest con el estilo BehaviorSpec.
Mockea el repositorio con MockK.
Cubre los casos: crear usuario exitosamente, email duplicado, usuario no encontrado."

# Y para tests de integracion:
"Genera tests de integracion para el endpoint POST /api/users usando
@SpringBootTest con WebTestClient y Testcontainers.
Testea: creacion exitosa (201), email invalido (400), email duplicado (409)"

> Necesito un endpoint GET /api/products/search que reciba un query param "q"
  y busque productos por nombre. Usa el patron que ya tenemos en los otros
  controllers (mira src/controller/OrderController.kt como referencia).
  La busqueda debe ser case-insensitive y retornar maximo 20 resultados.

> Cambia la busqueda para usar un indice full-text en vez de LIKE.
  Ya tenemos configurado tsvector en la tabla products.

> Genera tests de integracion para el endpoint de busqueda.
  Usa el setup que ya tenemos con @Testcontainers y PostgreSQL.
  Cubre: busqueda con resultados, busqueda sin resultados, query vacio retorna 400,
  limite de 20 resultados.

> Corre ./gradlew test --tests "*ProductSearch*"