Codeando con IA: agentes, skills y buenas practicas para no morir en el intento

1# Ejemplo en modo Ask:
2> Explicame como funciona el flujo de autenticacion en este proyecto.
3  Cual es la ruta que sigue un request desde que llega hasta que se valida el token?
4
5# La IA va a leer tus archivos, seguir el flujo y darte una explicacion.
6# Pero NO va a cambiar ni una linea de codigo.

1# Ejemplo en modo Agent:
2> Agrega un endpoint GET /api/users/{id} que retorne un usuario por ID.
3  Sigue el patron de OrderController. Incluye validacion del ID
4  y retorna 404 si no existe.
5
6# La IA va a:
7# 1. Leer OrderController.kt para entender el patron
8# 2. Leer la entity User.kt
9# 3. Crear o editar el UserController.kt
10# 4. Registrar la ruta en el controller con @GetMapping
11# 5. (Opcionalmente) correr tests para verificar

1# Ejemplo en modo Plan:
2> Necesito migrar el sistema de autenticacion de sesiones a JWT.
3  Planifica como lo harias paso a paso.
4
5# La IA te va a responder algo como:
6#
7# Plan de migracion: Sesiones -> JWT
8#
9# Paso 1: Crear el middleware de JWT
10#   - Archivo: src/security/JwtAuthFilter.kt
11#   - Dependencia: jjwt (ya esta en build.gradle.kts)
12#
13# Paso 2: Crear el servicio de tokens
14#   - Archivo: src/service/TokenService.kt
15#   - Funciones: generateToken(), verifyToken(), refreshToken()
16#
17# Paso 3: Modificar el login
18#   - Archivo: src/controller/AuthController.kt
19#   - Cambio: retornar JWT en vez de crear sesion
20#
21# Paso 4: Actualizar los endpoints protegidos
22#   - Archivos: todos los controllers que usan @Secured
23#   - Cambio: reemplazar filtro de sesion por JwtAuthFilter
24#
25# Paso 5: Tests
26#   - Actualizar tests existentes
27#   - Agregar tests para el flujo de JWT
28#
29# Quieres que proceda con este plan?

1# Ejemplo: instrucciones para un agente de exploracion (en CLAUDE.md)
2
3Cuando necesites explorar el codebase para entender la arquitectura:
4- Primero lee los archivos de configuracion (build.gradle.kts, application.yml)
5- Luego mapea la estructura de carpetas
6- Identifica los patrones de diseno usados
7- Resume tus hallazgos antes de hacer cambios

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

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

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

1# Patron "explorador + ejecutor":
2> Haz dos cosas en paralelo:
3  1. Explora el codebase y hazme un resumen de como funciona
4     el sistema de autenticacion actual (archivos involucrados,
5     flujo del token, donde se valida)
6  2. Mientras tanto, agrega tests para el endpoint GET /api/users
7     que ya existe en UserController.kt
8
9# El agente explorador te da contexto mientras el ejecutor avanza
10# con trabajo que no depende de esa exploracion.

1# Skill: /new-endpoint (ejemplo conceptual)
2
3## Instrucciones
4Cuando el usuario pida crear un nuevo endpoint, sigue estos pasos:
5
6### 1. Recopilar informacion
7- Pregunta: metodo HTTP, ruta, descripcion de lo que hace
8
9### 2. Crear el DTO de request/response
10- Ubicacion: src/dto/{recurso}/
11- Naming: {Recurso}Request.kt y {Recurso}Response.kt
12- Siempre incluir validaciones con Jakarta Validation (@field:NotBlank, etc.)
13
14### 3. Crear el controller
15- Ubicacion: src/controller/{Recurso}Controller.kt
16- Seguir el patron de OrderController como referencia
17- Incluir decoradores de Swagger/OpenAPI
18
19### 4. Crear el servicio
20- Ubicacion: src/service/{Recurso}Service.kt
21- Inyeccion por constructor, nunca usar @Autowired
22
23### 5. Crear tests
24- Ubicacion: src/test/kotlin/controller/{Recurso}ControllerTest.kt
25- Minimo 3 casos: happy path, validacion fallida, recurso no encontrado
26
27### 6. Verificar
28- Ejecutar los tests con ./gradlew test
29- Verificar que compila sin errores con ./gradlew compileKotlin

1# Cursor Notepad: "Nuevo Componente React"
2
3Cuando crees un nuevo componente React en este proyecto:
4
51. Usa TypeScript con interfaces (no types) para las props
62. Ubicalo en src/components/{NombreComponente}/
73. Crea estos archivos:
8   - index.tsx (el componente)
9   - {NombreComponente}.test.tsx (tests con Testing Library)
10   - {NombreComponente}.stories.tsx (Storybook)
114. Usa Tailwind para estilos, nunca CSS modules
125. Exporta el componente como named export, no default
136. Si tiene estado complejo, usa useReducer, no multiples useState

1# CLAUDE.md (Claude Code) / .cursorrules (Cursor) / .github/copilot-instructions.md (Copilot)
2
3## Stack del proyecto
4- Backend: Spring Boot 3.2 con Kotlin
5- Base de datos: PostgreSQL 15
6- ORM: Exposed (no JPA)
7- Testing: Kotest + Testcontainers
8
9## Convenciones
10- Nombres de endpoints en kebab-case
11- Siempre validar DTOs en el controller con @Valid
12- Los servicios nunca deben retornar entidades, solo DTOs
13- Logs estructurados con logback en formato JSON
14
15## Arquitectura
16- Patron: Hexagonal simplificada
17- Capas: controller -> service -> repository
18- Sin usar @Autowired, solo inyeccion por constructor

1# Paso 1: Crea la entity
2"Crea la entity User en src/entity/User.kt con campos: id, email, name, createdAt"
3
4# Verificas que la entity se ve bien...
5
6# Paso 2: Crea el repositorio
7"Crea el repositorio UserRepository en src/repository/ usando la entity User que acabamos de crear"
8
9# Verificas...
10
11# Paso 3: Crea el servicio
12"Crea el servicio UserService con metodos create, findById y findByEmail.
13Usa UserRepository por inyeccion de constructor"
14
15# Y asi sucesivamente...

1# La IA propone crear un archivo nuevo...
2"No, no crees un archivo nuevo. Agrega esa logica al servicio existente en src/service/OrderService.kt"
3
4# La IA usa una libreria que no quieres...
5"No uses java.util.Date, usamos kotlinx-datetime en este proyecto. Revisa el build.gradle.kts"
6
7# La IA sobredisena la solucion...
8"Eso es demasiado complejo. Solo necesito un when expression, no un patron Strategy"

1# Despues de crear tu servicio:
2"Genera tests unitarios para UserService.
3Usa Kotest con el estilo BehaviorSpec.
4Mockea el repositorio con MockK.
5Cubre los casos: crear usuario exitosamente, email duplicado, usuario no encontrado."
6
7# Y para tests de integracion:
8"Genera tests de integracion para el endpoint POST /api/users usando
9@SpringBootTest con WebTestClient y Testcontainers.
10Testea: creacion exitosa (201), email invalido (400), email duplicado (409)"

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

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

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

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