Comprehension debt
La brecha entre cuánto código existe en un sistema y cuánto cualquier humano realmente entiende. Término acuñado por Addy Osmani en un essay homónimo publicado a inicios de 2026, popularizado por developers que se reconocieron en él tras un año usando IA agentic (2026-05-19-comprehension-debt-ai-dev-trap).
“Making code cheap to generate doesn’t make understanding cheap to skip.” — Addy Osmani
El costo de producir código colapsó con los agentes IA. El costo de entenderlo no se ha movido nada. Nadie mide el segundo número, y ahí vive el problema.
Diferencia operativa con deuda-tecnica
| Eje | Deuda técnica | Comprehension debt |
|---|---|---|
| Cómo se detecta | Se anuncia sola: tests lentos, módulos frágiles, archivo que nadie quiere tocar | Invisible — todo va bien hasta que algo explota |
| Efecto sobre velocidad | Frena al equipo | Acelera al equipo (mientras dura) |
| Trade-off | Velocidad ahora, costo mañana en mantenimiento | Velocidad ahora, costo mañana en debugging/decisión |
| Mitigación | 4 hábitos (acotar, documentar, ticket, test) | Inquiry mode + grip arquitectónico personal |
Son conceptos hermanos pero NO equivalentes: una codebase puede tener bajo nivel de deuda técnica (clean, testeada, pasa CI) y a la vez alto nivel de comprehension debt (nadie del equipo puede explicar por qué tomó N decisión específica). El velocity chart se ve excelente justo hasta que algo explota y nadie en la sala puede leer el stack trace.
Síntomas observables
- El reflex “Let me ask Claude” contestando preguntas sobre el propio código del autor del PR. La broma sarcástica delata el slippage real.
- Aprobar PRs corriéndolos en vez de leyendo el diff. Sustituir lectura por test manual.
- Confesión de la entrevista: no poder pasar una coding interview sin autocompletion ni agente, aun siendo senior con años de experiencia.
- Migración de atención: el tiempo se va al workflow alrededor del código (comparar modelos, probar metodologías, tunear setup) en vez de al código mismo.
- “Nada ha pasado todavía” como argumento de seguridad. “No prueba que el suelo está sólido. Prueba que no has encontrado el spot suave.” Definición operativa de false confidence.
Evidencia cuantitativa — RCT Anthropic (enero 2026)
Estudio “How AI assistance impacts the formation of coding skills”:
- 52 software engineers aprenden la librería Python
Trio. Grupo A: con IA. Grupo B: sin IA. - Grupo A: quiz comprensión 50%. Grupo B: 67%. Diferencia de 17pp.
- Tiempo ahorrado por usar IA: ~2 min, no significativo estadísticamente.
- Debugging es la skill que cae el cliff más empinado entre todas las categorías medidas.
Trade resumido: un tercio menos del material retenido a cambio de dos minutos que ni siquiera se pueden probar.
La distinción que cambia todo — inquiry vs delegation
El mismo estudio identifica un sub-grupo que NO sufrió la caída:
| Modo de uso | Score de retención |
|---|---|
| Inquiry — preguntar follow-ups, pedir explicaciones, hacer preguntas de concepto mientras trabajas | ≥65% |
| Delegation — tomar output, ship, move on | <40% |
Misma herramienta, outcomes opuestos. La diferencia no es la IA, es qué le pides.
Cómo entrar en modo inquiry — operativa documentada
Del experimento accidental del autor de 2026-05-19-comprehension-debt-ai-dev-trap al entrar a un codebase Python desconocido sin haber programado en Python profesionalmente:
- Pre-task — pedir al modelo que enseñe el contexto: “walk me through the codebase”, “compara X y Y, generators, async/await semantics”, “dame el 20% que cubre el 80%“.
- Mid-task — pedir explicación inline: “implementa esto, pero explica qué estás haciendo y por qué a medida que avanzas”.
- Test del lunes — proxy operativo: ¿puedo contestar preguntas sobre el código sin abrir la chat window? “Al menos la mitad del tiempo. La otra mitad me daré pase porque no voy a fingir.”
Qué hold el humano vs qué hold el modelo
Regla destilada:
No es necesario recordar cada función — nadie hace eso, nadie nunca lo hizo. Lo que hay que hold es la arquitectura, los protocolos, y el por qué del sistema. La forma de la cosa. Los lugares donde es frágil. Las razones por las que se tomaron decisiones específicas. Esa es la parte que el modelo no puede hold por ti — porque esa es la parte por la que te están pagando para hold.
“El modelo no se levanta en la noche. Yo sí.”
Relación con otros conceptos
- deuda-tecnica — par contrastivo (ver tabla arriba). Misma familia “deuda en software”, efectos opuestos sobre observabilidad y velocidad.
- vibe-coding — cierra una tensión del concept: el techo del vibe coding NO se mide en MRR sino en cuánto puedes contestar sobre tu sistema sin chat window. Riesgo real, no anecdótico.
- seniority-developer — interpela el eje “skill técnico” del seniority: si la sintaxis se delega y el criterio también, ¿qué queda de senior?
- burnout — paralelismo conceptual: ambos son tipos de drift invisible que se siente como win hasta que colapsa. False confidence en ambos casos.
Cuándo aplica este frame
- Senior eng en compañía con incidentes 2 a.m. — alta urgencia, regla “test del lunes” no negociable.
- Fundador solo a $0-30k MRR vibe coding (ss-vibe-coding-practica) — bajo riesgo mientras nadie llame a las 2 a.m., pero el primer incident sin Claude disponible mide la deuda acumulada.
- Equipo enterprise con muchos PRs por día y “spawn six parallel agents” — caso de mayor exposición. La regla “quizás slow down un poco, quizás la calidad sube, quizás el incidents channel se vuelve más callado, menos heroic, más boring” aplica aquí.
Mitigaciones declaradas
- Slow down — incluso si el modelo puede ir más rápido, el cerebro del humano necesita tiempo para hold el sistema.
- Pregúntale al modelo en vez de darle órdenes — inquiry default, delegation cuando hay urgencia justificada.
- Hold la arquitectura en tu propia cabeza — no cada línea, sí la forma, los protocolos y el por qué.
- Setup portable como hedge — skills, prompts y workflows propios para no depender de un proveedor (cierra parcialmente la dependencia documentada en la source: Anthropic apretó límites + Opus más lento = compañía entera afectada en 1h).
Antecedente pre-IA — copy-paste sin entender (Gunter, oct 2024)
omnivore-habitos-foco-dev-agregada documenta el mismo frame aplicado a frameworks/tools en 2024:
“Frequently copying and pasting code without fully understanding it can lead to bugs, security issues, and redundant code.” — Gunter
“Using frameworks and tools can make coding faster and easier, but relying on them too much can stop you from learning how things work underneath.” — Gunter
= la deuda de comprensión pre-existió a los LLMs. Frameworks pesados, copy-paste de Stack Overflow, dependencia ciega de tooling — todos producen el mismo efecto que Osmani describe con IA, en menor escala. Esto sugiere que el frame de Osmani es continuación de un patrón, no anomalía nueva.
Refuerzo institucional — Medium Newsletter (oct 2024)
omnivore-tech-debt-agregada aporta la versión institucional del inquiry mode:
“The team before you had different constraints but knew what they were doing. If you don’t understand a choice, ask about the context of the decision.”
= ante código heredado, inquiry mode = preguntar por qué antes de juzgar. Misma operativa, dominio distinto.
Segunda voz independiente — Substack Weekly Stack (mayo 2026)
inbox-2026-05-ai-coding-claude-agregada documenta una entrada explícita “Comprehension Debt: The Hidden Cost of AI-Generated Code” (Substack Weekly Stack, 2026-05-06) que adopta el término con frame ligeramente distinto:
“Comprehension debt = código que pasa tests pero ningún humano puede modificar con confianza.”
Propuesta operativa nueva: comprehension budget por módulo — límite de LOC que nadie ha revisado profundamente. Code reviews en la era AI deben incluir “¿entiendes esto suficientemente para mantenerlo?” como criterio explícito.
Cierre parcial de la pregunta abierta #3: hay segunda voz adoptando el término. El concept ya no es hallazgo aislado de 1 RCT — es vocabulario emergente de industria en 2026. La RCT Anthropic enero 2026 también es citada independientemente en Is AI Making You a Worse Developer? (Strategize Your Career, 2026-04-29) — voz #3.
Métrica nueva pendiente de verificar: Carnegie Mellon reporta “código generado por IA es 41% más complejo” (citado en Strategize 2026-04-29, fuente primaria sin verificar).
Tercera voz convergente — code review como nuevo DORA metric (2026-05-14)
“Code Review is the New Bottleneck For Engineering Teams” (Engineering Leadership, vía inbox-2026-05-engineering-career-leadership-agregada) aporta el frame operativo:
- Code review = el nuevo DORA metric con AI coding.
- Smaller PRs es el lever de mayor impacto — todo lo demás es marginal.
- La habilidad del reviewer se desplaza: más system design, menos sintaxis.
Convergente con comprehension-debt vía mecanismo observable: si el reviewer no puede sostener el sistema mentalmente, los PRs grandes se aprueban corriéndolos (no leyéndolos) → debt acumulada.
Fuentes
- 2026-05-19-comprehension-debt-ai-dev-trap — destilación del essay original de Addy Osmani + RCT Anthropic + experimento accidental del autor.
- inbox-2026-05-ai-coding-claude-agregada ⭐ — segunda voz independiente (Substack Weekly Stack 2026-05-06) + tercera voz (Strategize 2026-04-29) + cuarta voz operativa (Engineering Leadership 2026-05-14).
- inbox-2026-05-engineering-career-leadership-agregada — frame “smaller PRs” + harness training (Pointer #712).
- omnivore-habitos-foco-dev-agregada — antecedente pre-IA del frame (Gunter, oct 2024).
- omnivore-tech-debt-agregada — versión institucional del inquiry mode aplicado a código heredado.
- ai-engineer-coding-modelos-agregada ⭐ — cuarta voz convergente: el frame “vibe coding hangover” / código basura (slop) es el síntoma observable del mismo problema; Ralph Loops, RPI y TDD con agentes como antídotos arquitectónicos que fuerzan inquiry mode estructurado. Matt Pocock + Dex Horthy convergen con Osmani: “Software Fundamentals Matter More Than Ever” + “No Vibes Allowed: Solving Hard Problems in Complex Codebases”.
Preguntas abiertas
- ¿Existe métrica observable de comprehension debt a nivel de equipo? El frame “comprehension budget por módulo” (Substack Weekly Stack 2026-05-06) es la primera propuesta operativa pero ningún caso real lo aplica todavía.
- ¿Cómo cambia el frame cuando el agente abre el PR y revisa el PR (no solo escribe)? Pointer #712 sugiere que el senior debe pasar de “revisar diffs” a “entrenar el harness” — primera propuesta operativa, pero falta validación en equipos reales.
¿Hay segunda fuente independiente que confirme la curva inquiry vs delegation con números distintos?→ Resuelta parcialmente (Substack Weekly Stack + Strategize Your Career adoptan el término; Carnegie Mellon aporta métrica nueva 41% más complejo, fuente primaria pendiente).- ¿La asimetría senior↑/junior↓ por IA (frame Strategize 2026-04-29) es reversible? Implicaciones para hiring pipelines.