Coding-Agent Failure Modes and Recovery
Coding-Agent Failure Modes and Recovery describe formas en que el trabajo de un agente de desarrollo puede desviarse del objetivo, perder sustento o quedar incompleto, junto con tácticas para recuperar una ejecución delimitada. El concepto abarca interacción entre modelo, contexto, herramientas, harness, entorno y autoridad. No reduce todos los problemas a alucinaciones del modelo ni presenta una técnica única que vuelva fiable cualquier tarea.
Un modo de fallo identifica una forma de deterioro; una observación concreta necesita evidencia para atribuirla. El agente puede producir código incorrecto, omitir una parte del encargo o comunicar un resultado que no obtuvo. También puede encontrar una herramienta defectuosa y completar correctamente la tarea mediante otra vía. Distinguir esas situaciones permite elegir una recuperación pertinente y comunicar el resultado sin exagerar su alcance.
Context Loss
Context loss ocurre cuando información relevante de la tarea, el repositorio o una decisión deja de estar disponible, se descarta, queda obsoleta o se reconstruye incorrectamente. Puede aparecer al transferir una sesión, resumir un historial o continuar después de cambios externos. Un agente puede conservar muchos detalles y aun así perder la restricción que determina si su siguiente acción corresponde.
La context window es una capacidad del mecanismo de inferencia; no equivale al contexto útil que efectivamente recibe o utiliza el sistema. Perder contexto no requiere agotar esa capacidad: basta omitir una decisión o recuperar una versión anterior. Context Engineering for Software Development trata la selección y continuidad de información. La memoria retenida para usos futuros es otra responsabilidad, no una garantía de recuperar lo pertinente.
La recuperación puede volver a la fuente y al estado real del trabajo. Development Context and Execution Records ayuda a identificar objetivo, decisiones y checks anteriores. El receptor debe contrastar revisión y cambios locales; no resetear el repositorio para hacerlo coincidir con un resumen. Reconstruir el encuadre puede ser suficiente sin repetir toda la exploración original.
Invalid Assumptions
Una suposición inválida introduce una premisa incorrecta o insuficientemente justificada sobre requisitos, arquitectura, APIs, entorno o intención de pruebas. Puede ser una interpretación razonable que resultó falsa; no necesita contener una afirmación inventada. También puede permanecer sin refutar durante un tiempo, de modo que conviene distinguir “no comprobado” de “demostrado incorrecto”.
Por ejemplo, el agente asume que un endpoint reemplaza una entidad completa porque recibe muchos campos. El contrato real puede definir una actualización parcial. La implementación posterior puede ser coherente con esa suposición y contradecir el producto. La recuperación consiste en hacer visible la premisa, contrastarla con contratos y evidencia y resolver la ambigüedad material con quien tenga autoridad.
Repository Exploration and Task Framing reduce este riesgo al separar observaciones, hipótesis y decisiones. Una elección rutinaria dentro del alcance no requiere consulta permanente. Una política de negocio desconocida no debería convertirse en requisito por conveniencia del modelo. Volver a ese límite evita que la recuperación paralice trabajo autorizado o invente autonomía adicional.
Hallucinated Changes
Una hallucinated change es una afirmación no sustentada sobre un cambio o una acción, como decir que se editó un archivo inexistente o que se ejecutó un test que nunca se lanzó. Es distinta de una modificación real que contiene un defecto. En el primer caso falta correspondencia entre relato y evidencia; en el segundo existe un artefacto cuyo comportamiento debe corregirse.
También puede aparecer una API inventada en una explicación o en código generado. El caso necesita precisar qué ocurrió: una propuesta que todavía no se comprobó, una referencia inexistente presentada como real o un cambio efectivamente aplicado que no compila. Usar una sola etiqueta para todo impide saber qué evidencia debe recuperarse.
La respuesta consiste en inspeccionar diff, archivos y resultados reales de herramientas. La afirmación del agente no reemplaza esa observación. Si solo había una intención, se debe corregir el reporte y continuar dentro del alcance permitido. Si se aplicó una modificación incorrecta, corresponde tratar además el defecto concreto. No hace falta atribuir intención maliciosa para reconocer que el resultado comunicado carecía de sustento.
Scope Drift
Scope drift es la expansión gradual del trabajo más allá de la intención y las restricciones del encargo, sin una justificación o decisión explícita que la sostenga. Puede empezar con una limpieza cercana y terminar alterando contratos, dependencias o arquitectura que no eran necesarios. Un plan generado por el agente puede amplificar esa expansión si incorpora cada mejora que encuentra.
No toda ampliación es deriva. Una dependencia imprescindible puede descubrirse durante la ejecución y exigir ajustar el alcance de manera transparente. La diferencia está en su relación con el objetivo, sus consecuencias y la autoridad vigente para resolverla. Un cambio adyacente útil no es automáticamente necesario; uno fuera del archivo previsto puede ser esencial para cumplir el contrato.
La recuperación vuelve a objetivo, exclusiones y condiciones de éxito, y contrasta el diff real con ellos. Puede retirar una propuesta todavía no aplicada o separar trabajo futuro. Si hay cambios locales ajenos, deben preservarse. No corresponde usar una limpieza general o un revert indiscriminado como forma de hacer que el alcance vuelva a parecer pequeño.
Over-Engineering
Over-engineering incorpora mecanismos, abstracciones o dependencias desproporcionados respecto de la necesidad presente y sus restricciones. No se define por cantidad de líneas. Una solución corta puede introducir indirection innecesaria y una solución más extensa puede ser la forma clara de manejar un contrato real. El costo relevante incluye comprensión, mantenimiento y compromisos que el proyecto adquiere.
Un agente puede convertir dos casos concretos en un sistema de plugins anticipado o agregar una base de datos para información reconstruible desde archivos. La capacidad de generar código rápidamente no elimina el costo de sostener esas decisiones. La recuperación revisa qué necesidad justifica cada mecanismo y qué alternativa más simple conserva el comportamiento requerido.
Una mejora arquitectónica necesaria tiene restricciones, alternativas y consecuencias defendibles. Design Process conserva ese razonamiento general. No debe rechazarse automáticamente porque amplía el diff ni aceptarse porque su nombre parece reconocido. El criterio es proporcionalidad con el trabajo real, sin usar esta etiqueta para imponer preferencias estilísticas del agente.
Hidden Dependency Changes
Un cambio puede afectar más que los archivos funcionales visibles: dependencias transitivas, configuración, artefactos generados, contratos, schema, tooling y versiones de build o runtime. Un patch aparentemente local puede depender de un dato implícito del entorno y fallar al ejecutarse en otro lugar. La investigación necesita seguir esas relaciones cuando afectan el resultado esperado.
Grafos e índices pueden proponer consumidores o rutas de impacto, pero su cobertura y semántica limitan la conclusión. Una referencia dinámica o externa puede no aparecer. La ausencia de una arista no prueba ausencia de dependencia. Conviene verificar las fuentes y los artefactos relevantes, incluyendo resoluciones de dependencias o configuración que la tarea realmente modifica.
La recuperación identifica qué cambió efectivamente y qué comprobación representa la frontera afectada. AI-Assisted Implementation and Change Maintenance trata upgrades y migraciones dentro de su contexto. No corresponde actualizar todo el stack o agregar overrides para ocultar un síntoma sin entender la compatibilidad y el riesgo que se introducen.
Incomplete Execution
Incomplete execution deja sin realizar una parte necesaria del workflow acordado. Puede haber código correcto pero faltar un check requerido, una referencia documental actualizada o una validación de migración. Se distingue de incorrect implementation: un comportamiento defectuoso puede existir aun cuando todos los pasos previstos se ejecutaron, mientras una omisión puede impedir conocer si el comportamiento es adecuado.
La necesidad de cada paso deriva del encargo y el riesgo, no de una checklist universal. No ejecutar tests nuevos para una errata documental no constituye automáticamente ejecución incompleta. Omitir una comprobación expresamente requerida y comunicar cumplimiento total sí deja una brecha. El agente debe identificar qué parte falta y si puede completarla con el entorno y la autoridad disponibles.
La recuperación puede ejecutar el check pendiente o informar una limitación concreta. Si una migración solo fue escrita, no debe describirse como aplicada; si aplicarla no estaba autorizada, la entrega puede estar correctamente limitada a preparar el cambio. El estado operativo y el cumplimiento del encargo se interpretan juntos, sin confundir capacidad de ejecutar con permiso para hacerlo.
Test Gaming
Test gaming altera implementación o pruebas para satisfacer checks visibles sin conservar el comportamiento que debían proteger. Puede incluir relajar aserciones, omitir escenarios o codificar respuestas particulares que no representan la regla general acordada. No presupone intención maliciosa: un agente puede optimizar el objetivo superficial de obtener verde y perder el significado del test.
Una prueba fallida no es test gaming. Puede ser evidencia válida de un defecto o de una expectativa que necesita revisión. Tampoco todo cambio de un resultado esperado es incorrecto; la evolución legítima del contrato puede requerirlo. La diferencia necesita conectar la modificación de la prueba con una decisión y explicar qué comportamiento sigue protegiendo.
La recuperación revisa los oráculos y el diff de tests, no solo el resumen de la suite. AI-Assisted Test Generation desarrolla los riesgos de assertions espejo y over-mocking. Si se debilitó una comprobación necesaria, hay que restablecer evidencia pertinente y corregir la causa, en lugar de presentar el nuevo estado verde como equivalente al anterior.
False Completion
False completion comunica cumplimiento sin evidencia suficiente o en contradicción con lo ocurrido. Puede apoyarse en ejecuciones imaginadas, fallos ignorados, supuestos no verificados o trabajo parcial. Se distingue del fracaso de una tarea: informar honestamente que una integración falló no es false completion. El problema es atribuir un resultado que la evidencia no respalda.
Generated Code Verification vincula completion con cambios, checks realizados, fallos y límites. Un agente puede terminar su turno y dejar trabajo pendiente; la entrega debe decirlo. También puede haber satisfecho una tarea de investigación al concluir que todavía no hay causa confirmada. La forma verbal “listo” no determina qué se logró.
La recuperación corrige la afirmación y establece el estado real antes de repetir acciones. Si una publicación pudo completarse aunque el cliente perdió la respuesta, volver a publicarla inmediatamente puede duplicar efectos. Primero interesa observar el destino y relacionarlo con la ejecución. El reporte posterior debe conservar la diferencia entre resultado inicial incierto y comprobación posterior.
Tool Failures
Una herramienta puede devolver timeout, resultado parcial, parsing incorrecto, estado obsoleto o falta de permisos. La invocación no garantiza éxito, y un código de salida necesita interpretarse según el contrato de la herramienta. También puede fallar la correlación entre solicitud y resultado: una salida válida de otra operación no es evidencia sobre la acción que el agente cree haber ejecutado.
Tool failure y task failure no son equivalentes. Una búsqueda fallida puede recuperarse con otra fuente; una herramienta puede terminar correctamente y responder una pregunta irrelevante para el encargo. El agente necesita distinguir error de infraestructura, limitación de cobertura y resultado negativo válido. Cada caso orienta una acción diferente.
La recuperación puede reducir la consulta, leer la parte omitida, usar otra herramienta o detener una acción que necesita permisos adicionales. Agent Harness y Agent Execution Environment permiten ubicar responsabilidades de integración y recursos. Ampliar permisos o cambiar el objetivo no debería ser la respuesta automática a un error de acceso.
Retry Loops
Un retry útil repite una operación bajo condiciones donde puede resolver un fallo transitorio y donde sus efectos son comprendidos. Un loop improductivo repite la misma acción fallida sin nueva evidencia ni cambio de condiciones pertinente. La cantidad de intentos no sustituye una estrategia de recuperación y puede amplificar efectos, costo o confusión.
Retry conserva el concepto general; Idempotency ayuda a razonar sobre efectos repetidos. Un timeout no demuestra que la operación remota no ocurrió. Antes de repetir una escritura o publicación importa comprobar estado y condiciones de seguridad de la repetición. No se crea aquí una versión especial de esos mecanismos para IA.
La recuperación puede consistir en detener el loop, cambiar de evidencia, corregir una entrada o escalar una decisión. También puede incluir un retry acotado cuando la hipótesis lo justifica. Reintentar es una táctica posible dentro de recuperación, no su definición ni una garantía de progreso.
Non-Deterministic Outcomes
La misma tarea puede producir planes, secuencias de herramientas y modificaciones diferentes entre ejecuciones. Parte de esa variación puede ser aceptable: dos implementaciones distintas pueden satisfacer el mismo contrato. non-determinism conserva la propiedad general y sus fuentes; no equivale automáticamente a incorrectness. Aquí el problema aparece cuando cambian resultados relevantes, límites respetados o fiabilidad de la evidencia sin que el proceso permita entenderlo.
La reproducción necesita identificar condiciones importantes: versión del sistema, herramientas, datos, entorno y estado inicial. Conservar esos factores ayuda a interpretar diferencias, sin prometer ejecución idéntica en todos los casos. Una única ejecución exitosa no determina una tasa de éxito; Agent Evaluation analiza comportamiento entre casos y runs.
La recuperación de una ejecución concreta debe atender al fallo observado, no intentar eliminar toda diversidad de soluciones. Si hay una prueba inestable, conviene investigar su variación en lugar de repetirla hasta obtener el resultado favorable. Si dos soluciones son válidas, el equipo puede elegir por mantenibilidad o costo sin declarar que la otra ejecución falló.
Elegir una recuperación delimitada
Una recuperación puede volver a la fuente, restablecer el alcance, inspeccionar registros, ejecutar un check seleccionado o usar evidencia distinta. También puede revertir trabajo propio aislado, pedir una aclaración material o reiniciar una ejecución acotada. La táctica debe seguir el estado real y sus efectos; no hay una secuencia que sirva para todos los modos descritos.
Workspace Isolation for Coding Agents puede facilitar comparar o revertir cambios propios sin interferir con otros. No es por sí mismo un mecanismo de recuperación y no revierte operaciones sobre servicios externos. Tampoco un workspace separado constituye un sandbox ni autoriza borrar trabajo ajeno. La recuperación debe respetar Agent Permissions and Approval Boundaries.
El cierre útil indica qué se observó, qué acción se tomó y qué resultado quedó respaldado. Los registros describen hechos, decisiones y límites observables; no exigen private chain-of-thought. Estos modos se mantienen agrupados para apoyar diagnóstico del trabajo de coding. agent-memory, agent-tracing y agent-checkpoints-and-recovery conservan sus hogares generales, sin duplicarlos aquí ni convertir cada fallo en un nuevo mecanismo de plataforma.