Primer curso de IA para desarrolladores con experiencia

¿Qué es MCP y por qué importa?

MCP (Model Context Protocol) es un estándar abierto que permite conectar herramientas de IA con fuentes de contexto: bases de datos, sistemas de tickets, repositorios privados, logs de aplicaciones, etc. Sin MCP, tendrías que copiar y pegar manualmente todo el contexto. Con MCP, el asistente lo trae automáticamente.

# Instrucciones para Copilot

## Stack
- Java 17 + Spring Boot 3.5
- JPA + Hibernate
- MockMvc para tests

## Convenciones de este proyecto
- Controllers: sufijo Controller, en paquete `com.company.api.controller`
- Services: sufijo Service, en paquete `com.company.business.service`
- Entities: en paquete `com.company.persistence.entity`
- DTOs: sufijo DTO, usados en responses de endpoints

## Patrones esperados
- DTOs siempre en responses, nunca expongas entidades JPA
- Tests unitarios usan @SpringBootTest con MockMvc
- Métodos privados innecesarios; mantener público solo lo que es necesario

## Qué NO cambiar
- No modificar archivos de configuración (application.properties)
- No tocar la estructura del build.gradle
- No cambiar nombres de métodos públicos existentes

## Definición de terminado para cada tarea
- Código compila sin warnings
- Tests pasan (ejecuta `./gradlew test`)
- Cambios aparecen en un diff limpio, sin reformateo accidental

# Contexto del proyecto
- Stack: Java 17 + Spring Boot + JPA
- Capas: Controller -> Service -> Repository
- No exponer entidades JPA fuera del dominio
- Inyección por constructor
- Logs sin datos sensibles

# Cómo pedir cambios
- Sigue los patrones de OrderController y OrderService
- Si falta contexto, pregunta antes de inventar
- Genera tests para errores y casos límite

# Definición de terminado
- Diff revisable
- Tests ejecutados
- Sin helpers no usados
- Sin cambios fuera de alcance

3.X — Sesión Real en IDE: De Ticket a Commit

El objetivo es ver el ciclo completo con un caso único y consistente. Aquí usamos el dominio de pedidos para que el patrón luego conecte con el taller central.

Iteración 1 — El primer prompt (demasiado vago)

El asistente generó algo aparentemente correcto, pero ignoró convenciones del proyecto: devolvía la entidad Order directamente, dejó el umbral hardcodeado y no cubrió los casos de error.

Iteración 2 — Prompt mejorado con contexto

@GetMapping("/pending-review")
public ResponseEntity<List<OrderPendingReviewResponse>> getPendingReview(
        @RequestParam(defaultValue = "7") Integer days) {
    if (days < 0) {
        throw new IllegalArgumentException("Days must be positive");
    }
    return ResponseEntity.ok(orderService.findPendingReview(days));
}

Iteración 3 — Pedir los tests adecuados

VSCode como base: las tres herramientas principales

VSCode es el IDE de referencia para este módulo porque concentra la mayor parte del ecosistema. Las mecánicas son transferibles a JetBrains, Neovim o cualquier editor con extensiones equivalentes. Aquí comparamos las tres opciones que más se usan en equipos Java/Spring.

# Instrucciones para GitHub Copilot

## Stack y arquitectura
- Java 17 + Spring Boot 3.5 + JPA
- Capas: Controller → Service → Repository
- DTOs como records de Java 17

## Convenciones
- Inyección SIEMPRE por constructor
- No exponer entidades JPA en respuestas de API
- Tests con JUnit 5 + Mockito, sin @SpringBootTest salvo integración
- Logs con SLF4J, sin datos personales ni tokens

## Al generar código
- Sigue el patrón de OrderController y OrderService
- Si falta contexto, pregunta antes de inventar
- Genera siempre el test unitario junto al código

# Skill: Code Review de PR

## Objetivo
Revisar el diff de una PR antes de pedir revisión humana.

## Pasos
1. Lee el diff completo con `git diff main`
2. Busca: entidades JPA expuestas, NPE potenciales, SQL concatenado, logs con datos sensibles
3. Verifica que hay tests para casos feliz, borde y error
4. Genera un resumen de riesgos en formato:
   - 🔴 Crítico: [descripción]
   - 🟡 Atención: [descripción]
   - ✅ OK: [descripción]

## Reglas
- No modifiques código sin pedirlo explícitamente
- Si algo no está claro, señálalo como "revisar con el equipo"

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "mvn spotless:apply && mvn test -q"
        }]
      }
    ]
  }
}

Comparativa de las tres herramientas en el IDE

proyecto/
├── .agent-instructions.md      # Instrucciones para el agente
├── SKILL.md                      # Skills reutilizables
├── README.md                     # Documentación general
├── src/
│   ├── main/
│   │   └── java/com/company/
│   │       ├── api/
│   │       │   ├── controller/   # Controllers (REST endpoints)
│   │       │   └── dto/          # DTOs (request/response)
│   │       ├── business/
│   │       │   └── service/      # Services (lógica)
│   │       └── persistence/
│   │           ├── entity/       # Entidades JPA
│   │           └── repository/   # Repositories
│   └── test/
│       └── java/com/company/     # Tests espejo de main
├── build.gradle                  # Build config
└── .gitignore

# Proyecto
- Stack: Java 17 + Spring Boot + JPA
- Dominio principal: Orders
- Capas: Controller -> Service -> Repository

# Reglas
- No exponer entidades JPA en respuestas
- Inyección por constructor
- Nada de logs con datos sensibles
- No cambiar configuración sin pedirlo

# Validación
- Ejecuta tests relevantes
- Resume qué has cambiado
- Señala riesgos y supuestos
- Si falta contexto, no inventes

4.X — Debugging Asistido por IA: Cómo No Perder el Tiempo

La IA puede ser muy útil para debugging, pero solo si le das el contexto correcto. El error más común es pegar un stack trace y esperar magia. La clave es dar contexto de tres capas: qué esperabas, qué ocurrió y dónde crees que está el problema.

Flujo de debugging con agente

4.X — MCP: conectando el agente con contexto útil

MCP (Model Context Protocol) permite conectar el agente con fuentes externas sin pegar manualmente tickets, logs, documentación o metadatos de repositorio en cada prompt.

Conectores que suelen aportar más

Subagentes: delegar subtareas a agentes especializados

Los subagentes son una evolución del agente único: en lugar de un agente que lo hace todo, defines un agente coordinador que delega subtareas a agentes especializados. Cada subagente trabaja en paralelo, con su propio contexto y objetivo. El coordinador integra los resultados.

Cuándo usar subagentes en tu trabajo diario

Skills: flujos de trabajo reutilizables entre sesiones

Un Skill es un fichero de texto que describe un flujo de trabajo completo: qué contexto necesita, qué pasos sigue y cómo valida el resultado. El agente lo lee al principio de la sesión y lo aplica de forma consistente. Sirve para que el equipo comparta criterio, no solo código.

Anatomía de un Skill útil

# Skill: Preparar PR para revisión

## Cuándo usarlo
Antes de pedir review a un compañero. Corre este Skill
y corrige lo que encuentre antes de abrir la PR.

## Contexto necesario
- Acceso al repositorio y al diff completo (git diff main)
- Stack: Java 17 + Spring Boot + JPA

## Pasos
1. Lee el diff con `git diff main --stat` para ver el alcance
2. Para cada fichero modificado, busca:
   a. Entidades JPA expuestas en DTOs o respuestas REST
   b. Validaciones ausentes (nulos, rangos, formatos)
   c. SQL construido por concatenación
   d. Logs con datos sensibles (PII, tokens, passwords)
3. Comprueba cobertura: ¿hay test para caso feliz, borde y error?
4. Genera resumen estructurado:
   🔴 Crítico (bloquea merge): ...
   🟡 Importante (corregir antes de merge): ...
   🔵 Sugerencia (puede ir en ticket): ...
   ✅ Sin issues detectados en: ...

## Criterio de salida
- Resumen entregado
- Ningún item 🔴 sin respuesta
- Riesgos señalados explícitamente aunque no sean bloqueantes

"Antes de proponer cambios, resume cómo funciona hoy este flujo, enumera riesgos y plantea un plan en pasos. No generes código todavía."

"Primero propón los tests o el contrato de esta API. Cuando estén claros, genera la implementación mínima para que pasen."

"Empieza con una versión simple y correcta. En la siguiente iteración añade validaciones, manejo de errores y pruebas. Explica cada cambio."

"Usa estos archivos como referencia de estilo y arquitectura. No inventes capas nuevas. Si falta contexto, dilo antes de generar cambios."

Estoy en [stack backend] con [ORM o framework]. A partir de este contexto, genera:

1. Una entidad [NombreEntidad] con estos campos:
   [listar campos con tipos]

2. Un DTO separado para entrada o salida, según corresponda

3. Validaciones y anotaciones solo si encajan con este proyecto

Restricciones:
- Respeta la arquitectura y convenciones de los archivos adjuntos
- No inventes helpers, utilidades ni capas nuevas
- Si detectas una decisión ambigua, enumérala antes de generar código
- Devuelve imports correctos y nombres consistentes con el repositorio

Genera un servicio de aplicación para [NombreDominio] siguiendo la arquitectura existente del proyecto.

Necesito:
1. Métodos y casos de uso concretos: [listar]
2. Dependencias ya existentes que debe reutilizar
3. Transaccionalidad donde aplique
4. Validación de entrada y errores de negocio coherentes
5. Logging solo donde aporte trazabilidad real

No pongas lógica de negocio en el controller. Si la capa service actual del proyecto sigue otro patrón, ajústalo a ese patrón en lugar de inventar uno nuevo.

Genera tests para [Clase o caso de uso] usando el framework que ya tiene este proyecto.

Quiero que cubras:
1. Caso correcto
2. Entradas inválidas o incompletas
3. Casos límite y nulos
4. Errores esperados del dominio
5. Verificación de efectos laterales relevantes

Reglas:
- No dependas del orden de ejecución
- No uses sleeps ni temporizadores arbitrarios
- Si faltan dependencias o contexto para un test fiable, indícalo antes de inventar mocks irreales

Genera un template Thymeleaf para [caso de uso] siguiendo la estructura visual y de fragments que ya usa el proyecto.

Incluye:
1. Tabla o formulario según el caso
2. Enlaces y acciones con `th:href` o `th:action`
3. Mensajes de validación y estados vacíos
4. Nombres de variables coherentes con el controller
5. Clases CSS existentes antes de proponer estilos nuevos

Si el proyecto mezcla Thymeleaf con Bootstrap u otra librería, reutiliza los componentes reales en lugar de crear HTML genérico.

5.X — Cuando la IA Falla: Señales y Soluciones

Saber cuándo no confiar en el output es tan importante como saber promtear bien. Estas son las señales de alarma que debes reconocer desde el primer día.

5.X — Museo de los Horrores: Código Real Generado por IA

Estos ejemplos vienen de proyectos reales (anonimizados). El objetivo no es reírse, sino entrenar el ojo para detectar estos patrones en tus propias revisiones.

@Test
void testCreateOrder() {
    CreateOrderRequest req = new CreateOrderRequest(
        "Cliente", "Desc", BigDecimal.TEN);
    // El service devuelve lo que el mock dice
    when(repo.save(any())).thenReturn(new Order());
    OrderDTO result = service.createOrder(req);
    assertNotNull(result); // ← esto SIEMPRE pasa
    // No verifica campos, no verifica que se llamó al repo,
    // no prueba validación, no prueba errores
}

@Query(value = "SELECT * FROM users WHERE name = '"
    + "#{ #name }" + "'", nativeQuery = true)
// La IA generó concatenación de strings en una query
// nativa. Vulnerable a SQL injection.

5.X — Cuándo NO Usar la IA

La IA no es la herramienta correcta para todo. Usarla indiscriminadamente genera código que no entiendes, deuda técnica invisible, y dependencia que te hace menos productivo a largo plazo.

Ejercicio 1 — Guiado (20 min): Endpoint con Test

El instructor ejecuta esto en vivo. El equipo sigue en sus propias máquinas.

Paso 1 — Inicializar el contexto (2 min)

Antes de escribir ningún prompt, abre estos archivos en tabs: Order.java, OrderRepository.java, OrderService.java, OrderController.java. Si usas un agente con instrucciones persistentes, prepara el archivo de contexto del proyecto antes de pedir cambios.

Paso 2 — El prompt inicial (5 min)

Paso 3 — Revisar el output (5 min)

Antes de ejecutar nada, revisa el código generado buscando estos puntos concretos:

• ¿Usa @Autowired en campo? → Incorrecto, pide que lo corrija
• ¿El record tiene todos los campos? → Comprueba que coincide con el prompt
• ¿Los tests cubren lista vacía? → Si no, pide que los añada
• ¿Hay algún get(0) sin comprobar si la lista está vacía? → Bug potencial

Paso 4 — Ejecutar y verificar (5 min)

# Ejecutar solo los tests nuevos
mvn test -Dtest=OrderServiceTest -q

# Si pasan, arrancar y probar el endpoint
mvn spring-boot:run &
curl http://localhost:8080/api/orders/summary | jq .

Paso 5 — Optimizar con un segundo prompt (3 min)

Ejercicio 2 — Semi-guiado (30 min): Revisión Manual de Pedidos

Ahora trabajáis en parejas. Tenéis el esqueleto del prompt — completadlo y ejecutadlo.

Vuestro punto de partida

Criterios de revisión para vuestro propio PR

• ¿La restricción "una revisión abierta por pedido" está en BD, en servicio o en ambos?
• ¿Qué pasa si el pedido no existe al crear la revisión? ¿Hay un test para eso?
• ¿Están cubiertos los cambios de estado inválidos?
• ¿El endpoint de listado tiene paginación o devuelve todo?

Ejercicio 3 — Libre (para casa): Code Review de vuestro propio código

Ejercicio 4 — Reto: Refactorización Guiada por IA

El reto concreto

1. Pedir a la IA que implemente GET /api/orders/export?format=csv
2. Revisar si mete la lógica de serialización CSV directamente en el Service (probablemente sí)
3. Dirigirla para que extraiga un OrderCsvExporter separado
4. Pedir tests para: lista vacía, caracteres especiales en campos, encoding UTF-8
5. Verificar que el Content-Type y los headers de descarga son correctos

Proyecto Base para los Ejercicios

# 1. Descomprime el proyecto
unzip curso-ia-spring-base.zip
cd curso-ia-spring-base

# 2. Compila y ejecuta tests
mvn clean test

# 3. Arranca la aplicación
mvn spring-boot:run

# 4. Prueba que funciona
curl http://localhost:8080/api/orders | jq .

# 5. Abre el proyecto en tu IDE y empieza los ejercicios

Integración con tu Flujo Git y PRs

La IA no vive fuera de tu workflow — tiene que encajar en él. Aquí el patrón que funciona mejor en equipos con PRs y code review:

# Opcional: indica en el commit que fue asistido por IA
git commit -m "feat(orders): add summary endpoint [ai-assisted]"

# Así el equipo sabe qué revisar con más atención en el PR

Checklist de Revisión para Código Generado por IA

Úsala en tus primeras semanas hasta que desarrolles el instinto. Después la habrás interiorizado.

Seguridad: Qué No Pegar Nunca en el Chat

Tu Plan de los Primeros 30 Días

El error más común es querer usar todo a la vez desde el día uno. La adopción que funciona en equipos serios es progresiva: primero criterio, luego repetibilidad, después automatización.