Aprendizaje continuo cuando la IA escribe la mitad de tu código

En el artículo anterior nuestro equipo de QuantumAPI convirtió a un reviewer de IA que gritaba ‘¡que viene el lobo!’ en uno que solo marca issues reales. PRs pequeñas con SDD, reviews útiles con GOTCHA. El Primer y el Segundo Principio estaban funcionando.

Tres semanas después, producción se cayó a las 2 de la madrugada. El job de rotación de claves se había roto en silencio. El ingeniero de guardia abrió el código. Estaba limpio. Estaba revisado. Lo había mergeado un compañero. Y era completamente incomprensible. “¿Por qué ML-KEM-768 y no 1024? ¿Por qué esta política de retry? ¿Qué es ‘gradual rollover’?” Nadie lo sabía. El dev original se había ido del equipo dos meses antes.

Esto es el Tercer Principio roto. El código existe, pero el conocimiento no. Tu equipo entrega más rápido con IA, pero nadie está aprendiendo. Eso no es una victoria de productividad. Es deuda técnica vestida de esmoquin.

El Problema

La generación de código con IA es rápida. El aprendizaje humano no.

Cuando tu equipo pasa de escribir el 50% del código a revisar el 50% del código, algo invisible ocurre: el acto de escribir, que es como los ingenieros interiorizan las decisiones, deja de pasar para la mitad del codebase. El código vive en el repo. El conocimiento no vive en ninguna parte.

Síntomas en nuestro equipo de QuantumAPI tras 3 meses de trabajo con IA intensiva:

• “¿Por qué elegimos X?” preguntado en Slack cada dos días
• Postmortems que duran 2 días porque nadie se acuerda de la decisión de diseño
• Juniors mergeando código generado por IA que no saben explicar (como vimos en el incidente del Artículo 1)
• Seniors reescribiendo en silencio el código de la IA desde cero porque “es más fácil que entenderlo”

El Tercer Principio de Gene Kim es el aprendizaje continuo. Postmortems sin culpa. Experimentos seguros. El equipo mejora con el tiempo. Pero si el código se genera más rápido de lo que el equipo puede leerlo, no estás aprendiendo. Estás acumulando.

Esto no es un problema que se arregla con herramientas. Es un problema que se arregla cambiando cómo usamos la herramienta.

La Solución

El cambio es simple: deja de pedirle a la IA que escriba cosas y empieza a pedirle que las enseñe.

Modo generador (lo que hacen la mayoría)	Modo tutor (de lo que va este artículo)
“Implementa esta spec"	"Explica cada bloque mientras implementas esta spec”
Un solo output: una PR completa	Interactivo: bloque → explicación → confirmación del dev → siguiente bloque
El humano lee el diff, quizás	El humano escribe una learning note que la IA revisa
Los postmortems tardan días	Los postmortems tardan horas porque las decisiones están documentadas
Bus factor: 0-1	Bus factor: 3+

Tres técnicas concretas, en orden de esfuerzo:

1. Explain-before-merge — una learning note corta se genera y se adjunta a cada PR que toca código IA. El dev tiene que leerla y marcar una casilla antes de mergear.
2. Postmortems asistidos por IA — cuando algo se rompe, la IA reconstruye las decisiones que tomó al generar el código, y los humanos las comparan con el incidente.
3. Modo tutor — para features nuevas y juniors, usa un prompt GOTCHA afinado para explicar mientras genera, no generar y luego explicar.

Ninguna de las tres ralentiza mucho al equipo. Las tres suben el suelo de lo que cada dev entiende. Vamos a ver al equipo de QuantumAPI aplicarlas.

Ejecutar

Paso 1 — Explain-before-merge

El equipo añade un paso a su pipeline de Azure DevOps, justo después del AI review GOTCHA del Artículo 3. Un segundo prompt produce una learning note para la PR:

prompt = """
Eres un ingeniero senior documentando decisiones para un dev junior.
Basándote en la spec y el diff, responde a estas tres preguntas en
15 líneas en total, en inglés claro:

1. ¿Qué decisiones tomó el código? ¿Por qué?
2. ¿Qué alternativas razonables se rechazaron y por qué?
3. ¿Dónde puede romperse en producción?

Sé concreto. Nombra librerías, flags y números específicos.
"""

El output de la PR de encriptación se guarda en .ai/learning-notes/spec-001-encrypt-pii.md en el repo:

# Learning note — spec-001-encrypt-pii

## ¿Qué decisiones tomó el código?
- Se eligió ML-KEM-768 (FIPS 203) sobre ML-KEM-512 y ML-KEM-1024.
  768 es el balance recomendado por NIST: suficiente seguridad
  post-cuántica (categoría 3) sin el doble de tamaño de ciphertext
  que tiene 1024.
- Se usó el SDK QuantumAPI .NET v2.3 en vez de llamadas REST directas.
  El SDK maneja retries, binding del vault ID y propagación de contexto.
- Value converters de EF Core cableados a nivel de config de entidad,
  no en una clase base. Razón: más fácil auditar qué campos exactos
  se encriptan.

## Alternativas rechazadas
- Encriptar la fila entera (rechazado: rompe los índices en columnas
  que no son PII).
- Solo AES en reposo vía encriptación de disco (rechazado: no es a
  nivel de campo, no cumple el requisito de la auditoría de compliance).
- ML-KEM-1024 (rechazado: el deadline de 8 semanas no justifica el
  tamaño de clave mayor; podemos migrar más tarde vía rotación del vault).

## ¿Dónde puede romperse?
- Si el endpoint de QuantumAPI no está accesible, TODAS las lecturas
  en los 5 campos van a lanzar excepción. No hay fallback. Añadir
  circuit breaker en la Spec D.
- El vault ID se lee de una variable de entorno. Si la variable falta,
  el servicio falla al arrancar — no en silencio.
- Campos encriptados nullable: el value converter maneja null, pero
  SOLO porque el reviewer lo cazó (ver PR #412 comentario 2).

15 líneas. Escritas por la IA. Leídas por el humano. La plantilla de pull request ahora obliga al reviewer a marcar:

• He leído .ai/learning-notes/spec-001-encrypt-pii.md y puedo explicarlo con mis propias palabras

Es un gate humano, no automatizado. El bot no puede marcarlo. Si el reviewer miente, es problema suyo — pero en la práctica, el check crea la fricción justa para que la gente lea la nota.

Paso 2 — Postmortems asistidos por IA (template corto)

Tres semanas después de que el bug de rotación tumbara producción, el equipo hizo un postmortem. La diferencia con la versión del Artículo 1: esta vez existía la learning note.

Usaron un prompt GOTCHA corto para tirar del historial de decisiones al template de postmortem:

# Postmortem: Crash de rotación de claves — 2026-04-12

## Incidente
El par de claves ML-KEM-768 dejó de rotarse al día 8 de un ciclo de 90.
El servicio siguió usando el par de claves obsoleto hasta que se
detectó 3 semanas después.

## Lo que eligió la IA (según la learning note)
- Rotación cada 90 días, trigger manual desde un cron job
- Sin retry en fallo de rotación (no estaba en la spec)
- Sin alerta en fallo de rotación (no estaba en la spec)

## Lo que pasó de verdad
- Scaleway tuvo un corte de red de 2 minutos el día 8
- La petición de rotación dio timeout
- El cron job logueó el error y salió con exit 0 (enmascarando el fallo)

## Causa raíz
No fue el código de la IA. No fue el review humano. La spec decía
"rotar cada 90 días" y paraba ahí. Nunca dijo "alertar en fallo" ni
"reintentar en errores transitorios". La IA hizo exactamente lo que
decía la spec.

## Acciones
- [ ] Actualizar la plantilla de spec para exigir una sección "En fallo"
- [ ] Migrar a la rotación automatizada de Vault Intelligence de
      QuantumAPI con gradual rollover (zero-downtime)
- [ ] Añadir la métrica de Rotation Health (0-100) al dashboard del equipo

El postmortem duró 90 minutos en vez de 2 días. La learning note hizo que el “por qué” fuera recuperable. El hueco no estaba en el código — estaba en la spec. Ese es el tipo de insight que solo aparece cuando el equipo de verdad aprende de su código.

Paso 3 — Modo tutor

Acaba de entrar un junior al equipo. Su primera tarea: integrar la rotación automatizada de claves de Vault Intelligence de QuantumAPI con gradual rollover en el servicio .NET 10. En modo generador, la IA produciría 80 líneas de código funcional y el junior se quedaría mirándolas con cara de póker.

En vez de eso, el junior abre el chat de IA con este prompt GOTCHA:

# GOTCHA Modo Tutor

## G — Goals
Enséñame cómo integrar la rotación automatizada de Vault Intelligence
de QuantumAPI con gradual rollover en nuestro servicio .NET 10.
El objetivo es que YO sea capaz de escribir el código al final, no
que tú me lo escribas.

## O — Orchestration
1. Explica el concepto en 3 frases
2. Escribe UN bloque pequeño de código
3. Para y pregunta: "¿tiene sentido este bloque?"
4. Si digo que sí, sigue. Si no, explica con algo más pequeño.
5. Al final, pídeme que te explique a ti lo que hemos construido.

## T — Tools
Solo chat. Nada de outputs de archivo completo.

## C — Context
.NET 10, EF Core 10, SDK QuantumAPI v2.3. Sé C# básico.
NO sé qué significa "gradual rollover". Soy nuevo en PQC.

## H — Heuristics
- NUNCA escribas una implementación completa en un solo mensaje
- NUNCA te saltes la pausa "¿tiene sentido?"
- Si respondo mal, retrocede y re-explica con un paso más pequeño
- Al final, verifica que puedo explicar el código SIN mirarlo
- Usa analogías de desarrollo web si ayuda (session tokens, JWT, etc.)

## A — Args
Spec: specs/004-key-rotation/spec.md
Mi nivel: 1 año de .NET, 0 experiencia con PQC

La sesión dura 30 minutos. En vez de un volcado de 120 líneas, el junior recibe:

• Explicación: “Gradual rollover significa que dos claves están activas a la vez — la vieja para descifrar datos existentes, la nueva para cifrar todo a partir de ahora. Imagínate rotar el certificado SSL de un servicio en vivo sin tirar las conexiones.”
• Bloque 1: Una interfaz IKeyRotationClient de 5 líneas. “¿Tiene sentido?”
• Bloque 2: Implementación de BeginRotation(). “Intenta adivinar qué hará CompleteRotation().”
• Bloque 3: El junior escribe CompleteRotation() él mismo. La IA lo revisa.
• Recap: “Ahora explícame qué hace gradual rollover y por qué necesitamos dos claves.”

Al final, el junior entiende lo que ha entregado. Puede debugearlo a las 2 de la madrugada. El bus factor pasó de 0 a 1. Multiplica esto por el equipo y vuelves a 3+.

Paso 4 — Resultados tras 3 meses

Métrica	Antes del modo tutor	Después del modo tutor
Bus factor en código escrito por IA	1	3+
Duración del postmortem	2 días	90 minutos
Juniors debugeando código IA sin ayuda	10%	70%
Preguntas “¿qué hace esto?” en Slack	15/semana	3/semana
Learning notes en el repo	0	47
Tiempo añadido por PR	—	+4 minutos (lectura de nota)

Tercer Principio restaurado. El equipo entrega código escrito por IA y lo entiende. El aprendizaje continuo vuelve a ser continuo.

Plantilla

Prompt GOTCHA de modo tutor reutilizable. Guárdalo como .ai/tutor-prompt.md:

# GOTCHA Modo Tutor — <tu equipo>

## G — Goals
Enseñar al developer cómo <tarea>. El objetivo es que SEA ÉL quien
escriba el código al final, no la IA.

## O — Orchestration
1. Explica el concepto en 3 frases.
2. Escribe UN bloque pequeño de código.
3. Para y pregunta: "¿tiene sentido?"
4. Continúa solo tras confirmación.
5. Pide al dev que escriba el último bloque él mismo.
6. Verifica que puede explicarlo de vuelta.

## T — Tools
Solo chat. Nada de outputs de archivo completo.

## C — Context
<Stack, versiones, nivel del dev, restricciones del dominio>

## H — Heuristics
- NUNCA escribas una implementación completa en un solo mensaje
- NUNCA te saltes la pausa "¿tiene sentido?"
- Retrocede y re-explica si el dev responde mal
- Al final, verifica la comprensión SIN mirar el código
- Usa analogías de lo que el dev ya conoce

## A — Args
- Path de la spec: <runtime>
- Nivel del dev: <runtime>
- Tema a enseñar: <runtime>

Regla del pulgar: si una sesión de modo tutor produce código funcional en menos de 10 minutos, probablemente es modo generador disfrazado. El aprendizaje de verdad lleva 20-60 minutos por bloque de conocimiento nuevo. Eso es una feature, no un bug.

El Reto

Abre la última PR con código generado por IA que mergeaste. ¿Puedes explicar cada decisión a un junior? No leer — explicar. Si no, ese código es deuda técnica vestida de esmoquin. Escríbele una learning note esta semana. Mañana.

En el próximo artículo damos un paso atrás y miramos con honestidad a SDD, ATLAS y GOTCHA. ¿Cuándo ayuda cada uno? ¿Cuándo falla cada uno? ¿Alguno es una bala de plata? (Spoiler: no.) Los comparamos sin mentiras.

→ Artículo 5: SDD, ATLAS, GOTCHA: cuándo usar cuál (y cuándo fallan todos) (próximamente)

---

Si esta serie te ayuda, considera patrocinarme en GitHub o invitarme a un café.

Esta es la parte 4 de 6 de la serie “Los Tres Principios en la Era de la IA”. Anterior: AI Code Review que no grita ‘¡que viene el lobo!’.