Cuando un coding agent local falla, no empieces cambiando modelo, cuantización, ventana de contexto y entorno de herramientas al mismo tiempo. El mismo parche roto puede venir de tres capas distintas: el modelo o runtime no tiene precisión suficiente, el agente no recibió la evidencia correcta, o el harness no puede aplicar cambios, ejecutar comandos, leer pruebas y devolver feedback de forma estable.
| Síntoma | Sospecha primero | Prueba | Primer arreglo |
|---|---|---|---|
| Falla en una edición mínima antes de que importen las herramientas | Modelo, runtime o cuantización | Ejecuta la misma tarea pequeña con mayor precisión local o con una base hosted, sin archivos extra | Cambia cuantización, runtime o modelo para ese tipo de tarea |
| Pierde el archivo, la regla o una decisión previa | Selección de contexto | Inicia una sesión limpia con solo archivos objetivo, prueba fallida y regla obligatoria | Reduce contexto y carga evidencia exacta, no más texto del repo |
| Explica el arreglo correcto, pero el patch, comando o test se rompe | Harness y feedback de herramientas | Compara el patch previsto por el modelo con el tool log, command output y test result | Repara edición, permisos, cwd, schemas, hooks de test o retry loop |
| Solo funciona tras cambiar varias cosas | Aún no hay diagnóstico | Restablece mismo repo, misma tarea, sesión limpia, archivos fijos y una variable | Repite el control antes de seguir ajustando |
La base hosted solo sirve como línea de comparación. Si la misma tarea mínima pasa hosted y falla localmente, todavía hay que diagnosticar el stack local por capas. Si ambos fallan, probablemente la tarea, los archivos o los criterios de aceptación no están especificados. Detén el ajuste local de esa tarea cuando una comparación justa muestre que la calidad, velocidad o confiabilidad de herramientas no alcanza el nivel necesario.
Matriz rápida de diagnóstico
Un coding agent local no es solo un modelo. En la ejecución real participan pesos, runtime de inferencia, cuantización, KV cache, selección de archivos, reglas del proyecto, historial, llamadas a herramientas, edición de archivos, comandos de shell, pruebas, permisos, sensores y revisión. Desde fuera todo parece “el agente se equivocó”, pero la causa puede estar en cualquier parte de ese circuito.
| Capa | Qué controla | Patrón de fallo | Conclusión prematura |
|---|---|---|---|
| Modelo y runtime | Tamaño del modelo, cuantización, KV cache, CPU/GPU, servidor de inferencia | Razonamiento débil en tareas pequeñas, structured output roto, decode lento, OOM al crecer la secuencia | Que todos los modelos locales son malos |
| Contexto y retrieval | Archivos cargados, reglas, historial, summaries, tool definitions, logs | Edita archivo equivocado, olvida una restricción, omite un símbolo cercano, lee más sin mejorar | Que una ventana mayor lo arregla |
| Harness y feedback | Aplicación de edits, command runner, permissions, schemas, tests, sensors, retries | La idea es correcta, pero fallan patch, cwd, test output o permisos | Que el modelo no podía resolver la tarea |
La primera acción útil no es elegir una configuración universal. Es construir una comparación pequeña, controlada y reproducible que cambie una sola capa.
Ejecuta el control de una variable
El diagnóstico solo vale si la comparación es justa. Mantén el mismo repositorio, la misma tarea, la misma instrucción, el mismo conjunto de archivos y una sesión limpia. Elige el caso real más pequeño que reproduzca el fallo: una prueba fallida, una edición mala, un comando que el agente ejecuta mal, un error de permisos o un archivo que siempre interpreta mal.
Registra modelo, cuantización, runtime, context length, archivos cargados, harness, comando exacto, stdout, stderr, resultado de tests y patch final. Luego cambia exactamente una cosa.
| Cambio único | Qué demuestra si mejora | Qué no demuestra | | --- | --- | --- | --- | | Mayor precisión, modelo local más grande o baseline hosted | Modelo o runtime eran un cuello probable | Que contexto y harness estén sanos | | Sesión limpia con archivos objetivo | Contexto amplio, historial o retrieval estaban contaminando | Que el modelo pequeño basta para todo el repo | | Mismo modelo en otro harness | Tool loop, edit application, tests o permissions participaron en el fallo | Que el nuevo harness sea mejor para todo | | Misma tarea, pero el modelo solo propone patch y tú aplicas/testeas | La idea era buena y falló la ejecución | Que la revisión manual deba rescatar cada corrida |
La decisión entre ruta local y cloud viene después de encontrar la capa fallida. Para esa decisión posterior, usa local versus cloud coding agents.
Cuándo sospechar cuantización o runtime
Sospecha la capa de modelo cuando el fallo aparece antes de que contexto o herramientas puedan explicarlo. Señales típicas: no sostiene una edición de dos pasos, rompe JSON de tool call en una tarea diminuta, repite errores simples de sintaxis, se vuelve demasiado lento al crecer la secuencia o presiona memoria durante prefill.
La cuantización reduce memoria y cómputo, pero también puede reducir precisión. Aun así, “Q4 falló” no significa “lo local no sirve”. Ejecuta la misma tarea pequeña con una cuantización menos agresiva, un modelo más apto para código si tu hardware lo permite o una base hosted. Mantén el contexto mínimo para no mezclar un problema de retrieval.
Un buen registro de runtime incluye model id, quantization format, context-length setting, inference server, device placement, memory pressure, prefill speed, decode speed, ajustes de KV cache y si el mismo command/test pasó. Sin esos datos, culpar a la cuantización es solo una hipótesis.
Cuándo sospechar contexto
Sospecha contexto cuando el modelo funciona aislado, pero dentro del repositorio no usa los hechos correctos. Puede editar un archivo hermano, olvidar una convención local, ignorar una interfaz cercana, mezclar una decisión antigua o leer más archivos sin acercarse al arreglo.
El contexto no es volcar todo el proyecto. Debe incluir el archivo objetivo, la prueba fallida, la schema o interfaz cercana, la regla que gobierna el cambio, el output reciente del comando y un mapa breve de archivos. Una ventana larga solo ayuda si la evidencia relevante sigue siendo recuperable.
Haz una prueba en sesión limpia: target file, nearest test, interface cercana y governing instruction. Indica también qué directorios no debe leer. Si mejora, la reparación no empieza por el modelo sino por eliminar stale history, ruido, misses de retrieval y definiciones de herramientas innecesarias.
Cuándo sospechar harness
Sospecha harness cuando el modelo sabe qué hacer, pero el ciclo de ejecución falla. Nombra el archivo correcto y describe un patch razonable, pero el edit tool no aplica el diff, el command runner usa un cwd incorrecto, permisos bloquean la verificación, el output de tests no vuelve al prompt o el retry repite el mismo error.
Separa la intención del modelo del trace real. Pídele el intended patch sin aplicarlo y pruébalo manualmente, o ejecuta el mismo modelo en otro harness. Si la idea funciona y el loop automático no, el arreglo está en tool schemas, working directory, permissions, deterministic checks, sensors y review gates.
Un buen harness no necesita magia. Debe aplicar cambios de forma confiable, ejecutar comandos fijos, mostrar errores reales a la siguiente iteración, tener condiciones de parada y no ocultar pruebas fallidas.
Construye el paquete de evidencias
Una consulta útil al equipo o a soporte no necesita todo el chat. Necesita un paquete que reproduzca el fallo y separe observación de interpretación.
| Campo | Qué registrar |
|---|---|
| Task | La tarea mínima del repo que reproduce el fallo |
| Model/runtime | Modelo, cuantización, runtime, device placement, context length |
| Context | Archivos, reglas, historial, summaries, retrieval y logs cargados |
| Harness | Tool wrapper, edit method, command runner, permission mode, test command |
| Symptom | El fallo exacto, no la explicación |
| Tool log | Patch application, command output, test result, permission o schema error |
| Control comparison | Qué quedó fijo, qué cambió y cómo cambió el resultado |
| First fix | Un solo arreglo probado y su pass/fail |
| Decision | Seguir afinando, cambiar harness, usar hosted baseline o detener local |
“Una configuración local de baja precisión falla en una tarea pequeña sin contexto, y una configuración de mayor precisión pasa” es evidencia. “Todos los agentes cuantizados son inútiles” no lo es.
Ajustar, cambiar o detener
Después de una o dos comparaciones controladas, elige una ruta. No sigas afinando solo porque la configuración parece estar cerca.
Ajusta model/runtime cuando el fallo aparece antes de efectos de contexto o harness y mejora con una base local más fuerte. Usa cuantización menos agresiva, un modelo más orientado a código, runtime settings guardados o una frontera de tarea más pequeña.
Reduce contexto cuando el agente funciona con archivos elegidos a mano, pero falla en una sesión amplia. Agrega un file map, elimina conversación vieja, fija tests exactos y usa command output como evidencia. Si un patch pequeño necesita una ventana enorme, el diagnóstico todavía no está cerrado.
Repara harness cuando la idea es correcta y el loop de herramientas rompe la tarea. Las correcciones viven en schemas, edit application, command wrappers, permission policy, reglas del proyecto, sensors y review checks.
Usa hosted baseline como ruta de entrega cuando el stack local no alcance calidad o velocidad tras una comparación justa. Si la siguiente decisión es Claude Code contra Codex, usa Claude Code vs Codex. Si el problema son usage meters y context accounting en Codex, consulta Codex token usage. Si la preocupación es API-key spend, usa Codex CLI token cost estimate.
Preguntas frecuentes
¿La cuantización es la causa más común?
No por sí sola. La cuantización puede bajar precisión, pero contexto ruidoso y harness roto producen el mismo síntoma externo. Prueba una tarea pequeña, con contexto mínimo y una base de mayor precisión o hosted.
¿Cómo sé si el problema es contexto?
Ejecuta la misma tarea en una sesión limpia con target files, nearest tests y governing rules. Si mejora, la sesión amplia probablemente tenía noise, stale history, retrieval miss o demasiadas tool definitions.
¿Qué cuenta como fallo de harness?
Ocurre cuando el intended fix es plausible, pero el sistema de ejecución no cierra el ciclo. Failed patch, wrong cwd, permission loop, malformed tool call, ignored test output y retry sin aprendizaje entran aquí.
¿Debo pasar enseguida a Claude Code, Codex u otro hosted agent?
Primero usa hosted route como baseline sobre la misma tarea mínima. Si hosted pasa y local sigue fallando después del diagnóstico por capas, usa hosted para esa tarea. Si ambos fallan, mejora task description, files, tests y acceptance criteria.
¿Qué envío al pedir ayuda?
Envía model/runtime, quantization, loaded files, harness, prompt, tool log, command output, test result y una comparación de una variable. Excluye secretos y código privado que no sea necesario para reproducir el fallo.