Nota del autor: a partir de las ideas de Addy Osmani sobre la «rendición cognitiva» y la «deuda de comprensión», este artículo reúne una lista de autoevaluación y plantillas de indicaciones para antes de fusionar un PR. También compara el enfoque de revisión de LobeHub, basado en informes de aceptación, para ayudarte a elegir la intensidad de revisión según el riesgo.
Si usas Claude Code, Cursor o Cline a diario para entregar código, quizá te haya pasado: un agente entrega en minutos un PR de cientos de líneas, con nombres coherentes, una estructura clara y todas las pruebas en verde, así que haces clic en «Aprobar». Unas semanas después, alguien pregunta por qué se escribió así esa lógica y no sabes qué responder. Este artículo se centra en acciones concretas de comprobación, como pedirle a la IA que te examine, para que puedas hacerte responsable de cada cambio que apruebas sin tener que revisar el código línea por línea.
Este artículo no pretende convencerte de que vuelvas a escribir código a mano. El propio Addy Osmani, ingeniero de Claude Code, ha dejado claro que nadie espera que un ingeniero memorice toda la base de código. La cuestión no es si lees cada línea, sino si sabes qué entiendes y qué no.
Qué te llevarás: entenderás la progresión entre «descarga cognitiva», «cesión del juicio» y «rendición cognitiva»; tendrás una lista de preguntas y plantillas de indicaciones listas para copiar antes de fusionar un PR; y aprenderás a elegir la intensidad de revisión según el riesgo del cambio.
No le des el visto bueno al Agent sin pensar: claves de la deuda de comprensión
Según informó QbitAI en un artículo reproducido por 36Kr, Addy Osmani, exingeniero de Google que ahora trabaja en Claude Code, planteó un problema incómodo: cuanto más fiable parece lo que genera la IA, menos cuidado ponemos al revisarlo. Osmani divide este proceso en varias etapas progresivas y plantea dos nuevos tipos de «deuda». Conviene aclarar que los conceptos siguientes proceden de la cobertura de los medios; para conocer la formulación exacta, consulta el texto original de Addy.
| Concepto | Significado | Ejemplo típico |
|---|---|---|
| Descarga cognitiva | Delegas tareas concretas en la IA, pero sigues entendiendo el trabajo y puedes evaluar el resultado | Le pides al Agent que escriba código repetitivo y tienes claro qué está haciendo |
| Cesión del juicio | Las respuestas de la IA se convierten poco a poco en la base predeterminada para seguir trabajando | La segunda vez apenas revisas el resultado y sigues adelante con lo que diga el Agent |
| Rendición cognitiva | Delegas incluso las decisiones que deberías tomar por tu cuenta | «Si lo dice la IA, seguro que tiene sentido»: todas las pruebas pasan y fusionas el código sin más |
| Deuda de comprensión | La complejidad del código y del sistema crece, pero la comprensión de los desarrolladores no sigue el mismo ritmo | Cuando hay que modificar una función, nadie entiende bien la estructura interna |
| Deuda de intención | La IA decide por ti los objetivos, las restricciones y los compromisos que no quedaron claros en los requisitos | No tienes claro qué quieres, pero el Agent entrega un resultado que parece convincente |
Cómo se llega a la rendición cognitiva y a la deuda de comprensión
La rendición cognitiva no ocurre de la noche a la mañana. Al principio solo «descargas» tareas concretas, y eso no tiene nada de malo: es como usar un compilador en lugar de escribir ensamblador a mano. El peligro aparece en la segunda etapa: cuando el Agent ofrece resultados fiables varias veces seguidas, sus conclusiones se convierten casi sin darte cuenta en tus premisas y empiezas a saltarte la verificación. En la tercera etapa, el botón de «aprobar» se convierte en un sello automático y dejas de actuar como ingeniero para limitarte a dar el visto bueno.
Addy puso un ejemplo muy ilustrativo: un Agent entrega de golpe 600 líneas de código, bien estructuradas y con todas las pruebas aprobadas, y el desarrollador las fusiona con confianza. Pero puede que el Agent haya cambiado discretamente el orden de procesamiento de las transacciones o ajustado alguna condición límite. Esos cambios no producen errores en ese momento, pero cuando el sistema falla de verdad, el desarrollador descubre que no puede explicar por qué el código funciona así. Ese es el «interés» de la deuda de comprensión, que siempre vence en el momento menos oportuno.
La deuda de intención aparece antes, en la definición de los requisitos. Los Agents actuales son tan buenos completando lo que falta que, incluso cuando tú no tienes las ideas claras, pueden entregar un trabajo que parece muy razonable. El problema es que la IA ya ha tomado por ti, sin decirlo, las decisiones sobre los objetivos, el alcance y los compromisos que no definiste bien. La deuda de intención y la de comprensión suelen acumularse: no tienes claro qué querías al principio ni qué hizo finalmente el Agent.
6 métodos para saldar la deuda de comprensión
Addy comparte numerosas recomendaciones prácticas en su artículo. Las hemos organizado en 6 métodos, indicando qué tipo de deuda aborda cada uno y en qué momento del flujo de trabajo conviene usarlo.
| Método | Cuándo usarlo | Deuda que aborda principalmente | Acción en una frase |
|---|---|---|---|
| 1. Pide al agente que te examine | Después de un cambio importante y antes de fusionarlo | Deuda de comprensión | Pídele que resuma los cambios y sus motivos, y luego te haga preguntas; fusiona solo si respondes todas correctamente |
| 2. Escribe una lista de requisitos antes de empezar | Antes de escribir la indicación | Deuda de intención | Define para quién es, qué problema resuelve, qué queda fuera y cuáles son los criterios de finalización |
| 3. Pregunta por las decisiones no autorizadas | Al terminar una tarea larga | Deuda de comprensión y de intención | Pregunta qué decisiones tomó sin tu autorización y en qué supuestos se basó |
| 4. Pregunta qué no se probó | Al revisar los resultados de las pruebas | Deuda de comprensión | Revisa primero las pruebas ejecutadas y sus resultados, y después lee el resumen de la IA |
| 5. Conserva el material original | Cuando varios agentes trabajan en paralelo | Deuda de comprensión | Conserva las fuentes originales y las evidencias de verificación de las tareas importantes; si no puedes revisarlas todas, reduce el trabajo en paralelo |
| 6. Practica sin conexión periódicamente | Cada semana y cada mes | Deterioro de habilidades | Programa una vez por semana sin depender de un agente y revisa cada mes qué habilidades has delegado |
Pide a la IA que te examine: la comprobación clave de la deuda de comprensión
Esta es la idea más interesante de todo el método. Cuando un agente termine una modificación importante, no te apresures a aprobarla. Pídele que actúe como examinador: que resuma qué cambió y por qué, y que después formule algunas preguntas sobre los cambios. Establece una regla: solo se fusiona el código si respondes todas correctamente.
Su valor está en convertir esa sensación vaga de «creo que más o menos lo entendí» en un resultado verificable. Las preguntas que no puedas responder señalan precisamente dónde tienes deuda de comprensión.
Pregunta por las decisiones no autorizadas y lo que no se probó
En las tareas de larga duración, el agente puede elegir parámetros predeterminados, ajustar el alcance de la implementación o incluso decidir entre requisitos que entran en conflicto. Estas decisiones no siempre aparecen en el resumen final porque parecen «demasiado naturales». Por eso, en lugar de preguntar simplemente «¿terminaste?», es más útil profundizar: ¿qué decisiones tomaste sin mi autorización explícita? ¿En qué puntos te basaste en tus propios supuestos? ¿Qué queda sin verificar? ¿Qué cambios podrían afectar a otras funciones?
Con las pruebas ocurre lo mismo. Addy recuerda que unas pruebas en verde solo demuestran que se cumplieron las condiciones que cubren. Si los casos límite no se incluyeron, el informe puede verse impecable de todos modos. El orden correcto es revisar primero qué pruebas se ejecutaron realmente y qué resultados arrojaron, y después leer el resumen generado por la IA. Para cambios de alto riesgo, también puedes pedirle a otro agente que busque problemas de forma independiente y desde otra perspectiva.
Guía rápida de autoevaluación antes de fusionar: 5 pasos para no dar por bueno todo lo que hace el agente
Al combinar los métodos anteriores, obtenemos un proceso que puedes seguir antes de fusionar cada PR. No exige revisar cada línea, pero sí dejar constancia de que has pensado en cada paso.
- Escribe tus expectativas antes de empezar: describe con tus propias palabras los requisitos y lo que esperas que ocurra. Si después de dos rondas de ajustes de la indicación sigues sin estar satisfecho, vuelve a revisar los requisitos en lugar de seguir acumulando indicaciones.
- Pide explicaciones sobre las decisiones: al terminar la tarea, pide al agente que enumere las decisiones no autorizadas, las suposiciones y los puntos que no ha verificado.
- Comprueba las pruebas reales: revisa los comandos de prueba que se ejecutaron y sus resultados, y pregunta qué casos límite quedaron sin cubrir.
- Pide al agente que te examine: haz una autoevaluación con preguntas basadas en el diff de los cambios. Si fallas alguna, vuelve al código hasta entenderla.
- Busca algo que se haya pasado por alto: cuando el agente entregue su trabajo, identifica al menos una cosa que podría no haber comprobado.
Ejemplo mínimo de indicación para evaluar tu deuda de comprensión
Esta es la indicación más habitual para pedirle al agente que te examine. Puedes pegarla directamente en una conversación de Claude Code, Cursor o Cline:
在我合并这次改动之前，请先做两件事：
1. 用不超过 10 条要点总结本次改了哪些文件、每处改动的原因。
2. 根据本次 diff 给我出 5 道题，重点覆盖：事务/调用顺序、
边界条件、错误处理、对其他模块的影响。
先只给题目，等我作答后再批改，并指出我答错的地方对应哪段代码。
规则：我没有全部答对之前，不要建议合并。
Ver la plantilla completa de preguntas antes de fusionar
# 阶段 A：开工前（偿还意图债，由我先填写）
需求说明：
- 面向谁：
- 要解决的问题：
- 明确不做的事：
- 完成标准（做到什么程度算完成）：
- 我预期的改动范围和结果：
# 阶段 B：任务结束后（请 Agent 逐条回答）
1. 你做了哪些我没有明确授权的决定？请列出决定内容和理由。
2. 哪些地方依赖了你自己的假设？假设不成立时会发生什么？
3. 还有哪些内容没有验证？
4. 哪些改动可能影响其他功能或模块？
5. 你实际运行了哪些测试命令？请贴出原始输出，而不是总结。
6. 哪些边界情况没有写进测试？
# 阶段 C：出题考核（偿还理解债）
请根据本次 diff 出 5 道题，先只给题目。
我作答后请批改，答错的题请定位到具体代码行。
我未全部答对前，不要建议合并。
# 阶段 D：高风险改动追加（可交给另一个独立会话）
请你作为独立审查者，不参考上一个会话的总结，
只基于原始需求和 diff，找出最可能出问题的 3 个地方。
🎯 Recomendación de uso: completa tú mismo la etapa A antes de empezar, en lugar de pedirle al agente que la escriba por ti. Para la etapa D, conviene abrir una sesión nueva y evitar que el resumen del agente anterior influya en la revisión independiente. Esto también conecta con la advertencia de Addy sobre la pérdida de información al transmitir mensajes entre varios agentes.
Lista rápida de preguntas antes de hacer el merge
| Etapa | Preguntas imprescindibles | Señales de alerta |
|---|---|---|
| Antes de empezar | ¿Puedo explicar con mis propias palabras los requisitos y los criterios de finalización? | No puedo definir qué queda fuera del alcance |
| Tras la entrega | ¿Qué decisiones tomó el agente sin autorización? | Respondo «ninguna», pero el diff claramente va más allá del alcance |
| Pruebas | ¿Qué pruebas se ejecutaron realmente? ¿Qué quedó sin probar? | Solo hay un resumen, sin la salida original |
| Evaluación | ¿Podría responder correctamente a todas las preguntas? | Fallo preguntas sobre el orden de las transacciones o las condiciones límite |
| Cierre | ¿Puedo identificar algo que el agente no haya revisado? | No se me ocurre nada |
Comparación: dejar que la IA te examine frente a revisar informes de aceptación
Un enfoque muy diferente procede de LobeHub, una plataforma de código abierto para la colaboración entre agentes (con unas 84.000 estrellas en GitHub). Según informó White Whale Lab, el equipo afirma que «casi ya no revisa el código» y que se centra en los informes multimodales de aceptación del agente. Para ello utiliza Acceptance, una herramienta desarrollada internamente y publicada como código abierto en septiembre de este año: antes de entregar el trabajo, el agente desglosa los requisitos en puntos de comprobación directamente observables, los ejecuta uno por uno en el producto real y reúne capturas de pantalla, grabaciones y registros en un informe en línea. Una persona puede aprobar el conjunto o devolver puntos concretos por separado.
| Dimensión | Que la IA te examine | Revisión mediante informe de aceptación |
|---|---|---|
| En qué se centra | Lógica interna del código, decisiones no autorizadas y supuestos | Comportamiento externo observable del producto |
| Tipo de evidencia | Preguntas y respuestas, resultados de la evaluación | Capturas de pantalla, grabaciones, registros y comandos ejecutados |
| Problemas que puede detectar | Orden de las transacciones, casos límite y decisiones implícitas | Si la interfaz, las interacciones y las funciones cumplen los requisitos |
| Problemas que puede pasar por alto | Preguntas que no se te ocurrió plantear | Lógica interna invisible y riesgos de arquitectura |
| Requisitos previos | Que el desarrollador esté dispuesto a dedicar tiempo a comprender los cambios | Que los requisitos puedan desglosarse en comprobaciones observables y exista un entorno de ejecución automatizado |
| Papel de la persona | Comprender los cambios concretos y asumir la responsabilidad por ellos | Definir los criterios de aceptación y tomar la decisión final |
Análisis comparativo de los dos enfoques de revisión
Revisión mediante informe de aceptación: este método es muy eficiente para verificar el comportamiento observable, y los comentarios de devolución pueden señalar un punto de comprobación concreto. En la prueba descrita en el reportaje, la persona encargada de la revisión solo devolvió el punto relativo al fondo oscuro; el agente modificó una sola línea de CSS y no cambió los demás archivos. Sin embargo, el método depende de que los requisitos puedan desglosarse en comprobaciones observables. El reportaje también señala que, en tareas más complejas, la seguridad, la arquitectura y la calidad final siguen requiriendo criterio humano, y que algunas etapas del envío de comentarios aún necesitan intervención manual. La afirmación de que el equipo «casi ya no revisa el código» procede del propio equipo y no se ha verificado de forma independiente.
Que la IA te examine: este enfoque es más eficaz para sacar a la luz problemas que «no se ven en la interfaz», como el orden de las transacciones o los casos límite, y cubre así los puntos ciegos del informe de aceptación. Pero su alcance depende de la calidad de las preguntas y también exige que el desarrollador dedique tiempo a comprender los cambios. Los dos enfoques no se excluyen: lo más razonable es usar el informe de aceptación para confirmar «si se hizo bien» y las preguntas para comprobar «si entiendo por qué se hizo así».
Elige la intensidad de la revisión de la deuda de comprensión según el riesgo del cambio
No todos los PR necesitan pasar por el proceso completo. Addy también advierte que, cuando el volumen de contenido generado supera lo que puedes supervisar con responsabilidad, ya no estás revisando: estás apostando a que no haya problemas. La siguiente tabla ofrece una referencia por niveles de riesgo; conviene ajustar los criterios a la realidad de cada equipo.
| Nivel de riesgo | Cambios típicos | Intensidad de revisión recomendada |
|---|---|---|
| Bajo | Textos, estilos, scripts independientes, prototipos | Basta con un informe de aceptación o una comprobación manual; registra lo esperado |
| Medio | Funcionalidades habituales de negocio, incorporación de interfaces | Pregunta por las decisiones no autorizadas y verifica los resultados reales de las pruebas |
| Alto | Transacciones, permisos, pagos, migraciones de datos | Proceso completo de 5 pasos + evaluación mediante preguntas + revisión por un agente independiente |
| Por encima de la capacidad | Producción paralela de varios agentes que no se alcanza a revisar | Añade comprobaciones automatizadas o reduce el número de tareas en paralelo |
💡 Recomendación: Si tu equipo ya cuenta con un sistema consolidado de aceptación automatizada, puedes reservar la evaluación mediante preguntas para los cambios de alto riesgo. Si no es así, mantén al menos la regla de «solo se fusiona si se responde correctamente» en los PR que afecten a la consistencia de los datos y los permisos.
Preguntas frecuentes FAQ
P1: ¿Qué es la deuda de comprensión y en qué se diferencia de la deuda técnica?
La deuda de comprensión aparece cuando la complejidad del código y de los sistemas crece, pero la comprensión que tienen los desarrolladores no avanza al mismo ritmo. La deuda técnica suele deberse a problemas de calidad del propio código. En cambio, la deuda de comprensión puede darse incluso cuando el código es bueno: el problema es que las personas no lo entienden, y suele hacerse evidente cuando llega el momento de modificarlo.
P2: ¿Qué diferencia hay entre pedirle a la IA que te haga preguntas y pedirle que explique el código?
Cuando la IA te explica algo, recibes la información de forma pasiva y es fácil caer en la ilusión de que ya lo entendiste. En cambio, una evaluación te obliga a responder activamente y permite relacionar tus errores con partes concretas del código. Así, una comprensión difusa se convierte en algo que puedes comprobar.
P3: ¿No dar por bueno el trabajo del agente significa que hay que revisar el código de la IA línea por línea?
No. Según se ha informado, el equipo de Claude Code no exige que sus ingenieros memoricen todo el repositorio: cuando necesitan modificar una parte, recurren a Claude para volver a entender la lógica relevante. La clave es tener claro qué entiendes y qué no, y decidir la profundidad de la revisión según el riesgo.
P4: ¿En qué situaciones de desarrollo resulta útil este método?
Principalmente en estas:
– **Tareas de agentes de larga duración**: pueden dar lugar a decisiones no autorizadas, por lo que conviene usar una lista de preguntas de seguimiento
– **Cambios en el backend que afectan a transacciones o casos límite**: conviene hacer una evaluación mediante preguntas
– **Desarrollo en paralelo con varios agentes**: conviene conservar los materiales originales y controlar el número de tareas paralelas
– **Revisión de código en equipo**: la lista de preguntas puede incorporarse a la plantilla de PR
P5: ¿Cómo aplicar este proceso de autoevaluación de la deuda de comprensión en Claude Code, Cursor y Cline?
El método no depende de ninguna herramienta concreta; lo importante son las indicaciones y el proceso:
1. Guarda la plantilla completa de indicaciones de este artículo como un fragmento reutilizable para el equipo
2. Antes de empezar, escribe a mano la fase A; al terminar la tarea, pega las fases B y C
3. Para cambios de alto riesgo, abre una sesión independiente y ejecuta la fase D
También puedes incluir «fusionar solo si se responde correctamente» en las normas de revisión de PR del equipo.
P6: ¿Qué limitaciones conocidas tienen estos métodos?
Conviene ser objetivos:
– **Datos sobre su eficacia**: por ahora no hay datos públicos que demuestren cuánto reducen la tasa de defectos o mejoran la eficiencia
– **Costo de tiempo**: el proceso completo alarga el ciclo de fusión y no es adecuado para todos los PR
– **Puntos ciegos de las preguntas**: el agente puede pasar por alto problemas de los que él mismo no es consciente, así que no conviene omitir el paso de «encontrar algo que no se haya detectado»
– **Sobre la fuente**: las opiniones de Addy provienen de una referencia en medios; conviene verificar por cuenta propia las palabras del texto original
P7: ¿De verdad es necesario practicar programación sin conexión todas las semanas?
Según Addy, las habilidades que no se usan durante mucho tiempo pueden deteriorarse. Completar tareas de vez en cuando por tu cuenta, sin recurrir al agente, te ayuda a calibrar tu nivel real. Revisar también una vez al mes qué habilidades has delegado a la IA y cuáles debes seguir dominando cuesta poco y puede evitar que la rendición cognitiva avance sin que te des cuenta.
No le des el visto bueno al Agent sin más: claves de la deuda de comprensión
- La rendición cognitiva es gradual: empieza al delegar tareas cognitivas, sigue al ceder el criterio y termina al dejar todas las decisiones en manos de otro.
- La deuda de comprensión cobra intereses después: cuanto más rápido se escribe el código, más se acumula lo que no entiendes y más problemas aparecen cuando toca modificarlo.
- La deuda de intención se genera antes de empezar: escribe tu propia lista de requisitos y, si tras dos rondas de indicaciones el resultado no te convence, vuelve a aclararlos.
- La acción clave es ponerte a prueba: pide al Agent que resuma los cambios y te haga preguntas; solo integra los cambios si respondes bien a todas.
- Que todos los tests pasen no significa que no haya problemas: revisa primero los resultados de los tests que realmente se ejecutaron y después pregunta qué quedó sin probar.
- El informe de aceptación y las preguntas se complementan: el primero verifica el comportamiento externo; las segundas comprueban si entiendes la lógica interna.
- Revisa según el nivel de riesgo: si no das abasto, añade automatización o reduce el trabajo en paralelo; no dependas de la suerte.
Resumen
Los puntos clave para no darle el visto bueno al Agent sin más:
- Reconoce la etapa: ten cuidado de no pasar de «dejar que la IA trabaje» a «dejar que la IA decida». La deuda de comprensión y la deuda de intención son subproductos de ese proceso.
- Actúa: escribe lo que esperas antes de empezar, pregunta al recibir la entrega por las decisiones no autorizadas y lo que no se ha probado, y pide a la IA que te haga preguntas antes de integrar los cambios.
- Ajusta la revisión al riesgo: para cambios de bajo riesgo, usa un informe de aceptación o una revisión puntual; para los de alto riesgo, sigue el proceso completo y añade una revisión independiente.
La IA seguirá escribiendo código cada vez más rápido, pero quien aprueba los cambios siempre es responsable de ellos. La próxima vez que vayas a hacer clic en «Aprobar», pídele antes al Agent que te haga 5 preguntas y comprueba cuántas puedes responder correctamente.
📚 Referencias
- QbitAI: Guía completa de agentes para ingenieros de Claude (republicado por 36Kr): presenta las ideas de Addy Osmani sobre la rendición cognitiva, la deuda de comprensión y la deuda de intención, junto con métodos prácticos.
- Enlace:
36kr.com/p/4056027738116995 -
Nota: Es la fuente principal de la metodología de este artículo y se trata de una cobertura de prensa.
-
Publicación original de Addy Osmani: fuente original citada en el artículo.
- Enlace:
x.com/addyosmani/status/2117512471930167377 -
Nota: Consulta el original para verificar la redacción exacta; el enlace debe verificarse por separado.
-
Baijing Lab: Una empresa de IA con 80.000 estrellas decide dejar que la IA tome el control (republicado por 36Kr): presenta la arquitectura de agente supervisor de LobeHub y su práctica de informes de aceptación.
- Enlace:
36kr.com/p/4056040123945860 - Nota: Fuente de contraste para la revisión mediante informes de aceptación. La afirmación de que «casi no miran el código» proviene del propio equipo.
Autor: Equipo técnico de APIYI
