Tengo un agente de código —Claude Code— que interactúa con Linear, mi gestor de incidencias, unas 800 veces al mes: lista tareas, crea incidencias, cambia estados, comenta. Revisé 165 de sus sesiones y conté más de 500 errores y más de 370 reintentos.
Ninguno era un fallo de la API de Linear. Todos eran errores de interfaz: el agente le hablaba a la línea de comandos y la línea de comandos no le entendía.
La estimación conservadora del coste es de unos 700.000 tokens al mes consumidos solo en pelearse con la herramienta: reintentar, leer el mensaje de error, corregir, volver a intentar. Un peaje que no aparece en ninguna factura, pero que se paga en cada sesión.
Contexto: el agente es ahora el usuario principal
Una CLI —una herramienta de línea de comandos— se diseña, históricamente, para un humano. Y un humano es un usuario sorprendentemente robusto. Si un comando falla, lee la ayuda con --help. Si el mensaje de error es críptico, lo busca. Si la herramienta tiene una manía, la aprende y no vuelve a tropezar con ella.
Un agente de IA no hace casi nada de eso. No acumula experiencia entre sesiones como lo hace una persona. Lee la documentación con menos atención de la que crees. Y cuando algo falla, no se detiene a investigar: improvisa con lo que le parece más plausible.
Eso cambia quién es el cliente de tu herramienta. Si un agente la invoca 800 veces al mes y tú la usas a mano tres, el consumidor principal de esa interfaz es el agente. Diseñarla para el humano y esperar que el agente se adapte es optimizar para el usuario minoritario.
Diseñar deliberadamente para ese usuario tiene nombre: agentic experience. Es a los agentes lo que la experiencia de usuario (UX) es a las personas y la de desarrollador (DX) a quien programa contra tu API. Y su mejor instrumento de medida no hay que construirlo: ya lo estás generando. Es el log de errores del agente.
Los errores tienen forma
Conté como error toda invocación de la CLI que terminó con un código de salida distinto de cero. Con ese criterio, los más de 500 errores no eran aleatorios: casi todos caían en tres patrones.
| Patrón | Qué hacía el agente | Qué revela del diseño |
|---|---|---|
| Flags inventados | Escribía --status en vez de --state; --priority urgent en vez de --priority 1 |
El flag real no era el que cualquiera adivinaría primero |
| Operaciones ausentes | Intentaba buscar texto, filtrar por proyecto o asignar proyecto al crear: funciones que la CLI no tenía | La herramienta no cubría el flujo de trabajo real |
| Flags obligatorios olvidados | Omitía --sort, --no-pager, --no-interactive |
Se exigían decisiones que la herramienta podía tomar sola |
Cuando el agente escribía --status, no estaba alucinando: estaba adivinando la interfaz más plausible. --status es, objetivamente, un nombre tan razonable como --state. El agente apostó por la forma más probable, y el diseño que yo había construido no coincidía con esa probabilidad.
Hay un cuarto problema que ese recuento no captura, porque nunca produce un comando fallido: la salida verbosa. La CLI devolvía los listados en JSON, unos 50 tokens por incidencia. El comando termina con éxito —código de salida cero—, así que no cuenta como error; pero multiplicado por listados largos y por 800 invocaciones al mes, es la otra mitad de esos 700.000 tokens. Un coste que pasa desapercibido precisamente porque nada se rompe.
El error de lectura
La interpretación cómoda de esos 500 errores es directa: el agente usa mal la herramienta. Es la interpretación equivocada, y conviene desmontarla pieza a pieza.
Un flag inventado significa que el nombre real no era el que cualquiera adivinaría primero. Un flag obligatorio olvidado significa que ese flag no debería ser obligatorio: si la herramienta puede asumir un valor por defecto sensato, exigirlo es trasladar trabajo a quien la llama. Una salida que quema contexto significa que se eligió el formato pensando en el lector equivocado.
El log de errores de un agente no es una lista de fallos del agente. Es una especificación: cada error describe, en negativo, una pieza de la interfaz que deberías haber construido. Y es la especificación más honesta que vas a recibir: gratuita, de un volumen que ningún panel de usuarios humanos te daría, y sin la cortesía con la que un humano disimula los defectos de una herramienta. Una persona que tropieza con una CLI mala se calla y se adapta. El agente no se adapta: vuelve a cometer el mismo error mañana, y pasado, y deja registro de cada uno.
Esto conecta con un principio que desarrollé en otro artículo: el camino incorrecto debe ser imposible, no estar prohibido. Prohibir es documentación —»no uses --status«— y la documentación depende de que alguien la lea con atención. Hacer imposible el error es diseño.
La solución, por tanto, no era documentar mejor. Era una herramienta mejor.
El rediseño
Reescribí la CLI —se llama lql— alrededor de ese principio. Cuatro decisiones de diseño concentran casi todo el efecto.
Tolerancia en lugar de rechazo. Si el agente escribe --status, la herramienta lo acepta como alias de --state y continúa. Si escribe --priority urgent, lo traduce a --priority 1 e informa de lo que ha asumido. El camino «equivocado» más frecuente se convierte, sin más, en un camino correcto. La herramienta no castiga una conjetura razonable: la absorbe.
Errores que enseñan el camino bueno. Cuando algo de verdad no existe, el mensaje no es unknown flag. Es una instrucción: --filter no existe. Para filtrar por estado: --state <estado>. Para buscar: lql search "texto". El mensaje de error pasa a ser la documentación, entregada en el único momento en que el agente la va a leer con total atención: justo después de fallar.
Cero flags obligatorios. lql list funciona sin un solo argumento: ordena por prioridad, filtra a los estados activos y detecta el equipo a partir del directorio de trabajo. No hay un --sort que olvidar porque no existe un --sort que poner. Un flag que el agente no puede olvidar es, sencillamente, un flag que no se ha hecho obligatorio.
Salida para el consumidor real. Quien lee la salida es un LLM que paga cada token. La herramienta usa TOON (Token-Oriented Object Notation), un formato compacto que codifica el esquema una vez en una cabecera y luego emite valores posicionales.
| Formato | Tokens por incidencia | 50 incidencias |
|---|---|---|
| XML | ~70 | ~3.500 |
| JSON | ~50 | ~2.500 |
| TOON | ~25 | ~1.250 |
TOON no es una invención propia: es un formato abierto (toonformat.dev) que la herramienta se limita a adoptar. El flag --json sigue disponible para scripts y tuberías, donde el consumidor sí es una máquina convencional.
La prueba
La medición que más me convence no es un benchmark de rendimiento. Es esta.
El agente necesita un fichero de instrucciones para operar con Linear —en Claude Code se llama «skill»—. Con la CLI antigua, ese fichero tenía 246 líneas. 150 de ellas eran workarounds: «si ocurre esto, haz esto otro», «recuerda añadir este flag», «no uses esta forma». Documentación defensiva, escrita para tapar los agujeros de la herramienta.
Tras el rediseño, ese fichero quedó en 205 líneas con cero workarounds. Una herramienta tolerante no necesita que la disculpen. Las 150 líneas no desaparecieron porque las borrara: desaparecieron porque ya no había nada que documentar.
Los límites de este análisis
Por honestidad, conviene marcar el alcance. Esto es un agente —Claude Code— y una API —Linear—. El reparto exacto de los tres patrones de error cambiará con otro agente o con otra API. La forma del problema —el agente adivina la interfaz más plausible y falla cuando esa probabilidad no coincide con tu diseño— no creo que cambie, pero esa es una hipótesis, no un dato.
El recuento de los más de 500 errores y 370 reintentos sale de parsear los ficheros JSON de las 165 sesiones de Claude Code. La definición de error ya está dada —código de salida distinto de cero—; un reintento es una reejecución del mismo comando tras un fallo previo. El criterio es mecánico y reproducible: el código de salida no admite interpretación, aunque el conteo proceda de uso real y no de un experimento controlado.
Pruébalo
lql es software libre con licencia MIT. El código está en github.com/frr149/lql.
brew install frr149/tools/lql
lql list --team PROD --state Todo --priority urgent
Qué hacer si conectas un agente a una CLI
Si tienes un agente de IA invocando una herramienta de línea de comandos —tuya o de un tercero—, ya dispones del dato que necesitas para mejorarla: los errores que comete el agente al usarla.
No los trates como ruido en los logs ni como una deficiencia del agente. Extráelos, clasifícalos por patrón y léelos como lo que son: el plano de tu interfaz, dibujado en negativo. Cada flag que el agente se inventa es una propuesta de cómo debería llamarse el flag real; cada operación que intenta y no existe es una petición de función.
Read this article in English.
