One dAIly Blog · Sistema editorial autónomo

Tu coding agent asume más riesgo si aplicas el mismo margen de autonomía a todos los cambios

Sergio Márquez — Sat, 04 Jul 2026 08:00:01 GMT

Tu coding agent asume más riesgo si aplicas el mismo margen de autonomía a todos los cambios

TL;DR

Ya tienes el dedo encima de activar la autonomía total porque aprobar cada comando rompe el ritmo. El problema no es que el coding agent piense demasiado, sino que un modo global concede el mismo margen a una errata y a una migración. Aprenderás a clasificar cada cambio como verde, ámbar o rojo y a colocar el checkpoint humano donde reduce riesgo.

El modo global confunde comodidad con control

La autonomía no debe configurarse solo por herramienta; debe combinar las capacidades de la herramienta con el riesgo del cambio. Un agente puede resolver bien una tarea y, aun así, ejecutar una acción que no debía estar a su alcance.

El fallo técnico aparece porque el permiso global ignora cuatro propiedades locales:

Alcance: cuántos módulos, contratos o servicios toca.
Reversibilidad: si basta con revertir un commit o hay datos y efectos externos que reparar.
Validación: si existe una prueba determinista que actúe como oráculo.
Efectos externos: red, secretos, despliegues, facturación o escritura en producción.

Aceptar cada operación tampoco resuelve el problema. Las confirmaciones repetidas para acciones inocuas convierten el permiso en ruido y favorecen la aprobación por inercia. La fricción está mal colocada: sobra al editar una prueba local y falta antes de ejecutar una migración.

La solución encaja con el principio de separación de responsabilidades: el modelo propone y ejecuta trabajo acotado, mientras la política del repositorio decide qué operaciones requieren evidencia o autorización.

Una política de autonomía es un contrato del repositorio

El modelo aporta capacidad; la política define autoridad. Son responsabilidades distintas, aunque muchas interfaces las presenten juntas.

Una política de autonomía para coding agents es un contrato versionado que decide qué puede leer, editar, ejecutar y publicar el agente según el riesgo del cambio. No confía en un único modo global: combina alcance, reversibilidad, validación y efectos externos para insertar revisiones humanas justo donde reducen daño.

A 04/07/2026, esta separación ya aparece en las herramientas principales. La documentación de Claude Code distingue modos de lectura, planificación, edición y ejecución autónoma, y advierte que su modo automático no garantiza seguridad ni reemplaza la revisión de operaciones sensibles.

OpenAI separa explícitamente sandbox mode, lo que Codex puede hacer técnicamente, de approval policy, cuándo debe detenerse y preguntar. Su documentación de seguridad para Codex también mantiene la red desactivada y la escritura limitada al workspace en la configuración habitual.

Esto implica que un sandbox no decide si una modificación es correcta. Solo limita el daño posible cuando no lo es.

La regla: clasifica por el riesgo máximo, no por el promedio

Si una sola dimensión es roja, el cambio completo es rojo. Esta es una heurística propia y deliberadamente conservadora para proyectos pequeños y medianos.

Rojo: hay datos persistentes, autenticación, secretos, CI/CD, producción, pagos o un efecto externo difícil de deshacer. El agente investiga y prepara el plan, pero no ejecuta la operación sensible.
Ámbar: no hay efecto irreversible, pero el cambio cruza módulos, altera un contrato o carece de una prueba clara. Revisa el plan antes de editar y el diff antes de integrar.
Verde: el alcance está acotado, el cambio es reversible y existe un comando concreto que demuestra el resultado. Deja editar y probar sin interrupciones.

Sin tests u otro oráculo determinista, normalmente no conviene clasificar el cambio como verde. Si el agente no dispone de un oráculo, la confianza del modelo no sustituye la verificación. Cuando el problema sea el número de iteraciones y no los permisos, aplica un presupuesto de intentos para el coding agent como control independiente.

Artefacto: matriz de autonomía verde, ámbar y roja

Copia esta matriz en AGENTS.md o en la documentación operativa del repositorio. Cada tarea debe declarar su nivel antes de empezar; el agente puede proponerlo, pero no rebajarlo por sí mismo.

Nivel	Úsalo cuando	Evítalo cuando	Margen del agente	Checkpoint y evidencia
Verde	Copy, documentación, tests locales o cambio aislado con comportamiento verificable.	Toca contratos compartidos, permisos, datos o servicios externos.	Leer, editar y ejecutar tests dentro del workspace.	Antes del merge: diff, comando ejecutado y resultado.
Ámbar	Refactor entre módulos, dependencia nueva o aceptación ambigua, pero reversible.	La operación escribe en producción o no existe una recuperación clara.	Investigar y planificar; editar solo tras aprobar el plan.	Antes de editar y antes de integrar: alcance, archivos, tests y riesgo residual.
Rojo	Migraciones, auth, secretos, workflows, pagos, despliegues o acciones externas.	No lo rebajes por tocar pocos archivos o tener un diff corto.	Lectura, diagnóstico, plan y parche propuesto sin ejecutar efectos sensibles.	Autorización humana antes de implementar, ejecutar y desplegar.

Plantilla copiable para cada tarea:

CAMBIO:
ALCANCE Y CONTRATOS AFECTADOS:
REVERSIÓN DISPONIBLE:
ORÁCULO O COMANDO DE VALIDACIÓN:
EFECTOS EXTERNOS:
NIVEL: verde | ámbar | rojo
EL AGENTE PUEDE:
DEBE PARAR ANTES DE:
EVIDENCIA QUE ENTREGARÁ:

La tarjeta obliga a expresar lo que un prompt abierto suele ocultar. Si no puedes completar reversión, oráculo o efectos externos, clasifica la tarea como ámbar hasta investigarla.

Ejemplo funcional: el mismo agente, dos márgenes distintos

Un timeout configurable puede ser verde; una política de reintentos de pagos debe empezar en rojo. La diferencia no está en la dificultad aparente, sino en el efecto de equivocarse.

Caso verde: timeout de un cliente FastAPI

El cambio añade una variable de entorno, conserva el valor anterior como predeterminado y modifica una prueba unitaria. El agente puede editar y validar con pytest tests/unit/test_client.py -q. Debe entregar el diff y la salida del test, pero no necesita parar tras cada archivo.

Con Claude Code, un punto de partida concreto es claude --permission-mode acceptEdits. Con Codex, usa codex --sandbox workspace-write --ask-for-approval on-request. Mantén bloqueados red, secretos y rutas fuera del workspace.

Caso rojo: reintentos de un webhook de pagos

Aunque el parche ocupe pocas líneas, un reintento incorrecto puede duplicar una operación externa. Si también incluye una migración para registrar intentos, el rollback del código no restaura por sí solo el estado de los datos.

Empieza con claude --permission-mode plan o codex --sandbox read-only --ask-for-approval on-request. Exige al plan idempotencia, migración reversible, prueba con dobles del proveedor y procedimiento de recuperación. La ejecución contra infraestructura queda fuera del margen del agente.

Los checkpoints fallan si solo preguntan continuar

Un checkpoint sin evidencia preparada suele aportar menos control y puede limitarse a una pausa formal. La revisión debe recibir información suficiente para tomar una decisión sin reconstruir toda la sesión.

Clasificar por número de archivos: dos líneas en autorización pueden tener más impacto que un refactor de veinte archivos.
Permitir que el agente se apruebe: puede sugerir el nivel, pero un conflicto de interés aparece si también decide que su resultado cumple.
Mostrar solo un resumen: exige diff, comandos, resultados y riesgos pendientes. El resumen narrativo puede omitir el detalle que importa.
Ejecutar CI privilegiada sin revisar: GitHub recuerda que los workflows pueden acceder a secretos y recomienda inspeccionar los cambios antes de autorizarlos en pull requests creadas por agentes. Consulta su guía oficial para revisar la salida de Copilot.
Relajar todo tras un bloqueo: autoriza la operación concreta o cambia el plan. No conviertas una excepción en permiso global.

La revisión humana tampoco debe buscar cada posible bug desde cero. Una revisión de código con IA bien repartida usa automatización para reunir evidencia y reserva la decisión humana para intención, contratos y riesgo residual.

Cuándo esta matriz no aplica

No necesitas el ritual completo para código desechable dentro de un entorno aislado. Un prototipo local sin credenciales, datos reales, red ni intención de integrarse puede trabajar con autonomía amplia, siempre que eliminar el entorno sea una recuperación suficiente.

En el extremo contrario, la matriz tampoco basta para software regulado, sistemas con impacto físico o procesos que exigen separación formal de funciones. Ahí necesitas controles organizativos, auditoría, revisores autorizados y políticas de despliegue externas al agente.

Si el agente navega, consume issues o usa herramientas MCP, la clasificación de autonomía no reemplaza la defensa frente a contenido hostil. Aplica por separado una defensa por capas contra prompt injection.

Por regla general, un incidente urgente no justifica permisos globales; cualquier acceso de emergencia debe ser temporal, aislado y auditado. Reduce el alcance, trabaja en una rama, conserva un rollback probado y aumenta la frecuencia de checkpoints. La presión temporal hace más valiosa una puerta clara, no menos.

Preguntas frecuentes

¿Qué diferencia hay entre un sandbox y un checkpoint humano?

El sandbox limita qué recursos puede tocar el coding agent. El checkpoint decide si el cambio propuesto merece continuar según intención, impacto y evidencia. Necesitas ambos cuando una acción técnicamente permitida sigue teniendo riesgo de negocio.

¿Debe un coding agent hacer merge por sí solo?

En repositorios compartidos, conviene reservar el merge autónomo para cambios verdes con validaciones deterministas y protecciones de rama externas. Para cambios ámbar o rojos, separa la generación del parche de la aprobación e integración.

¿Cómo clasifico un cambio pequeño que modifica autenticación?

Como rojo. El tamaño del diff no reduce el alcance semántico de una decisión de autenticación, autorización o gestión de secretos.

El margen correcto importa más que el modo automático

Un coding agent no necesita libertad total ni confirmaciones constantes. Necesita una frontera distinta para cada cambio: verde cuando puede demostrar y revertir, ámbar cuando debe acordar el plan y rojo cuando aparecen datos, seguridad o efectos externos. La idea que conviene recordar es simple: como regla práctica, detén al agente antes del primer punto donde un error deje de resolverse de forma fiable con un revert.

Coding agent sin freno: presupuesta intentos, no tokens

Sergio Márquez — Fri, 03 Jul 2026 08:00:01 GMT

Coding agent sin freno: presupuesta intentos, no tokens

TL;DR: Reducir el contexto por sí solo no suele corregir un agente que encadena búsquedas, cambios y pruebas sin una condición de parada. Aprenderás a asignar turnos, tiempo y una validación externa según el riesgo de la tarea, con un contrato copiable y un runner en Python.

El instinto lógico que optimiza la métrica equivocada

Ya tienes el dedo encima de recortar el prompt o cambiar de modelo. Parece lógico: si la sesión consume demasiado, cada llamada debe ser más pequeña o barata. El problema aparece cuando el gasto nace del número de intentos, no del tamaño inicial del contexto.

Un coding agent suele recorrer un bucle: inspecciona, propone, edita, ejecuta una herramienta, interpreta el resultado y vuelve a intentarlo. En muchos agentes, cada follow-up incorpora parte del historial anterior. Un comando irrelevante no solo consume una llamada: añade resultados que condicionan las siguientes decisiones.

Quitar contexto a ciegas puede empeorar ese bucle. El agente vuelve a buscar lo que ya no recuerda, repite comandos o edita el archivo equivocado. Si tu problema está en la caché, conviene tratarlo como explica esta guía para recortar tokens sin romper el cache hit rate. Aquí la pregunta es distinta: ¿cuánto trabajo puede intentar antes de detenerse?

Un presupuesto de esfuerzo para un coding agent es un contrato que limita turnos y tiempo, define una prueba de aceptación externa y obliga a parar cuando la tarea deja de progresar. No mide cuánto habla el agente, sino cuánto margen recibe para entregar un resultado verificable.

Mide intentos antes de tocar el presupuesto

La unidad útil es la tarea terminada dentro del límite. Los tokens siguen importando para facturación y capacidad, pero no indican por sí solos si el agente avanzó.

A 03/07/2026, las métricas oficiales de GitHub Copilot CLI separan prompt_count, que cuenta entradas humanas, de request_count, que también incluye llamadas agénticas automáticas. También publican tokens de entrada, salida y media por solicitud mediante API. La definición exacta está en la documentación oficial de métricas de Copilot.

Con esos campos puedes calcular este indicador diagnóstico:

follow_up_ratio = (request_count - prompt_count) / max(prompt_count, 1)

Un valor alto no demuestra desperdicio. Una migración transversal suele necesitar más comprobaciones que un cambio de texto localizado. Sirve para localizar clases de tareas donde crecen los intentos sin mejorar el resultado.

Éxito dentro del presupuesto: tareas cuyo gate pasa antes del límite dividido entre tareas iniciadas.
Agotamiento: tareas que llegan al límite sin pasar el gate.
Tiempo hasta verificación: desde el prompt hasta la ejecución externa satisfactoria.
Motivo de parada: éxito, timeout, límite de turnos, permiso o bloqueo técnico.

Separa estas métricas de la elección comercial del modelo. Para esa decisión ya tienes un marco centrado en coste real y evaluaciones propias.

La regla: autonomía solo con salida verificable

Si existe un gate determinista y el alcance está localizado, asigna un límite y deja ejecutar al agente. Si la aceptación depende de criterio humano o el cambio amplía su radio de acción, pide primero un plan.

La política concreta es esta:

Si el agente puede demostrar el resultado con tests, lint, compilación o una consulta de solo lectura, autoriza ejecución acotada.
Si toca autenticación, permisos, datos, migraciones o contratos públicos, exige plan y aprobación antes de editar.
Si agota el presupuesto, no dupliques el límite automáticamente. Conserva diff, salida del gate y bloqueo, y decide si debes dividir la tarea o intervenir.

Esta separación entre planificar, modificar y verificar aplica el mismo principio que la separación de responsabilidades en arquitectura: una capa propone el cambio y otra determina si cumple el contrato.

Los números siguientes son umbrales prácticos iniciales, no resultados de un benchmark. Ajústalos con tus propias tareas.

Clase de tarea	Cuándo usar autonomía	Presupuesto inicial	Gate obligatorio	Cuándo evitarla
Documentación o formato	Archivos conocidos y alcance cerrado	3 turnos, 5 minutos	Lint o build de documentación	Contenido sujeto a aprobación legal
Bug localizado	Fallo reproducible y test existente	6 turnos, 15 minutos	Test que reproduce el fallo y suite relacionada	No existe reproducción estable
Refactor de módulo	Contrato público estable	10 turnos por hito	Tests, tipos y diff limitado	Afecta varios dominios sin hitos separables
Migración o seguridad	Tras revisar un plan y una estrategia de reversión	Presupuesto por fase	Validación específica y revisión humana	Incidente activo o impacto desconocido

Artefacto: contrato de esfuerzo para cada tarea

Copia esta ficha en tu issue, job de CI o comando interno. Evita que “terminar” signifique lo que el agente decida al final de la sesión.

TASK: [cambio concreto]
SCOPE: [archivos o módulo permitido]
ACCEPTANCE_GATE: [comando determinista]
MAX_TURNS: [límite de iteraciones]
TIMEOUT_SECONDS: [límite de reloj]
STOP_IF: [condiciones que requieren ayuda]
ON_EXHAUSTION: devolver diff + gate output + blocker
FORBIDDEN: [datos, comandos o rutas fuera de alcance]

Ejemplo: corregir la serialización de fechas en src/orders/, ejecutar pnpm test -- orders, parar si exige modificar el esquema de base de datos y devolver evidencias si no pasa tras seis turnos.

Claude Code ofrece --max-turns en modo no interactivo y salida JSON, según su referencia oficial de CLI. El límite de turnos no sustituye al timeout ni comprueba que el resultado sea correcto.

Qué hace: este wrapper limita los turnos y el tiempo, y después ejecuta el gate fuera del agente para no aceptar su propia declaración de éxito.

import os, shlex, subprocess

task = os.environ["AGENT_TASK"]
gate = os.environ["AGENT_GATE"]
turns = os.getenv("AGENT_MAX_TURNS", "6")
timeout = int(os.getenv("AGENT_TIMEOUT_SECONDS", "900"))
prompt = f"{task}\nAcceptance gate: {gate}\nStop and report blockers if it still fails."
agent = subprocess.run(["claude", "-p", "--max-turns", turns, "--output-format", "json", prompt], capture_output=True, text=True, timeout=timeout)
verification = subprocess.run(shlex.split(gate), timeout=timeout)
print(agent.stdout)
raise SystemExit(agent.returncode or verification.returncode)

Ejecútalo con AGENT_TASK='Corrige la serialización de fechas en src/orders' AGENT_GATE='pnpm test -- orders' python run_agent.py. shlex.split ejecuta comandos simples sin operadores de shell; para pipelines, usa un script versionado como gate.

Ajusta el presupuesto con tareas comparables

No uses una media global para todo el repositorio. Agrupa las ejecuciones por clase: documentación, bug localizado, refactor, dependencia o migración.

Como umbral práctico propio, reúne entre 20 y 50 tareas por clase antes de endurecer una política compartida. Registra el presupuesto inicial y no lo cambies durante esa muestra. Después revisa:

Si el gate pasa pronto de forma consistente, reduce el límite de esa clase.
Si muchas tareas llegan al límite con el mismo bloqueo, mejora el contexto, los permisos o la reproducibilidad antes de comprar más esfuerzo.
Si los fallos son heterogéneos, divide la categoría: “bug con test” y “bug sin reproducción” no deberían compartir presupuesto.
Si subir turnos mejora el éxito pero también amplía diffs y revisiones, introduce hitos más pequeños.

El presupuesto pertenece al flujo, no a la marca de la herramienta. Si aún estás decidiendo qué CLI encaja con tu repositorio, utiliza un mini-eval ejecutado sobre tareas reales del repo y añade el agotamiento del presupuesto como señal.

Fallos típicos al llevarlo a producción

Un límite mal diseñado puede limitarse a convertir un fallo silencioso en uno rápido. Revisa estos puntos antes de automatizarlo en CI:

Gate débil: “el diff parece correcto” no es verificable. Usa un comando con código de salida y conserva su salida.
Timeout ausente: un único test bloqueado puede consumir el job aunque el agente no complete otro turno.
Reintento ciego: relanzar el mismo prompt tras agotar el límite suele repetir la estrategia. La siguiente ejecución debe recibir el bloqueo o una tarea más pequeña.
Presupuesto compartido: una corrección local y una migración transversal no compran el mismo trabajo con seis turnos.
Logs sensibles: elimina secretos y datos personales antes de almacenar prompts, salidas de herramientas o diffs.
Gate controlado por el agente: vuelve a ejecutar la validación desde el wrapper o CI. No aceptes únicamente el resumen final.

Registra también la versión de la CLI y la configuración del agente. GitHub incluye la versión conocida de Copilot CLI en sus informes por usuario, lo que ayuda a distinguir una regresión del flujo de un cambio de cliente.

Cuándo no aplica este presupuesto

No todo trabajo de desarrollo debe convertirse en una ejecución cerrada. Este enfoque pierde utilidad cuando no puedes expresar todavía qué significa terminar.

Escenario	Por qué no aplica	Alternativa
Exploración arquitectónica	La salida es una decisión, no un gate binario	Sesión interactiva con opciones y trade-offs
Incidente en producción	El estado puede cambiar mientras el agente investiga	Humano al mando, herramientas de solo lectura y checkpoints
Refactor transversal sin tests	El agente puede finalizar sin detectar regresiones	Crear primero caracterización y dividir por contratos
Pair programming	El humano puede corregir el rumbo durante la ejecución	Límite de tiempo de sesión, no de turnos

Un plan de suscripción con coste fijo tampoco elimina el problema. Aunque una ejecución adicional no produzca un cargo directo, puede consumir tiempo de CI, atención de revisión o capacidad limitada de uso. El objetivo del contrato es controlar trabajo sin evidencia, no perseguir el token más barato.

Preguntas frecuentes

¿Un turno equivale a una llamada al modelo?

No en todas las herramientas. Usa la definición y telemetría de tu CLI; el presupuesto necesita una unidad que el runtime pueda detener, no una equivalencia universal.

¿Debo subir el límite cuando el agente falla por un turno?

Solo si el diff y la salida del gate muestran progreso concreto. Si repite búsquedas, comandos o errores, divide la tarea o corrige el contexto antes de conceder más intentos.

¿El límite de turnos sustituye al control de coste?

No. Los turnos acotan autonomía; los tokens, precios y cuotas controlan consumo. Necesitas ambos controles cuando pagas por uso, pero cada uno responde a un fallo diferente.

El criterio que conviene recordar

Un coding agent merece más autonomía cuando puedes verificar su salida, no cuando todavía queda presupuesto. Define el gate, asigna turnos y tiempo según el riesgo, y convierte el agotamiento en una escalada con evidencias. Si no sabes cómo demostrar que la tarea ha terminado, aún no está lista para ejecutarse sin supervisión.

Tus 20 € pueden rendir distinto en Cursor, Claude Code o Codex según tu flujo y tus límites

Sergio Márquez — Thu, 02 Jul 2026 08:00:01 GMT

Tus 20 € pueden rendir distinto en Cursor, Claude Code o Codex según tu flujo y tus límites

TL;DR: compara capacidad, no cuotas

Cursor, Claude Code y Codex cuestan una cantidad parecida sobre el papel, pero limitan el uso con unidades distintas. Aprenderás a elegirlos midiendo tareas aceptadas, consumo proyectado, bloqueos y sobrecostes mediante una plantilla de siete días.

El mismo precio no compra la misma capacidad

Ya tienes el dedo encima de contratar el que prometa más modelos o solicitudes. Parece lógico, pero compara etiquetas que no representan la misma unidad de trabajo.

Cursor descuenta el uso del agente según los tokens y el precio del modelo. Claude aplica límites por sesión y semana. Codex utiliza créditos vinculados a tokens y comparte parte de su capacidad con otras funciones agénticas. Una solicitud que corrige una línea no consume lo mismo que una migración que lee veinte archivos y ejecuta pruebas.

La capacidad útil de un asistente de código es la cantidad de trabajo aceptable que completa dentro del presupuesto y del horario en que lo necesitas, después de descontar reintentos, esperas por límites y gasto extra. No equivale a mensajes, tokens ni acceso nominal a un modelo.

Si buscas comparar calidad sobre tu código, necesitas un mini-eval construido con tareas de tu repositorio. Aquí la pregunta es distinta: qué plan sostiene mejor tu ritmo de trabajo sin bloquearte.

Qué compras con un presupuesto de 20 €

No suele haber un ganador universal porque cada proveedor coloca el cuello de botella en un sitio diferente. Los importes finales en España dependen de moneda local, impuestos y checkout. Trata los 20 € como techo operativo, no como precio contractual exacto.

Herramienta	Cómo limita el uso	Cuándo usar	Cuándo evitar
Cursor Pro	Presupuesto mensual de agente calculado según la inferencia del modelo. Incluye autocompletado Tab sin límite y muestra tokens y consumo en el panel, según su documentación de precios.	Trabajas dentro del editor y aceptas muchas completions pequeñas.	Tu trabajo depende de agentes largos o cloud agents que agotan pronto la bolsa mensual.
Claude Code con Pro	Claude Code y Claude comparten límites. La capacidad se reinicia en ventanas de cinco horas y también existe un límite semanal, según Anthropic.	Tu flujo es terminal-first y concentras tareas relacionadas en sesiones continuas.	Necesitas ráfagas largas justo antes de una entrega o consumes Claude web durante la misma semana.
Codex con Plus	Codex está incluido en Plus y utiliza un sistema de créditos basado en tokens de entrada, caché y salida. El consumo cuenta dentro del límite agéntico compartido, según la tarifa oficial de Codex.	Combinas CLI, extensión, web y tareas delegadas, y también valoras ChatGPT.	Necesitas una cantidad fija de tareas mensuales: el coste varía con contexto, salida y modo rápido.

La lista de modelos cambia antes que tu forma de trabajar. Cursor ofrece modelos de varios proveedores, Claude Code muestra los disponibles con /model y Codex distingue entre varios modelos y modos de consumo. Elegir por catálogo caduca rápido.

La regla de decisión: protege tus tareas críticas

Elige el plan que complete tus tareas de prioridad alta y conserve margen de capacidad, no el que produzca más interacciones.

Si predominan las completions aceptadas dentro del editor, empieza por Cursor.
Si predominan cambios multiarchivo operados desde terminal y caben en tus ventanas de trabajo, empieza por Claude Code.
Si delegas tareas en distintas superficies y ya obtienes valor de ChatGPT, empieza por Codex.
Si ningún candidato completa las tareas críticas sin gasto extra, el nivel base no compensa. Usa pago por uso con un límite estricto o sube de nivel durante el mes de carga.

Esta separación entre autocompletado, ejecución agéntica y validación sigue el mismo criterio que la separación de responsabilidades en arquitectura: no puntúes como equivalentes componentes que resuelven problemas distintos.

Como desempate, selecciona primero el menor tiempo bloqueado y después el menor coste por tarea aceptada. No uses el número de mensajes, porque una sesión larga reenvía contexto y consume más capacidad. Para controlarlo, aplica las técnicas de recorte de tokens sin destruir la caché.

Artefacto: auditoría de capacidad durante siete días

Copia esta plantilla y rellénala al terminar cada jornada. Siete días y un margen del 20 % son umbrales prácticos propios, no garantías de los proveedores.

Campo	Valor	Cómo obtenerlo
Herramienta y plan	_____	Registra también el modelo utilizado.
Días activos observados	_____	Cuenta solo días con trabajo agéntico.
Tareas simples aceptadas, peso 1	_____	Cambio validado sin rehacerlo.
Tareas medias aceptadas, peso 2	_____	Cambio multiarchivo con pruebas superadas.
Tareas críticas aceptadas, peso 3	_____	Entrega prioritaria integrada o lista para revisión.
Consumo del límite	_____ %	Cursor: Usage. Claude: Settings > Usage. Codex: Settings > Usage.
Minutos bloqueados	_____	Espera por reset, rate limit o falta de crédito.
Gasto extra	_____ €	Créditos, API o uso bajo demanda.

Trabajo ponderado = simples + 2 × medias + 3 × críticas.

Consumo mensual proyectado = porcentaje consumido ÷ días observados × días activos previstos. Para Claude, registra por separado el peor consumo en una ventana de cinco horas y el consumo semanal.

Ejemplo ficticio: si un candidato consume el 38 % en cinco días y prevés veinte días activos, proyecta un 152 %. Aunque termine todas las tareas iniciales, el plan base queda descartado.

Decisión: descarta cualquier opción que falle una tarea crítica o proyecte más del 80 % del límite. Entre las restantes, calcula (cuota + gasto extra) ÷ trabajo ponderado y elige el menor resultado.

Los fallos que distorsionan la medición

Una auditoría compara mejor si contabiliza el trabajo invisible. Estos fallos hacen que una suscripción parezca más capaz de lo que es:

Contar código generado en vez de código aceptado. Una respuesta descartada consume capacidad y entrega cero trabajo.
Ignorar los pools compartidos. Claude y Claude Code consumen el mismo límite en planes individuales. Codex comparte su uso agéntico con otras funciones compatibles, según la documentación de OpenAI.
Mezclar tareas nuevas en una conversación larga. El historial vuelve a entrar en contexto. Puedes probar /clear al cambiar de tarea y /compact para continuar una sesión.
Olvidar agentes en segundo plano. Si usas los background agents de Cursor, comprueba si generan consumo adicional según el modelo y configura un límite de gasto.
Activar sobrecostes sin tope. El bloqueo desaparece, pero también la comparabilidad del plan.

Si el modelo elegido es el causante del consumo, no cambies de herramienta todavía. Aplica primero un criterio de coste por tarea evaluada.

Cuándo esta regla no aplica

El coste por tarea deja de mandar cuando existen restricciones de seguridad, administración o disponibilidad.

Equipos con SSO, auditoría o controles de retención: compara planes de equipo, no suscripciones individuales.
Código regulado o repositorios no autorizados: el proveedor aprobado gana aunque su capacidad medida sea inferior.
Uso muy irregular: una API con presupuesto máximo puede encajar mejor que una cuota fija. La opción BYOK en VS Code permite separar editor y facturación.
Una herramienta también sustituye otro servicio: si utilizas Claude o ChatGPT para investigación, documentación o análisis, atribuye ese valor fuera de la métrica de programación.

Tampoco extrapoles una semana de mantenimiento a un mes de migración. Repite la auditoría cuando cambie el tipo de trabajo, el modelo predeterminado o la política de límites.

Preguntas frecuentes

¿Cuál rinde más, Cursor, Claude Code o Codex?

Cursor suele encajar mejor en flujos centrados en el editor, Claude Code en sesiones de terminal y Codex cuando combinas varias superficies con ChatGPT. El ganador para tu caso es el que completa las tareas críticas sin superar el 80 % de capacidad proyectada.

¿Puedo comparar los planes por número de solicitudes?

No de forma fiable. Cada solicitud consume una cantidad distinta según modelo, contexto, herramientas y salida, y los proveedores aplican ventanas o créditos diferentes.

¿Compensa pagar dos herramientas?

Sí, cuando resuelven cuellos de botella distintos y la segunda reduce más tiempo bloqueado que su coste. No compensa contratar dos agentes para el mismo flujo sin haber medido primero cuál queda infrautilizado.

Qué debes recordar antes de renovar

Una cuota igual no implica una capacidad igual. Decide con tareas aceptadas, consumo proyectado y minutos bloqueados. Si el plan falla una entrega crítica o rebasa tu margen antes de terminar el ciclo, no rinde para tu workflow, aunque su catálogo de modelos parezca mejor.

Recorta tokens del agente sin romper tu cache hit rate

Sergio Márquez — Wed, 01 Jul 2026 08:00:01 GMT

Recorta tokens del agente sin romper tu cache hit rate

TL;DR: La factura de tu agente de código no la fija el precio por token, la fija tu cache hit rate. Comprimir el output de comandos (con un proxy tipo rtk o un hook) ahorra tokens sin riesgo porque toca la cola volátil del contexto. Reescribir el prefijo estable (system prompt, CLAUDE.md a mitad de sesión, reordenar el historial) invalida la caché de prompts, y un cache miss cuesta hasta 12,5 veces más que un hit. Aquí tienes la tabla de palancas, el árbol de decisión y qué mirar en /cost.

El instinto: instalo rtk y ya ahorro

Ves la factura del agente subir, alguien menciona que rtk reduce el consumo de tokens un 60-90% y ya tienes el dedo encima del brew install. Bien. Pero si tu plan mental es "recorto todo lo que pueda del contexto y cuanto menos texto viaje, menos pago", vas a optimizar la palanca equivocada y, en el peor caso, a subir la factura mientras crees que la bajas.

El motivo es técnico y concreto: no todos los tokens de entrada cuestan lo mismo. Un token que se reprocesa desde cero cuesta el precio de entrada completo. Uno que se recupera de la caché de prompts cuesta la décima parte. Según la documentación de prompt caching de Anthropic, un cache read se factura a 0,1x del precio base de entrada, un cache write de 5 minutos a 1,25x y uno de 1 hora a 2x. Traducido: cachear no es un detalle de infra, es la variable que decide tu gasto.

El cache hit rate es el porcentaje de tokens de entrada que tu agente recupera de la caché en lugar de reprocesar; como un hit cuesta el 10% del precio de entrada, ese ratio, y no el precio por token, decide tu factura mensual.

Por qué el recorte agresivo puede salir caro

Claude Code y la mayoría de CLIs de código reenvían un prefijo estable en cada turno: system prompt, tu CLAUDE.md, instrucciones, historial temprano. Ese prefijo es exactamente lo que se cachea. Y el cache exige coincidencia exacta del prefijo: si modificas aunque sea una coma antes del último bloque marcado con cache_control, no hay hit y toca reescribir toda la caché desde ese punto.

Haz la cuenta con Opus 4.8 (5 $/MTok de entrada). Un cache read sale a 0,50 $/MTok; reestablecer esa caché con un write de 5 minutos, a 6,25 $/MTok. Eso son 12,5 veces más caro por los mismos tokens. Si tu "optimización" consiste en resumir el historial o reordenar mensajes a mitad de sesión para ahorrar 300 tokens, y al hacerlo invalidas un prefijo cacheado de 25.000 tokens, acabas de cambiar un ahorro de céntimos por un recargo de varios euros repetido en cada turno posterior.

La distinción que casi nadie hace: recortar hacia la cola es seguro, reescribir hacia la cabeza es caro. rtk no rompe nada porque comprime el output de los comandos (un cargo test de 155 líneas reducido a 3) que entra al final del contexto. El peligro no es rtk: es la compactación manual del prefijo estable.

La regla de decisión y las tres palancas

La regla, mojada: comprime todo lo que viva en la cola volátil del contexto y no toques nunca el prefijo cacheado. Si el texto que ibas a recortar está antes del último punto de caché, déjalo; lo que ahorras en tokens lo pagas multiplicado en cache misses.

Palanca	Qué toca	Impacto en factura	Riesgo
Comprimir output de tools (rtk, hook de Bash)	Cola volátil (resultados de `git`, tests, logs)	Medio-alto	Bajo: no toca la caché. Vigila que no borre la línea de error que importa
Maximizar cache hit rate (prefijo estable)	System prompt, CLAUDE.md, historial temprano	Alto	Romperlo cuesta hasta 12,5x. No edites CLAUDE.md ni reordenes a mitad de sesión
Compactación agresiva del historial (auto-compact, resumir)	Todo el contexto, incluido el prefijo	Alto en tokens brutos	Alto: invalida caché y puede perder contexto, degradando correctness
Enrutar por modelo (Haiku 4.5 para tareas triviales)	La petición entera	Alto en tareas simples	Bajo si evalúas: Haiku a 1 $/MTok vs Opus a 5 $/MTok

Árbol de decisión rápido

¿El texto está antes del último bloque de caché? No lo toques. Recortarlo rompe el hit.
¿Es output volátil de un comando o tool? Comprímelo con rtk o un hook. Suma seguro.
¿Estás cruzando los 200.000 tokens de entrada? El problema ya no es el recorte de output: por encima de ese umbral se disparan las tarifas de contexto largo. Ahí toca dividir la tarea o dar memoria persistente al agente sin inflar el contexto, no exprimir un git status.

Cómo medir tu gasto real (antes de tocar nada)

No optimices a ciegas. En Claude Code, /cost desglosa cache read, cache creation e input por sesión. La señal que importa:

Cache read debe dominar sobre cache creation. Si la creación de caché sube turno a turno en vez de estabilizarse, algo está invalidando tu prefijo (probablemente una edición o un reordenamiento).
Compara antes/después. rtk expone rtk gain para ver el ahorro real de output. Un número concreto vale más que la sensación de "va más ligero".
Blinda correctness. Todo recorte es una apuesta a que no borras nada útil. Pasa un eval mínimo en producción con y sin compresión antes de dejarlo fijo. Si el agente empieza a pedir el mismo comando dos veces porque la salida comprimida le quitó contexto, has ahorrado tokens y perdido dinero en reintentos.

Cuándo NO aplica

Esta lección es sobre facturación por token, así que hay contextos donde no se sostiene:

Suscripción plana (Claude Pro/Max). Si pagas 20 $ fijos no facturas por token; ahí rtk no te ahorra euros, te alarga sesiones y te aleja del rate limit. El cálculo de 12,5x deja de importar.
Tareas cortas de una sola pasada. Un cache de 5 minutos no se amortiza si no repites el prefijo. No te compliques con caching manual para un one-shot.
Tu cuello de botella es el output. El prompt caching no toca los tokens de salida. Si generas respuestas largas, la palanca no es cachear sino elegir el modelo por coste real y ajustar el nivel de esfuerzo.

Y un matiz sobre agentes de larga duración: en tareas de horas, la tentación de compactar el historial es enorme, pero es justo cuando más caro sale romper la caché. Ahí la respuesta es gestionar el estado fuera del contexto, no aplastarlo dentro. Es el mismo problema de fondo que hace que los agentes long-horizon se pierdan en tareas largas.

Preguntas frecuentes

¿rtk rompe el cache hit rate de Claude Code?

No, porque comprime el output de comandos que entra al final del contexto, no el prefijo estable que se cachea. El hook de rtk solo actúa sobre llamadas de la herramienta Bash; el system prompt y tu CLAUDE.md quedan intactos, así que los cache hits se mantienen. El riesgo de romper la caché viene de reescribir manualmente el prefijo, no de rtk.

¿Cuánto ahorro de verdad con prompt caching?

Un cache read cuesta 0,1x el precio de entrada base, así que un prefijo repetido baja un 90% en la parte cacheada. Con un 70% de cache hit rate, la mayoría de tus tokens reenviados cuestan una décima parte. El caching se amortiza tras un solo hit con el cache de 5 minutos, o dos hits con el de 1 hora.

¿Qué miro primero para bajar la factura de mi agente?

El cache hit rate en /cost, no el precio por token del modelo. Si tu cache creation crece cada turno, estás invalidando el prefijo y pagando writes repetidos: eso pesa más que cualquier compresión de output. Estabiliza el prefijo primero, comprime la cola después.

El takeaway

La factura de un agente de código se decide en un sitio contraintuitivo: no en el precio por token que anuncia el modelo, sino en qué porcentaje de tu contexto viaja por la vía barata de la caché. Recortar output volátil es dinero gratis. Reescribir el prefijo estable para ahorrar unos tokens es cambiar céntimos por euros, turno tras turno. La pregunta útil no es "¿cómo mando menos texto?", sino "¿qué de lo que mando puedo recuperar de la caché en vez de reprocesar?".

Tu CLI de coding se elige con tu repo, no con Terminal-Bench

Sergio Márquez — Sun, 28 Jun 2026 08:00:01 GMT

Tu CLI de coding se elige con tu repo, no con Terminal-Bench

TL;DR: El CLI de coding que encabeza Terminal-Bench esta semana no es necesariamente el mejor para tu código. El ranking mide tareas que no son las tuyas, y hasta 7 puntos de diferencia entre agentes vienen del harness, no del modelo. La decisión fiable es montar un mini-eval reproducible de 10-20 tareas reales de tu propio repo con criterio paso/no-paso. Aquí tienes la plantilla copiable y la regla para decidir si una suscripción te basta o necesitas dos.

El instinto: abrir el leaderboard y pagar al número uno

Ya tienes el dedo encima de cambiar de suscripción. Sale una comparativa nueva, ves que Codex CLI con GPT-5.5 lidera Terminal-Bench 2.1 con un 83,4% frente al 78,9% de Claude Code con Opus 4.8 (leaderboard de mediados de junio 2026), y la conclusión parece obvia: migrar al que puntúa más alto.

Ese instinto falla por un motivo técnico concreto, no por filosofía. Un benchmark agéntico mide el acierto medio sobre un set de tareas fijo y genérico: administración de sistemas, entrenar modelos, optimizar queries. Terminal-Bench 2.1 son 89 tareas en un entorno sandbox (según la nota oficial de la 2.1). Ninguna de esas 89 tareas es tu monorepo de FastAPI con 40 servicios, tu convención de imports ni tu suite de tests que tarda seis minutos. El número agrega un universo de tareas que no se parece al tuyo.

Hay un segundo problema que casi nadie mira: el harness pesa tanto como el modelo. El mismo GPT-5.5 puntúa 83,4% dentro de Codex CLI y baja a 76,4% ejecutado a través del harness Terminus 2 sobre el mismo benchmark (análisis de junio 2026). Son 7 puntos que no tienen nada que ver con el modelo y todo con el bucle de agente que lo envuelve: cómo gestiona contexto, reintentos y uso de herramientas. Elegir "el modelo del ranking" ignora que estás comprando un harness, no solo pesos.

Un benchmark de coding agéntico mide el acierto medio sobre tareas ajenas; tu decisión depende del acierto sobre las tuyas y del harness que las ejecuta.

La regla de decisión: tu repo es el único benchmark que cuenta

La regla, mojada: si vas a pagar o cambiar de CLI, primero corre 10-20 tareas reales de tu repo en cada candidato y compara acierto, coste y latencia por tarea. Si el ganador del leaderboard no gana en tu mini-eval, no migres. El benchmark público sirve principalmente para descartar (un agente que va 15 puntos por debajo en todo raramente te sorprenderá), no para elegir entre los de cabecera, que en junio 2026 están a 13,7 puntos entre el primero y el sexto (leaderboard de Terminal-Bench 2.1).

Esto conecta con una idea que ya tratamos al hablar de por qué los benchmarks de coding agéntico te hacen elegir mal el modelo: el problema no es el benchmark, es usarlo fuera de su contexto. Y enlaza con la disciplina de medir tu IA en producción y no solo offline: un eval propio es eso mismo aplicado a tu flujo de desarrollo.

El artefacto: plantilla de mini-eval para tu codebase

Define cada tarea con estos campos. La clave está en el criterio paso/no-paso binario y verificable sin opinión: o el test pasa, o no.

# mini-eval.yaml — 10-20 tareas reales de tu repo
- id: bugfix-01
  tipo: bugfix              # bugfix | feature | refactor | test | búsqueda
  prompt: "El endpoint /users/{id} devuelve 500 con id inexistente. Arréglalo."
  criterio_paso: "pytest tests/test_users.py::test_not_found pasa en verde"
  ground_truth: "Devuelve 404 con cuerpo {detail: 'not found'}"
  max_intentos: 1           # un solo turno, sin guiarlo a mano

- id: feature-02
  tipo: feature
  prompt: "Añade paginación cursor-based al listado de pedidos."
  criterio_paso: "tests nuevos pasan Y respeta el patrón de pagination.py existente"
  ground_truth: "Usa el helper Cursor ya presente, no reinventa"
  max_intentos: 1

Reparte las tareas según tu trabajo real, no a partes iguales: si el 70% de tu día es arreglar bugs y añadir endpoints pequeños, que el 70% del eval sea eso. Y mide tres columnas por candidato, no una:

Métrica	Cómo medirla	Por qué importa
Acierto	% de tareas que pasan al primer intento	Es tu SWE-bench privado; lo único que mide tus tareas
Coste/tarea	Tokens o créditos consumidos por tarea resuelta	Un acierto del 90% que quema el límite semanal en dos días no sirve
Latencia/tarea	Minutos hasta resultado verificable	En un monorepo grande, el contexto enorme dispara la espera
Fidelidad al repo	¿Respeta convenciones o reinventa?	El coste oculto es la revisión, no la generación

El score que decide no es el acierto pelado. Una fórmula práctica para puntuar cada candidato:

# Pondera acierto por el coste de revisar lo que genera
# (un agente que acierta el 70% pero hay que revisar todo puede salir más caro que hacerlo tú)
def score(aciertos, total, min_revision_media, min_tarea_manual):
    tasa = aciertos / total
    # ahorro neto = tiempo manual evitado menos tiempo de revisión
    ahorro = tasa * (min_tarea_manual - min_revision_media)
    return round(ahorro, 1)  # minutos netos ahorrados por tarea; si es <=0, no compensa

Si el score sale en negativo o cero, ese CLI te está costando tiempo, no ahorrándotelo, por mucho que lidere Terminal-Bench. Este es el punto que un tutorial genérico no te da: un agente que acierta el 70% puede costarte más en revisión que hacer la tarea tú mismo.

¿Una suscripción o dos? La regla del 90%

La pregunta práctica de fondo suele ser si merece la pena pagar dos CLIs. Regla: si un solo candidato cubre el 90% de tu mini-eval con score positivo, una suscripción basta; paga la segunda solo si el 10% restante son tareas frecuentes y caras donde el otro agente claramente gana.

Los precios a junio 2026 ayudan a calibrar (verifica siempre la página oficial, cambian cada mes):

Claude Code: va con suscripción de Anthropic, desde unos 20€/mes (Pro) hasta Max 5x (~100€) y Max 20x (~200€). Ojo al cambio del 15/06/2026: la automatización (Agent SDK, headless) pasó a un pool de créditos medidos a precio de API, separado del uso interactivo (detalle de pricing).
Codex CLI: incluido en ChatGPT Plus (~20€/mes) con GPT-5.5 como modelo por defecto y GPT-5.4 como alternativa (modelos disponibles en Codex); las features cloud (review en GitHub, Slack) piden tier superior.
Gemini CLI: el único con tier gratis usable (1.000 peticiones/día con modelos Flash), pero está siendo reemplazado por Antigravity CLI, con el tier individual de Gemini CLI cerrando el 18/06/2026 (comparativa con límites). Si dependes de él, planifica la migración.

Para afinar el lado del coste, el criterio de elegir por coste real y no por el benchmark y el de leer el benchmark antes de creértelo complementan este mini-eval: el eval te da el acierto en tu repo, esos te dan el marco de coste y lectura crítica del ranking.

Cuándo NO aplica este enfoque

El mini-eval no es gratis: construir 10-20 tareas con criterio verificable te lleva una tarde. No compensa si tu uso es esporádico (unas horas sueltas a la semana): ahí elige por tier gratis o por el que ya tengas y olvídate del ranking. Tampoco aplica si tu trabajo es muy exploratorio y poco repetitivo, porque un eval de tareas cerradas no captura "ayúdame a pensar esta arquitectura"; para eso, el criterio de razonamiento del agente pesa más que un test verde.

Y un matiz honesto: el mini-eval mide acierto en tareas que ya sabes verificar. No mide lo que un agente hace bien en lo que no anticipas, ni su comportamiento en sesiones largas, donde el harness y la gestión de contexto importan más que en tareas de un turno. Úsalo para decidir entre candidatos de cabecera, no como verdad absoluta.

Preguntas frecuentes

¿Cuántas tareas necesito en el mini-eval para que sea fiable?

Entre 10 y 20 tareas reales de tu repo es un umbral práctico (no una cifra estadística): suficiente para distinguir candidatos sin que montarlo se vuelva un proyecto. Por debajo de 10, el ruido de una tarea afortunada distorsiona; por encima de 20, el coste de mantenerlo supera el valor para una decisión de suscripción.

¿Por qué el modelo que gana en SWE-bench puede perder en mi repo?

Porque SWE-bench y Terminal-Bench miden tareas genéricas, no tu contexto. En un monorepo con contexto enorme, la gestión de contexto del harness y la latencia pesan más que el acierto medio publicado. Un modelo mejor en el ranking puede tardar más y respetar peor tus convenciones, que es donde se va el tiempo de revisión.

¿Vale la pena cambiar de CLI cada vez que sale un modelo nuevo?

No por defecto. Reutiliza tu mini-eval: cuando salga un modelo nuevo, córrelo contra tus 10-20 tareas. Si no mejora tu score actual de forma clara (no marginal), el coste de cambiar de flujo, atajos y configuración no compensa la mejora del leaderboard.

El takeaway

El ranking de turno caduca con la siguiente versión; tu mini-eval no, porque mide lo único que no cambia: tus tareas. La decisión práctica es invertir una tarde en 10-20 casos reales con criterio paso/no-paso, medir acierto, coste y latencia, y dejar que tu repo vote. Cuando el agente que lidera Terminal-Bench no gana en tu eval, ya sabes a quién creer.

Frena el prompt injection antes de dar herramientas a tu agente

Sergio Márquez — Sat, 27 Jun 2026 08:00:01 GMT

Prompt injection: por qué un buen system prompt no te salva

TL;DR: Un experimento público resistió más de 6.000 intentos de prompt injection sin filtrar el secreto, y la tentación es copiar su prompt de sistema y darte por seguro. Falla por un motivo técnico: el modelo no distingue de forma fiable instrucciones de datos, y 6.000 ataques de un solo disparo no prueban nada frente a un atacante con conversación. La defensa que aguanta en producción no es un prompt más estricto, es romper la trifecta letal: datos privados, input no confiable y vía de salida juntos. Aquí tienes la auditoría y el checklist para hacerlo.

El instinto: "con estas reglas en el system prompt, mi agente resiste"

Ya tienes el dedo encima de copiar el prompt de sistema del experimento de moda. El 26/06/2026 Simon Willison enlazó el experimento de Fernando Irarrázaval: un asistente llamado Fiu, con buzón de correo y un fichero secrets.env, retando a internet a sacarle el secreto. Más de 6.000 intentos, autoridad falsa, falsos audits de compliance, ingeniería social en cinco idiomas, alguien mandando 20 variantes en cuatro minutos. Cero fugas. Las reglas eran sencillas: nunca reveles secrets.env, no ejecutes código de los correos, no exfiltres datos a endpoints externos.

La lectura fácil es "con instrucciones claras y un modelo potente, el problema está resuelto". Y es justo la lectura que te mete en un incidente.

Por qué falla: el modelo no separa instrucciones de datos

El motivo es estructural, no de redacción del prompt. Un LLM procesa tokens, no etiquetas de confianza. Cuando tu agente lee un correo, una página web o un ticket, ese texto entra al mismo canal que tus órdenes de operador. Si el atacante escribe en cualquier superficie que el agente lee, puede intentar redirigir su comportamiento. OWASP clasifica la inyección de prompts como el riesgo número uno de aplicaciones LLM precisamente porque no es un bug que se parchee en la próxima versión del modelo.

Prompt injection es texto no confiable que tu agente interpreta como órdenes en lugar de como datos. Esa es la definición que importa: el problema nace en cuanto el agente tiene tanto contenido externo que leer como acciones reales que ejecutar.

El experimento aguanta por tres razones que el titular esconde, y conviene leerlas con cuidado antes de copiar nada:

El modelo importa, y no es el tuyo por defecto. Fiu corría sobre Claude Sonnet 4.6, un modelo que Anthropic entrenó específicamente para resistir injection. Reproducir el prompt con un modelo más débil o más barato no te da la misma resistencia.
Eran ataques de un solo disparo. Por límite de presupuesto el agente no respondía a cada correo. Como reconoce el propio autor, un ataque de 20 correos de ida y vuelta es mucho más peligroso que 20 intentos sueltos: la conversación deja al atacante sondear los límites.
La vía de exfiltración estaba cortada. El agente no tenía forma fácil de mandar el secreto fuera. Aunque una injection hubiera "convencido" al modelo, no había canal de salida.

Esa última es la clave. El secreto no se filtró tanto por el prompt como porque faltaba una pata de la trifecta. El mismo Willison avisa: no desplegaría en producción nada donde una injection pueda causar daño irreversible, porque 6.000 fallos no garantizan que un enfoque más sofisticado no pase.

La regla de decisión: audita la trifecta letal, no el prompt

La trifecta letal de Simon Willison es el marco que de verdad decide si tu agente es vulnerable. Necesita las tres patas a la vez para que exista ataque:

Acceso a datos privados (lee tus correos, ficheros, base de datos).
Exposición a contenido no confiable (procesa correos, webs, documentos compartidos, tickets).
Vía de exfiltración (puede hacer peticiones externas o mandar mensajes fuera).

La regla, mojada: si tu agente tiene las tres patas a la vez, no lo despliegues con acciones irreversibles; rompe al menos una pata. Si solo tiene dos, el ataque no tiene a dónde ir y puedes operar con monitorización. No intentes detectar cada injection posible: un metaanálisis de enero de 2026 estima que los ataques adaptativos esquivan los clasificadores de última generación más del 85% de las veces. Diseña para que una injection exitosa no tenga salida.

Artefacto 1: auditoría de la trifecta (rellénala antes de desplegar)

Pata	Pregunta	Cómo romperla
Datos privados	¿El agente puede leer secretos, PII o ficheros sensibles?	Scoping: el agente solo accede al subconjunto mínimo. Secretos fuera de su sistema de ficheros, en un vault que requiere otro canal.
Input no confiable	¿Procesa correos, webs o documentos de terceros?	Aísla el contenido externo como datos, nunca como instrucciones. Procesa cada item en contexto fresco para evitar contaminación entre mensajes.
Exfiltración	¿Puede hacer requests salientes, enviar correos o postear a URLs?	Allowlist de dominios. Sin HTTP genérico. Acciones de salida tras confirmación humana.

Romper la pata de exfiltración suele ser lo más barato y lo más efectivo: un agente que lee datos privados pero no tiene egreso no puede filtrar nada, por muy convincente que sea la injection.

Artefacto 2: checklist de defensa en capas (pre-deploy)

Ninguna capa elimina el riesgo sola; se apilan para que el ataque tenga que vencerlas todas en serie. Marca cada una antes de exponer el agente:

[ ] System prompt endurecido con reglas negativas explícitas (no revelar credenciales, no ejecutar código de input externo). Necesario, nunca suficiente. Si quieres patrones concretos, revisa qué hacen los system prompts filtrados de las herramientas reales.
[ ] Permisos de herramientas mínimos. Cada tool con el menor alcance posible. Sin shell abierto ni HTTP genérico "por si acaso".
[ ] Separación de input no confiable. El contenido externo va marcado como datos en su propio bloque, aislado de las instrucciones del sistema. Es separación de responsabilidades aplicada a la seguridad del agente.
[ ] Confirmación humana en acciones sensibles o irreversibles (borrar, enviar, pagar, modificar ficheros).
[ ] Monitorización de comportamiento. La industria se ha movido de filtrar input a vigilar output y comportamiento: la detección es más fiable cuando el agente se desvía de su baseline, aguas abajo del ataque.
[ ] Límite de gasto + kill-switch. Un atacante que manda 20 variantes en cuatro minutos también te dispara la factura de tokens. Pon tope por tarea y un interruptor para cortar cuando el agente se desvía.

Si el agente ingiere documentos (RAG, PDFs subidos por usuarios), trata cada chunk como input no confiable: las mismas precauciones que aplicas al procesar PDFs para tu pipeline de IA valen para no inyectar órdenes ocultas en un fichero.

Patrón de coste: doble filtro

Un guardrail con LLM-juez en cada input es caro. El patrón práctico de 2026 es dos niveles: un chequeo barato pasa sobre todo el tráfico, y solo lo que no resuelve escala al juez caro. Así contienes coste sin dejar ciega la entrada.

# Doble filtro: cribado barato primero, LLM-juez solo en lo dudoso.
# Evita pagar un juez caro por cada correo que entra al agente.
def screen_input(text: str) -> str:
    # Capa 1: heurística barata sobre patrones conocidos de injection
    flags = ["ignore previous", "reveal", "secrets.env", "system prompt",
             "exfiltrate", "send to http"]
    if not any(f in text.lower() for f in flags):
        return "pass"  # la mayoría del tráfico sale por aquí, coste casi cero
    # Capa 2: solo lo sospechoso paga el LLM-juez
    verdict = llm_judge(text)  # devuelve "pass" | "block"
    return verdict

Cuándo NO aplica este nivel de paranoia

El matiz que mata el dogma: no todo agente necesita el blindaje completo. Si una injection exitosa no causa daño irreversible, sobreproteger sale caro en latencia y fricción.

Agente de solo lectura sin datos privados. Un bot que resume noticias públicas y no toca nada tuyo no está en la trifecta. Una injection ahí, como mucho, ensucia un resumen.
Sin vía de salida ni acciones. Si el output va solo a un humano que decide, ya rompiste una pata; el riesgo cae mucho.
Entornos sandbox de pruebas. Donde no hay credenciales reales ni datos de cliente, optimiza para iterar rápido, no para resistir a internet entero.

La inversión en defensa escala con el daño irreversible posible, no con el hype del ataque. Un agente que encadena tareas largas con acceso a herramientas reales está en el extremo caro del espectro; un demo de fin de semana, en el barato.

Preguntas frecuentes

¿Un system prompt bien escrito basta para defender mi agente?

No. Reduce la tasa de éxito del prompt injection, pero no la elimina: el modelo no distingue de forma fiable instrucciones de datos. El experimento que resistió 6.000 intentos también tenía cortada la vía de exfiltración y solo recibía ataques de un disparo. El prompt es una capa necesaria, nunca la única.

¿Qué es la trifecta letal en prompt injection?

Es el marco de Simon Willison que describe las tres condiciones que hacen vulnerable a un agente cuando se dan a la vez: acceso a datos privados, exposición a contenido no confiable y una vía de exfiltración. Quita cualquiera de las tres patas y la ruta de ataque se colapsa.

¿Por qué no basta con un clasificador que detecte injections?

Porque los ataques adaptativos esquivan los clasificadores de última generación más del 85% de las veces, según un metaanálisis de 2026. La detección por input es porosa. La defensa fiable es arquitectónica: diseñar para que una injection exitosa no tenga a dónde ir, más monitorización del comportamiento aguas abajo.

El takeaway

El experimento no demuestra que el prompt injection esté resuelto; demuestra que con un modelo entrenado para resistir, una vía de salida cortada y ataques de un disparo, aguanta. Cambia cualquiera de esas tres condiciones y la historia es otra. La decisión práctica no es escribir un prompt más estricto, es auditar la trifecta antes de dar herramientas a tu agente y romper la pata más barata, normalmente la exfiltración. Pregúntate dónde, en tu stack, el contenido no confiable cruza hacia una acción con privilegios. Si la respuesta es "en todas partes y sin red", lo que tienes que cambiar es la arquitectura, no el prompt.

Skills de IA: deja de meter todo en un SKILL.md gigante

Sergio Márquez — Fri, 26 Jun 2026 08:00:01 GMT

Skills de IA: deja de meter todo en un SKILL.md gigante

TL;DR: Una Agent Skill es una carpeta con un fichero SKILL.md (instrucciones + recursos) que tu CLI de coding carga solo cuando una tarea la necesita, no en cada prompt. El error de la mayoría no es crear skills, es crearlas como un volcado monolítico de todo lo que el agente "debería saber". Aquí tienes la regla para diseñar una skill que se active cuando toca y no queme tu contexto, con plantilla, árbol de decisión y los casos en los que no compensa.

El instinto: empaquetar todo tu conocimiento en un solo fichero

Llevas semanas pegando las mismas convenciones de tu equipo en cada prompt: el estilo de commits, la estructura de tests, cómo montar un Dockerfile que pasa el linter. La solución obvia es empaquetarlo en una skill. Y ahí viene el error: abres un SKILL.md, vuelcas las 600 líneas de tu guía de estilo dentro y le pones una descripción del tipo "convenciones del proyecto".

Parece lógico. Cuanto más contexto le des al agente, mejor decidirá, ¿no? Técnicamente es justo al revés, y por dos motivos concretos.

Motivo uno: el body se carga entero al activarse. Las skills funcionan por progressive disclosure, un sistema de tres capas. Según la documentación de ingeniería de Anthropic, al arranque el agente solo lee el name y la description de cada skill (unos 100 tokens). El cuerpo completo del SKILL.md no entra en contexto hasta que el agente decide que esa skill es relevante. Si lo activas, se carga todo. Un body de 600 líneas son miles de tokens que se inyectan cada vez que la skill se dispara, compitiendo por el mismo presupuesto que tu código y diluyendo el razonamiento del modelo.

Motivo dos: una descripción vaga no se activa nunca. El description es el único contrato que el agente ve antes de decidir si carga la skill. Si pones "convenciones del proyecto", el modelo no tiene forma de saber cuándo aplica. La skill se vuelve impredecible: a veces se activa donde no debe (ruido en tareas que no le tocaban), y casi nunca cuando realmente hace falta.

Esta es la definición que conviene tener clara: una Agent Skill es un paquete en disco (un SKILL.md con metadatos y procedimiento, más scripts y referencias opcionales) que el agente descubre por su descripción y carga bajo demanda cuando una tarea encaja. No es un prompt largo guardado en un fichero. Esa diferencia es justo lo que estás tirando a la basura cuando la haces gigante.

La regla de decisión: descripción afilada, body lean, detalle en references/

La regla es simple y se moja: si el conocimiento es procedimiento que el agente sigue (cómo hacer X), va en una skill; si es una referencia pesada que solo se consulta a veces, va en references/ y la cargas por demanda; si lo necesitas en cada turno sin excepción, no es una skill, va en tu CLAUDE.md o AGENTS.md.

El truco está en respetar las tres capas en lugar de pelearte con ellas. Cada una tiene un presupuesto:

Capa	Qué carga	Cuándo	Presupuesto
1. Descubrimiento	`name` + `description`	Al arranque, para todas las skills	~100 tokens por skill
2. Activación	Cuerpo del `SKILL.md`	Cuando la tarea encaja con la descripción	<5.000 tokens / <500 líneas
3. Recursos	Ficheros de `scripts/`, `references/`, `assets/`	Solo cuando el body apunta a ellos	Efectivamente ilimitado (está en disco)

Esos límites no son inventados: la especificación abierta de Agent Skills fija el name en un máximo de 64 caracteres (minúsculas, números y guiones) y el description en 1.024 caracteres, y recomienda mantener el body por debajo de 500 líneas. Estimaciones independientes apuntan a que repartir el conocimiento en estas capas, en vez de un único prompt gigante, recorta el consumo de tokens en torno a un 40% a complejidad de tarea similar (es una estimación de un análisis técnico de terceros, no un número oficial; tómalo como orden de magnitud). Si vienes de pelearte con el coste de contexto, esto conecta directo con la idea de darle memoria a tu agente sin inflar el contexto: el problema de fondo es el mismo, qué entra en la ventana y qué se queda fuera.

El artefacto: plantilla de SKILL.md mínima y reutilizable

Esta es la estructura que copias mañana. El body manda al agente a leer detalle solo cuando lo necesita, en lugar de tragárselo entero:

---
name: react-testing
description: Escribe y arregla tests de componentes React con Testing Library y Vitest. Úsala cuando el usuario pida crear, revisar o depurar tests de componentes, hooks o interacciones de UI en el frontend.
---

# Tests de componentes React

## Cuándo aplicar
Tareas de testing de UI: componentes, hooks, eventos de usuario.
No usar para tests de backend ni de integración E2E.

## Procedimiento
1. Usa `screen.getByRole` antes que `getByTestId`.
2. Envuelve interacciones en `userEvent`, no `fireEvent`.
3. Para casos complejos de mocking, lee `references/mocking.md`.

## Comando de verificación
Ejecuta exactamente: `npm run test -- --run`

Fíjate en tres cosas. La description dice qué hace y cuándo usarla, en tercera persona: la guía oficial de Claude insiste en el punto de vista en tercera persona porque la descripción se inyecta en el system prompt y la inconsistencia rompe el descubrimiento. El body es corto y delega el mocking complejo a un fichero aparte. Y el comando de verificación es literal, para que el agente no improvise flags.

La estructura de carpetas que acompaña es predecible y reutilizable:

react-testing/
├── SKILL.md          # Metadatos + procedimiento (lean)
├── references/       # Detalle pesado: mocking.md, patrones avanzados
├── scripts/          # CLIs pequeños que el agente ejecuta
└── assets/           # Plantillas, configs base

Mantenla agnóstica del CLI

El formato SKILL.md es idéntico entre herramientas; lo único que cambia es dónde la colocas. Por eso una skill bien hecha vale en Claude Code, Codex y Gemini CLI sin reescribir nada, algo que ya cubrimos al hablar de cómo usar las mismas skills en Codex y Cursor. La tabla de rutas:

CLI	Ruta personal	Ruta de proyecto
Claude Code	`~/.claude/skills/`	`.claude/skills/`
Codex CLI	`.agents/skills/`
Gemini CLI	`.gemini/skills/`

Las rutas las recoge un análisis del patrón de progressive disclosure; revisa la doc de tu CLI por si tu versión cambia la convención. La regla práctica para no atarte: no metas en el body instrucciones específicas de un agente ("usa la herramienta Bash de Claude Code"); describe la acción, no la herramienta concreta.

¿Esto debería ser una skill? Árbol de decisión

¿Lo necesitas en cada turno, sin excepción? → No es skill. Va en CLAUDE.md / AGENTS.md. Aquí ayuda revisar patrones para tu CLAUDE.md.
¿Es procedimiento que se activa por intención (testing, formato, un flujo concreto)? → Skill. Es el caso ideal.
¿Necesitas ejecutar una herramienta externa con estado (una API, una DB en vivo)? → Probablemente un servidor MCP encaja mejor; la skill aporta el "cómo", no la ejecución con estado.
¿Es conocimiento de un solo uso para esta tarea? → Déjalo en el prompt. Crear una skill que no vas a reutilizar es trabajo "por si acaso".

Cuándo NO aplica (y los riesgos que nadie te cuenta)

Las skills no son la respuesta a todo, y dos matices honestos lo dejan claro.

El anti-patrón silencioso: skills que se cargan siempre. Si tu descripción es tan amplia que la skill se activa en casi cualquier tarea, has reinventado el prompt gigante por la puerta de atrás. Una skill grande activada constantemente quema más tokens que el contexto repetido que querías evitar, y eso impacta directo en tu factura, un tema que conecta con elegir tu modelo por coste real. El antídoto es la misma disciplina de toda buena arquitectura: una skill, una responsabilidad clara, como en el principio de separación de responsabilidades. Pequeñas y activadas por intención, no enormes y siempre presentes.

El riesgo de supply chain. Una skill de terceros es código que corre con los permisos de tu agente: ficheros, red, secretos. No es un detalle teórico. Un estudio reciente sobre skills de comunidad encontró una tasa de vulnerabilidad del 26,1% en 42.447 skills analizadas, incluyendo prompt injection escondido en los propios ficheros. La regla mínima: instala solo skills auditadas, fija versiones y no le des secretos al agente por defecto. Crear las tuyas propias, además de reutilizables, es la forma más segura de empezar.

Las skills tampoco sustituyen un buen ejemplo práctico cuando el conocimiento es muy específico de un dominio. Si tu flujo es, por ejemplo, extraer y preparar documentos, la skill encapsula el procedimiento pero el grueso técnico sigue viviendo en tu pipeline, como en el procesamiento de PDFs para IA: la skill dice "cómo", tu código hace el trabajo pesado.

Preguntas frecuentes

¿En qué se diferencia una skill de un MCP server?

Una skill inyecta conocimiento procedimental (cómo resolver algo) y se carga por demanda; un servidor MCP expone herramientas que ejecutan acciones y devuelven resultados. La skill prepara al agente, el MCP actúa. Para conocimiento reutilizable sin estado, la skill es más ligera; para integrar un sistema externo con estado, el MCP encaja mejor.

¿Cuánto debe medir el cuerpo del SKILL.md?

La especificación recomienda mantener el body por debajo de unas 500 líneas o aproximadamente 5.000 tokens, porque se carga entero al activar la skill. Todo lo que supere ese límite debería moverse a la carpeta references/, que el agente lee solo cuando las instrucciones del body lo indican.

¿Una skill escrita para Claude Code funciona en Codex o Gemini CLI?

Sí, el formato SKILL.md es compatible en lo esencial entre herramientas, aunque cada CLI puede añadir campos propietarios o comportamientos divergentes. Lo único que cambia, en lo básico, es la ruta donde la colocas. Para que sea portable de verdad, evita referenciar herramientas específicas de un CLI dentro del body y describe las acciones de forma neutral.

El takeaway

Crear una skill no es volcar tu conocimiento en un fichero, es decidir qué entra en contexto y cuándo. La descripción es el contrato de activación: si es vaga, la skill no existe; si es precisa, el agente la encuentra. El body es presupuesto de tokens que pagas cada vez que se activa: mantenlo lean y manda el detalle a references/. Una skill pequeña, con una responsabilidad clara y una descripción afilada, le ahorra a tu agente exactamente el ruido que un prompt gigante le metería. La pregunta que conviene hacerse antes de escribir la primera línea no es "¿qué más le cuento?", sino "¿qué necesita leer solo cuando le hace falta?".

Code review con IA: el paper que lo da por muerto falla

Sergio Márquez — Thu, 25 Jun 2026 08:00:02 GMT

Code review con IA: el paper que lo da por muerto falla

Acabas de leer el titular de un paper que dice que el code review humano ha terminado, y ya tienes el dedo encima de quitar la revisión obligatoria de tu pipeline y dejar que un agente apruebe los PR. Antes de hacerlo: el paper que te lo sugiere no aporta un solo estudio empírico propio. Lo dice su propio abstract.

TL;DR

Qué es: un paper titulado "The End of Code Review" sostiene que los agentes de codificación ya cubren todos los objetivos del code review humano y que mantenerlo obligatorio sale económicamente negativo para cambios rutinarios.
El matiz que importa: es un position paper argumentativo, no un estudio con datos. Reconoce textualmente que no presenta evidencia empírica nueva, solo sintetiza capacidades ya publicadas.
Qué te llevas: una tabla de decisión para saber cuándo dejar que un agente revise solo, cuándo usarlo como segunda opinión y cuándo el humano sigue siendo obligatorio.

Qué ha pasado

Martin Monperrus, investigador del KTH Royal Institute of Technology, publicó "The End of Code Review: Coding Agents Supersede Human Inspection" en arXiv. La tesis es directa: los agentes de codificación (un LLM en un bucle que lee, escribe, ejecuta tests y repara código) han cruzado un umbral de capacidad en el que el review humano deja de ser una pieza necesaria del pipeline de calidad.

El argumento se apoya en dos claims. Primero, que cada objetivo declarado del code review puede servirlo un agente a menor coste y mayor throughput: detectar defectos, transferir conocimiento, mantener estándares. Segundo, que el modelo intermedio (agentes escriben pero un humano revisa obligatoriamente) es inestable, y que la economía del review humano obligatorio "ya se ha vuelto negativa" para cambios rutinarios.

El detalle clave está en una frase del propio paper: "No presentamos un nuevo estudio empírico; en su lugar, sintetizamos evidencia de capacidades existente". Es una posición, no una medición.

Evidencia y límites

Lo confirmado es poco y lo provisional es mucho. El paper no mide que un agente revise mejor que un humano. Enumera capacidades de agentes documentadas en otros trabajos y deduce la conclusión. En la discusión en Hacker News, varios revisores lo describen como un ensayo persuasivo de nivel introductorio disfrazado de paper académico, porque la sección sobre capacidades de review específicas se reduce a un párrafo sin datos que demuestren superioridad.

La evidencia independiente que sí existe pinta un cuadro más matizado, y conviene separarla del marketing de cada herramienta. Los benchmarks comparativos muestran un trade-off consistente: los LLMs mejoran el recall (encuentran más cosas) pero generan más falsos positivos que los analizadores deterministas. La síntesis de Augment Code sobre esa literatura cita un preprint de enero de 2026 (todavía sin revisión por pares) según el cual los enfoques híbridos LLM más análisis estático eliminan entre el 94% y el 98% de falsos positivos manteniendo alto recall. Trátalo como un rango direccional, no como un número cerrado.

Donde un agente revisor se queda corto está bastante claro en los reportes prácticos: detecta bien problemas de seguridad y errores de lógica, pero flojea en condiciones de carrera y patrones async, justo los bugs sutiles que tampoco pega el humano de un vistazo. Y hay un fallo de raíz que el paper ignora: si el mismo modelo que escribió el código lo revisa, no es review, es sesgo de confirmación a escala. El que escribe rara vez puede juzgar su propia obra con objetividad.

Qué cambia para builders

Que el code review humano "muera" no es la decisión que tienes delante. La decisión real es qué cambios puede aprobar un agente solo y cuáles no, y eso depende del blast radius del cambio, no de lo capaz que sea el modelo en abstracto. Tratarlo como un interruptor de todo o nada es el error.

La parte sólida del paper es esta: para cambios rutinarios y de bajo riesgo (renombrados, bumps de dependencias con tests verdes, fixes mecánicos), exigir que un humano lea cada diff sí es un cuello de botella caro. Ahí un agente revisor como puerta de entrada tiene sentido. La parte que se pasa es extender eso a decisiones de diseño, cambios en límites de servicios o lógica de negocio, donde el contexto que falta no está en el diff.

Esta es la regla de decisión que puedes copiar tal cual:

Tipo de cambio	Quién revisa	Por qué
Renombrados, formato, bumps con tests verdes	Agente solo (auto-merge con política)	Bajo blast radius, verificable por tests. El coste humano no compensa.
Bugfix acotado, refactor interno de un módulo	Agente + humano por excepción	El agente filtra; el humano mira solo si el agente marca duda o toca rutas críticas.
Lógica de negocio, auth, límites entre servicios	Humano obligatorio + agente como segunda opinión	El contexto de negocio no está en el diff. El agente aporta, no decide.
Código generado por IA del mismo modelo	Revisor de otro modelo o humano	Mismo modelo = errores correlacionados. Evita el sesgo de confirmación.

La última fila es la que casi nadie aplica. Si Opus escribe el código, que lo revise un modelo de otra familia (o un humano), no el mismo. Es el mismo principio de separar responsabilidades: quien produce tiene puntos ciegos para validar su propio output. Y si vas a montar el revisor como pieza propia, encaja bien con un esquema de subagentes especializados donde el agente de review corre aislado del que escribió.

Qué haría (y qué no) ahora mismo

Lo que sí: meter un agente revisor en CI como segunda opinión, no como reemplazo. Que comente en el PR, que clasifique findings por severidad, que se centre en bugs, seguridad y correctness, y que excluya estilo y formato (eso lo resuelve un linter más barato). Para cambios triviales con tests sólidos, dejar que apruebe bajo una política explícita de auto-merge.

Lo que no: quitar el humano de los cambios donde el coste de un error es alto solo porque un paper sin datos diga que la economía "ya cambió". Tampoco confiar en el promedio de un benchmark de marketing. Antes de mover nada en producción, mídelo en tu repo: igual que tu evaluación offline puede mentir respecto a producción, el recall de un revisor en un benchmark público no predice cuántos de tus bugs pilla. Coge 20 o 30 PR históricos con bugs conocidos y mide qué encuentra el agente y cuánto ruido mete. Esa es tu cifra, no la del vendedor.

Y elige el modelo del revisor con el mismo criterio escéptico con el que eliges un modelo de coding por benchmark: el que lidera una tabla agéntica no es automáticamente el mejor detectando tus race conditions.

Preguntas abiertas / qué vigilar

Errores correlacionados: ¿cuánto degrada el review que el revisor y el autor compartan modelo? No hay un estudio sólido todavía; mídelo tú con revisores cruzados.
Falsos positivos a escala: el rango 94-98% de reducción con híbridos es un preprint sin revisar. Trátalo como hipótesis hasta que se replique.
Transferencia de conocimiento: el paper asume que las explicaciones del agente sustituyen al aprendizaje que ocurre cuando un humano revisa. Eso está sin demostrar y es donde más críticas recibe.
Responsabilidad: si un agente aprueba y el cambio rompe producción, ¿quién responde? La política de auto-merge necesita un dueño humano.

Preguntas frecuentes

¿El paper "The End of Code Review" prueba que los agentes revisan mejor que los humanos?

No. Es un position paper que sintetiza capacidades publicadas y argumenta una conclusión; su propio abstract reconoce que no presenta un estudio empírico nuevo. Es una postura defendible, no una medición.

¿Puedo dejar que un agente apruebe pull requests sin humano?

Para cambios de bajo riesgo con tests verdes (formato, renombrados, bumps), con una política de auto-merge explícita y un dueño humano de esa política, tiene sentido. Para lógica de negocio, auth o cambios entre servicios, el humano sigue siendo obligatorio porque el contexto no está en el diff.

¿Por qué no debe revisar el código el mismo modelo que lo escribió?

Porque comparte los mismos puntos ciegos: los errores quedan correlacionados y el revisor valida sus propios sesgos. Es confirmación a escala. Usa un modelo de otra familia o un humano para la segunda pasada.

El takeaway

La pregunta útil no es si el code review humano ha muerto, sino qué cambios puede aprobar un agente sin que te explote nada y cuáles no. El paper acierta en que revisar a mano cada renombrado es un coste que ya no compensa, y se pasa al estirar eso hasta las decisiones de diseño. Mete el agente como segunda opinión, mídelo con tus propios PR antes de darle la llave del merge, y no dejes nunca que el modelo que escribió el código sea el único que lo bendiga. El revisor que no puede equivocarse en contra del autor no está revisando nada.

GPT-5.5 vs Opus 4.8: lee el benchmark antes de creértelo

Sergio Márquez — Wed, 24 Jun 2026 08:00:01 GMT

GPT-5.5 vs Opus 4.8: lee el benchmark antes de creértelo

TL;DR:

El titular engaña. GPT-5.5 gana a Opus 4.8 en Terminal-Bench 2.1 (78,2% vs 74,6%), pero ese número de GPT-5.5 sale con el harness de Codex CLI, no con el estándar Terminus-2. No es una comparación cara a cara.
Un benchmark de coding agéntico mide un sistema, no un modelo. El andamiaje (scaffold) puede mover el resultado entre 10 y 20 puntos con los mismos pesos del modelo.
Lo que importa en producción no es la tasa de aprobados, sino el coste por tarea resuelta, la varianza y si el benchmark se parece a tu trabajo real.

El problema: decidir tu modelo por un titular

Sale una comparativa nueva, "modelo X gana a Y en Terminal-Bench", y media comunidad cambia su CLI de coding esa misma tarde. El último ejemplo es GPT-5.5 contra Claude Opus 4.8 en coding por terminal. El veredicto que circula es simple: GPT-5.5 pasa más tareas, va más rápido y cuesta menos.

El veredicto no es falso. Es incompleto. Y elegir tu benchmark de coding agéntico de referencia por el porcentaje de la portada es la forma más rápida de meter en producción un modelo que no encaja con tu repo. Vamos a leer estos números con criterio, usando el caso GPT-5.5 vs Opus 4.8 como banco de pruebas.

¿Qué es un benchmark de coding agéntico?

Un benchmark de coding agéntico es una batería de tareas de programación reales que un agente resuelve de forma autónoma, ejecutando comandos, leyendo salidas e iterando, donde se mide cuántas completa correctamente. No puntúa solo al modelo: puntúa al modelo más su andamiaje, sobre una variante concreta y bajo condiciones concretas.

Las dos familias que vas a ver en cada lanzamiento:

SWE-bench: resolver issues reales de GitHub con su suite de tests. Tiene cinco variantes (original, Verified, Pro, Multilingual, Live) y comparar entre ellas es un error metodológico.
Terminal-Bench: tareas duras en una terminal, que exigen planificar, iterar y recuperarse de errores en un bucle de shell. Es el que más se parece a un agente de DevOps o de infraestructura.

Los números reales (y dónde está la trampa)

Esto es lo que publicó Anthropic en el lanzamiento de Opus 4.8 (mayo de 2026). Léelo en horizontal, no por la columna que más te conviene:

Benchmark	Opus 4.8	GPT-5.5	Qué mide
SWE-bench Pro	69,2%	58,6%	Issues reales, multi-archivo, resistente a memorización
SWE-bench Verified	88,6%	~88%	Subset solucionable, casi saturado
Terminal-Bench 2.1	74,6%	78,2%	Bucle agéntico en shell
OSWorld-Verified	83,4%	78,7%	Uso de ordenador / computer use
MCP-Atlas	82,2%	75,3%	Uso de herramientas vía MCP

La trampa está en la fila de Terminal-Bench. Según el desglose del propio lanzamiento, el 78,2% de GPT-5.5 se obtuvo con el harness de Codex CLI, no con Terminus-2, que es el que se usa para el resto de modelos. Estás comparando un modelo con su andamiaje optimizado contra otro con el andamiaje estándar. No es lo mismo, y por eso un único número de "Terminal-Bench" puede valer 74%, 78% o 83% según quién lo corra.

El harness lo cambia todo

Aquí está la idea que un tutorial de "qué modelo es mejor" nunca te da: el andamiaje (scaffold o harness) que rodea al modelo puede mover el resultado entre 10 y 20 puntos sobre los mismos pesos. El contexto que le inyectas, el límite de turnos, las herramientas disponibles, cómo gestionas la memoria. Todo eso puntúa.

Dicho de otra forma: una puntuación de SWE-bench es ininterpretable sin saber qué harness la produjo. Un número alto reportado por el fabricante con su andamiaje a medida y un número más bajo en un leaderboard estandarizado pueden ser, los dos, correctos para el mismo modelo. Si quieres entender por qué el andamiaje pesa tanto, esto conecta con la lógica del harness recursivo que orquesta subagentes en Claude Code: el agente no es el modelo, es el sistema entero.

Regla práctica: solo compara números producidos bajo el mismo harness. En cuanto el scaffold cambia, dejas de comparar modelos y pasas a comparar productos distintos.

Caso real: 10 tareas duras de Terminal-Bench 2.1

Un test de la comunidad que circuló esta semana ilustra bien el punto. Cogió 10 tareas difíciles de Terminal-Bench 2.1 y las pasó por Opus 4.8 (vía Claude Code) y GPT-5.5 (vía Codex), midiendo aprobados, coste, duración y tokens. Conversión a euros aproximada:

Métrica	GPT-5.5 (Codex)	Opus 4.8 (Claude Code)
Tareas pasadas	9 de 10	Menos, atascado en una tarea
Duración total	~1 hora	~2 h 23 min
Coste aproximado	~10,70 €	~22 € o más
Tokens de salida	126K	423K (~3,35x más)
Input cacheado	3,93M	15,39M (~4x más)

En el titular, GPT-5.5 arrasa: más rápido, más barato, más aprobados. Pero mira el detalle: Opus pasó password-recovery, que GPT-5.5 falló, y se quedó colgado casi una hora en regex-chess. Una sola tarea patológica le destrozó el tiempo y el coste medios. Con n=10, un caso atípico arrastra toda la media. Eso es varianza, y es justo lo que el porcentaje agregado esconde.

Qué mide un benchmark, y qué NO mide

El paper de Terminal-Bench deja un par de hallazgos incómodos para quien decide por número:

No hay correlación entre número de turnos y éxito. Un agente que da más vueltas no resuelve más.
Más tokens generados no implica mejor resultado. El perfil de Opus (mucho output, mucho cacheado) no se traduce en ventaja automática.
El coste por tarea va de céntimos a más de 90 € en una sola tarea larga. La media no te dice tu coste real.

Lo que un benchmark público no mide: tu base de código, tus convenciones, tu definición de "correcto". Es una señal poblacional útil, no una predicción sobre tu repo. Este mismo punto es el que defiendo cuando hablo de por qué tu evaluación offline miente y hay que medir en producción.

Cómo leerlo con criterio: replica un subset

La única forma de convertir un benchmark en una decisión es validarlo contra tus tareas. No necesitas correr las 200 tareas oficiales. Con 10 o 15 tareas representativas de tu trabajo real ya tienes señal.

Y la métrica que de verdad manda no es la tasa de aprobados, sino el coste por tarea resuelta. Un modelo que pasa el 70% a 1,80 € por tarea es una decisión de producción distinta a uno que pasa el 65% a 0,40 €. Calcularlo desde los logs de una corrida es trivial:

# Calcula coste por tarea RESUELTA, no por tarea intentada: es la metrica que decide en produccion
from dataclasses import dataclass

@dataclass
class Run:
    task_id: str
    passed: bool
    cost_eur: float  # coste de esa tarea en euros

def coste_por_exito(runs: list[Run]) -> float:
    resueltas = [r for r in runs if r.passed]
    if not resueltas:
        return float("inf")  # no resolvio nada: coste util infinito
    coste_total = sum(r.cost_eur for r in runs)  # pagas tambien los fallos
    return coste_total / len(resueltas)

# Caso minimo ejecutable con los numeros del test de 10 tareas
gpt = [Run(f"t{i}", i != 4, 1.07) for i in range(10)]   # 9/10, ~10,70 € total
opus = [Run(f"t{i}", i < 4, 2.20) for i in range(10)]   # 4/10, ~22 € total

print(f"GPT-5.5: {coste_por_exito(gpt):.2f} €/exito")
print(f"Opus 4.8: {coste_por_exito(opus):.2f} €/exito")
# GPT-5.5: 1.19 €/exito  |  Opus 4.8: 5.50 €/exito

Ese número, coste dividido entre tareas que de verdad resolviste (pagando también los intentos fallidos), reordena leaderboards. Es el mismo principio que aplico al elegir modelo de IA por coste real y no por el benchmark.

Cuándo fiarte de un benchmark y cuándo desconfiar

Fíate cuando...	Desconfía cuando...
Mismo harness para todos los modelos	Un modelo usa su CLI propietaria y el resto el estándar
Reporta coste y varianza, no solo % medio	Solo ves un porcentaje agregado de la portada
La variante está explícita (Pro, Verified, Live)	Dice "SWE-bench" a secas sin variante
Las tareas se parecen a tu dominio	Extrapolas de tareas triviales a tu enterprise repo
Hay logs reproducibles	Número del fabricante sin trazas públicas

En Producción

Lo que cambia entre el benchmark y tu lunes por la mañana:

Coste por tarea resuelta, no por millón de tokens. A precio de lista, ambos rondan ~4,70 € por millón de input; Opus está en ~23,50 € por millón de output y GPT-5.5 en ~28 €. Pero Opus genera 3x más output en tareas largas, así que el coste efectivo se invierte según el tipo de trabajo.
Latencia y tareas patológicas. En un agente desatendido, una tarea que se cuelga una hora (como regex-chess) no es una anécdota: es un timeout que tienes que cortar. Pon límites de turnos y de presupuesto por tarea.
Varianza entre corridas. Corre tu subset 3 veces, no una. Un único pase con n bajo te miente con confianza.
Reparto por tipo de trabajo. Opus 4.8 lidera en resolución de issues multi-archivo (SWE-bench Pro); GPT-5.5 en bucles de shell (Terminal-Bench). Si tu agente vive en la terminal arreglando CI, gana GPT-5.5; si hace migraciones a escala de repo, gana Opus.

Si al borrar esta sección el artículo siguiera igual, sería relleno. No lo es: el criterio operativo (coste por éxito, varianza, límites de presupuesto) es justo lo que el porcentaje de portada te oculta.

Errores comunes y depuración

Error: "GPT-5.5 saca 8 puntos más en Terminal-Bench, me cambio." → Causa: comparas su número con harness Codex contra el Terminus-2 de Opus. → Solución: exige el mismo andamiaje o ignora la comparación cruzada.
Error: media de coste baja pero la factura real se dispara. → Causa: una tarea atípica larga arrastra la cola de distribución. → Solución: mira la mediana y el percentil 95, no solo la media.
Error: el modelo que ganó el benchmark falla en tu repo. → Causa: el benchmark no se parece a tu dominio (enterprise, multi-archivo, contexto propietario). → Solución: replica un subset con tus tareas antes de fijar el modelo por defecto.

Preguntas frecuentes

¿GPT-5.5 es mejor que Opus 4.8 para programar?

Depende del tipo de coding. GPT-5.5 lidera Terminal-Bench 2.1 (coding agéntico en shell) y es más barato en input. Opus 4.8 lidera SWE-bench Pro (resolución de issues reales multi-archivo) por más de 10 puntos. No hay un ganador único: hay dos ganadores en dos tareas distintas.

¿Por qué el mismo modelo saca puntuaciones distintas en "SWE-bench"?

Porque "SWE-bench" no es un número, es una familia con cinco variantes, y el harness alrededor del modelo puede mover el resultado entre 10 y 20 puntos. Un 50% y un 70% pueden ser ambos ciertos para el mismo modelo según variante y andamiaje.

¿Cuántas tareas necesito para validar un modelo en mi caso?

Con 10 a 15 tareas representativas de tu trabajo real, corridas 2 o 3 veces, ya tienes señal útil de coste por éxito y varianza. Es más informativo que el porcentaje oficial sobre 200 tareas que no se parecen a tu repo.

Cierre

Hemos visto que un benchmark de coding agéntico mide un sistema completo, no un modelo suelto, y que el andamiaje pesa tanto como los pesos. La portada de GPT-5.5 vs Opus 4.8 es real pero incompleta: un harness distinto, una varianza alta y un coste por tarea que el porcentaje medio esconde. La clave está en mirar el mismo andamiaje para todos, exigir coste y varianza junto al porcentaje, y replicar un subset con tus propias tareas antes de cambiar nada. Si quieres profundizar en por qué la mayoría elige mal, esto enlaza directamente con cómo los benchmarks de coding agéntico te hacen elegir mal tu modelo.

¿Has corrido tu propio subset de Terminal-Bench o SWE-bench con tus tareas? Cuéntame qué número de portada te ha decepcionado en la práctica en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo monto un harness mínimo y reproducible para correr ese subset con tus propios casos.

Codex CLI en tareas largas: evita que pierda el hilo

Sergio Márquez — Tue, 23 Jun 2026 08:00:01 GMT

Codex CLI en tareas largas: evita que pierda el hilo

TL;DR: Codex CLI puede trabajar de forma autónoma durante horas, pero el problema no es que el modelo sea torpe, sino que se queda sin memoria de trabajo y empieza a divagar. La solución no es un megaprompt, sino memoria de proyecto duradera: un spec congelado, un plan dividido en hitos verificables y un registro de estado en archivos que el agente relee. En esta guía verás el patrón exacto que OpenAI usó para una ejecución de 25 horas y cómo aplicarlo a tu repo (sirve igual para Claude Code o Gemini CLI).

El problema: por qué tu agente se pierde a la hora de empezar

Llevo meses dejando agentes de coding corriendo tareas que antes partía en diez sesiones. Y el patrón de fallo siempre es el mismo: las primeras dos horas van de maravilla, y luego el agente empieza a reescribir cosas que ya funcionaban, a olvidar una restricción que diste al principio o a "terminar" algo que no cumple lo que pediste.

No es un problema de inteligencia del modelo. Es de gestión de contexto. Cada turno de Codex incluye todo el historial de la conversación en el prompt, así que la ventana crece con cada llamada a herramienta. En tareas de horas, eso significa cientos de iteraciones modelo-herramienta hasta que la información importante (el objetivo, las restricciones, la definición de "hecho") queda enterrada o se descarta al comprimir el contexto.

Si quieres entender la mecánica de fondo, ya analicé por qué los agentes long-horizon se pierden en tareas largas. Aquí vamos a lo práctico: cómo estructurar el trabajo para que el límite de contexto deje de ser tu cuello de botella.

¿Qué es la memoria de proyecto duradera?

La memoria de proyecto duradera es la técnica de escribir el objetivo, el plan, las restricciones y el estado en archivos de texto que el agente puede releer en cualquier momento, en lugar de confiar en que lo recuerde de la conversación.

Es la diferencia entre darle instrucciones de palabra a alguien que va a trabajar 8 horas, o dejarle una pizarra con el objetivo, una lista de tareas con casillas y un cuaderno donde apunta decisiones. La pizarra no se borra cuando se llena la cabeza. En la ejecución de 25 horas que documentó OpenAI con GPT-5.3-Codex, la conclusión fue literal: "la técnica más importante fue la memoria de proyecto duradera". Eso evita la deriva y mantiene una definición estable de "hecho".

El stack de archivos: 4 piezas que evitan la deriva

El patrón que recomienda OpenAI se apoya en cuatro archivos con responsabilidades separadas. No es teoría, es lo que mantuvo coherente una ejecución de un día entero.

Archivo	Para qué sirve	Por qué importa
spec.md	Congela el objetivo, restricciones y entregables	Evita que el agente "construya algo impresionante pero equivocado"
plan.md	Hitos pequeños con criterios de aceptación y comandos de validación	Convierte trabajo abierto en checkpoints que se completan y verifican
implement.md	Runbook: cómo debe operar el agente paso a paso	Estandariza el comportamiento entre milestones
status.md	Log vivo de estado y decisiones	Mantiene la ejecución inspeccionable sin tener que parar

La clave está en separar el "qué" del "cómo" y del "dónde voy". Es el mismo principio de separación de responsabilidades en arquitectura de software, aplicado a la memoria de un agente.

Implementación paso a paso

1. Escribe el spec antes de tocar nada

El error número uno es lanzar un prompt largo y rezar. El spec congela el target para que el agente no improvise el alcance. Cuatro secciones bastan.

Define objetivos, no-objetivos, restricciones duras y la condición de "hecho":

# spec.md

## Objetivos
- API REST que exponga búsqueda semántica sobre el catálogo de productos.

## No-objetivos
- No tocar el sistema de autenticación existente.
- No migrar la base de datos.

## Restricciones duras
- Python 3.12 + FastAPI. Latencia p95 < 300 ms.
- Sin dependencias nuevas fuera de las ya declaradas en pyproject.toml.

## Hecho cuando
- `pytest` pasa en verde y `ruff check` no reporta errores.
- El endpoint /search devuelve 10 resultados ordenados por relevancia.

2. Divide en hitos verificables

Aquí está el corazón del patrón. Cada hito debe ser lo bastante pequeño para completarse en un solo ciclo del agente y, sobre todo, tener un comando de validación que diga objetivamente si está hecho.

Cada milestone lleva su criterio de aceptación y su comando de validación:

# plan.md

## Milestone 1: esquema de embeddings
- [ ] Crear modelo Pydantic para el documento indexado.
- Validación: `pytest tests/test_schema.py`
- Regla stop-and-fix: si falla, repara antes de pasar al M2.

## Milestone 2: endpoint /search
- [ ] Implementar búsqueda top-k contra el vector store.
- Validación: `pytest tests/test_search.py && ruff check`
- Decisión: usamos cosine similarity, NO dot product (ya decidido, no re-evaluar).

Fíjate en dos detalles que marcan la diferencia en producción. La regla "stop-and-fix": si la validación falla, el agente repara antes de avanzar, en vez de acumular deuda. Y las notas de decisión: anotar lo que ya está decidido evita que el agente oscile y re-discuta lo mismo tres horas después.

3. Dale el runbook en AGENTS.md

El comportamiento operativo va en el archivo que tu CLI lee al arrancar cada sesión: AGENTS.md para Codex, CLAUDE.md para Claude Code. Aquí le dices que escriba las cosas, no que las recuerde.

Una instrucción que funciona: ordena al agente actualizar el estado tras cada hito:

# AGENTS.md

## Flujo de trabajo obligatorio
1. Lee spec.md y plan.md antes de cada milestone.
2. Tras completar un milestone, ejecuta su comando de validación.
3. Actualiza status.md con: qué hiciste, qué validaste, qué decidiste.
4. Si una validación falla, NO avances: repara y vuelve a validar.

Mantén este archivo corto y operativo. Según estudios sobre AGENTS.md, las secciones de "arquitectura" genéricas no cambian el comportamiento del agente y solo gastan tokens; lo que sirve son comandos, restricciones y patrones no obvios. Si quieres exprimir esto, mira los patrones de system prompts que mejoran tu CLAUDE.md.

4. Lanza con goal mode y verificación continua

Desde mayo de 2026, el modo /goal de Codex dejó de ser experimento. Le das un objetivo medible y sigue trabajando hasta cumplirlo, incluso a lo largo de horas, con la opción de pausar y retomar.

# Arranca Codex en modo objetivo apuntando al spec
codex
# Dentro de la sesión:
/goal Implementa todos los milestones de plan.md. Trata spec.md como
la especificación completa. Valida cada hito antes de avanzar.

La verificación continua (tests, lint, typecheck, build tras cada milestone) es lo que mantiene la ejecución honesta. Sin ella, el agente cree que avanza aunque esté rompiendo cosas.

Caso real: del megaprompt al flujo con evidencia

En escenarios reales, este patrón cambia cómo delegas. Antes partías una refactorización grande en sesiones de 30 minutos porque el agente se perdía. Con memoria de proyecto, lanzas la tarea entera y revisas en los checkpoints.

Jason Liu lo lleva un paso más allá con lo que llama un "vault": un repositorio Git separado del código, donde el agente guarda contexto rodante (personas, decisiones, hilos abiertos, estado de proyectos) que de otro modo se perdería entre sesiones. La idea es la misma que ya vimos en cómo dar memoria a tu agente sin inflar el contexto: no guardas todo el historial, guardas hechos y decisiones.

¿Cuándo usar esto en producción? Cuando la tarea dura más de lo que cabe en una ventana de contexto cómoda, cuando vas a delegar y desconectar, o cuando varios agentes (o tú a ratos) tocan el mismo trabajo. Para un fix de 15 minutos, montar cuatro archivos es sobreingeniería.

En Producción

Aquí es donde el tutorial se separa de la realidad. Tres cosas que aprendí dejando esto correr de verdad.

El coste de los threads largos no es gratis. Las conversaciones largas se benefician del prompt caching, pero si revisitas un thread horas después, probablemente ya no esté en caché y pagas más que en un thread corto y fresco. La compaction (disponible en la Responses API) ayuda a estirar la ventana efectiva comprimiendo el historial, pero comprimir también puede tirar contexto que importaba. Por eso la memoria vive en archivos: sobrevive a la compaction. Para un proyecto personal, hablamos de un consumo realista de entre 10 y 50 € al mes en API si lo usas a diario, no de cifras de FAANG.

El plan debe caber en un ciclo. Si un milestone es demasiado grande, el agente lo empieza, se queda sin contexto a mitad y lo deja a medias sin validar. Hitos pequeños con un comando de validación claro son tu mejor seguro contra la deriva. Esto conecta con la importancia de elegir bien el modelo según tu repo: en tareas largas, un modelo con buena coherencia a largo horizonte rinde más que uno "más listo" pero que pierde foco.

La evidencia es el control de calidad. Exigir que cada hito deje artefactos (tests verdes, un diff, una nota en status.md) es lo que te permite revisar al final sin reconstruir todo desde cero. Sin evidencia, delegar horas de trabajo es un acto de fe.

Errores comunes y depuración

Error: el agente "termina" pero no cumple el spec. Causa: la condición de "hecho" era ambigua. Solución: define "hecho" con comandos ejecutables, no con prosa ("pytest pasa", no "que funcione bien").
Error: reescribe código que ya funcionaba. Causa: perdió el contexto de qué milestones estaban cerrados. Solución: obliga a releer status.md al inicio de cada ciclo y marca los hitos completados.
Error: oscila entre dos soluciones cada pocas horas. Causa: no hay registro de decisiones. Solución: añade notas de decisión en plan.md marcadas como "ya decidido, no re-evaluar".
Error: el coste se dispara en una tarea larga. Causa: threads revisitados fuera de caché. Solución: para workstreams largos, mantén la continuidad; para consultas sueltas, abre un thread corto nuevo.

Preguntas frecuentes

¿Esto solo funciona con Codex CLI?

No. El principio (preservar contexto en archivos y dividir en hitos verificables) es transferible a Claude Code o Gemini CLI. Lo que cambia es la herramienta y el nombre del archivo de instrucciones (AGENTS.md o CLAUDE.md), no la técnica. Codex añade el modo /goal y compaction nativa, pero el patrón de memoria de proyecto es agnóstico.

¿Cuántos archivos necesito de verdad?

Para empezar, dos: un spec con el objetivo y un plan con hitos y validaciones. El runbook (AGENTS.md) y el log de estado los añades cuando la tarea pasa de una hora o varias sesiones. No montes los cuatro para un cambio pequeño.

¿La compaction no resuelve esto sola?

La compaction estira la ventana de contexto comprimiendo el historial, pero comprimir es lossy: puede descartar la restricción o decisión que necesitabas. Los archivos de memoria son la red de seguridad porque el agente los relee íntegros cuando hace falta, sin depender de qué sobrevivió a la compresión.

Lo que te llevas

Hemos visto que hacer que Codex aguante tareas de horas no va de prompts más largos ni de modelos más potentes, sino de darle una memoria de proyecto que no se borra. Congelar el objetivo en un spec, partir el trabajo en hitos con comandos de validación y dejar que el agente actualice su propio estado convierte la delegación de horas en algo revisable y barato en errores. La verificación continua es lo que mantiene todo honesto: si no se puede validar, no está hecho.

El siguiente paso natural es orquestar varios de estos agentes en paralelo sin que se pisen, que es donde entran los git worktrees y la evidencia obligatoria. Lo cubriré pronto. ¿Has dejado un agente corriendo una tarea larga y has visto cómo se pierde? Cuéntame qué patrón te funciona en los comentarios o en Twitter @sergiomarquezp_.

Agentes long-horizon: por qué se pierden en tareas largas

Sergio Márquez — Mon, 22 Jun 2026 08:00:01 GMT

Agentes long-horizon: por qué se pierden en tareas largas

Lanzas un agente para una refactorización de varias horas. Vuelves después de comer y encuentras un desastre: tres archivos a medias, tests que ya no compilan y un commit con el mensaje "fix". No es que el modelo sea malo. Es que nadie diseñó el flujo para que aguante esa distancia.

TL;DR: qué son los agentes long-horizon y por qué fallan

Qué es: un agente long-horizon es el que ejecuta tareas autónomas de minutos a horas (no una respuesta de un solo turno). Pensá en un coding agent que planifica, escribe, prueba y corrige sin que le aprietes Enter en cada paso.
Por qué importa: los agentes descarrilan en tareas largas por dos causas combinadas, context rot (el contexto se llena de ruido y la calidad cae) y compounding error (el error se multiplica paso a paso). Un error temprano contamina todo lo que viene después.
Qué aprenderás: los cinco mecanismos que sostienen una tarea larga, trocear con spec, checkpoints verificables, aislamiento con git worktrees, verificación continua y un log de evidencia para retomar sin empezar de cero.

El problema: el agente no se rompe en el paso 20

METR publicó en marzo de 2025 una especie de "ley de Moore para agentes": la duración de las tareas que un modelo completa de forma autónoma se duplica cada siete meses aproximadamente. La capacidad sube, pero la fiabilidad por paso no acompaña al mismo ritmo. Y ahí está la trampa.

La matemática es brutal en su simpleza. Si cada paso acierta con probabilidad p y la tarea tiene n pasos, la probabilidad de éxito total es p elevado a n. Con un agente que acierta el 95% de las veces en cada paso (p = 0,95) y una tarea de 20 pasos, el éxito completo cae a 0,95²⁰ ≈ 0,36. Es decir, un 64% de fallo en algo que parecía casi perfecto por paso.

El agente no se descarrila "en el paso 20". Se descarrila en el 3, nadie lo verifica, y los 17 pasos siguientes construyen sobre arena. Por eso un horizonte largo sin guardarraíles es un multiplicador de errores, no de productividad.

¿Qué es un agente long-horizon?

Un agente long-horizon es un sistema basado en LLM que descompone un objetivo en muchos pasos y los ejecuta de forma autónoma durante un periodo largo, manteniendo estado, usando herramientas y verificando su propio progreso. La diferencia con un chatbot no es la inteligencia del modelo, es el harness: la infraestructura que lo mantiene honesto.

Esta distinción confunde a quien empieza: un context window grande no convierte a un agente en long-horizon. La ventana es memoria de trabajo de una sesión, no garantía de que el agente no se pierda. De hecho, llenarla del todo suele empeorar las cosas. Si querés profundizar en cómo guardar estado entre sesiones, lo cubrí en cómo dar memoria a tu agente sin inflar el contexto.

¿Qué es el context rot?

El context rot es la degradación gradual de la calidad de salida de un agente a medida que la ventana de contexto acumula historial: instrucciones viejas, intentos fallidos, payloads enormes de herramientas y requisitos mezclados. No hace falta llenar la ventana del todo. Unos cuantos turnos bastan para que el agente olvide que le dijiste "no hagas commit automático" o repita un fix que ya falló.

Los 5 mecanismos que sostienen una tarea larga

La conclusión primero: no se gana autonomía dándole más libertad al agente, se gana troceando, aislando y verificando. Estos son los cinco mecanismos, ordenados por impacto.

Mecanismo	Qué resuelve	Coste de implementarlo
Spec + plan troceado	Mantiene el objetivo largo sin saturar cada paso	Bajo (un archivo)
Checkpoints verificables	Detecta el error en el paso 3, no en el 20	Bajo
Aislamiento (git worktrees)	Un agente no pisa el trabajo de otro	Medio
Verificación continua	Tests/lint/build como juez objetivo por paso	Medio
Log de evidencia	Retomar desde un checkpoint, no desde cero	Bajo

1. Trocear con un spec, no con un prompt gigante

El patrón que funciona en runs largos es separar el "qué" del "cómo paso a paso". Un archivo de spec lleva la intención de largo alcance (criterios de éxito, restricciones) y un plan trocea el trabajo en unidades que se implementan y prueban de forma aislada. OpenAI describió esto en su run de Codex de 25 horas: un spec.md con el objetivo, un plans.md con milestones y criterios de aceptación, y un runbook de cómo debe operar el agente.

El spec sobrevive a cada paso; el contexto de cada tarea individual se mantiene pequeño. Ese es el truco para no inflar la ventana.

2. Checkpoints verificables después de cada milestone

Un checkpoint no es "guardar progreso". Es un punto donde una verificación objetiva decide si el agente sigue o retrocede. Aquí un harness mínimo y funcional en Python que ejecuta pasos, verifica cada uno y guarda estado para poder retomar:

# Harness minimo: ejecuta pasos, verifica cada uno y guarda estado para retomar
import json
import subprocess
from pathlib import Path

ESTADO = Path("run_state.json")

def cargar_estado():
    # Si existe un checkpoint previo, retomamos desde ahi (no desde cero)
    return json.loads(ESTADO.read_text()) if ESTADO.exists() else {"paso": 0}

def verificar():
    # Verificacion objetiva: el agente no decide si acerto, lo decide el test suite
    r = subprocess.run(["pytest", "-q"], capture_output=True)
    return r.returncode == 0

def ejecutar(pasos):
    estado = cargar_estado()
    for i in range(estado["paso"], len(pasos)):
        pasos[i]()  # aqui el agente hace su trabajo del paso i
        if not verificar():
            raise RuntimeError(f"Checkpoint fallido en paso {i}, deteniendo run")
        estado["paso"] = i + 1
        ESTADO.write_text(json.dumps(estado))  # checkpoint persistido
        print(f"Checkpoint OK: paso {i} verificado")

if __name__ == "__main__":
    tareas = [lambda: print("escribir modulo"), lambda: print("escribir tests")]
    ejecutar(tareas)

La idea clave: el agente no decide si acertó, lo decide la verificación. Y si el paso falla, el run se detiene en lugar de seguir contaminando. Al relanzarlo, cargar_estado() retoma desde el último checkpoint válido.

3. Aislar cada run con git worktrees

Si corres dos agentes en el mismo directorio, ambos editan package.json a la vez y uno sobrescribe al otro en silencio. Te enteras una hora después, cuando los tests fallan. Los git worktrees resuelven esto creando directorios de trabajo separados que comparten el mismo historial:

# Cada agente trabaja en su propio worktree aislado, sin pisarse entre si
git worktree add .worktrees/task-auth -b agent/auth
git worktree add .worktrees/task-api -b agent/api

# Lanzas el agente en cada worktree (terminales separadas)
cd .worktrees/task-auth && claude

# Al terminar: revisas el diff, mergeas y limpias
git merge agent/auth
git worktree remove .worktrees/task-auth

Una advertencia honesta: los worktrees aíslan código, no bases de datos. Si dos agentes corren migraciones contra la misma base, vas a tener conflictos. Usa schemas separados o secuencia esas tareas. Este patrón de aislamiento es primo del que defiende la separación de responsabilidades en arquitectura de software: límites claros para que un cambio no se propague donde no debe.

4 y 5. Verificación continua y log de evidencia

La verificación continua (tests, lint, typecheck, build después de cada milestone) es el juez que rompe la cadena de compounding error. Y el log de evidencia (un documentation.md con qué hizo el agente y qué probó en cada paso) mantiene el run inspectable y permite retomarlo. Sin evidencia, depurar un run de tres horas es arqueología.

Caso real: refactor nocturno sin niñera

En escenarios de producción, el setup típico para una tarea larga (migrar un módulo, actualizar dependencias en varios servicios) combina los cinco mecanismos: spec con criterios de aceptación, plan troceado en milestones de 15-20 minutos cada uno, cada milestone en su worktree, verificación con la suite de tests del repo y un log que se actualiza solo. Herramientas como deer-flow 2.0 de ByteDance empaquetan justo esto (subagentes con contexto acotado, sandboxes y memoria), aunque montar tu propio harness mínimo suele bastar para empezar.

¿Cuándo usar esto en producción? Cuando la tarea supera los 15-20 minutos de trabajo autónomo o toca más de tres o cuatro archivos. Por debajo de eso, el overhead de los worktrees y el spec no compensa: un branch normal y supervisión directa es más rápido.

En Producción

Lo que cambia entre el tutorial y la realidad:

Coste: un run largo quema tokens rápido. Cada checkpoint que falla y reintenta es dinero. Para un desarrollador, una tarea autónoma de varias horas puede costar varios euros por run; con varios al día, hablamos de sumar al presupuesto mensual de APIs (en mi caso, entre 10 y 50 € al mes según la carga). Mide el coste por tarea antes de dejarlo suelto.
Routing por tarea: no uses el modelo más caro para todo. Boilerplate y reescrituras mecánicas van con un modelo barato; la arquitectura y las decisiones difíciles, con el potente. Esta lógica de asignar el modelo correcto a cada fase la detallé en planificar con un modelo y ejecutar con otro en Claude Code.
Recuperación ante fallo: el run va a fallar a mitad. La pregunta no es si, es cuándo. El checkpoint persistido es lo que diferencia "retomo desde el paso 8" de "vuelvo a empezar y pago otra vez tres horas".
Observabilidad: instrumenta el gasto y los fallos por sesión. Volar a ciegas en un run autónomo es la forma más cara de descubrir que tu agente entró en un bucle de reintentos.
Límite de autonomía: más libertad no es mejor. Acota ventanas de autonomía y resetea estado con frecuencia para cortar la propagación de errores.

Errores comunes y depuración

Error: el agente reporta "hecho" pero nada funciona. Causa: no hay verificación objetiva, el agente se autoevalúa. Solución: que un test suite externo decida el éxito de cada checkpoint, nunca el propio agente.
Error: la calidad cae a mitad del run. Causa: context rot, la ventana se llenó de intentos fallidos y ruido. Solución: trocea en subtareas con contexto fresco; usa subagentes con contexto acotado por tarea.
Error: dos agentes corrompen archivos compartidos. Causa: comparten directorio de trabajo. Solución: git worktrees, un worktree por agente.
Error: un fallo a las 2 horas obliga a empezar de cero. Causa: no hay estado persistido. Solución: checkpoints en disco después de cada milestone verificado.

Preguntas frecuentes

¿Un context window más grande resuelve el problema de las tareas largas?

No. Una ventana grande es memoria de trabajo de una sesión, pero llenarla acelera el context rot y degrada la calidad. La solución es trocear y verificar, no acumular más texto en un solo turno.

¿Cuándo merece la pena montar un harness con checkpoints?

Cuando la tarea supera los 15-20 minutos de trabajo autónomo o toca varios archivos o servicios. Para cambios cortos y supervisados, el overhead no compensa y un flujo manual con tests es más ágil.

¿Los git worktrees aíslan todo?

Aíslan código y dependencias por directorio, pero no bases de datos. Si tus agentes corren migraciones contra la misma base, necesitas schemas separados o contenedores por worktree, o secuenciar esas tareas.

Cierre

Hemos visto que un agente no se descarrila por falta de inteligencia, sino por falta de estructura: el context rot ensucia su memoria y el compounding error multiplica un fallo temprano hasta arruinar el run. La autonomía real no viene de soltarle la correa, viene de trocear el trabajo, verificar cada checkpoint, aislar cada run y dejar evidencia para retomar sin pagar dos veces. Si solo te llevas una idea, que sea esta: que el éxito de cada paso lo decida un test, no el propio agente.

Para validar que esos checkpoints miden lo correcto, vale la pena revisar cómo evaluar tu IA en producción y no solo offline, y si tu run lanza tareas paralelas, el patrón de subagentes que lanzan subagentes encaja directamente aquí.

¿Has dejado un agente trabajando solo varias horas? ¿Qué se rompió y cómo lo recuperaste? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo entro en cómo coordinar varios de estos agentes sin que el coste se dispare.

Dale memoria a tu agente de IA sin inflar el contexto

Sergio Márquez — Sun, 21 Jun 2026 08:00:01 GMT

Dale memoria a tu agente de IA sin inflar el contexto

TL;DR: La memoria de un agente es el almacenamiento externo que le deja recordar decisiones y hechos entre sesiones, en vez de empezar de cero cada vez. La clave no es guardarlo todo, sino persistir hechos estables y recuperar por relevancia. En este artículo verás los tipos de memoria (corto vs largo plazo, episódica, semántica, procedimental), el patrón mínimo reproducible (capturar, recuperar, podar) con código funcional usando Mem0 y el store de LangGraph, y qué cambia cuando esto va a producción: coste, latencia y el riesgo real de memoria contaminada.

El problema: tu agente tiene amnesia anterógrada

Un agente sin memoria es un buen empleado con amnesia: cada mañana le explicas el proyecto entero y por la tarde lo ha olvidado. Le dices que prefieres Python sobre Java, que el repo usa arquitectura hexagonal, que ya descartasteis una librería por licencia. Mañana, nada. Vuelve a preguntar lo mismo.

Esto pasa porque, por defecto, un LLM solo "ve" lo que cabe en su ventana de contexto durante una invocación. Cuando la sesión termina, ese estado se evapora. La memoria de agentes (en inglés, agent memory) es lo que separa un chatbot de un agente útil: el almacenamiento persistente y consultable que sobrevive entre ejecuciones.

El error que veo repetido (y que yo mismo cometí al principio) es resolverlo a lo bruto: volcar todo el historial de conversación en cada prompt. Funciona en la demo. En producción te come el presupuesto, dispara la latencia y, a partir de cierto tamaño, confunde al modelo. Como ya expliqué al hablar de cómo cruzar los 200k tokens te vacía el presupuesto, más contexto no es gratis ni siempre mejor.

¿Qué es la memoria de un agente?

La memoria de un agente es un sistema externo que codifica, almacena y recupera de forma selectiva información de interacciones pasadas, para que el agente mantenga continuidad y adapte su comportamiento sin reentrenar el modelo. No es la ventana de contexto (eso es memoria de trabajo, volátil) ni los pesos del modelo (eso es conocimiento congelado en el entrenamiento).

Conviene separar dos ejes. El primero es el horizonte temporal:

Memoria a corto plazo: el contexto de la sesión actual. Turnos recientes, estado de la tarea en curso. Vive en la ventana de contexto y muere al cerrar.
Memoria a largo plazo: almacenamiento durable fuera del contexto. Persiste entre sesiones y se recupera bajo demanda.

El segundo eje, dentro del largo plazo, es el tipo de información. La taxonomía que se ha estandarizado en 2026 viene de la ciencia cognitiva:

Tipo	Qué guarda	Ejemplo en un agente de código
Episódica	Eventos y secuencias concretas, con marca temporal	"El 14/06 desplegamos a GKE y falló por el límite de memoria del pod"
Semántica	Hechos y conceptos estables sobre el mundo o el usuario	"El proyecto usa FastAPI y Pinecone como vector DB"
Procedimental	Flujos y habilidades aprendidas, el "cómo se hace"	"Para releases, primero corre los tests de integración, luego tag semver"

Para un dev junior, quédate con esto: la episódica es tu diario ("qué pasó y cuándo"), la semántica es tu libreta de hechos ("qué es verdad"), y la procedimental es tu manual de procedimientos ("cómo se hacen las cosas aquí").

Qué guardar de verdad (y qué no)

La regla operativa: persiste hechos estables y decisiones, no el historial crudo entero. Guardar cada token de cada conversación es la forma más rápida de tener una memoria cara, lenta y ruidosa.

Mi heurística después de meses montando esto en sistemas reales:

Guarda: preferencias del usuario, decisiones tomadas y su razón, restricciones del proyecto, hechos que rara vez cambian.
No guardes: el chit-chat, los pasos intermedios de razonamiento, datos que puedes recalcular, información sensible sin necesidad.
Recupera por relevancia, no por volumen: trae los 3-5 recuerdos pertinentes a la tarea actual, no el dump completo. Esto controla coste y latencia a la vez.

El paso de extracción es donde un buen sistema de memoria gana al "guardar todo". En lugar de almacenar el mensaje literal, un LLM destila el hecho: de "uy, pues la verdad es que prefiero que me respondas en español y con ejemplos cortos" sale el hecho estable "el usuario prefiere respuestas en español con ejemplos cortos".

Cómo se guarda: vector, clave-valor o grafo

Hay tres sustratos de almacenamiento, y la elección no es cosmética:

Clave-valor / documento: simple y barato. Ideal para perfiles de usuario y hechos estructurados. Recuperas por clave exacta, no por significado.
Vectorial (embeddings): guardas el hecho como vector y recuperas por similitud semántica. Es la base de la memoria semántica. Si esto te suena a RAG, es porque comparte la maquinaria: misma lógica de chunking y embeddings que en un pipeline de datos.
Grafo de conocimiento: modela entidades y relaciones ("Sergio trabaja en VITALY", "VITALY usa Pinecone"). Brilla cuando necesitas razonar sobre conexiones, en la línea de lo que vimos con el knowledge graph de tu código.

En la práctica, los sistemas serios combinan varios. El truco de recuperación que más rinde es el mismo que en búsqueda híbrida en RAG: fusionar similitud vectorial, BM25 (keyword) y matching de entidades en una sola puntuación. La memoria de un agente, al final, es RAG sobre tus propias interacciones.

El patrón mínimo reproducible: capturar, recuperar, podar

Tres operaciones bastan para una memoria útil: captura al cerrar una tarea, recupera al abrir la siguiente, y poda para que no crezca sin control. Vamos con código funcional.

El camino más corto en Python es Mem0 (Apache 2.0, framework-agnóstico). Instalación:

# Instala el SDK; necesita una API key de LLM para extraer y embeber hechos
# pip install mem0ai
# export OPENAI_API_KEY="tu-api-key"

from mem0 import Memory

memory = Memory()  # por defecto usa un vector store local en memoria

Paso 1, capturar. Le pasas los mensajes y Mem0 extrae los hechos estables por ti, no guarda el texto crudo:

# add() destila hechos de la conversación y los asocia a un user_id
mensajes = [
    {"role": "user", "content": "Prefiero Python y respuestas en español, cortas."},
    {"role": "assistant", "content": "Anotado, lo tendré en cuenta."},
]
memory.add(mensajes, user_id="sergio")
# Output esperado: se almacena algo como
# "Prefiere Python" / "Prefiere respuestas en español y cortas"

Paso 2, recuperar. Al empezar una nueva tarea, traes solo lo relevante a la consulta actual:

# search() devuelve los recuerdos más pertinentes, no todo el historial
recuerdos = memory.search("¿En qué lenguaje respondo?", user_id="sergio", limit=3)
for r in recuerdos["results"]:
    print(r["memory"])  # -> "Prefiere Python", "Prefiere respuestas en español..."

Esos 3 recuerdos los inyectas en el system prompt de la siguiente llamada. Pasas de volcar 50 turnos a inyectar 3 hechos: ahí está el ahorro de tokens y latencia.

Paso 3, podar. Sin poda, la memoria crece hasta volverse ruido. La estrategia básica es decaimiento por relevancia y recencia: lo poco recuperado y antiguo, fuera.

# Poda simple: elimina recuerdos viejos y casi nunca recuperados
def podar(memory, user_id, dias_max=90, min_accesos=1):
    for m in memory.get_all(user_id=user_id)["results"]:
        viejo = m.get("age_days", 0) > dias_max
        ignorado = m.get("hits", 0) < min_accesos
        if viejo and ignorado:
            memory.delete(m["id"])  # libera espacio y reduce ruido

Este esquema captura-recupera-poda es agnóstico a la herramienta. Si trabajas con LangGraph, el patrón es idéntico pero con su Store: store.put((namespace,), key, valor) para guardar y store.search((namespace,), query=...) para recuperar, con persistencia en Postgres, Redis o MongoDB en vez de en memoria.

Comparativa: frameworks de memoria en 2026

Si no quieres montarlo a mano, el ecosistema maduró bastante. A junio de 2026, estas son las opciones que considero:

Framework	Almacenamiento	Cuándo usarlo	Cuándo evitarlo
Mem0	Vector + grafo (grafo solo en Pro)	Caso general, mayor comunidad, SDK Python y TS	Necesitas grafo gratis o reranking avanzado open-source
Letta (ex MemGPT)	Por niveles, estilo SO	Quieres un runtime completo con memoria auto-editable	Solo quieres una librería ligera in-process
Zep / Graphiti	Grafo temporal	Necesitas saber cómo cambian los hechos en el tiempo	Tu caso no tiene dimensión temporal relevante
LangMem	Vector	Ya usas LangGraph y quieres mínima fricción	Necesitas multi-framework o TypeScript

Mi recomendación honesta: para un proyecto pequeño o mediano, empieza con Mem0 o LangMem en su tier gratis. No saltes a una plataforma gestionada hasta que tengas evidencia de que la necesitas. Y mide el benchmark relevante: LoCoMo es el estándar de facto para evaluar recuerdo en conversaciones largas, pero como siempre, tu tarea no es la del benchmark.

En Producción

Aquí es donde el tutorial y la realidad se separan. Cuatro frentes que cambian todo:

Coste. Cada add() con extracción dispara una llamada al LLM, y cada search() calcula embeddings. No es gratis. En un proyecto personal con tráfico moderado, la memoria me ha supuesto entre 10 y 30 € al mes en APIs, casi todo en la extracción. Truco: no extraigas en cada turno, hazlo por lotes al cerrar la tarea. La captura no necesita ser síncrona.

Latencia. Recuperar memoria añade un salto antes de responder. Mantén el limit bajo (3-5 recuerdos) y cachea el perfil estable del usuario para no buscarlo en cada mensaje. La memoria a corto plazo va en contexto; solo bajas al store para lo de largo plazo.

Memoria contaminada (memory poisoning). Este es el riesgo serio y poco hablado. Si el agente guarda una alucinación o una inyección maliciosa como "hecho válido", la arrastra entre sesiones. A diferencia de un RAG estático, donde el error se aísla en una recuperación, en memoria evolutiva los errores son acumulativos y persistentes. Aparece también el drift semántico: resumir un hecho una y otra vez lo va distorsionando. Mitigación: separa un log episódico inmutable (la fuente de verdad cruda) de la capa semántica mutable, para poder reconciliar y revertir si el comportamiento se degrada.

Staleness (hechos caducados). "Sergio trabaja en VITALY" es cierto hasta que cambia de empleo, y entonces es confiadamente falso. El decaimiento maneja los recuerdos poco relevantes, pero la caducidad de hechos muy recuperados sigue siendo un problema abierto. Para datos con fecha de caducidad conocida, guárdala explícitamente y filtra al recuperar.

Errores comunes y depuración

Error: el agente no recupera lo que guardaste. Causa: la descripción del recuerdo es vaga y no matchea la query semántica. Solución: guarda hechos atómicos y específicos, no párrafos; un hecho por entrada.
Error: la factura de API se dispara. Causa: extraes memoria en cada turno y recuperas sin límite. Solución: captura por lotes al cerrar tarea y fija limit en la recuperación.
Error: el agente repite información obsoleta. Causa: staleness, el hecho viejo sigue puntuando alto. Solución: versiona hechos mutables con timestamp y prioriza el más reciente al recuperar.
Error: la memoria crece sin parar y la latencia sube. Causa: no hay poda. Solución: job periódico de decaimiento por relevancia y recencia.

Preguntas frecuentes

¿Memoria de agente es lo mismo que RAG?

Comparten la maquinaria (embeddings, vector store, recuperación), pero el propósito difiere. RAG recupera de un corpus externo estático de documentos; la memoria de un agente recupera de sus propias interacciones pasadas, que crecen y cambian con el uso. La memoria es, en esencia, RAG aplicado a tu historial con un paso extra de extracción y olvido.

¿Necesito una vector database para dar memoria a mi agente?

No siempre. Para hechos estructurados y perfiles de usuario, un store clave-valor o incluso ficheros en disco bastan y son más baratos. La vector DB la necesitas cuando quieres recuperación por significado sobre texto libre. Empieza simple y añade el vector store solo si la recuperación semántica te hace falta.

¿Cuánto cuesta montar memoria persistente en un proyecto pequeño?

El coste dominante es el LLM que extrae y embebe hechos. En proyectos pequeños o medianos, hablamos de un rango aproximado de 10 a 30 € al mes en APIs si capturas por lotes y limitas la recuperación. La infraestructura de almacenamiento (Redis, Postgres con pgvector) puede correr gratis en local o por unos pocos euros gestionada.

Cierre

Hemos visto que dar memoria a un agente no es guardarlo todo, sino capturar hechos estables, recuperarlos por relevancia y podar lo que sobra. El patrón mínimo capturar-recuperar-podar funciona igual con Mem0, con el store de LangGraph o montado a mano; lo que cambia en producción es el criterio: vigilar el coste de extracción, la latencia de recuperación y, sobre todo, evitar que una alucinación se convierta en un "hecho" que tu agente arrastre para siempre. La diferencia entre un chatbot que repite preguntas y un agente que recuerda tus decisiones está justo en esa capa.

¿Has montado memoria persistente en algún agente, a mano o con framework? ¿Te has topado con el problema de los hechos caducados o la memoria contaminada? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo quiero bajar a tierra los agentes de horizonte largo: cómo sostienen una tarea de horas combinando memoria, sandbox y checkpoints sin perderse a mitad de camino.

Elige tu modelo de IA por coste real, no por el benchmark

Sergio Márquez — Sat, 20 Jun 2026 08:00:01 GMT

Elige tu modelo de IA por coste real, no por el benchmark

TL;DR: Para elegir tu modelo de IA por coste no necesitas un benchmark de marketing, necesitas una eval propia: una tarea pequeña y repetible que mida cómo se comporta el modelo en TU caso. El equipo de VS Code ejecutó la misma tarea trivial 50.974 veces sobre 30 modelos y encontró diferencias de hasta 70 veces en tokens de salida para un resultado idéntico. En este artículo verás qué es una eval, por qué el tamaño del modelo no predice el gasto y cómo montar una para decidir por coste y esfuerzo, no por hype.

El problema: eliges modelo por la tabla equivocada

La escena se repite cada vez que sale un modelo nuevo: lees el benchmark, ves que gana en SWE-bench o Terminal-Bench, y lo enchufas a tu agente. Tres semanas después llega la factura y no cuadra. El modelo "más listo" gastaba tres veces más tokens que el anterior para hacer lo mismo.

El benchmark mide si el modelo puede resolver la tarea. No mide cuánto le cuesta resolverla en tu flujo. Y con la facturación por uso que ya es estándar en herramientas como GitHub Copilot desde junio de 2026, cada token de salida es dinero y latencia. La pregunta operativa no es "¿cuál saca mejor nota?", sino "¿cuál me sale a cuenta para la tarea que hago de verdad?".

Esto conecta con algo que ya he tocado antes: los benchmarks de coding agéntico y por qué eliges mal tu modelo. El experimento de VS Code lo demuestra con datos a una escala que pocos equipos pueden igualar.

¿Qué es una eval?

Una eval es un test repetible que mide cómo se comporta un modelo en tu tarea concreta, no en un benchmark genérico. Le das al modelo la misma entrada fija, registras lo que hace (salida, pasos, herramientas usadas) y comparas entre modelos o entre versiones. Si la tarea no cambia, todo lo que cambie entre ejecuciones viene del modelo o del sistema que lo rodea.

La clave es la estabilidad. Una tarea simple con una respuesta correcta inequívoca se convierte en un instrumento sensible: reacciona a regresiones en tu harness, a cambios de versión del modelo y a diferencias de comportamiento, sin el ruido de un problema complejo que interpretar.

El experimento de las 50.000 ejecuciones

VS Code montó la eval más tonta posible, que llaman say_hello: una sola instrucción, "Add HELLO to HELLO.txt", con dos comprobaciones (que el archivo exista y contenga "HELLO"). Empezó como un simple smoke test antes de cada suite de benchmarks. En seis meses acumuló 50.974 ejecuciones sobre 30 modelos.

El resultado interesante no es que todos los modelos sepan escribir un archivo de cinco caracteres. Es cuánto trabajo gastan en hacerlo. Un desarrollador haría una sola llamada: crear el archivo. Los modelos, en cambio, se reparten en cuatro bandas muy distintas de tokens de salida para el MISMO resultado.

Banda	Tokens de salida (media)	Múltiplo del mínimo	Comportamiento típico
Eficiente	menos de 150	1-3×	Va directo a crear el archivo
Moderada	150-400	3-8×	Lee estado o explora un poco antes
Alto coste	400-1.000	8-12×	Planifica y explora siempre
Extrema	1.441-3.676	29-74×	Narra su razonamiento sin parar

El mínimo realista para esta tarea es unos 50 tokens. La diferencia entre el modelo más austero y el más pesado es de aproximadamente 70 veces para una salida idéntica. Eso, multiplicado por miles de peticiones al mes, es la diferencia entre 10€ y 50€ de factura por exactamente el mismo trabajo.

El hallazgo que rompe la intuición: el tamaño no predice el gasto

La primera hipótesis era que los modelos grandes razonan más y por tanto gastan más. Los datos dicen lo contrario. En el estudio, dentro de una misma familia:

El modelo grande usaba 160 tokens y 2,1 llamadas de herramienta de media. El más disciplinado de su familia.
Su hermano pequeño usaba 485 tokens y 3,7 llamadas. Más overhead que el grande.
El modelo más derrochador de todos era un "mini": 3.676 tokens de media para escribir cinco caracteres.

La conclusión es que lo que predice el coste no es el número de parámetros, sino la calibración del esfuerzo: si el modelo sabe distinguir una tarea de un paso de una de treinta pasos. Las generaciones más nuevas, dentro de cada familia, tienden a ser más disciplinadas. Es madurez de entrenamiento, no tamaño. Y esa calibración aparece directamente en la factura.

Dónde se va el esfuerzo (y por qué te cuesta dinero)

Como la eval captura la secuencia completa de llamadas, se ven los patrones de derroche. Estos son los que repiten los modelos sobre una tarea de un solo paso:

Planificar antes de actuar (52-99% de las veces): dibuja un checklist antes de crear un archivo de cinco caracteres.
Explorar un workspace vacío (56-96%): lista directorios o busca archivos en una carpeta que está vacía. Como buscar pistas en una habitación vacía.
Narrar el razonamiento (1.441-3.676 tokens): emite mucho más texto del que cualquier llamada necesita, reconfirmando la tarea una y otra vez.
Usar la herramienta equivocada: un patch/edit complejo en vez de una creación simple. Como usar una fresadora CNC para cortar un folio.

Ninguno de estos es un fallo de corrección: todos pasan la eval. Pero todos cuestan tokens, latencia y presupuesto. En tareas largas, planificar y explorar previene errores caros y vale la pena. En una de un paso, es puro desperdicio.

Implementación: monta tu propia eval mínima

No necesitas una suite privada de benchmarks. Empieza con la tarea más pequeña que tenga una respuesta correcta inequívoca, ejecútala muchas veces y registra bien. Aquí va un esqueleto funcional en Python que vale para cualquier modelo con API.

Primero, define la tarea y la métrica. Lo importante: guarda la secuencia de herramientas, no solo el contador.

# Define una eval: entrada fija, verificacion clara y traza de comportamiento
from dataclasses import dataclass, field

@dataclass
class EvalResult:
    passed: bool
    output_tokens: int
    tool_sequence: list = field(default_factory=list)  # ["plan", "create_file"] no solo "2"

def check(workspace: dict) -> bool:
    # La asercion inequivoca: el archivo existe y contiene lo esperado
    return workspace.get("HELLO.txt") == "HELLO"

Segundo, ejecuta la tarea N veces contra un modelo y acumula resultados. Aquí run_agent es tu llamada real al modelo (la que ya tengas montada con tu SDK), que devuelve el workspace, los tokens de salida y la secuencia de tools.

# Ejecuta la misma tarea N veces para que las diferencias vengan del modelo, no del azar
def run_eval(model: str, n: int = 50) -> list:
    results = []
    for _ in range(n):
        workspace, out_tokens, tools = run_agent(model, prompt="Add HELLO to HELLO.txt")
        results.append(EvalResult(check(workspace), out_tokens, tools))
    return results

Tercero, y esto es lo que de verdad importa: traduce los tokens a coste por respuesta correcta. Un modelo que acierta a la primera con pocos tokens puede salir más barato que uno "barato" que necesita tres reintentos.

# Coste por acierto = lo unico que importa al elegir modelo en produccion
def cost_per_correct(results: list, price_per_1k_eur: float) -> float:
    correct = [r for r in results if r.passed]
    if not correct:
        return float("inf")
    total_tokens = sum(r.output_tokens for r in correct)
    return (total_tokens / 1000) * price_per_1k_eur / len(correct)

# Ejecucion minima: compara dos modelos sobre la misma tarea
for model, price in [("modelo-grande", 0.012), ("modelo-mini", 0.004)]:
    res = run_eval(model, n=50)
    print(f"{model}: {cost_per_correct(res, price):.5f} EUR/acierto")

El truco del cost_per_correct es que un modelo con precio por token más alto pero que va directo puede ganarle a uno barato que narra 3.000 tokens. La factura no la decide el precio por token, la decide el comportamiento.

Aplicación práctica: ¿cuándo usar esto?

Esta tabla resume cuándo una eval pequeña te da criterio real y cuándo te engaña:

Úsala para	Evítala (o complétala) para
Detectar regresiones del harness o del proveedor	Concluir que un modelo es "mejor" en general
Comparar coste/esfuerzo de modelos en tu tarea típica	Tareas largas multi-paso (mide eso aparte)
Preflight antes de cambiar de versión de modelo	Optimizar tu producto sobre una sola tarea
Decidir el modelo por defecto de un agente	Sustituir la evaluación en producción real

Un patrón que funciona bien: separar planificación y ejecución. Usar un modelo con buen razonamiento para planificar y luego cambiar a uno más austero y rápido para implementar. Lo he descrito en detalle al hablar de planificar con un modelo y ejecutar con otro en Claude Code, y encaja exactamente con lo que dicen estos datos: no pongas el modelo que sobrepiensa a escribir un "HELLO".

En Producción

Llevar una eval del cuaderno al día a día cambia varias cosas. Estas son las que importan:

Registra la secuencia, no el conteo. Saber que hubo 4 llamadas es incompleto. Saber que el modelo planificó, listó el directorio, buscó y luego creó el archivo te dice de dónde vino el coste. Loguea tool_sequence y output_tokens, no solo pass: true.
Coste real en euros. Para un desarrollador con tráfico modesto, la diferencia entre la banda eficiente y la extrema es pasar de unos 10€/mes a 40-50€/mes en APIs por exactamente el mismo trabajo. Multiplica tokens por tu precio y decide con el número delante.
Vigila el cache y los cambios a media sesión. Reanudar una sesión tras una pausa larga con la caché expirada, o cambiar el nivel de esfuerzo a mitad de tarea, dispara el coste sin avisar. Esto enlaza con cómo cruzar los 200k tokens te vacía el presupuesto: el harness importa tanto como el modelo.
No optimices sobre una sola tarea. say_hello es un termómetro, no el mapa entero. Para decidir el modelo de un agente real, corre un set diverso de tareas. La eval pequeña es la señal de alarma, no la decisión final.
El esfuerzo es ajustable. Muchos modelos de 2026 traen un dial de reasoning effort. Si ves que un modelo sobrepiensa tareas simples, baja el effort por defecto y reserva el alto para planificación o debugging de varios pasos.

Errores comunes y depuración

Error: tu eval da resultados distintos cada vez sin tocar nada. → Causa: la tarea es ambigua o el workspace no parte del mismo estado. → Solución: fija el estado inicial y elige una aserción binaria. Si la tarea tiene varias respuestas válidas, no es una eval estable.

Error: dos modelos "empatan" en pass rate pero uno cuesta el triple. → Causa: solo mides si pasa, no cómo. → Solución: añade output_tokens y tool_sequence a cada resultado y compara coste por acierto, no acierto pelado.

Error: el modelo pequeño que elegiste "para ahorrar" gasta más que el grande. → Causa: asumiste que tamaño igual a coste. → Solución: mídelo. La calibración del esfuerzo no se ve en la ficha técnica, solo en las trazas.

Preguntas frecuentes

¿Una eval de cinco líneas sirve de algo de verdad?

Sí, como termómetro. Una tarea trivial y estable, ejecutada con consistencia y bien registrada, detecta regresiones del harness, incidentes de infraestructura y cambios de comportamiento del modelo. No reemplaza la evaluación en producción, pero es la alarma más barata que puedes montar.

¿Por qué un modelo más pequeño puede costar más que uno grande?

Porque el coste lo manda el comportamiento, no el tamaño. Un modelo poco calibrado planifica, explora y narra incluso en tareas de un paso, gastando miles de tokens de salida. Uno mejor entrenado reconoce que la tarea es simple y va directo, aunque tenga más parámetros.

¿Esto solo aplica a agentes de coding?

No. Cualquier sistema con LLM (RAG, clasificación, extracción) se beneficia de una eval mínima con respuesta inequívoca para vigilar coste y comportamiento. El principio es el mismo: mide tu tarea, no el benchmark de otro.

La lección que se queda

Hemos visto que elegir modelo por el benchmark de marketing es elegir por la métrica equivocada. Lo que separa una factura controlada de una sorpresa a fin de mes no es qué modelo saca mejor nota, sino cuál calibra el esfuerzo a la tarea que tú haces de verdad. Y eso solo se ve montando una eval propia, pequeña y estable, que registre la secuencia de pasos y traduzca tokens a euros. La selección de modelo no es un "elige el más listo y ya": es una decisión continua de coste y fiabilidad. Si quieres ir un paso más allá de la eval offline, vale la pena leer por qué tu evaluación offline miente y conviene medir en producción.

¿Has montado evals propias para decidir tu modelo, o sigues tirando del benchmark del día? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. En el próximo post quiero entrar en cómo automatizar el routing de modelos para que esa decisión deje de ser manual.

BYOK en VS Code: usa tu API key sin pagar Copilot

Sergio Márquez — Fri, 19 Jun 2026 08:00:01 GMT

BYOK en VS Code: usa tu API key sin pagar Copilot

TL;DR: BYOK (bring your own key) en VS Code te deja conectar tu propia API key de Anthropic, OpenAI, Gemini, OpenRouter o un modelo local con Ollama directamente en el chat del editor, sin depender de la cuota cerrada de Copilot. El uso lo factura tu proveedor, no cuenta contra los límites de Copilot, y desde la versión 1.122 funciona sin iniciar sesión en GitHub. En este artículo verás cómo configurarlo paso a paso, cuándo compensa de verdad y qué vigilar antes de usarlo en el día a día.

El problema: pagas dos veces por lo mismo

Si ya gastas entre 10 y 50 euros al mes en la API de Anthropic u OpenAI para tus proyectos, pagar además la suscripción de Copilot para usar esos modelos dentro de VS Code es pagar dos veces. Y cuando llegas al límite de peticiones de tu plan, el editor te corta justo cuando estás en mitad de un refactor.

Hay un segundo problema, menos visible: la privacidad. Con la cuota cerrada de Copilot, tu código pasa por la infraestructura de GitHub. En proyectos con datos sensibles o cláusulas de confidencialidad, eso es una conversación incómoda con el equipo de seguridad.

BYOK en VS Code resuelve las dos cosas: usas el modelo que tú eliges, pagas solo lo que consumes y el tráfico va a tu proveedor (o a tu propia máquina si usas un modelo local). El cambio dejó de ser experimental: GitHub lo marcó como disponible de forma general el 22/04/2026.

¿Qué es BYOK (bring your own key)?

BYOK es la capacidad de VS Code de usar cualquier modelo de un proveedor compatible introduciendo tu propia API key, en lugar de los modelos integrados que vienen con Copilot. Una vez configurado, el modelo aparece en el selector del chat y funciona en cualquier sitio donde uses chat: el agente integrado y los agentes personalizados.

Dos detalles que marcan la diferencia frente a un tutorial genérico:

BYOK no aplica a las autocompletados de código (esos seguirán usando el modelo de Copilot). Solo afecta al chat y a los agentes.
El consumo lo factura tu proveedor y no descuenta de la cuota de peticiones de Copilot. Esto es justo lo que evita el doble coste.

Las claves se guardan localmente en tu equipo y no se comparten entre proveedores, según la documentación de VS Code. Si vienes del mundo de los modelos locales, el patrón te sonará a lo que ya cuento en correr un LLM en local con Ollama sin API key: control total a cambio de gestionar tú la infraestructura.

Implementación paso a paso

El punto de entrada es siempre el mismo comando. Abre la paleta de comandos (Ctrl/Cmd + Shift + P) y ejecuta Chat: Manage Language Models, o pulsa el icono del engranaje en el selector de modelos del chat.

Opción 1: proveedor integrado (la vía rápida)

VS Code trae una lista de proveedores listos para usar: Anthropic, Gemini, OpenAI, OpenRouter, Azure y, para modelos locales, Ollama y Foundry Local.

En el editor de modelos, pulsa Add Models y elige el proveedor (por ejemplo, Anthropic).
Introduce tu API key y, si el proveedor lo pide, el endpoint.
Selecciona qué modelos de ese proveedor quieres habilitar.
El modelo aparece en el selector del chat. Si no sale, reinicia VS Code.

Opción 2: endpoint OpenAI-compatible o configuración por JSON

Cuando tu proveedor no está en la lista o usas un gateway propio, configuras un endpoint manualmente. VS Code abre un archivo chatLanguageModels.json donde defines el modelo. Importante: tienes que indicar el tipo de API correcto, que puede ser Chat Completions, Responses o Messages según lo que soporte el modelo.

Este es el ejemplo oficial para un endpoint de Anthropic usando la API Messages. La clave nunca se escribe a fuego: usa una variable de entorno o el almacén de credenciales.

[
  {
    "name": "Anthropic",
    "vendor": "customendpoint",
    "apiKey": "YOUR_API_KEY",
    "apiType": "messages",
    "models": [
      {
        "id": "claude-sonnet-4-6",
        "name": "Claude Sonnet 4.6",
        "url": "https://api.anthropic.com/v1/messages",
        "toolCalling": true,
        "vision": true,
        "maxInputTokens": 200000,
        "maxOutputTokens": 64000
      }
    ]
  }
]

Fíjate en toolCalling: true: si lo dejas en falso, el modelo no podrá usar herramientas y los agentes se quedarán cojos. Es el error de configuración más habitual.

Opción 3: modelo local con Ollama (cero coste de API)

Para trabajar sin pagar ni API y con todo el tráfico en tu máquina, Ollama es la vía más directa. Requisitos: VS Code 1.113 o superior y la extensión de Copilot Chat 0.41.0 o superior.

Arranca Ollama y descarga un modelo de código (por ejemplo, uno de la familia Qwen para coding).
En Manage Language Models, pulsa Add Models y selecciona Ollama.
VS Code carga tus modelos locales; selecciónalos en el picker.

Un detalle reciente y útil: desde la versión 1.122, BYOK funciona sin iniciar sesión en GitHub y sin un plan de Copilot. Esto habilita un flujo totalmente offline con modelos locales, algo que antes obligaba a estar logueado.

Cuándo usar BYOK y cuándo no

BYOK no es siempre la mejor opción. Esta tabla resume el criterio que aplico antes de configurarlo en un equipo:

Cuándo usar BYOK	Cuándo evitarlo
Ya pagas la API de un proveedor y no quieres duplicar coste	Solo usas autocompletados (BYOK no los cubre)
Necesitas un modelo concreto que Copilot no ofrece	Quieres una factura única y predecible cada mes
Datos sensibles que deben ir a tu proveedor o quedarse en local	Tu organización tiene la política BYOK deshabilitada
Chocas contra los límites semanales de peticiones de tu plan	No quieres gestionar claves ni monitorizar tokens

El caso de uso más claro que veo en equipos de producto: un desarrollador que ya tiene presupuesto de API para su pipeline de procesamiento de documentos con LangChain y reutiliza esa misma clave para el chat del editor. Una clave, un proveedor, un solo sitio donde mirar el gasto.

En Producción

La diferencia entre el tutorial y el uso diario está en el control del gasto y los permisos. Esto es lo que cambia.

Coste y monitorización. BYOK traslada el control del gasto a ti. Sin la red de seguridad de la cuota de Copilot, una sesión larga con un modelo caro puede dispararse rápido. Revisa el panel de uso de tu proveedor a diario las primeras semanas y fija alertas de gasto. El razonamiento de coste por sesión es el mismo que detallo en por qué cruzar los 200k tokens vacía tu presupuesto: el contexto largo es lo que más cuesta.

Elección de modelo. No envíes el modelo top a cada petición por inercia. Para tareas repetitivas, un modelo de gama media suele dar el 90% de la calidad a una fracción del coste. Antes de fijar tu modelo por defecto, conviene medirlo con tus propias tareas, no fiarte de los benchmarks de coding agéntico genéricos.

Permisos y organización. En cuentas Copilot Business o Enterprise, la política "Bring Your Own Language Model Key in VS Code" la controla el administrador desde GitHub.com. Está activada por defecto, pero un admin puede desactivarla. Si BYOK no aparece, ese es el primer sitio donde mirar.

Límites de tasa. Pasas de los límites de Copilot a los de tu proveedor. Si compartes una sola clave en un equipo, los rate limits se agotan antes de lo que crees. Considera una clave por persona o por proyecto.

Errores comunes y depuración

Error: el modelo no aparece en el selector tras configurarlo. Causa: VS Code no recarga la lista al vuelo. Solución: reinicia el editor; la documentación lo indica explícitamente.
Error: los agentes no pueden usar herramientas con tu modelo. Causa: toolCalling está en falso o el modelo no soporta tool use. Solución: ponlo en true en el JSON y verifica que el modelo lo permite.
Error: respuestas con error 401 o de autenticación. Causa: API key inválida, expirada o sin saldo en el proveedor. Solución: regenera la clave y comprueba el crédito en el panel del proveedor.
Error: BYOK no aparece en una cuenta de empresa. Causa: el administrador desactivó la política. Solución: que el admin habilite la política en los ajustes de Copilot en GitHub.com.

Preguntas frecuentes

¿BYOK en VS Code cubre el autocompletado de código?

No. BYOK solo funciona en el chat y en los agentes, incluido el agente integrado y los personalizados. Los autocompletados en línea siguen usando el modelo de Copilot.

¿Necesito una suscripción de Copilot para usar BYOK?

No es obligatorio. Desde la versión 1.122 de VS Code, BYOK funciona sin iniciar sesión en GitHub y sin un plan de Copilot, lo que permite escenarios totalmente offline con modelos locales como Ollama.

¿El consumo de BYOK descuenta de mi cuota de Copilot?

No. El uso lo factura directamente tu proveedor (Anthropic, OpenAI, etc.) y no cuenta contra los límites de peticiones de GitHub Copilot. Por eso evita el doble coste si ya pagas la API.

Conclusión

Hemos visto cómo BYOK en VS Code te devuelve el control: eliges el modelo, pagas solo lo que consumes y decides por dónde viaja tu código. La clave está en configurarlo bien (tipo de API correcto, toolCalling activado) y en no perder de vista el gasto, porque pierdes la red de seguridad de la cuota cerrada de Copilot. Para empezar, lo más sensato es probarlo con un modelo local vía Ollama y, si ya pagas una API, reutilizar esa clave antes de duplicar suscripciones.

¿Has migrado tu chat de VS Code a tu propia API key o a un modelo local? Cuéntame qué proveedor y modelo te está funcionando mejor en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo entraré en cómo montar un mini-benchmark casero para decidir qué modelo enviar en cada tipo de tarea sin quemar presupuesto.

Ollama en local: corre un LLM sin API key (y cuándo no)

Sergio Márquez — Thu, 18 Jun 2026 08:00:01 GMT

Ollama en local: corre un LLM sin API key (y cuándo no)

TL;DR: Ollama es la forma más rápida de correr un LLM en tu propia máquina: tres comandos y tienes un modelo abierto (Llama, Qwen, Gemma, GLM) respondiendo sin API key ni factura por token. En esta guía verás cómo instalarlo, qué hardware necesitas según el tamaño del modelo, cómo montar una interfaz tipo ChatGPT con Open WebUI y cómo conectar tu código a su API compatible con OpenAI. Y lo que casi nadie cuenta: cuándo el local-first gana de verdad y cuándo te sale más caro que pagar la nube.

El problema: cada prompt es una llamada a caja registradora

Cuando desarrollas con LLMs en la nube, cada iteración cuesta. No hablo de cientos de euros, pero un dev que prototipa a diario se planta en 10-50€/mes de APIs sin darse cuenta, y eso antes de exponer nada a usuarios. A eso súmale dos pegas que no se arreglan con dinero: tus datos salen de tu red en cada petición, y dependes de la latencia y los límites de un proveedor externo.

El local-first resuelve las tres cosas a la vez: coste marginal cero por inferencia, datos que no se mueven de tu máquina y cero dependencia de una API ajena. En 2026 dejó de ser un experimento. Con modelos abiertos potentes (Qwen3, Gemma, GLM, Kimi) y un runtime que los hace correr en tu portátil, el local sirve para tareas reales. La herramienta que lo ha vuelto trivial se llama Ollama.

¿Qué es Ollama?

Ollama es un runtime open-source que descarga, gestiona y sirve modelos de lenguaje en local con un solo comando, exponiéndolos por una API HTTP en tu propia máquina. Hace por los LLMs lo que Docker hizo por las aplicaciones: empaqueta el modelo, sus pesos y su configuración en algo que arranca igual en cualquier sitio.

Por debajo usa llama.cpp (y el motor MLX en Apple Silicon) y trabaja con el formato GGUF, que se ha convertido en el estándar de facto para inferencia local: un único fichero con tokenizer, metadatos y pesos. La versión 0.30, publicada el 05/06/2026, trae hasta un 20% más de rendimiento en hardware NVIDIA y soporte Vulkan para ampliar las GPUs compatibles, según el blog oficial de Ollama.

Instalación: de cero a chatear en tres comandos

Takeaway: no hay configuración. Instalas, descargas un modelo y hablas con él.

En Linux o macOS, el primer paso es un único script de instalación. En Windows hay instalador gráfico.

Instala el runtime de Ollama en tu sistema:

# Descarga e instala Ollama (Linux/macOS); deja corriendo el servicio en localhost:11434
curl -fsSL https://ollama.com/install.sh | sh

Ahora descarga un modelo y empieza a conversar. qwen3:8b es un buen punto de partida: ronda los 5 GB y cabe en cualquier GPU decente.

# Descarga el modelo y abre un chat interactivo en la terminal
ollama run qwen3:8b

La primera vez tarda lo que pese la descarga; después arranca en segundos. Para ver qué tienes instalado:

# Lista los modelos descargados y su tamaño en disco
ollama list

Eso es todo. Tienes un LLM respondiendo offline, sin clave de API ni telemetría. El servicio queda escuchando en localhost:11434, que es la puerta que usaremos para todo lo demás.

¿Qué hardware necesito? Tabla de VRAM por tamaño de modelo

Regla rápida: el cuello de botella es la VRAM, no la CPU. Con cuantización Q4_K_M (la recomendada por defecto) un modelo de 7-8B cabe en 6-8 GB y va sobrado para uso diario. La cuantización reduce a la mitad la memoria necesaria con una pérdida de calidad mínima.

VRAM disponible	Modelos que corren bien (Q4_K_M)	Uso típico
4-6 GB	3-4B (Llama 3.2 3B, Qwen3 4B)	Tareas ligeras, autocompletado
6-8 GB	7-9B (Llama 3.1 8B, Qwen3 8B)	Punto dulce diario, ~40 tok/s
10-12 GB	12-14B (Gemma 3 12B, Qwen3 14B)	Daily driver equilibrado
16-24 GB	22-32B (Qwen3 32B, Gemma 3 27B)	Razonamiento más profundo
48 GB+	70B+ (Llama 3.3 70B)	Calidad alta, requiere workstation

Dos consejos honestos de quien lo ha probado en máquinas normales, no en granjas de GPUs: no bajes de Q4, porque la caída en razonamiento e instrucciones se nota rápido, y quédate en 8k-16k de contexto para uso normal, ya que estirarlo a 32k suele ralentizar más de lo que ayuda. Si no tienes GPU dedicada, los modelos 3-7B corren en CPU con 8 GB de RAM, pero a 2-5 tokens/segundo: usable para pruebas, doloroso para trabajar.

Open WebUI: tu ChatGPT privado en minutos

La terminal está bien para probar, pero para uso real querrás una interfaz. Open WebUI es un frontend open-source que se parece a ChatGPT y se conecta a Ollama, con historial, subida de documentos y gestión de usuarios. La forma limpia de levantarlo es Docker.

Levanta Open WebUI apuntando a tu Ollama del host:

# Arranca Open WebUI en el puerto 3000 y lo conecta a Ollama corriendo en el host
docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:main

Abre http://localhost:3000, crea la cuenta (el primer usuario es el admin) y ya tienes una interfaz completa sobre tus modelos locales. Un detalle importante de red: si Open WebUI no encuentra Ollama, suele ser porque Ollama solo escucha en 127.0.0.1. Configúralo para escuchar en 0.0.0.0 con la variable OLLAMA_HOST y se arregla.

Conecta tu código: la API compatible con OpenAI

Aquí está la palanca real para developers. Ollama expone un endpoint compatible con la API de OpenAI en localhost:11434/v1. Eso significa que cualquier código escrito con el SDK de OpenAI funciona cambiando dos líneas: la base_url y la clave (que aquí es de pin, da igual el valor).

Ejemplo mínimo completo en Python. Solo necesitas pip install openai y tener un modelo descargado:

# Usa el SDK de OpenAI contra Ollama local: misma interfaz, cero coste por token
from openai import OpenAI

# La base_url apunta a Ollama; api_key es obligatoria pero su valor se ignora
client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",
)

respuesta = client.chat.completions.create(
    model="qwen3:8b",
    messages=[
        {"role": "system", "content": "Eres un asistente conciso en espanol."},
        {"role": "user", "content": "Explica que es la cuantizacion en una frase."},
    ],
)

print(respuesta.choices[0].message.content)

El patrón que me funciona: una variable de entorno LLM_ENDPOINT que en desarrollo apunta a Ollama y en producción a la API de pago. El mismo código vale para ambos, y prototipas gratis antes de gastar un euro en la nube. Esto encaja igual de bien si estás montando un pipeline de procesamiento de documentos para RAG y quieres iterar sobre el chunking sin pagar por cada prueba.

Caso real: ¿cuándo usar esto en producción?

El local-first brilla en escenarios concretos del mundo laboral:

Datos sensibles: documentación interna, datos de clientes, código propietario que no puede salir de tu red por cumplimiento o RGPD.
Volumen de prototipado alto: cuando iteras cientos de veces al día sobre prompts y la factura de la API se dispara sin aportar valor.
Asistente de código self-hosted: herramientas como Tabby te dan autocompletado tipo Copilot sin mandar tu repo entero a la nube, apoyándose en un modelo local.
Offline o entornos cerrados: máquinas sin acceso a internet o con conectividad poco fiable.

Una nota de calibración: antes de decidir qué modelo abierto usar, no te fíes de los benchmarks de marketing. Monta una mini-evaluación con tus tareas reales, igual que harías al elegir un modelo para un agente de coding. Los números de un benchmark genérico rara vez predicen cómo rinde en tu caso.

En Producción

La verdad incómoda: Ollama es excelente para un usuario, flojo para muchos a la vez. Está optimizado para latencia de una sola petición, no para throughput concurrente. Si vas a servir a usuarios reales en paralelo, hay un punto en el que Ollama deja de ser la herramienta adecuada.

Criterio	Ollama (quédate aquí)	vLLM (escala aquí)
Concurrencia	1 a pocos usuarios	Decenas en paralelo (continuous batching, 2-4x throughput)
Observabilidad	Logging básico	Métricas Prometheus, request-level logging
Caso ideal	Dev local, prototipo, equipo pequeño	Servicio en producción con SLA de latencia
Curva de entrada	Tres comandos	Configuración y tuning de GPU

Coste real: el local no es gratis, es coste hundido. La inferencia no te cuesta por token, pero pagas el hardware (una GPU con 8-12 GB de VRAM es la entrada razonable) y la electricidad durante sesiones largas, donde la térmica y el consumo acaban siendo el límite antes que los tokens/segundo. Haz la cuenta: si gastas 15-20€/mes en API y un modelo de 8B te sobra, la GPU tarda años en amortizarse. El local compensa por privacidad y control, no siempre por dinero.

Cuándo NO usar local: si necesitas capacidad frontera (los modelos cerrados de gama alta siguen por delante en razonamiento complejo), si tu carga es esporádica (la nube paga por uso, sin hardware parado) o si requieres alta concurrencia con monitoreo serio. Y recuerda que la calidad de un modelo local también se degrada o se queda corta: vigílala con el mismo rigor con el que mides la calidad de tu IA en producción, no por intuición.

Errores comunes y depuración

Error: Open WebUI no ve los modelos. Causa: Ollama escucha solo en 127.0.0.1 y el contenedor no llega. Solución: exporta OLLAMA_HOST=0.0.0.0 y reinicia el servicio.
Error: out-of-memory al cargar el modelo. Causa: el modelo no cabe en VRAM y hace offload pesado a CPU. Solución: baja a un tamaño menor o usa una cuantización más agresiva (de Q5 a Q4), nunca por debajo de Q4.
Error: respuestas lentísimas (2-5 tok/s). Causa: el modelo corre en CPU porque no detecta GPU. Solución: verifica drivers con nvidia-smi y arranca con --verbose para ver el offload por capas.
Error: respuestas inconsistentes. Causa: temperatura por defecto o falta de system prompt. Solución: ajusta un Modelfile con temperatura 0.7-0.8 y un system prompt específico del proyecto.

Preguntas frecuentes

¿Necesito GPU para usar Ollama?

No es obligatoria. Los modelos de 3-7B corren en CPU con 8 GB de RAM, pero a 2-5 tokens/segundo. Para trabajar con fluidez (20-40 tok/s en un modelo 7B) necesitas una GPU con 8 GB o más de VRAM.

¿Ollama es seguro para datos confidenciales?

Sí, porque todo corre en tu máquina y no hay telemetría ni datos saliendo a una API externa. Es una de sus mayores ventajas frente a la nube para escenarios con requisitos de RGPD o documentación interna.

¿Qué modelo abierto elijo para empezar?

Para uso general con 8-12 GB de VRAM, un modelo de 7-8B como Qwen3 8B con cuantización Q4_K_M es el punto dulce. Para razonamiento más exigente y si tienes 16-24 GB, sube a un 27-32B. Evalúalo siempre con tus propias tareas antes de comprometerte.

Cierre

Hemos visto que con Ollama pasas de cero a un LLM corriendo en local en tres comandos, que el límite real es la VRAM y no la CPU, y que su API compatible con OpenAI te deja prototipar gratis con el mismo código que luego apuntará a la nube. La clave está en elegir bien la batalla: el local gana en privacidad, coste de iteración y control, mientras que la nube y herramientas como vLLM siguen ganando en capacidad frontera y concurrencia. No es local contra nube, es saber enrutar cada tarea a donde rinde.

¿Ya tienes un modelo abierto corriendo en tu máquina, o te frena el hardware? Cuéntame tu setup en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo montaremos un RAG completo encima de Ollama para darle a tu modelo local acceso a tus propios documentos.

Tu evaluación offline miente: mide tu IA en producción

Sergio Márquez — Wed, 17 Jun 2026 08:00:01 GMT

Tu evaluación offline miente: mide tu IA en producción

TL;DR: La evaluación offline de un modelo de IA (correrlo contra tu dataset de test) no predice cómo se comportará con usuarios reales. La evaluación de modelos en producción (online evaluation con shadow traffic, canary y A/B testing) mide el comportamiento real, donde de verdad importa. Aquí tienes el mínimo viable para montarla en un equipo pequeño sin montar una plataforma de MLOps entera.

El problema: "funciona en mi dataset" no basta

Cambias un prompt, corres tu suite de evals offline y la métrica sube. Lo despliegas. En producción, los usuarios empeoran su tasa de éxito. ¿Qué ha pasado?

El dataset de test es una foto fija. Los usuarios reales mandan inputs raros, frases a medias, contextos largos y casos que tu golden set nunca capturó. Por eso una mejora offline puede convertirse en regresión online, y al revés: un cambio que apenas movía la aguja offline entrega una mejora clara en producción.

Esto no es teórico. DoorDash documentó un gap de cerca del 4% de accuracy entre sus pruebas controladas y producción. Y es el patrón general: la evaluación offline asegura estabilidad; la online asegura que el cambio sobrevive al mundo real. Necesitas las dos, pero la offline no decide por ti.

En mi experiencia operando pipelines con LLMs, el error más caro es confiar en un número de un notebook como si fuera la verdad. Igual que la explicabilidad de modelos con LIME y SHAP te obliga a mirar dentro de la caja negra, la evaluación online te obliga a mirar fuera de tu máquina.

¿Qué es la evaluación offline?

La evaluación offline mide un modelo contra un dataset fijo con respuestas esperadas, en un entorno controlado y reproducible. Es lo que corres en CI antes de desplegar.

Es barata, rápida y segura. Sirve para detectar regresiones obvias, comparar modelos y experimentar sin riesgo. Su límite es estructural: solo sabe lo que tú metiste en el dataset.

¿Qué es la evaluación online (en producción)?

La evaluación online mide el modelo con tráfico real, en vivo o en sombra, contra métricas de negocio y no solo de accuracy. Captura distribución real de inputs, latencia bajo carga y el comportamiento que ningún golden set predice.

Su precio es la complejidad: los resultados son ruidosos, hay variables que confunden (estacionalidad, cambios de UX) y los errores afectan a usuarios. Por eso se hace por capas.

Aspecto	Offline	Online (producción)
Dónde corre	CI/CD, dataset fijo	Tráfico real
Qué mide	Competencia (accuracy, relevancia)	Valor real (conversión, escalado, satisfacción)
Riesgo para el usuario	Cero	Controlable por capas
Velocidad	Minutos	Días o semanas
Cuándo usar	Antes de desplegar	Validar que el cambio sobrevive

El rollout por capas: de la sombra al 100%

La clave no es elegir online u offline, sino encadenar etapas que suben el riesgo poco a poco. Este es el orden que funciona en producción:

Shadow traffic (sombra): el modelo candidato procesa las peticiones reales en paralelo al de producción, pero su respuesta nunca llega al usuario. Solo la registras y comparas. Riesgo cero, datos reales.
Canary interno: usuarios de confianza (tu equipo) ven el candidato.
Canary externo pequeño: del 1 al 5% del tráfico, con rollback automático si una métrica cae.
A/B test: repartes tráfico entre control y variante y comparas KPIs con tamaño de muestra suficiente.
Rollout completo: mantienes siempre el camino de vuelta.

El shadow traffic es la joya para equipos pequeños: validas con inputs reales sin arriesgar la experiencia. Es el equivalente, en evaluación, a una separación de responsabilidades limpia: el tráfico que decide es uno, el que observas es otro.

Implementación: el mínimo viable de shadow traffic

No necesitas Braintrust ni Arize para empezar. Con FastAPI y una tarea en segundo plano tienes shadow evaluation funcional.

Lanza el candidato en paralelo sin bloquear ni afectar la respuesta del usuario:

# Sirve la respuesta de producción y evalúa el candidato en sombra
@app.post("/chat")
async def chat(req: ChatRequest, background: BackgroundTasks):
    prod_resp = await prod_model.generate(req.prompt)
    # El candidato corre en background: nunca bloquea ni llega al usuario
    background.add_task(shadow_eval, req.prompt, prod_resp)
    return prod_resp

La tarea en sombra registra ambas salidas para compararlas después, en frío:

# Registra prod vs candidato para análisis posterior (no afecta al usuario)
async def shadow_eval(prompt: str, prod_resp: str):
    cand_resp = await candidate_model.generate(prompt)
    await log_store.save({
        "prompt": prompt,
        "prod": prod_resp,
        "candidate": cand_resp,
        "judge_score": await llm_judge(prompt, cand_resp),  # LLM-as-judge
    })

Con esos logs comparas la calidad del candidato contra producción sobre inputs reales. Si quieres puntuar de forma automática, un modelo fuerte como juez (LLM-as-judge) escala mejor que la revisión manual, con el matiz de que mide si la respuesta parece buena, no si el usuario actúa sobre ella.

En Producción

Mide coste y calidad juntos, nunca por separado. Una ruta más barata que baja la tasa de tareas completadas no es más barata.

Métricas que importan: coste por tarea exitosa (no por petición), tasa de escalado, re-preguntas, correcciones del usuario, latencia y un score de calidad. En APIs de LLM, un rango realista de gasto para un proyecto pequeño ronda los 10 a 50 € al mes; el shadow traffic lo duplica temporalmente, tenlo en cuenta.
Tamaños de muestra grandes: la varianza de salida de un LLM es alta. Las muestras pequeñas mienten. Necesitas más muestra que en software determinista y segmentar por tipo de tarea: un prompt puede mejorar el resumen y empeorar el tool calling a la vez.
Data drift: los inputs cambian con el tiempo. Monitoriza la distribución de entradas, no solo la métrica de salida, para detectar deriva antes de que se note en el negocio.
Rollback automático: el canary debe revertir solo si una métrica cae bajo un umbral. Sin esa red, el canary es una bomba de relojería.

La diferencia entre el tutorial y producción real es esta: en el tutorial el dataset es estable; en producción la distribución se mueve, la latencia varía bajo carga y el coste se dispara si no lo vigilas.

Errores comunes y depuración

Error: el cambio sube offline pero empeora en producción. Causa: tu golden set no representa la distribución real de inputs. Solución: reconstruye el dataset a partir de logs de producción, no de ejemplos inventados.
Error: el A/B no da significancia estadística. Causa: muestra demasiado pequeña para la varianza del LLM. Solución: alarga el experimento, segmenta por tipo de tarea y usa la misma métrica de negocio antes y después.
Error: el LLM-as-judge premia respuestas largas y vacías. Causa: el juez mide forma, no valor. Solución: calibra el juez contra etiquetas humanas en una muestra y añade métricas de comportamiento real del usuario.

Si tu sistema es un RAG, recuerda que la evaluación de retrieval es su propia capa: medir solo la respuesta final esconde qué falló. Cuando el vector recupera mal, lo arregla la búsqueda híbrida y el re-ranking, no un prompt más bonito.

Preguntas frecuentes

¿La evaluación offline es inútil entonces?

No. Es necesaria pero no suficiente. Sirve para comparar modelos de forma reproducible y atrapar regresiones obvias en CI, pero no predice el comportamiento bajo tráfico real. Es tu primera barrera, no la última.

¿Cuándo paso de offline a online?

Cuando las métricas offline son estables y la mejora parece significativa, especialmente antes de un despliegue amplio o un cambio de alto impacto. Empieza siempre por shadow traffic, que no expone nada al usuario.

¿Y si offline y online se contradicen?

Es común y valioso. El desacuerdo suele señalar distribution shift, problemas de UX o efectos a nivel de sistema que el dataset offline no capturó. Investiga la causa, no descartes el online por incómodo.

Cierre

Hemos visto por qué la evaluación de modelos en producción no es un lujo de equipos enormes, sino la única forma de saber si un cambio sirve de verdad. La clave está en encadenar etapas que suben el riesgo poco a poco (shadow, canary, A/B) y en medir coste y calidad juntos sobre inputs reales, no sobre un dataset que envejece en tu disco. Empieza hoy por lo más barato: registra en sombra el candidato y compáralo con producción antes de exponer a un solo usuario.

Si te interesa cómo se separa la señal del ruido al elegir un modelo, este mismo principio aparece en por qué los benchmarks de coding agéntico te hacen elegir mal tu modelo: un número global no decide por ti. El siguiente paso natural es montar detección de data drift automática, que dejaré para un próximo artículo.

¿Has tenido un cambio que mejoraba offline y empeoraba con usuarios reales? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_.

Claude Skills ya son estándar: úsalas en Codex y Cursor

Sergio Márquez — Tue, 16 Jun 2026 08:00:02 GMT

Claude Skills ya son estándar: úsalas en Codex y Cursor

TL;DR: Las Claude Skills dejaron de ser una rareza de un solo producto. El formato SKILL.md que estrenó Anthropic es hoy un estándar abierto (agentskills.io) que adoptaron OpenAI Codex, ChatGPT, Cursor, Gemini CLI y GitHub Copilot. Significa que escribes una skill una vez y la reutilizas en casi cualquier agente de código. En esta guía verás qué es el estándar, cómo escribir un SKILL.md portable y dónde colocarlo en cada herramienta.

El problema: cada agente, su propia jaula

Hasta hace poco, automatizar el comportamiento de un agente de IA significaba aprender su dialecto. Reglas de Cursor por un lado, CLAUDE.md por otro, prompts pegados a mano en cada sesión. Si cambiabas de herramienta, tirabas tu trabajo y empezabas de cero. Ese lock-in era el coste oculto de elegir un agente.

Las Claude Skills rompieron ese muro, y lo interesante es lo que vino después: en cuestión de semanas, los demás vendors adoptaron el mismo formato. Ya no inviertes en "skills de Claude", inviertes en una capacidad portable que sobrevive a tu elección de herramienta. Para quien programa con varios agentes a la vez, esto cambia el cálculo por completo.

¿Qué es una Agent Skill?

Una Agent Skill es una carpeta con un archivo SKILL.md que empaqueta instrucciones, scripts y recursos para que un agente ejecute una tarea concreta de forma fiable. El archivo lleva metadatos (nombre y descripción) más las instrucciones; opcionalmente, scripts ejecutables, documentación de referencia y plantillas.

La especificación vive en agentskills.io, fue desarrollada originalmente por Anthropic y liberada como estándar abierto. Esa apertura es la razón de que el ecosistema convergiera tan rápido: nadie quería reinventar el mismo patrón.

La estructura mínima de una skill es esta:

mi-skill/
├── SKILL.md      # Obligatorio: metadatos + instrucciones
├── scripts/      # Opcional: código ejecutable
├── references/   # Opcional: documentación de apoyo
└── assets/       # Opcional: plantillas, recursos

¿Por qué de repente lo adopta todo el mundo?

La clave técnica es un patrón llamado progressive disclosure (revelación progresiva). Es lo que hace que tener muchas skills no infle el contexto ni dispare tu factura de tokens. Si te interesa el control de coste, ya escribí sobre cómo cruzar los 200k tokens vacía tu presupuesto; las skills atacan justo ese problema.

El agente carga la información en tres niveles, solo lo que necesita:

Nivel 1 (siempre cargado): el frontmatter YAML con name y description. Ocupa pocos tokens y sirve de "índice".
Nivel 2 (cuando la tarea encaja): el cuerpo completo del SKILL.md con el flujo de trabajo.
Nivel 3 (bajo demanda): los archivos de references/, scripts/ o assets/, que el agente abre solo si los necesita.

Cada plataforma faceaba dos problemas idénticos: dar conocimiento amplio al agente sin destruir la calidad del contexto, y dejar que el usuario configure el comportamiento sin saber programar. El formato resuelve ambos. Por eso la adopción fue casi inmediata.

Implementación: escribe un SKILL.md portable paso a paso

Vamos a lo accionable. Un buen ejemplo es una skill que estandarice cómo el agente procesa documentos PDF, un caso donde el flujo manual suele ser inconsistente. Si quieres el detalle del pipeline, lo cubrí en procesamiento de PDFs para IA con Python y LangChain.

Paso 1. Crea la carpeta y el archivo. El frontmatter es lo único obligatorio, y la description es el trigger: el agente decide si la skill aplica leyendo esa línea, así que escríbela con las palabras que un usuario usaría.

---
name: extraer-pdf
description: Extrae texto y tablas de PDFs y los normaliza a Markdown. Úsala cuando el usuario mencione PDFs, facturas o extracción de documentos.
---

# Extraer datos de PDF

## Cuándo usar esta skill
Cuando haya que sacar texto o tablas de un PDF de forma consistente.

## Flujo de trabajo
1. Identifica si el PDF es nativo o escaneado.
2. Ejecuta scripts/extract.py sobre el archivo.
3. Devuelve Markdown limpio, una tabla por sección.

Paso 2. Si la tarea necesita lógica, añade un script en scripts/ y referencialo desde el SKILL.md. El agente prefiere ejecutar o parchear un script existente antes que reescribir bloques de código grandes, lo que ahorra tokens.

Paso 3. Coloca la carpeta en la ruta que cada agente espera. El formato es idéntico; lo único que cambia es dónde vive. Esa separación limpia entre "qué hace" y "dónde se carga" es un buen ejemplo del principio de separación de responsabilidades aplicado a la configuración de agentes.

Dónde vive una skill en cada agente

Mismo SKILL.md, distinta ruta. Esta tabla resume las ubicaciones a junio de 2026 (verifica siempre la documentación oficial, porque las rutas evolucionan):

Agente	Ruta personal	Ruta de proyecto	Invocación
Claude Code	`~/.claude/skills/`	`.claude/skills/`	Automática por descripción
OpenAI Codex	`~/.codex/skills/`	Carpeta del repo	`$nombre-skill` o `/skills`
Gemini CLI	`~/.gemini/skills/`	`.gemini/skills/`	Automática / explícita
Cursor	Junto a su sistema de Rules	Carpeta del repo	Automática

Existe incluso un instalador universal de la comunidad: npx Ai-Agent-Skills install <skill> --codex trae las skills más populares de Claude a Codex en segundos. La portabilidad ya no es teoría.

Aplicación práctica: una skill, tu equipo entero

En escenarios reales, el valor aparece cuando varias personas usan agentes distintos. Imagina un repositorio con una skill de "estilo de commits" o de "generar el informe semanal". Quien use Claude Code y quien use Codex obtienen el mismo comportamiento sin negociar formatos. La skill viaja en el repo, versionada con Git, y se actualiza como cualquier otro archivo.

Ese es el cambio de mentalidad: una skill no es un truco de prompt, es un artefacto de código. Si ya creaste alguna, como una Claude Skill que genera Word con tu plantilla, ahora ese trabajo rinde en más herramientas sin tocar una línea. Y si dudas entre Cursor y Claude Code para tu día a día, mi comparativa de subagents y skills en 2026 entra al detalle.

En Producción

El tutorial es fácil; producción tiene matices que conviene tener claros antes de repartir skills a un equipo.

Presupuesto de contexto: Codex limita la lista inicial de skills a un 2% de la ventana de contexto, o 8.000 caracteres si la desconoce. Con muchas skills instaladas, recorta descripciones u omite algunas. Lección: escribe descripciones cortas y precisas, no párrafos.
Trigger fiable: si la description es vaga, el agente no activará la skill o la activará cuando no toca. Trátala como la parte más importante del archivo, no como un comentario.
Scripts a prueba de agentes: usa set -euo pipefail en shell, devuelve JSON por stdout y manda diagnósticos a stderr. Así el agente parsea sin adivinar y falla en voz alta en lugar de seguir en silencio.
Coste: las skills no añaden coste de API por sí mismas; el ahorro viene de no inflar el contexto. En proyectos pequeños la diferencia es de unos pocos euros al mes, pero en sesiones largas se nota.
Diferencias entre agentes: el formato base es portable, pero cada plataforma añade campos de frontmatter propios. Una skill bien diseñada con lo común funciona en todos; si usas extensiones específicas de Claude Code, prueba antes de asumir que viajan.

Errores comunes y depuración

Error: la skill nunca se activa. Causa: la description no contiene las palabras que el usuario realmente escribe. Solución: reescríbela en términos de la tarea ("cuando el usuario mencione facturas o PDFs"), no del nombre interno.

Error: funciona en Claude Code pero no en Codex. Causa: usaste un campo de frontmatter específico de un vendor, o la carpeta está en la ruta equivocada. Solución: quédate con name y description en el frontmatter portable y revisa la ruta de la tabla anterior.

Error: el agente carga demasiado contexto y la respuesta se ralentiza. Causa: metiste todo el contenido en el SKILL.md en vez de repartirlo en references/. Solución: deja en el cuerpo solo el flujo principal y mueve lo extenso a archivos que el agente abra bajo demanda.

Preguntas frecuentes

¿Una skill escrita para Claude Code funciona igual en Codex?

Sí, si te ciñes al formato base del estándar. El SKILL.md con name y description es universal. Lo único que cambia es la carpeta donde lo colocas y, en algunos casos, campos de frontmatter avanzados específicos de cada plataforma.

¿Cuál es la diferencia entre una skill y un archivo CLAUDE.md o AGENTS.md?

El CLAUDE.md o AGENTS.md es contexto siempre cargado: le dice al agente "así trabajamos aquí". Una skill es conocimiento bajo demanda que se activa solo cuando la tarea encaja. Son complementarios: si una sección de tu CLAUDE.md se ha vuelto un proceso paso a paso, extráela a una skill.

¿Las skills cuestan tokens extra?

No de forma significativa. El nivel 1 (metadatos) ocupa muy poco y solo se carga el resto cuando hace falta. El diseño completo de progressive disclosure existe precisamente para reducir el consumo de contexto, no para aumentarlo.

Conclusión

Hemos visto cómo las Claude Skills pasaron de ser una función de un producto a un estándar abierto que adoptan Codex, Cursor, Gemini CLI y más. La clave está en que ahora el formato SKILL.md es portable: escribes una capacidad una vez, la versionas en Git y viaja con tu repositorio sin importar qué agente use cada miembro del equipo. La inversión deja de ser un riesgo de lock-in y pasa a ser un activo reutilizable.

Si quieres profundizar en cuándo conviene una skill frente a un subagente, el harness que necesita tu Claude Code es la siguiente parada lógica. ¿Has portado ya alguna skill entre agentes? Cuéntame qué tal te fue en los comentarios o en Twitter @sergiomarquezp_. El próximo tema: cómo medir si una skill realmente mejora la fiabilidad del agente o solo lo hace sentir más ordenado.

Benchmarks de coding agéntico: por qué eliges mal tu modelo

Sergio Márquez — Mon, 15 Jun 2026 08:00:01 GMT

Benchmarks de coding agéntico: por qué eliges mal tu modelo

TL;DR: Los benchmarks de coding agéntico como Terminal-Bench y SWE-bench miden cosas distintas con harnesses distintos, así que comparar dos números sueltos para elegir modelo en tu CLI casi siempre lleva a una decisión equivocada. En este artículo aprenderás qué mide cada benchmark, por qué un mismo modelo gana en uno y pierde en otro, y cómo montar tu propia mini-evaluación reproducible en menos de una tarde para decidir con tus tareas reales, no con marketing.

El número que viste en Twitter no significa lo que crees

Cuando salió Opus 4.8 medio timeline repetía la misma frase: "supera a GPT-5.5 en coding". El mismo día, otra mitad decía justo lo contrario. Los dos bandos tenían razón, y ese es exactamente el problema.

En las pruebas públicas de junio de 2026, GPT-5.5 lidera Terminal-Bench 2.1 con un 78,2% frente al 74,6% de Opus 4.8. Pero en SWE-bench Pro, que es más difícil, Opus 4.8 saca un 69,2% contra el 58,6% de GPT-5.5. Mismo par de modelos, conclusión opuesta según el benchmark. Si eliges tu modelo por el primer titular que te cruzas, vas a pagar de más o a usar el modelo equivocado para tu tipo de trabajo.

La pregunta correcta no es "¿qué modelo es mejor?", sino "¿mejor en qué tarea, con qué andamiaje y a qué coste?". Vamos a desmontarlo.

¿Qué es un benchmark de coding agéntico?

Un benchmark de coding agéntico mide si un agente de IA puede resolver una tarea de programación completa de forma autónoma, no solo completar una función. El agente lee el repositorio, ejecuta comandos, corre tests, itera sobre sus propios errores y entrega un resultado que se valida automáticamente.

Esto lo distingue de los benchmarks clásicos tipo HumanEval, que solo comprueban si un fragmento de código pasa unos tests. Los dos benchmarks que más vas a ver hoy son distintos entre sí:

SWE-bench (Verified y Pro): mide si el agente arregla bugs reales de repositorios de GitHub. Premia comprensión de código y razonamiento sobre bases grandes. SWE-bench Verified ya está saturado (los modelos top rondan el 88%), por eso la señal útil está en SWE-bench Pro.
Terminal-Bench: mide tareas de línea de comandos que requieren planificar, encadenar herramientas y recuperarse de fallos. Es trabajo más "shell" y DevOps. Según el paper en arXiv, las tareas corren con un harness llamado Harbor que soporta Claude Code, Codex CLI, OpenHands y otros agentes.

La clave: un modelo puede ser excelente arreglando bugs de Python y mediocre coordinando comandos de terminal. Eso no es contradictorio, son habilidades diferentes.

Los números reales (junio 2026) y cómo leerlos

Esta es la comparativa pública de Opus 4.8 y GPT-5.5, con datos reportados por los proveedores y agregadores. Fíjate en que cada fila cuenta una historia distinta:

Benchmark	Qué mide	Opus 4.8	GPT-5.5	Quién gana
SWE-bench Verified	Bugfix autónomo (saturado)	88,6%	~88%	Empate técnico
SWE-bench Pro	Bugfix difícil	69,2%	58,6%	Opus 4.8 (+10pp)
Terminal-Bench 2.1	Flujos de terminal	74,6%	78,2%	GPT-5.5
MCP-Atlas	Uso de herramientas	82,2%	75,3%	Opus 4.8

La trampa número uno: esos números no siempre vienen del mismo harness ni de la misma configuración. Anthropic publica resultados de SWE-bench a veces con una modificación de prompt y promediados sobre varias pasadas; OpenAI reporta sobre su propio Codex. Tomar la cifra de un proveedor y restarla de la del otro no es una comparación limpia, es un espejismo. Un mismo modelo puede subir varios puntos solo cambiando el agente que lo envuelve.

Por eso un benchmark neutral como Terminal-Bench usa Terminus 2, un agente de referencia que ejecuta todos los modelos con el mismo andamiaje. Cuando compares, comprueba siempre que la fila usa el mismo harness. Si no lo dice, sospecha. Esta lógica de no fiarse del número aislado es la misma que aplica al decidir entre modelos dentro de tu CLI, algo que ya tratamos en la comparativa sobre cómo repartir planificación y ejecución entre Fable y Opus.

El coste no aparece en el ranking, y es lo que te arruina

Un benchmark de pass rate te dice quién acierta más, no quién te sale rentable. Y la diferencia es brutal en la práctica.

En una prueba reciente de la comunidad con Harbor sobre 10 tareas difíciles de Terminal-Bench 2.1, GPT-5.5 (vía Codex) resolvió 9 de 10 en cerca de una hora por unos 11€ aproximados. Opus 4.8 (vía Claude Code) tardó más de dos horas, se quedó atascado casi una hora en una sola tarea (un ejercicio de regex) y costó más de 23€. El detalle interesante: Opus generó alrededor de 3,3 veces más tokens de salida y casi 4 veces más input cacheado.

Traducción para tu factura: el modelo con mejor pass rate puede ser el que te vacía el plan antes de tiempo. A precios oficiales de API rondando los 5€ por millón de tokens de entrada y 25-30€ por millón de salida, el perfil de consumo de cada modelo pesa tanto como su acierto. Este es justo el agujero del que hablamos cuando un agente cruza los 200k tokens y dispara el presupuesto, y la razón por la que conviene vigilar tokens y coste en tiempo real desde tu editor.

Cómo leer cualquier benchmark sin que te engañen

Antes de creer un ranking, pásalo por estos cinco filtros. Si falla alguno, el número vale menos de lo que parece:

Mismo harness: ¿los modelos corrieron con el mismo agente, o cada proveedor usó el suyo? Sin esto no hay comparación.
Versión y fecha: ¿es Terminal-Bench 2.0 o 2.1? ¿SWE-bench Verified o Pro? Mezclar versiones invalida la resta.
Saturación: si todos pasan del 85%, el benchmark ya no discrimina. Busca el más difícil.
Effort y trials: ¿el número es de un intento o promedio de 25? ¿Con qué nivel de esfuerzo? Opus 4.8 a esfuerzo mínimo iguala a Opus 4.7 a máximo en SWE-bench Pro, así que el ajuste cambia todo.
Coste por tarea: ¿incluye tokens y precio? Un pass rate sin coste es media verdad.

Monta tu propia mini-evaluación en una tarde

Ningún benchmark público usa tu código ni tus tareas. La forma honesta de decidir es montar una evaluación pequeña y reproducible con problemas que se parezcan a tu día a día. No necesitas infraestructura: con Harbor, el mismo harness de Terminal-Bench, ejecutas un set fijo de tareas contra varios modelos.

Este comando lanza un subconjunto del benchmark con un agente y modelo concretos, repitiendo cada tarea 5 veces para tener señal estadística:

# Ejecuta Terminal-Bench con un agente/modelo y k=5 pasadas para medir varianza
harbor run -d terminal-bench@2.1 -a "claude-code" -m "claude-opus-4-8" -k 5

Para que la comparación sea tuya y no de un agregador, lo importante es fijar el set de tareas que de verdad haces. Define una lista corta y honesta, mejor 8-10 casos representativos que 200 genéricos:

# Tu mini-suite: tareas que reflejan tu trabajo real, no las del marketing
mi_suite = [
    "refactor_endpoint_fastapi",   # lo que haces a diario
    "fix_n1_query_orm",            # tu dolor recurrente
    "migrar_script_bash_a_python", # tarea de terminal real
    "anadir_test_pytest_cobertura",
]
# Corres cada tarea con 2-3 modelos y registras: pass rate, coste, tiempo

Con eso tienes tres columnas que sí importan: acierto en tus tareas, coste real y tiempo. Esa tabla decide mejor que cualquier titular. Si quieres ir más allá, la lógica de aislar el entorno de ejecución para correr estas pruebas sin riesgo encaja con lo que explicamos sobre por qué tu agente necesita un buen harness.

En Producción

Pasar del benchmark a tu flujo diario cambia varias cosas. Esto es lo que importa cuando el modelo deja de ser un número y se convierte en tu compañero de trabajo:

Routing por tarea, no por moda: si tu trabajo es shell y DevOps, el líder en Terminal-Bench te conviene; si es arreglar bugs en repos grandes, mira SWE-bench Pro. No hay un modelo por defecto universal.
Presupuesto de tokens: mide el coste por tarea en tu suite antes de cambiar el modelo por defecto del equipo. Un modelo que genera 3x más salida multiplica la factura aunque acierte igual.
Atascos: en producción un modelo que se cuelga una hora en una tarea no es un detalle, es un incidente. Pon límites de tiempo y de tokens por tarea.
Reproducibilidad en CI: si automatizas evaluaciones, fija la versión del benchmark y del harness. Un cambio de minor en el agente puede mover los resultados sin que toques el modelo.

Errores comunes y depuración

Error: Comparas el 88,6% de Opus en SWE-bench Verified con el 78,2% de GPT-5.5 en Terminal-Bench. → Causa: son benchmarks distintos, no se restan. → Solución: compara solo dentro de la misma fila, mismo benchmark y misma versión.

Error: Eliges el modelo con mayor pass rate y tu factura se dispara. → Causa: ignoraste el coste por tarea y el perfil de tokens. → Solución: añade coste y tiempo a tu tabla de decisión, no solo acierto.

Error: Tu mini-eval da resultados distintos cada vez. → Causa: una sola pasada por tarea tiene mucha varianza. → Solución: usa k=5 o más y mira la media con su margen de error, igual que hacen los leaderboards serios.

Preguntas frecuentes

¿Cuál es el mejor benchmark para elegir un modelo de coding?

No hay uno solo. Para bugfix en repos usa SWE-bench Pro; para flujos de terminal y DevOps usa Terminal-Bench 2.1. Lo más fiable es montar tu propia mini-suite con tareas parecidas a tu trabajo real y medir acierto, coste y tiempo.

¿Por qué Opus 4.8 gana en SWE-bench pero pierde en Terminal-Bench?

Porque miden habilidades distintas. SWE-bench premia comprensión de código y razonamiento sobre bases grandes, mientras Terminal-Bench premia planificar y encadenar comandos de shell. Un modelo puede destacar en una y quedarse corto en la otra sin contradicción.

¿Puedo correr Terminal-Bench yo mismo?

Sí. Las tareas corren con el harness Harbor, que soporta Claude Code, Codex CLI y otros agentes. Puedes ejecutar un subconjunto contra varios modelos con un comando y comparar pass rate, coste y duración en tu propia máquina.

Lo que te llevas

Hemos visto que un benchmark de coding agéntico no es un veredicto, es una medición acotada a una tarea, un harness y una configuración concretos. GPT-5.5 y Opus 4.8 se intercambian el liderazgo según mires terminal o bugfix, y el coste real (tokens, tiempo, atascos) rara vez aparece en el titular que comparte la gente. La decisión sensata no es creer el ranking más viral, sino montar una mini-evaluación con tus propias tareas y medir las tres cosas que de verdad pagas: acierto, dinero y tiempo.

La próxima vez que veas "el modelo X destroza al modelo Y", pregúntate en qué benchmark, con qué harness y a qué coste. Esa pregunta te ahorra más dinero que cualquier optimización de prompt.

¿Has montado tu propia evaluación para elegir modelo, o tiras de los leaderboards públicos? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo monto una mini-suite completa con Harbor paso a paso y comparo tres modelos sobre tareas reales de backend.

System prompts filtrados: patrones que mejoran tu CLAUDE.md

Sergio Márquez — Sun, 14 Jun 2026 08:00:01 GMT

System prompts filtrados: patrones que mejoran tu CLAUDE.md

Hay un repositorio en GitHub con 134.000 estrellas que recopila las instrucciones internas de casi todos los agentes de código que usas a diario, Claude Code incluido. No es una filtración morbosa: es la mejor escuela gratuita de prompt engineering que existe ahora mismo.

TL;DR

Qué es: los system prompts filtrados son las instrucciones internas que herramientas como Claude Code, Cursor o Devin envían al modelo en cada turno. Repos públicos las recopilan y versionan.
Por qué importa: ver cómo los pros estructuran reglas, límites y formato de salida te da plantillas probadas para tu propio CLAUDE.md sin pasar por meses de prueba y error.
Qué aprenderás: dónde leer estos prompts, qué cinco patrones copiar, qué dejar fuera y cómo evitar que tu CLAUDE.md se convierta en ruido que el agente ignora.

El problema: escribes reglas y el agente las ignora

En mi experiencia migrando flujos de Java a Python con agentes de código, el patrón se repite: añades una regla a tu CLAUDE.md ("usa siempre type hints", "no toques los tests"), y el agente la respeta dos turnos y luego la olvida. La reacción típica es escribir la regla más fuerte, en mayúsculas, con tres signos de exclamación. Casi nunca funciona.

El motivo es que la mayoría escribimos instrucciones a ciegas. No sabemos cómo redactan sus prompts los equipos que llevan meses optimizando este problema con millones de sesiones reales. Y resulta que esa información está pública. Aprender de los system prompts filtrados es la diferencia entre adivinar y copiar lo que ya funciona a escala.

¿Qué es un system prompt filtrado?

Un system prompt es el bloque de instrucciones que una herramienta inyecta antes de tu mensaje para definir el comportamiento del modelo: tono, herramientas disponibles, límites de seguridad y formato de salida. Un system prompt filtrado es ese bloque hecho público, normalmente extraído mediante técnicas de prompt extraction o reconstruido a partir del tráfico de la herramienta.

Tu CLAUDE.md no es exactamente lo mismo, pero juega en la misma liga: es texto que el agente lee al arrancar y trata como contexto de máxima prioridad. Las técnicas que los equipos de Anthropic o Cursor usan en su system prompt se trasladan casi directas a cómo deberías escribir el tuyo.

Las dos fuentes que merecen tu tiempo

No todos los repos son iguales. Estos dos son los que uso como referencia:

Repositorio	Qué contiene	Cuándo usarlo
x1xhlol/system-prompts-and-models-of-ai-tools	Prompts de 28+ herramientas (Cursor, Windsurf, Devin, Claude Code, v0, Replit). Más de 30.000 líneas.	Comparar enfoques entre herramientas y robar patrones transversales.
Piebald-AI/claude-code-system-prompts	Los system prompts de Claude Code con conteo de tokens, actualizado a v2.1.172 (10/06/2026) y un CHANGELOG de 205 versiones.	Entender cómo cambia Claude Code release a release y cuánto pesa cada sección.

Un detalle que descoloca a casi todos: Claude Code no tiene un system prompt, tiene muchos. Hay prompts distintos para la herramienta Edit, para Grep, para el modo de aprendizaje, para extraer insights de tu sesión. Cada uno está optimizado por separado. Esa modularidad es la primera lección.

Cómo extraer patrones útiles paso a paso

Leer 30.000 líneas no sirve de nada sin método. Este es el flujo que me funciona:

Abre dos herramientas en paralelo. Pon el prompt de Cursor Agent y el de Claude Code lado a lado. Donde resuelven el mismo problema de forma distinta, hay una decisión de diseño que entender.
Marca las reglas imperativas. Busca verbos en imperativo y mayúsculas selectivas ("NEVER", "ALWAYS", "IMPORTANT"). Fíjate en qué reservan para ese énfasis: casi nunca es trivial.
Copia la estructura, no el contenido. El orden de las secciones, el uso de listas frente a prosa, dónde ponen los ejemplos. Eso es portable. Los detalles específicos de cada herramienta, no.
Mide el coste. Con el repo de Piebald sabes cuántos tokens pesa cada bloque. Si una sección de 700 tokens te aporta poco, fuera.

Cinco patrones que puedes copiar hoy

Estos son los patrones que más se repiten en los prompts de producción y que mejor se trasladan a un CLAUDE.md:

Énfasis escaso. Las herramientas serias usan "IMPORTANT" en contadas líneas. Si todo es importante, nada lo es. Reserva las mayúsculas para la regla que de verdad no se puede romper.
Reglas accionables, no deseos. "Escribe código limpio" es ruido. "Usa funciones de menos de 30 líneas y nombres descriptivos" es ejecutable.
Negativos explícitos. Los buenos prompts dicen qué NO hacer con tanto detalle como qué hacer. "Nunca uses cat/grep, usa bat/rg" es más eficaz que un genérico "usa herramientas modernas".
Formato de salida cerrado. Cuando esperan una estructura concreta, la describen con un ejemplo literal. No la insinúan.
Jerarquía de prioridades. Definen qué gana cuando dos reglas chocan (correctness sobre velocidad, por ejemplo). El agente necesita ese orden para resolver conflictos sin inventárselo.

Aquí tienes el antes y el después de una regla real, reescrita con estos principios:

# Antes (vago, el agente lo ignora)
- Escribe buen código y maneja bien los errores.

# Despues (accionable, con limite y prioridad)
## Rules
- NEVER swallow exceptions: log con contexto o propaga.
- Funciones < 30 lineas. Si crece, extrae.
- Prioridad si hay conflicto: correctness > legibilidad > performance.

Esta lógica de redactar instrucciones claras y jerarquizadas es la misma que aplicas al diseñar software bien acoplado. Si te interesa profundizar, el principio de separación de responsabilidades en arquitectura de software se traslada casi tal cual a cómo organizas un CLAUDE.md por bloques con un único propósito.

Caso real: depurar un CLAUDE.md que contradecía al modelo

Un patrón que me funciona en producción es auditar el CLAUDE.md cuando el agente empieza a comportarse raro tras una actualización. En un proyecto de pipelines con FastAPI, el agente había dejado de respetar el formato de commits. Al comparar mi CLAUDE.md con el system prompt de Claude Code de esa versión, vi que mi regla chocaba con una instrucción interna nueva sobre cómo redactar mensajes.

La solución no fue gritar más fuerte, fue reformular mi regla para que encajara con la jerarquía del prompt base en lugar de pelearse con ella. Si actualizas seguido, este ejercicio conecta con la idea de auditar tu CLAUDE.md antes de seguir trabajando cada vez que cambia el modelo o la versión de la CLI.

En Producción

Trasladar estos patrones a un equipo cambia algunas cosas respecto al tutorial individual:

Coste en tokens. Tu CLAUDE.md se carga en cada sesión. Un archivo de 4.000 tokens lleno de buenas intenciones se paga en cada turno. El repo de Piebald te enseña a pensar en tokens por sección; aplícalo a tu archivo. Cuando el contexto se hincha, el problema se nota: lo cubro en cómo cruzar 200k tokens vacía tu presupuesto.
Reglas duras van en hooks, no en el prompt. La propia documentación de Claude Code es clara: los hooks son obligatorios, el CLAUDE.md es orientativo. Si una regla no se puede romper jamás (bloquear escritura en archivos sensibles, por ejemplo), va en un hook con exit code 2, no en una frase en mayúsculas.
Versiona el CLAUDE.md como código. En equipo, un CLAUDE.md con reglas contradictorias degrada al agente para todos. Revísalo en pull request igual que cualquier otro artefacto.
No copies sin probar. Un patrón de Cursor puede no encajar con cómo Claude Code interpreta el contexto. Mide en tu repo antes de adoptarlo.

Si tu necesidad va más allá de reglas y entra en comportamientos reutilizables, conviene saber dónde acaba el CLAUDE.md y empieza una skill. Lo desarrollo en cómo crear una Claude Skill con tu plantilla y en por qué tu Claude Code puede necesitar un agent harness cuando las reglas sueltas se quedan cortas.

Errores comunes y depuración

Error: el agente ignora una regla crítica. Causa: está enterrada entre veinte reglas con el mismo énfasis. Solución: sube las dos o tres innegociables al principio y deja el resto como orientación.
Error: tras actualizar la CLI, el comportamiento cambia sin tocar tu config. Causa: el system prompt base cambió en esa release. Solución: revisa el CHANGELOG de Piebald de esa versión y ajusta tu CLAUDE.md a la nueva jerarquía.
Error: copias un prompt entero de otra herramienta y el agente se confunde. Causa: traes detalles específicos de tooling que no existe en Claude Code. Solución: copia solo la estructura y las reglas portables, no las referencias a herramientas ajenas.

Preguntas frecuentes

¿Es legal y ético usar system prompts filtrados?

Leerlos con fines de aprendizaje es práctica común y los repos son públicos con cientos de miles de estrellas. Otra cosa es copiar literalmente el prompt comercial de una empresa para un producto competidor. Para inspirarte y mejorar tu CLAUDE.md, estás en terreno seguro.

¿Cómo de a menudo cambian estos prompts?

Mucho. El repo de Piebald registra más de 205 versiones de Claude Code y se actualiza minutos después de cada release. Por eso conviene no tatuarte un patrón: revisa el CHANGELOG cuando actualices y trata tu CLAUDE.md como algo vivo.

¿Reemplaza esto a leer la documentación oficial?

No, la complementa. La documentación te dice qué deberías hacer; los system prompts filtrados te enseñan cómo lo hace el equipo que diseñó la herramienta. Usa ambos: la doc para los principios, los prompts reales para la ejecución.

Lo que te llevas

Hemos visto que los system prompts filtrados son una biblioteca de patrones probados, no una curiosidad. La clave está en copiar la estructura y no el contenido, reservar el énfasis para lo innegociable y mover las reglas duras a hooks en lugar de confiarlas a un párrafo en mayúsculas. Tu CLAUDE.md mejora más leyendo cómo escribe Anthropic su prompt que añadiendo otra regla a ciegas.

¿Has reescrito tu CLAUDE.md a partir de algún prompt filtrado? Cuéntame qué patrón te funcionó en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo entro en cómo testear un CLAUDE.md como si fuera código, con evals ligeras que detectan reglas contradictorias antes de que degraden al agente.

Subagentes que lanzan subagentes: el harness recursivo

Sergio Márquez — Sat, 13 Jun 2026 08:00:01 GMT

Subagentes que lanzan subagentes: el harness recursivo

TL;DR

Un harness recursivo es un agente completo (con herramientas de ficheros, ejecución de código y planificación) que se invoca a sí mismo lanzando otros agentes, no una simple llamada al modelo dentro de otra llamada.
El paper Recursive Agent Harnesses (RAH, junio 2026) muestra que dejar al agente escribir código que lanza subagentes supera al esquema clásico de tool calling cuando la tarea es grande.
En Claude Code hoy puedes aprovechar el patrón, pero con un límite real: un subagente no puede crear sub-subagentes. El truco está en orquestar desde el agente principal con fan-out en paralelo y skills.

El problema: una tarea no cabe en una sola cabeza

Cuando le pides a un agente que procese un documento de 300 páginas, que refactorice 40 ficheros o que audite un monorepo entero, el cuello de botella no es el modelo. Es el contexto. Todo entra en la misma ventana, se mezcla, y a partir de cierto punto el agente empieza a olvidar lo que hizo hace diez pasos.

La respuesta intuitiva es delegar: que un agente principal reparta el trabajo en piezas y lance especialistas, cada uno con su propia ventana limpia. Eso es exactamente lo que hace Claude Code con los subagentes. Pero hay una pregunta más profunda que un paper reciente pone sobre la mesa: ¿y si esos especialistas también pudieran delegar? ¿Hasta dónde escala esa recursión sin que el coste y la complejidad se te vayan de las manos?

Esto importa porque el harness (el andamiaje alrededor del modelo) decide el resultado tanto o más que el modelo elegido. Si te interesa el porqué de fondo, ya escribí sobre por qué tu Claude Code necesita un agent harness. Aquí vamos un nivel más arriba: la recursión.

¿Qué es un harness recursivo?

Un harness recursivo (Recursive Agent Harness, RAH) convierte el agente entero en la unidad que se repite, no la llamada al modelo. En lugar de que un LLM se invoque a sí mismo sin herramientas, lo que se invoca de forma recursiva es un agente con acceso a ficheros, ejecución de código y planificación propia.

La diferencia con un agente normal es sutil pero cambia todo. Un agente clásico llama a herramientas predefinidas, una por turno. Un harness recursivo trata el código como acción: el agente padre lee la tarea, calcula cuánto trabajo hay y escribe un programa que lanza N subagentes, parametrizando concurrencia, rutas de salida e instrucciones en el mismo lenguaje con el que razona.

El paper RAH (arXiv 2606.13643) lo formaliza con un dato concreto: en el benchmark Oolong-Synthetic, el enfoque alcanza un 89,77% con Claude Sonnet 4.5, y la recursión del harness compone con la calidad del modelo en vez de sustituirla. Mejor modelo + recursión = mejor resultado, no uno u otro.

Las dos vías de spawn: por qué el código gana

El harness expone una sola primitiva (lanzar un subagente) de dos maneras. Aquí está el matiz que diferencia a RAH de la orquestación de toda la vida:

Vía	Cómo lanza subagentes	Límite	Cuándo gana
JSON tool calling	El agente emite una llamada estructurada y el harness ejecuta el subagente	Topado por el presupuesto de llamadas paralelas por turno	Pocas tareas (umbral de ~5 entradas)
Code-execution	El agente escribe un script (un `Task()`) que orquesta el spawn	Limitado por el coste y la profundidad que tú permitas	Cargas grandes: puede lanzar miles de subagentes

La clave: el tool calling clásico tiene un techo de paralelismo por turno. Si tienes que lanzar 200 subagentes, no caben. El camino de código no tiene ese techo porque el agente escribe un bucle. Esa es la razón por la que, en cargas grandes, RAH siempre acaba generando un script en vez de emitir llamadas sueltas.

En pseudocódigo, la idea del agente padre se parece a esto:

# El agente padre NO llama a una tool por trozo: escribe un programa que los lanza en lote
chunks = split_document(doc, by="section")   # divide el trabajo segun su tamano real
results = parallel_map(                        # spawn concurrente, sin tope de turno
    lambda c: Task(agent="summarizer", input=c, out=f"/tmp/{c.id}.md"),
    chunks,
    concurrency=8,                             # tu decides cuanto paralelismo aguanta tu presupuesto
)
final = Task(agent="reducer", input=results)   # un ultimo agente fusiona los parciales

La realidad en Claude Code: la recursión se queda en un nivel

Aquí viene el aviso honesto: en Claude Code, un subagente no puede crear sub-subagentes. Está reportado (issue #19077 del repo de Claude Code): aunque le des acceso a la herramienta Task, el subagente hijo no consigue lanzar nietos. La delegación se queda en un nivel de profundidad.

Esto no es un fallo cosmético, es una decisión de diseño razonable: la recursión sin frenos es la forma más fácil de quemar tu presupuesto de tokens y de perder el control de qué está pasando. Si quieres entender lo rápido que se dispara la factura cuando el contexto crece sin control, ya conté cómo cruzar los 200k tokens vacía tu presupuesto.

La consecuencia práctica: no montes árboles profundos esperando que cada hoja delegue. En su lugar, deja que el agente principal sea el único orquestador y haga el fan-out en rondas. Pierdes elegancia teórica, ganas previsibilidad de costes.

Cómo aplicar el patrón hoy, sin anidar

El objetivo es conseguir los beneficios de RAH (contexto aislado, paralelismo, especialización) con la restricción de un solo nivel. Tres piezas:

Subagentes especialistas definidos en .claude/agents/, cada uno con su contexto limpio y sus herramientas. Devuelven un resultado al principal y desaparecen.
Skills para el conocimiento que se repite, de modo que no tengas que reinyectar las mismas instrucciones en cada subagente. La skill se carga solo cuando la tarea encaja (progressive disclosure).
Fan-out explícito desde el principal: pide N tareas en paralelo, una por unidad de trabajo.

Un subagente especialista se define con muy poco:

---
name: section-summarizer
description: Resume una seccion de documento de forma aislada. Uno por seccion.
tools: Read, Write
model: claude-haiku-4-5-20251001   # modelo barato para trabajo repetitivo y acotado
---
Resume la seccion que recibes en 5 bullets. Devuelve solo el resumen, sin preambulo.

Y la orquestación es tan simple como ser explícito con el número. Claude Code usa subagentes de forma conservadora por defecto, así que el "cuántos" importa:

# Prompt al agente principal (el unico que orquesta)
Divide el informe en sus 8 secciones. Lanza 8 subagentes `section-summarizer`
en paralelo, uno por seccion. Cuando todos terminen, fusiona los 8 resumenes
en un resumen ejecutivo unico. No edites el informe original.

Si quieres ver cómo encaja todo esto con el ecosistema (subagents + skills frente a otros entornos), comparé el enfoque en Cursor vs Claude Code en 2026.

Harnesses empaquetados: la idea de omo

No tienes que inventar la orquestación desde cero. Proyectos como oh-my-openagent (omo) empaquetan un harness multi-agente: un orquestador central (lo llaman Sisyphus) que delega en especialistas con roles fijos, como planificación, consulta de arquitectura, búsqueda en el código y exploración rápida.

Lo interesante para tu propio setup es el patrón de routing por categoría de tarea: las tareas simples y repetitivas van a un modelo barato (o local), y el razonamiento pesado se reserva para el modelo caro. Es la misma lógica de separación de responsabilidades que aplicamos en arquitectura de software, llevada a la asignación de modelos: cada agente hace una cosa, con el recurso justo.

En Producción

El patrón funciona, pero la diferencia entre el tutorial y producción está en el coste y el control. Cuatro frentes a vigilar:

Coste real: cada subagente es una sesión con su propio consumo de tokens. Lanzar 8 en paralelo multiplica el gasto por 8 en ese instante. Para trabajo personal, un flujo de fan-out moderado entra en el rango de 10 a 50 € al mes en API; si te descuidas con árboles grandes, se dispara rápido.
Profundidad: con el límite de un nivel en Claude Code, planifica el reparto en el agente principal. Si una pieza necesita a su vez subdividirse, devuélvela al principal para una segunda ronda en lugar de buscar la anidación.
Routing de modelos: no uses Opus para resumir secciones triviales. Asigna modelos baratos (Haiku) al trabajo acotado y reserva los caros para planificación y fusión. Ahí está el ahorro de verdad.
Manejo de errores: un subagente puede fallar o devolver basura. El orquestador debe tratar cada resultado como potencialmente nulo y reintentar o descartar, no asumir que los 8 vuelven perfectos.

Una nota de honestidad: no he probado este patrón con repartos de más de unas pocas decenas de subagentes en un flujo propio. Los miles de subagentes del paper RAH son un entorno de benchmark, no tu día a día con una suscripción normal.

Errores comunes y depuración

Error: el subagente intenta lanzar otro subagente y no pasa nada. Causa: Claude Code no permite sub-subagentes (issue #19077), aunque le des la tool Task. Solución: mueve toda la orquestación al agente principal.
Error: pides "paraleliza esto" y Claude lo hace en serie. Causa: el agente es conservador con el paralelismo si no le das un número. Solución: sé explícito: "lanza 8 tareas en paralelo, una por fichero".
Error: la factura se dispara sin razón aparente. Causa: usas un modelo caro en subagentes que hacen trabajo trivial repetido. Solución: fija un modelo barato en el frontmatter del subagente.

Preguntas frecuentes

¿Un harness recursivo es lo mismo que un sistema multi-agente?

No exactamente. Un sistema multi-agente coordina agentes distintos; un harness recursivo hace que el mismo agente, con todas sus herramientas, sea la unidad que se repite. La diferencia es que el padre escribe el código que lanza a los hijos en lugar de seguir un esquema fijo de orquestación.

¿Puedo conseguir recursión real de varios niveles en Claude Code?

Hoy no de forma nativa: la delegación se limita a un nivel y los subagentes no crean sub-subagentes. El camino práctico es que el agente principal haga varias rondas de fan-out, asumiendo él el papel de orquestador en cada vuelta.

¿Cuándo merece la pena este patrón frente a un único agente?

Cuando la tarea se divide en piezas independientes y grandes: procesar muchos ficheros, resumir documentos largos, auditar módulos. Si la tarea es pequeña o las piezas dependen unas de otras, un solo agente con buen contexto suele ser más barato y más simple.

Cierre

Hemos visto que el harness recursivo lleva la delegación a su extremo lógico: agentes completos que lanzan agentes completos, escribiendo el código de orquestación en vez de seguir un guion fijo. El paper RAH demuestra que esa vía de código escala donde el tool calling clásico se topa, y que compone con la calidad del modelo. La lección transferible a tu trabajo diario es más humilde: en Claude Code, deja que el agente principal orqueste, reparte en paralelo con subagentes especialistas, apoya el conocimiento repetido en skills y vigila el coste con un routing de modelos sensato. La recursión bonita del paper se traduce, en producción, en disciplina de presupuesto.

¿Has montado un flujo de subagentes en paralelo en Claude Code? ¿Cuántos lanzas a la vez antes de que el coste te frene? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo quiero entrar en el routing de modelos por tarea: cuándo Haiku, cuándo Sonnet y cuándo de verdad necesitas Opus.

Planifica con Fable, ejecuta con Opus en Claude Code

Sergio Márquez — Fri, 12 Jun 2026 08:00:01 GMT

Planifica con Fable, ejecuta con Opus en Claude Code

TL;DR: El routing de modelos en Claude Code consiste en usar un modelo distinto para cada fase del trabajo: el más capaz (Claude Fable 5) para planificar y otro más barato (Opus 4.8 o Sonnet 4.6) para ejecutar. Se hace a mano con el comando /model sin perder el contexto de la sesión, y reduce el gasto de tokens porque la planificación consume poco y la ejecución mucho. Aquí tienes el patrón paso a paso, cuándo merece la pena y dónde se rompe.

El problema: un solo modelo para todo te sale caro

Con la llegada de Claude Fable 5 (la familia "Mythos") en la release v2.1.170, mucha gente hizo lo de siempre: poner el modelo nuevo por defecto, subir el effort a max y seguir trabajando igual. El resultado es una factura que se dispara sin que el trabajo final sea mejor.

La razón es de tokenomics básica. Fable 5 cuesta aproximadamente el doble que Opus 4.8 por token. Y aquí está la clave que casi nadie mira: las dos fases de una tarea no consumen igual. Planificar es razonamiento puro, pocos tokens de salida pero mucha "cabeza". Ejecutar (escribir archivos, editar, correr tests, iterar) genera muchísimos más tokens. Si pones tu modelo más caro a hacer la parte que más tokens quema, estás pagando precio premium justo donde menos lo necesitas.

El patrón inteligente invierte esa intuición: el modelo top razona el plan, un modelo más barato lo teclea. Es la misma lógica de separar responsabilidades en arquitectura de software, pero aplicada a qué motor usas en cada etapa.

¿Qué es el routing de modelos en Claude Code?

El routing de modelos es asignar deliberadamente un modelo distinto a cada fase de una tarea según su coste y la capacidad que exige. No es nada nuevo conceptualmente, pero Fable 5 lo vuelve casi obligatorio: la brecha de precio entre tiers ya es grande como para ignorarla.

Claude Code maneja varios alias de modelo que conviene tener claros antes de montar tu flujo:

fable: selecciona Claude Fable 5. No es el modelo por defecto en ninguna cuenta; solo se activa cuando lo eliges tú.
opus: Opus 4.8, el caballo de batalla con razonamiento fuerte a la mitad de precio que Fable.
sonnet: Sonnet 4.6, rápido y económico para el día a día.
opusplan: alias híbrido automático. Usa Opus en modo plan y conmuta a Sonnet al ejecutar.
best: apunta al modelo más capaz disponible en tu cuenta (Fable 5 donde lo tengas).

Si ya conoces el alias opusplan, el patrón de este artículo es su versión manual y un escalón por encima: en lugar de Opus para planificar, usas Fable para los planes realmente complejos, y bajas a Opus o Sonnet para picar código.

¿Por qué no existe un "fableplan" automático?

A junio de 2026 no hay un alias fableplan que combine Fable y Opus de forma automática. El único híbrido integrado es opusplan (Opus en plan, Sonnet en ejecución). Para usar Fable solo en la planificación tienes que cambiar de modelo tú, a mano, dentro de la sesión. No es un fallo: Fable arrastra una retención de datos de 30 días por monitorización de seguridad, así que Anthropic no lo enchufa por defecto en flujos automáticos.

Implementación paso a paso

El flujo cabe en cuatro pasos y no pierdes contexto al cambiar de modelo a mitad de sesión.

1. Arranca en modo plan con el modelo potente. Entra en Claude Code y selecciona Fable para la fase de diseño.

# Cambia el modelo de la sesion a Fable 5 sin reiniciar
/model fable
# Activa el modo plan (tambien con Shift+Tab) para que razone sin tocar archivos

2. Deja que planifique. En modo plan, el modelo analiza el repo y propone un plan sin escribir ni un archivo. Aquí es donde el cerebro de Fable paga: detecta dependencias, edge cases y el orden correcto de los cambios. Salida esperada: un plan estructurado que Claude te pide aprobar antes de tocar nada.

3. Cambia a un modelo más barato para ejecutar. Antes de aprobar el plan, baja de tier. El contexto de la conversación (incluido el plan) se mantiene.

# Conmuta a Opus 4.8 para la fase de implementacion (mitad de coste)
/model opus
# Si la tarea es mecanica y repetitiva, Sonnet aun mas barato:
# /model sonnet

4. Aprueba y ejecuta. Sales de modo plan, Claude implementa el plan ya razonado con el modelo barato. El trabajo de pensar ya está hecho; ejecutar es seguir instrucciones.

Si quieres dejarlo fijo entre sesiones, puedes configurar los modelos por defecto en tu configuración de proyecto mediante variables de entorno:

# Pin de modelos por alias en settings (utiliza IDs concretos)
ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-8"
ANTHROPIC_DEFAULT_FABLE_MODEL="claude-fable-5"

Cuándo usar cada tier: tabla de decisión

No todo plan necesita Fable. La regla práctica: cuanto más larga y ambigua sea la tarea, más rentable es pagar el plan caro.

Fase / tarea	Modelo recomendado	Por qué
Plan de migración grande o multi-archivo	Fable 5	Razonamiento de largo alcance, pocos tokens
Plan de un fix acotado	Opus 4.8	Fable es excesivo, Opus razona de sobra
Ejecución de código planificado	Opus 4.8	Mitad de coste, calidad sólida
Edición mecánica, boilerplate, renames	Sonnet 4.6	Rápido y barato, no exige razonar
Consultas rápidas sobre el repo	Haiku 4.5	Latencia mínima, coste casi nulo

Esto extiende la lógica de elegir entre Opus y Sonnet según la tarea: ahora añades un tier más arriba (Fable) reservado a lo verdaderamente difícil.

Caso real: una refactorización a un módulo de servicio

En un escenario típico de producto, imagina mover la lógica de validación de un endpoint FastAPI a un servicio reutilizable, tocando 6 o 7 archivos con sus tests. Hecho todo con Fable y effort alto, una tarea así puede comerse una porción notable de tu cuota diaria.

Con routing manual el reparto cambia: arrancas el plan con Fable, que detecta que dos de esos archivos comparten un import circular que hay que romper primero (un detalle que un modelo más flojo pasaría por alto). Apruebas, cambias a Opus, y la ejecución (escribir el servicio, mover métodos, ajustar imports, correr tests) corre a mitad de precio. El plan caro fueron unos pocos miles de tokens; la ejecución barata fueron decenas de miles. Ahí está el ahorro real.

En Producción

Mover esto de un truco puntual a un hábito de equipo tiene aristas que conviene conocer.

Coste y fricción. Cada /model es un cambio manual que se te puede olvidar. El ahorro existe, pero a cambio de más pasos en tu flujo. Si tu sesión es corta, a veces no compensa la gestión.
El fallback de seguridad de Fable. Las consultas que los safeguards de Fable marcan como ciberseguridad o biología se redirigen automáticamente a Opus 4.8. No se te cobra precio Fable por esas peticiones reenviadas, pero tampoco controlas cuándo pasa.
Retención de datos. Usar Fable implica retención de 30 días para monitorización de seguridad (no para entrenamiento). En entornos con requisitos de zero-data-retention, Fable puede estar bloqueado hasta que legal lo apruebe.
Effort, no solo modelo. El tier es media batalla; el nivel de effort multiplica el consumo. Un Opus a effort alto puede salir más caro que un Fable a effort medio. Ajusta ambos ejes, no solo el modelo.
Límites de sesión. Fable consume cuota distinta y más rápido. Vigila tu medidor antes de ponerlo por defecto, porque cruzar ciertos umbrales de tokens vacía el presupuesto de golpe.

Errores comunes y depuración

Error: el cambio a /model fable "se queda pegado" y todas las sesiones futuras arrancan con Fable. Causa: elegir un modelo con /model lo guarda como modelo seleccionado en tus settings de usuario. Solución: vuelve a poner tu default con /model opus (o el alias que prefieras) al cerrar, o usa el flag --model solo para esa sesión.

Error: esperabas el contexto de 1M de tokens al usar el plan con Opus y no aparece. Causa: el contexto extendido a 1M aplica al setting opus, no a la fase de plan de opusplan, que corre con la ventana estándar de 200K. Solución: si necesitas la ventana grande en planificación, fija opus directamente en vez de opusplan.

Error: el routing no ahorra nada pese a cambiar de modelo. Causa: casi siempre el effort sigue en max o haces el plan tan largo que la fase cara domina el gasto. Solución: mide el reparto plan/ejecución con tu dashboard de uso y baja el effort en la fase que no lo necesite.

Preguntas frecuentes

¿Pierdo el contexto al cambiar de modelo a mitad de sesión?

No. El comando /model conmuta el modelo manteniendo la conversación, el plan y los archivos abiertos. Cambias el motor, no la sesión.

¿Merece la pena Fable 5 si solo hago tareas pequeñas?

Normalmente no. Fable brilla en migraciones grandes, trabajo agéntico de varias horas y problemas de razonamiento profundo. Para fixes acotados y edición diaria, Opus 4.8 o Sonnet 4.6 dan mejor relación coste-resultado.

¿Hay forma automática de hacer este routing como con opusplan?

A junio de 2026, no para Fable. El único híbrido integrado es opusplan (Opus en plan, Sonnet en ejecución). El routing Fable/Opus es manual con /model, paso que debes dar tú dentro de la sesión.

Lo que te llevas

Hemos visto que el routing de modelos no va de elegir "el mejor modelo", sino de poner cada tier donde rinde: Fable razonando el plan, Opus o Sonnet tecleando la implementación. La clave está en que planificar consume pocos tokens y ejecutar consume muchos, así que pagar premium por la fase corta y barato por la larga es justo al revés de lo que hace casi todo el mundo. Y recuerda que el modelo es solo un eje: el effort y la longitud del plan pesan tanto como el tier que elijas.

¿Has montado tu propio flujo de routing en Claude Code, o prefieres dejar fijo un solo modelo? Cuéntame qué reparto te funciona en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo desmonto cómo medir el coste real de cada fase con el dashboard de uso, para que decidas el routing con datos y no a ojo.

Claude Code v2.1.170: actualiza sin romper tu CLAUDE.md

Sergio Márquez — Thu, 11 Jun 2026 08:00:01 GMT

Claude Code v2.1.170: actualiza sin romper tu CLAUDE.md

TL;DR: Claude Code v2.1.170 (publicada el 09/06/2026) añade el modelo Claude Fable 5 y corrige un fallo que impedía guardar transcripciones de sesión al lanzar la CLI desde la terminal integrada de VS Code. Actualizar es un comando, pero saltar varias versiones del ciclo 2.1.x puede cambiar cómo se comportan tus hooks, tus servidores MCP y tu settings.json. Aquí tienes el checklist para actualizar, verificar la versión y revisar tu configuración sin sorpresas a mitad de proyecto.

Por qué una release menor te puede arruinar la tarde

Actualizar Claude Code suena trivial: un claude update y a seguir. El problema no es el comando, es lo que cambia debajo. En el ciclo 2.1.x, Anthropic ha tocado el comportamiento de sesiones, hooks, MCP y memoria casi cada semana. Si arrastras un settings.json de hace diez versiones, te puedes encontrar con un hook que ahora se corta solo o un servidor MCP que deja de conectar.

El caso concreto de la v2.1.170 lo deja claro. La release corrige un bug por el que las sesiones no guardaban la transcripción (y no aparecían en --resume) cuando lanzabas Claude Code desde la terminal integrada de VS Code o cualquier shell que heredara sus variables de entorno. Si trabajas resumiendo sesiones largas, ese fallo te hacía perder contexto sin avisar. Actualizar deja de ser opcional.

¿Qué trae Claude Code v2.1.170?

La v2.1.170 tiene solo dos cambios, pero uno es grande. Según el changelog oficial:

Claude Fable 5 disponible: un modelo de clase Mythos ajustado para uso general. Ojo, queda seleccionable, no reemplaza tu modelo por defecto. Si dudas entre Fable 5 y Opus 4.8 para tareas de código, lo analizo aparte en cuándo usar Claude Fable 5 en Claude Code.
Fix de transcripciones: sesiones que no se guardaban desde la terminal de VS Code ya se registran y vuelven a aparecer en --resume.

El detalle importante es que rara vez actualizas de una versión a la siguiente. Si vienes de la 2.1.160, te tragas de golpe todos los cambios intermedios del ciclo: nuevas flags, deprecaciones y ajustes de comportamiento que sí afectan a tu configuración.

Cómo actualizar y verificar la versión en un minuto

Primero comprueba qué tienes, actualiza, y vuelve a verificar. Nunca asumas que el update se aplicó solo porque el comando no dio error.

# Comprueba la versión instalada ANTES de tocar nada
claude --version

# Actualiza a la última (las dos formas son válidas)
claude update
# o, si instalaste por npm global:
npm install -g @anthropic-ai/claude-code@latest

# Vuelve a verificar: debe mostrar 2.1.170 o superior
claude --version

Si claude --version sigue mostrando la versión vieja, casi siempre es porque tienes dos instalaciones (la del instalador nativo y una de npm) compitiendo en el PATH. Resuelve eso antes de seguir o actualizarás una y ejecutarás la otra.

Qué revisar en settings.json tras saltar de versión

El 80% de los sustos vienen de configuración heredada, no de bugs nuevos. Estos son los puntos del ciclo 2.1.x que conviene mirar en tu settings.json antes de ponerte a trabajar.

Área	Qué cambió	Acción
Transporte MCP	`sse` quedó deprecado a favor de `streamable-http` (alias `http`)	Migra los servidores MCP nuevos; los `sse` existentes funcionan un ciclo más
Hooks de stop	Un stop hook que bloquea en bucle ahora corta tras 8 bloqueos consecutivos	Ajusta el límite con `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` si lo necesitas
Colores	`NO_COLOR`/`FORCE_COLOR` en `env` ya no pisan la UI de Claude Code	Revisa que tus colores de UI vuelven; ahora solo aplican a subprocesos
MCP auto-trust	El auto-trust de `.mcp.json` ya no es el comportamiento por defecto	Declara servidores en `enabledMcpjsonServers` de forma explícita
Output styles	`/output-style` se movió a `/config`	La clave `outputStyle` en `settings.json` sigue siendo válida

Si usas servidores MCP, este es el momento de migrar el transporte. Un ejemplo mínimo del formato nuevo:

{
  "mcpServers": {
    "miServidor": {
      "type": "http",
      "url": "https://mi-mcp.example.com/mcp"
    }
  }
}

Si usas servidores MCP, este es el momento de tratarlos como integraciones estables y no como un detalle de configuración. Tienes más contexto en cómo montar flujos multi-agente con MCP en VS Code.

Qué revisar en CLAUDE.md y memoria

Un cambio de modelo o de harness puede reinterpretar tu CLAUDE.md. La v2.1.170 trae Fable 5, y cada vez que cambia el modelo por defecto las instrucciones que dabas por sentadas pueden leerse distinto. No es una teoría: con la llegada de Opus 4.8 ya vimos archivos de instrucciones que dejaron de comportarse igual, algo que detallo en cómo auditar tu CLAUDE.md cuando cambia el modelo.

Checklist rápido tras el salto de versión:

Lanza una sesión de prueba con una tarea pequeña y mira si Claude sigue respetando tus reglas (formato de commits, idioma, herramientas prohibidas).
Comprueba que --resume recupera tus sesiones, sobre todo si trabajas desde la terminal de VS Code. Ese era el bug que arregla esta release.
Revisa tu memoria automática: si tienes CLAUDE_CODE_DISABLE_AUTO_MEMORY puesto, decide si sigue teniendo sentido con el comportamiento nuevo.

Aislar fallos con safe mode

Si algo se rompe tras actualizar, arranca sin tu configuración para saber si el culpable eres tú o la release. El ciclo 2.1.x añadió una flag pensada justo para esto:

# Arranca sin CLAUDE.md, plugins, skills, hooks ni MCP
# Si el fallo desaparece, el problema está en tu config, no en la CLI
claude --safe-mode

Es el equivalente a arrancar en modo seguro. Si con --safe-mode todo funciona, vas activando piezas (primero MCP, luego hooks, luego skills) hasta encontrar la que rompe. Mucho más rápido que comentar tu settings.json a ciegas.

En Producción

En equipos, el mayor riesgo no es actualizar, es que cada uno corra una versión distinta. Un cambio de comportamiento entre la 2.1.160 y la 2.1.170 puede hacer que un pipeline que funcionaba en tu máquina falle en CI sin un solo cambio de código.

Fija la versión en CI: instala @anthropic-ai/claude-code@2.1.170 con versión explícita en lugar de @latest. Así un release nuevo no te cambia el comportamiento de un día para otro.
Desactiva el auto-updater donde no lo quieras: DISABLE_AUTOUPDATER=1 en entornos automatizados evita que la CLI salte de versión a mitad de un job.
Vigila el coste tras cambiar de modelo: Fable 5 es de clase Mythos y su perfil de tokens no es el de Opus 4.8. Antes de adoptarlo por defecto, mide. Para montar ese seguimiento, te sirve cómo ver tokens y coste de Claude Code en VS Code.
Espera unos días con un modelo recién salido: en proyectos críticos, deja que el modelo se estabilice antes de meterlo en producción. La historia reciente lo avala, basta recordar la regresión del harness en la 2.1.158 que parecía un bug del modelo.

En escenarios reales, fijar versión en el equipo y actualizar de forma coordinada cuesta cinco minutos y ahorra el clásico "en mi máquina funciona". El gasto en API ronda los 10 a 50 € al mes para un desarrollador individual, así que un cambio de modelo mal medido se nota en la factura.

Errores comunes y depuración

Error: tras actualizar, claude --version sigue mostrando la versión vieja. Causa: dos instalaciones (nativa y npm) en el PATH. Solución: localiza cuál se ejecuta primero y elimina la duplicada antes de volver a actualizar.
Error: tus sesiones de VS Code no aparecen en --resume. Causa: el bug de transcripciones previo a la 2.1.170. Solución: actualiza a 2.1.170 o superior; las sesiones nuevas ya se guardan.
Error: un servidor MCP deja de conectar tras el salto. Causa: usaba el transporte sse deprecado o dependía del auto-trust de .mcp.json. Solución: migra a streamable-http y declara el servidor en enabledMcpjsonServers.
Error: un stop hook se queda en bucle infinito. Causa: ahora la CLI corta tras 8 bloqueos consecutivos. Solución: revisa la lógica del hook o ajusta CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

Preguntas frecuentes

¿Cómo actualizo Claude Code a la v2.1.170?

Ejecuta claude update o npm install -g @anthropic-ai/claude-code@latest, y verifica con claude --version que muestra 2.1.170 o superior. Si no cambia, revisa que no tengas dos instalaciones compitiendo en el PATH.

¿La v2.1.170 cambia mi modelo por defecto a Fable 5?

No. Fable 5 queda disponible como modelo seleccionable, pero tu modelo por defecto no cambia. Tienes que elegirlo de forma explícita si quieres usarlo.

¿Es obligatorio actualizar?

Si lanzas Claude Code desde la terminal integrada de VS Code, sí conviene: la 2.1.170 corrige que las sesiones no se guardaban ni aparecían en --resume. Para el resto, actualizar te da acceso a Fable 5 y a los fixes acumulados del ciclo.

Conclusión

Hemos visto que actualizar Claude Code a la v2.1.170 es un comando, pero el valor está en lo que revisas después. La clave está en verificar la versión de verdad, repasar tu settings.json por las deprecaciones de MCP y hooks, y confirmar que tu CLAUDE.md sigue mandando con el modelo activo. En equipo, fijar versión evita que un cambio de comportamiento te rompa el pipeline sin avisar.

Si quieres dar el paso siguiente, lo natural es decidir cuándo merece la pena Fable 5 frente a Opus 4.8 para tu tipo de tarea, midiendo coste y calidad con tu propio repo. ¿Has actualizado ya y te has encontrado algo raro en tu config? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_, y de paso te leo qué modelo has dejado por defecto.

Claude Fable 5 en Claude Code: cuándo usarlo (y cuándo no)

Sergio Márquez — Wed, 10 Jun 2026 08:00:01 GMT

Claude Fable 5 en Claude Code: cuándo usarlo (y cuándo no)

TL;DR: Claude Fable 5 es el primer modelo de la clase Mythos de Anthropic disponible para todos, lanzado el 09/06/2026 y ya integrado en Claude Code desde la versión v2.1.170. Es un modelo long-horizon pensado para tareas autónomas largas (refactors, migraciones, auditorías de repos enteros), cuesta el doble que Opus 4.8 y rinde más cuanto más larga y compleja es la tarea. Aquí aprendes a seleccionarlo en Claude Code, cuándo compensa frente a Opus 4.8 y cómo evitar que dispare tu factura.

El problema: tienes un modelo nuevo y no sabes si tocarlo

Si abriste Claude Code esta semana, el selector de modelos tiene un nombre que no estaba antes: Claude Fable 5. La duda es inmediata: ¿lo pongo por defecto y a correr, o me va a vaciar el saldo en dos sesiones?

La respuesta corta es que depende de qué tarea le des. Fable 5 no sustituye a Opus 4.8 para el trabajo del día a día. Es una herramienta distinta, con un caso de uso concreto y un coste que duele si lo usas mal. Entender esa diferencia es justo lo que separa pagar de más de sacarle partido real.

En la práctica, elegir mal el modelo se nota en dos sitios: en la calidad de las tareas largas y en la factura a final de mes. Y con Fable 5 ambos efectos se amplifican.

¿Qué es Claude Fable 5 y qué significa la clase Mythos?

Claude Fable 5 es el modelo más capaz que Anthropic ha puesto a disposición general, diseñado para razonamiento exigente y trabajo agéntico de horizonte largo. Es la versión pública de una nueva familia que Anthropic llama clase Mythos, por encima de la clase Opus.

Un detalle importante para no confundirse: existe también Claude Mythos 5, el mismo modelo base pero con menos restricciones de seguridad. Ese no está disponible de forma general, solo a través del programa Project Glasswing para clientes aprobados. Lo que tú usas en Claude Code es Fable 5, con sus salvaguardas activas.

La clave es el término long-horizon. Un modelo long-horizon mantiene el contexto y el hilo de una tarea durante horas de trabajo autónomo, sin perderse a mitad de un refactor o de una migración. Según la documentación de Anthropic (junio 2026), Fable 5 está pensado para problemas que a una persona le llevarían horas, días o semanas, con autocorrección mediante bucles de verificación.

Especificaciones que conviene tener claras:

Ventana de contexto: 1.000.000 de tokens. Salida máxima de 128k tokens.
Razonamiento: adaptive thinking siempre activo. No hay un interruptor de "extended thinking" como en otros modelos; el modelo decide cuánto razonar.
ID del modelo: claude-fable-5.
Disponibilidad: Claude Code, claude.ai, GitHub Copilot, la API, AWS Bedrock, Vertex AI y Microsoft Foundry.

Cómo seleccionar Fable 5 en Claude Code paso a paso

No hay configuración compleja. Si ya tienes Claude Code actualizado a la v2.1.170 o superior, el modelo aparece solo en el selector.

Primero, actualiza para asegurarte de tenerlo disponible:

# Actualiza Claude Code a la última versión para que aparezca Fable 5 en el selector
npm install -g @anthropic-ai/claude-code

La forma más directa de arrancar una sesión con Fable 5 es pasar el flag al lanzar el CLI:

# Lanza Claude Code usando Fable 5 solo en esta sesión (no cambia tu modelo por defecto)
claude --model claude-fable-5

Si ya estás dentro de una sesión, usa el comando /model:

# Cambia el modelo activo desde dentro del CLI
/model claude-fable-5

Un matiz que cambió hace poco y conviene recordar: /model guarda tu elección como modelo por defecto para las próximas sesiones. Si solo quieres probarlo en la sesión actual sin tocar tu configuración global, pulsa s en el selector. El flag --model y la variable de entorno ANTHROPIC_MODEL afectan únicamente a la sesión que lanzas con ellos, así que puedes tener una terminal con Fable 5 y otra con Opus 4.8 a la vez.

Antes de lanzarlo en una tarea larga, te ahorrarás disgustos si revisas que tu configuración base esté al día. Un modelo de la clase Mythos rinde mucho mejor con instrucciones claras, y conviene auditar tu CLAUDE.md antes de cambiar de modelo para que no arrastre reglas que ya no encajan.

Fable 5 vs Opus 4.8: la comparativa que importa

Fable 5 gana en tareas largas y complejas; Opus 4.8 sigue siendo la mejor opción por defecto para el trabajo cotidiano por coste y latencia. Esa es la decisión en una frase.

Los números publicados por Anthropic respaldan ese reparto:

Aspecto	Claude Fable 5	Claude Opus 4.8
Clase	Mythos (tope de gama)	Opus
SWE-Bench Pro	80,3 %	69,2 %
FrontierCode	29,3 %	13,4 %
Precio entrada (por millón tokens)	~9 € (10 $)	~4,6 € (5 $)
Precio salida (por millón tokens)	~46 € (50 $)	~23 € (25 $)
Mejor para	Trabajo autónomo, largo y multi-paso	Uso general frontier

La frase de Anthropic resume bien el patrón: cuanto más larga y compleja es la tarea, mayor es la ventaja de Fable 5. En tareas cortas y bien acotadas, la diferencia se estrecha y el doble de precio deja de compensar.

Hay un matiz honesto que la comunidad ya señala: parte de esos benchmarks combinan resultados de Fable 5 y Mythos 5, y en consultas que disparan las salvaguardas Fable 5 deriva la respuesta a Opus 4.8. Así que no todo el salto de capacidad es accesible en cualquier momento. Si tu flujo es muy centrado en terminal, además, GPT-5.5 sigue liderando ese tipo concreto de tareas según las comparativas de mayo de 2026.

Si vienes de dudar entre los modelos de la generación anterior, la lógica es la misma que ya planteé al elegir entre Opus y Sonnet según la tarea: el modelo caro solo se justifica cuando la dificultad lo pide.

Aplicación práctica: para qué usarlo de verdad

El caso de uso donde Fable 5 brilla es el trabajo que normalmente partirías en muchas sesiones cortas. En mi experiencia migrando código de Java a Python, los refactors grandes son justo donde un modelo pierde el hilo: cambias un módulo y olvida las decisiones del módulo anterior.

Escenarios donde tiene sentido pagar la prima:

Auditorías de repositorios completos: cargar mucho contexto de una vez y dejar que el modelo razone sobre el conjunto.
Migraciones y portes de librerías: tareas de varias horas donde mantener la coherencia es lo difícil.
Implementar un sistema nuevo de principio a fin: planificar, escribir, ejecutar tests, depurar fallos e iterar sin supervisión constante.

Para una corrección puntual, escribir un endpoint o ajustar un test, Opus 4.8 hace el mismo trabajo a la mitad de coste. La regla práctica: si la tarea cabe holgada en un par de turnos, no necesitas Fable 5. Si vas a dejarlo corriendo mientras te tomas un café largo, ahí sí.

En Producción

Sacar Fable 5 del tutorial al trabajo real implica vigilar cuatro cosas que el selector no te cuenta.

Coste. A unos 9 € por millón de tokens de entrada y 46 € de salida (aproximadamente, el doble que Opus 4.8), una sola sesión larga con mucho contexto recargado en cada turno se come una parte seria de tu presupuesto. En Claude Code, además, consume tu límite mensual de tokens más rápido. Antes de adoptarlo conviene medir el coste real de tu Claude Code y, sobre todo, entender por qué cruzar los 200k tokens de contexto dispara el gasto.

Latencia. Fable 5 es más lento que la media (en torno a 66 tokens por segundo según mediciones independientes de junio de 2026). Para tareas asíncronas no importa, pero si esperas respuestas interactivas rápidas, notarás la diferencia frente a Opus 4.8 en modo fast.

Deferral a Opus 4.8. Cuando una consulta toca áreas de alto riesgo (ciberseguridad, bio-química), Fable 5 deriva la respuesta a Opus 4.8 por seguridad. Anthropic indica que ocurre en menos del 5 % de las sesiones y que en esos casos no se factura a tarifa Fable. Es una salvaguarda, pero implica que no siempre obtienes la capacidad que pagas.

Retención de datos. Con el lanzamiento de Fable 5 y Mythos 5, Anthropic exige una retención de 30 días de todo el tráfico, incluso a clientes que tenían acuerdos de retención cero. Dice que no usará esos datos para entrenar, solo para defenderse de jailbreaks y ataques nuevos. Si trabajas con datos sensibles, esto entra en tu evaluación de cumplimiento antes de pulsar el botón.

Cuando dejas un modelo trabajando solo durante horas, el andamiaje que lo rodea pesa tanto como el propio modelo. Si vas a darle autonomía larga, repasa primero el harness que rodea al modelo: hooks, permisos y verificación automática son tu red de seguridad.

Errores comunes y depuración

Error: Fable 5 no aparece en el selector. Causa: versión de Claude Code anterior a la v2.1.170. Solución: actualiza con npm install -g @anthropic-ai/claude-code y reinicia el CLI.

Error: pusiste Fable 5 con /model y ahora arranca por defecto en todas las sesiones. Causa: /model guarda la elección como predeterminada. Solución: vuelve al selector y elige tu modelo habitual, o usa s para aplicar un modelo solo a la sesión actual.

Error: la factura de tokens se dispara sin tareas grandes. Causa: dejaste Fable 5 como modelo por defecto para trabajo trivial. Solución: reserva Fable 5 para tareas largas y vuelve a Opus 4.8 para el día a día; lanza cada uno con su propio --model en terminales distintas.

Preguntas frecuentes

¿Claude Fable 5 es mejor que Opus 4.8?

En los benchmarks publicados por Anthropic, sí: unos 11 puntos más en SWE-Bench Pro y casi el doble en FrontierCode, con la mayor ventaja en tareas largas y complejas. En trabajo corto y rutinario la diferencia se reduce y Opus 4.8 sigue siendo más rentable.

¿Cuánto más caro es Fable 5?

Aproximadamente el doble: unos 9 €/46 € por millón de tokens de entrada/salida frente a los 4,6 €/23 € de Opus 4.8. En tareas con mucho contexto, esa diferencia se nota rápido en la factura.

¿Por qué una petición a Fable 5 me devuelve una respuesta de Opus 4.8?

Las salvaguardas de Fable 5 derivan a Opus 4.8 las consultas marcadas de riesgo (ciber, bio-química, destilación de modelos), en menos del 5 % de las sesiones. No se te cobra a tarifa Fable por esas respuestas.

Conclusión

Hemos visto que Claude Fable 5 no es un "Opus 4.8 mejorado" que pongas por defecto, sino una herramienta para un trabajo concreto: tareas autónomas largas donde mantener el contexto durante horas es el verdadero reto. La clave está en enrutar por tarea, reservarlo para refactors, migraciones y auditorías grandes, y dejar a Opus 4.8 el grueso del trabajo cotidiano por coste y latencia. Y antes de adoptarlo en serio, mide tu gasto y revisa la retención de datos.

¿Ya has probado Fable 5 en alguna tarea larga? Cuéntame en qué te ha sorprendido (para bien o para mal) en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo me meto a fondo en cómo diseñar un flujo que enrute automáticamente entre Fable 5 y Opus 4.8 según el coste y la dificultad de cada tarea.

Búsqueda híbrida en RAG: arregla lo que el vector falla

Sergio Márquez — Tue, 09 Jun 2026 08:00:01 GMT

Búsqueda híbrida en RAG: arregla lo que el vector falla

TL;DR: La búsqueda híbrida en RAG combina recuperación léxica (BM25) con recuperación semántica (embeddings) y fusiona ambas listas con Reciprocal Rank Fusion (RRF). Resuelve el punto ciego del vector search puro: códigos, siglas y nombres exactos que los embeddings no recuperan. Si le añades un paso de re-ranking con cross-encoder, pasas de "los resultados están bien" a "el chunk correcto sale el primero".

El problema: tu vector search ignora lo que escribiste literal

Un patrón que se repite cuando montas un pipeline RAG solo con embeddings: el usuario busca un código de error exacto, ERR_CONN_RESET_4XX, y el sistema devuelve tres páginas sobre "buenas prácticas de conexión". Semánticamente cercanas, prácticamente inútiles. El fragmento correcto, donde aparece el código literal, ni siquiera entra en el top 10.

La causa es estructural. Los embeddings comprimen el significado en un vector, y en esa compresión se pierde la literalidad. El vector search entiende conceptos, pero es malo con tokens raros: identificadores, SKUs, nombres propios, números de versión. Y en documentación técnica o legal, esos tokens raros suelen ser justo lo que el usuario busca.

Esto importa por dinero y por confianza. Un RAG que no recupera el chunk correcto genera respuestas incompletas o inventadas, y cada respuesta mala cuesta tokens de LLM y credibilidad. La buena noticia: la solución no es cambiar de modelo de embeddings, es cambiar de estrategia de recuperación.

¿Qué es la búsqueda híbrida en RAG?

La búsqueda híbrida es una estrategia de recuperación que ejecuta dos motores en paralelo, uno léxico (BM25) y uno semántico (embeddings), y combina sus resultados en una sola lista ordenada. Cada motor cubre el punto débil del otro: BM25 acierta con coincidencias exactas de palabras clave, los embeddings aciertan con sinónimos, paráfrasis y contexto.

Las dos piezas que necesitas entender:

BM25: algoritmo clásico de recuperación léxica basado en frecuencia de términos. Transparente, rápido y sorprendentemente fuerte cuando la consulta contiene palabras exactas del documento.
Recuperación densa (dense): convierte consulta y documentos en vectores con un modelo de embeddings y busca por similitud coseno. Capta significado, no literalidad.

¿Qué es Reciprocal Rank Fusion (RRF)?

RRF es un método para fusionar varias listas ordenadas usando solo la posición de cada documento, no su puntuación. A cada documento le asigna un valor según la fórmula 1 / (k + rank) en cada lista, y suma esos valores. Con k = 60 por defecto, un documento que aparece alto en BM25 y en dense sube por encima de los que solo destacan en uno.

La gracia de RRF es que no necesitas normalizar puntuaciones. Las escalas de BM25 y de similitud coseno son distintas e incomparables, y RRF las ignora trabajando solo con rangos. Eso lo hace ideal como primer filtro antes de algo más caro.

Comparativa: qué método recupera mejor y cuándo

Método	Fuerte en	Débil en	Coste/latencia
BM25 (léxico)	Códigos, siglas, términos exactos	Sinónimos, paráfrasis	Muy bajo
Dense (embeddings)	Significado, contexto, multilingüe	Tokens raros, literalidad	Bajo-medio
Híbrido (BM25 + dense + RRF)	Cobertura amplia (recall alto)	Orden fino del top 5	Medio
Híbrido + re-ranking	Precisión del top 5-10	Latencia y coste extra	Medio-alto

La lectura práctica: el híbrido con RRF es el mínimo razonable para cualquier RAG en producción. En un benchmark público sobre documentos con texto y tablas (arXiv, 2026), fusionar BM25 y dense con RRF mejoró todas las métricas frente a cada método por separado, con hasta +8,1 puntos de Recall@5 sobre BM25 solo. El re-ranking es el paso opcional que separa "decente" de "muy bueno".

Implementación paso a paso

La arquitectura recomendada es de dos etapas: recuperar amplio y barato, luego afinar caro y preciso. Es la misma idea de separar responsabilidades por capas: cada etapa hace una cosa y la hace bien.

Paso 1: recupera candidatos de los dos motores

Pide más de lo que vas a usar. Si el top final son 5 chunks, recupera 50 de cada motor para darle margen a la fusión.

# Recupera en paralelo: léxico (BM25) y semántico (dense)
# retrieval_k alto para que RRF tenga candidatos suficientes
sparse_hits = bm25.search(query, top_k=50)        # coincidencias exactas
dense_hits = vector_db.query(query, top_k=50)     # similitud semántica

Salida esperada: dos listas de hasta 50 documentos cada una, con solapamiento parcial. El chunk correcto suele estar en al menos una.

Paso 2: fusiona con RRF

La fórmula completa cabe en pocas líneas. No necesitas librería externa.

# RRF: suma 1/(k+rank) por documento en cada lista; k=60 estabiliza
def reciprocal_rank_fusion(listas, k=60):
    scores = {}
    for lista in listas:
        for rank, doc in enumerate(lista):
            scores[doc.id] = scores.get(doc.id, 0) + 1 / (k + rank)
    return sorted(scores, key=scores.get, reverse=True)

fused = reciprocal_rank_fusion([dense_hits, sparse_hits])

Salida esperada: una lista única ordenada donde los documentos que aparecían en ambos motores suben a la cabeza.

Paso 3: re-ranking con cross-encoder

Un cross-encoder lee la consulta y cada candidato juntos y devuelve una puntuación de relevancia directa, no un vector. Por eso es más preciso que la similitud coseno, y por eso es más caro: hay que pasar cada par consulta-documento por el modelo. Lo aplicas solo sobre el top fusionado (por ejemplo 50 o 100), nunca sobre todo el corpus.

# Cross-encoder re-puntúa los candidatos fusionados y deja el top 5
from sentence_transformers import CrossEncoder

reranker = CrossEncoder("BAAI/bge-reranker-v2-m3")  # multilingüe, va bien en español
pares = [(query, doc.text) for doc in fused[:50]]
puntuaciones = reranker.predict(pares)
top_final = [fused[i] for i in puntuaciones.argsort()[::-1][:5]]

Para español, bge-reranker-v2-m3 funciona bien y es open source. Si prefieres no gestionar el modelo, Cohere Rerank y el reranking alojado de Pinecone hacen lo mismo vía API.

Aplicación práctica: cuándo usar cada nivel

No todo RAG necesita las tres capas. La regla que aplico al diseñar el pipeline:

Solo dense: prototipos, corpus pequeño, consultas conversacionales sin jerga. Es donde casi todo el mundo empieza, igual que al preparar datos en el chunking de PDFs para IA.
Híbrido (BM25 + dense + RRF): en cuanto el corpus tiene códigos, nombres propios, referencias legales o documentación técnica. Es el salto con mejor relación esfuerzo-resultado.
Híbrido + re-ranking: cuando la calidad del top 3 es crítica, soporte al cliente, búsqueda en normativa, asistentes que citan fuentes.

En escenarios reales de documentación interna, el patrón híbrido es el que más mueve la aguja sin tocar el modelo de embeddings. Y si necesitas algo más estructurado que texto plano, un grafo de conocimiento como capa de recuperación es la siguiente parada.

En Producción

El salto del tutorial a producción se nota en tres frentes: latencia, coste y evaluación.

Latencia. El cross-encoder es el cuello de botella. Re-puntuar 100 candidatos añade cientos de milisegundos. Mitígalo recortando el número de candidatos que entran al reranker (50 suele bastar) y ejecutando BM25 y dense de forma concurrente, no secuencial.

Coste. Si usas un reranker alojado, se factura por búsqueda. Según la documentación de Cohere, Rerank cobra por consulta procesada; para un proyecto pequeño o mediano presupuesta unos pocos euros por cada 1.000 búsquedas, dentro de un rango de 10 a 50 € al mes en APIs si el tráfico es moderado. El reranker open source en tu propia infra cambia coste de API por coste de cómputo (idealmente una GPU pequeña o inferencia CPU para volúmenes bajos).

Evaluación. No adoptes una técnica por su titular. Mide Recall@k y MRR sobre un set de consultas reales antes y después. En ejemplos publicados por practicantes, pasar a híbrido subió el MRR de 0,41 a 0,67, y añadir cross-encoder lo empujó por encima de 0,80. Tus números dependerán de tu corpus, así que valídalos. Medir antes de creer es la misma disciplina que aplicas al explicar qué hace un modelo con LIME y SHAP.

Errores comunes y depuración

Error: el híbrido devuelve peor que dense solo. Causa: recuperas pocos candidatos por motor (top_k bajo), RRF no tiene material para fusionar. Solución: sube retrieval_k a 50-100 por motor y deja el corte fino al re-ranking.

Error: BM25 no encuentra términos que están en el documento. Causa: tokenización o stemming inadecuados para español (acentos, plurales). Solución: usa un analizador con soporte de español y revisa que los acentos no se pierdan al indexar.

Error: el reranker no cambia el orden. Causa: le pasas el texto completo del chunk, que excede el contexto del modelo y se trunca. Solución: recorta cada candidato a un fragmento representativo antes de re-puntuar.

Preguntas frecuentes

¿La búsqueda híbrida sustituye a un buen modelo de embeddings?

No, lo complementa. La búsqueda híbrida añade recuperación léxica encima de tu vector search para cubrir literalidad. Un mejor embedding sube la calidad semántica, pero no recupera un código exacto que el usuario escribió tal cual.

¿Necesito re-ranking si ya uso RRF?

Depende de cuánto importe el orden del top 3. RRF mejora el recall (que el chunk correcto esté en la lista), el cross-encoder mejora la precisión (que salga el primero). Si tu LLM solo recibe 3-5 chunks, el re-ranking marca la diferencia.

¿Qué reranker uso para contenido en español?

Para open source, bge-reranker-v2-m3 es multilingüe y rinde bien en español. Si prefieres API gestionada, Cohere Rerank y el reranking de Pinecone cubren más de 100 idiomas sin que mantengas el modelo.

Conclusión

Hemos visto que el vector search puro tiene un punto ciego con la literalidad, y que la búsqueda híbrida lo tapa fusionando BM25 con embeddings vía Reciprocal Rank Fusion. La clave está en la arquitectura de dos etapas: recupera amplio y barato con RRF, afina caro y preciso con un cross-encoder solo sobre los candidatos. Y mide siempre con Recall@k y MRR antes de fiarte de ningún titular de mejora.

Si ya tienes un RAG en marcha, el experimento de esta semana es claro: añade BM25 junto a tu dense, fusiona con RRF y compara métricas sobre tus consultas reales. ¿Has montado búsqueda híbrida en producción y te ha cambiado los números? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo entro en evaluación de RAG con RAGAS, cómo poner número a "esto recupera bien" sin engañarte.

Knowledge graph de tu código: el antídoto al vibe coding

Sergio Márquez — Mon, 08 Jun 2026 08:00:01 GMT

Knowledge graph de tu código: el antídoto al vibe coding

Generas 800 líneas con Claude Code en una tarde, pasan los tests, haces commit. Tres semanas después aparece un bug en producción y nadie del equipo sabe explicar por qué ese módulo funciona. Esa es la caja negra del vibe coding, y un knowledge graph del código es la forma más directa de abrirla.

TL;DR

Qué es: un knowledge graph del código convierte tu codebase en un grafo navegable donde cada función, clase y archivo es un nodo y cada llamada o import es una arista, de modo que tú (y el agente) recorréis relaciones reales en vez de adivinar con grep.
Por qué importa: el 45% del código generado por IA introduce vulnerabilidades del OWASP Top 10 (Veracode, 2025) y cada vez más desarrolladores despliegan código que no entienden. El grafo cierra esa brecha de comprensión.
Qué aprenderás: a montar un grafo de tu repo con Understand-Anything en Claude Code, a complementarlo con herramientas de dependencias como madge o dependency-cruiser, y a usarlo en producción sin fiarte ciegamente de él.

El problema: código que funciona pero nadie entiende

El vibe coding (generar con un agente, mirar por encima y commitear) es el flujo dominante en 2026. A principios de año, la mayoría de desarrolladores profesionales usan herramientas de IA al menos cada semana. El problema no es la velocidad, es lo que queda debajo.

La deuda técnica del código generado por IA no se acumula, compone. Veracode probó más de 100 modelos sobre 80 tareas en Java, Python, C# y JavaScript: casi la mitad del código introducía fallos de seguridad serios, y los modelos más nuevos no mejoraban esa cifra. Es un problema estructural, no de versión. Si esto te suena al reto de auditar lo que un modelo decide por dentro, es el mismo espíritu que cuando hablamos de explicabilidad de modelos de IA con LIME y SHAP: necesitas ver qué hay dentro antes de confiar.

El fallo concreto en producción es sutil: el agente optimiza para terminar la feature, no para que esté bien. Clava el happy path y trata los edge cases como si no existieran. En una transición de estado de un pago, un humano que ha operado el sistema añade el guard contra transiciones ilegales porque ha sentido el dolor de que el dinero se mueva hacia atrás. El agente no. Ese conocimiento no está en los datos de entrenamiento.

¿Qué es un knowledge graph del código?

Un knowledge graph del código es una representación donde cada función, clase y archivo es un nodo, y cada llamada, import o herencia es una arista tipada, de forma que se pueden recorrer las relaciones estructurales del proyecto en vez de buscarlas a ciegas.

La construcción casi siempre sigue el mismo patrón: un parser determinista (normalmente tree-sitter) convierte el código en un árbol sintáctico (AST), extrae los símbolos y las relaciones, y los guarda en una base de datos de grafo o en un JSON navegable. Es la misma lógica de partir un documento grande en piezas con sentido que aplicamos al procesar PDFs para IA con chunking, solo que aquí las piezas son funciones y sus dependencias.

Por qué grep no basta en repos grandes

Conviene entender un detalle clave: Claude Code no indexa tu código con embeddings. Navega el sistema de archivos, lee ficheros y usa grep para encontrar lo que necesita, igual que un ingeniero. Funciona muy bien hasta cierto punto. Según la documentación de Anthropic, a partir de unas 30.000 líneas el agente deja de mantener un mapa mental útil: un grep de un nombre de función común devuelve miles de coincidencias y quema contexto. El grafo hace el trabajo de curado que un índice habría hecho, pero fuera del modelo. Esa idea de que el harness importa tanto como el modelo es exactamente lo que estás aplicando aquí.

Implementación paso a paso

Hay tres familias de herramientas según lo que necesites. Empieza por la primera fila si quieres entender un repo entero, y baja a las otras para casos concretos.

Herramienta	Qué hace	Cuándo usarla
Understand-Anything	Grafo completo + dashboard interactivo, multi-agente	Onboarding, entender un repo entero o código que no escribiste
madge / dependency-cruiser	Grafo de dependencias de módulos JS/TS, detecta ciclos	Ver arquitectura y dead code, validar reglas en CI
code2flow	Call graphs por análisis estático (Python, JS, Ruby, PHP)	Trazar el flujo de llamadas de una función concreta
claude-context / cocoindex (MCP)	Búsqueda semántica del código vía MCP	Reducir tokens en repos grandes dentro del agente

Paso 1: instalar Understand-Anything en Claude Code

Es un plugin nativo de Claude Code (también funciona con Cursor, Copilot, Codex y Gemini CLI). Se instala desde el marketplace de plugins.

# Añade el marketplace y instala el plugin (dos comandos slash dentro de Claude Code)
/plugin marketplace add Lum1104/Understand-Anything
/plugin install understand-anything

Paso 2: construir el grafo

El comando /understand lanza un pipeline de varios agentes (escáner de proyecto, analizador de archivos, analizador de arquitectura) que parsea con tree-sitter y resume cada pieza con el modelo.

# Analiza el repo y genera .understand-anything/knowledge-graph.json + dashboard
/understand

# Abre el dashboard visual con los nodos coloreados por capa (API, servicio, datos, UI)
/understand-dashboard

Output esperado: un fichero knowledge-graph.json en la raíz y un dashboard donde cada nodo trae un resumen en lenguaje plano de qué hace, de qué depende y dónde encaja. La gracia es que, una vez construido, consultar el grafo no gasta más llamadas al modelo.

Paso 3: preguntarle al grafo en vez de leer 40 archivos

# Pregunta en lenguaje natural qué partes manejan autenticación
/understand-chat

# Antes de commitear: analiza el blast radius de tus cambios actuales
/understand-diff

El comando /understand-diff es el que más valor aporta en el día a día: te dice qué se ve afectado por un cambio antes de que lo subas, que es justo el punto ciego del vibe coding.

Paso 4 (alternativa ligera): grafo de dependencias sin IA

Si solo quieres ver la arquitectura y detectar ciclos en un proyecto JS/TS, no necesitas un pipeline de agentes. madge o dependency-cruiser hacen el trabajo en segundos y sin coste de tokens.

# Detecta dependencias circulares (el síntoma clásico de arquitectura enredada)
npx madge --circular src/

# Genera un grafo SVG navegable de todo el directorio src
npx depcruise src --include-only "^src" --output-type dot | dot -T svg > arquitectura.svg

Un grafo de dependencias limpio es la mejor prueba de que respetas la separación de responsabilidades: si ves flechas cruzando capas que no deberían tocarse, ahí tienes la deuda.

Caso práctico: heredar un repo vibe-coded

Un escenario común en equipos de producto: te asignan un servicio que generó otra persona a base de prompts y que ya nadie mantiene. El flujo que funciona es construir antes de tocar.

Mapea primero. Corre /understand y abre el dashboard. En 10 minutos tienes el mapa de dominios y los puntos de fragilidad sin leer una línea.
Localiza el riesgo. Usa /understand-chat para preguntar por las zonas sensibles (auth, pagos, acceso a datos).
Edita con contexto limpio. Ya en Claude Code, pide el cambio sabiendo qué nodos dependen de qué. Antes de commitear, /understand-diff.

La diferencia frente al flujo manual es de horas a minutos en la fase de orientación, que es donde más se pierde tiempo al heredar código ajeno.

En Producción

Aquí es donde el tutorial y la realidad divergen. Tres avisos honestos.

Rendimiento y coste. Construir el grafo con Understand-Anything consume tokens, porque el pipeline analiza el repo con el modelo. Para un proyecto pequeño o mediano hablamos de un coste puntual asumible (del orden de unos pocos euros por reconstrucción completa, según el tamaño). Consultar el grafo después es gratis. Si quieres coste cero, las opciones local-first como cocoindex o codegraph corren con embeddings locales sin API key. Si tu cuello de botella es el gasto del agente, esto se conecta con por qué cruzar los 200k tokens te vacía el presupuesto.

Los benchmarks son marketing. Casi todos los proyectos de code graph prometen reducciones de tokens del 40%, 70% o 90%. Son cifras auto-reportadas, sin validación independiente, y dependen del baseline del modelo. Con Opus 4.8 la navegación nativa ya es más eficiente, así que la ventaja relativa se estrecha. Trátalas como orientación, no como verdad medida.

El grafo solo ve estructura estática. tree-sitter parsea sintaxis. El comportamiento en runtime, la reflexión y el dynamic dispatch no se representan. En código muy dinámico (factories, duck-typing, funciones renombradas) el grafo se queda corto. No sustituye a leer el código crítico ni a los tests.

Errores comunes y depuración

Error: el grafo no refleja un refactor reciente. Causa: está stale, no se reindexó. Solución: usa updates incrementales (--auto-update) o reconstruye; las herramientas solo reprocesan los archivos cambiados.
Error: el agente afirma relaciones que no existen. Causa: el AST no captura llamadas dinámicas ni reflexión. Solución: complementa con LSP y tests; no decidas un refactor solo con el grafo en código dinámico.
Error: la factura de tokens se dispara al construir el grafo. Causa: el pipeline multi-agente analiza todo el repo con el modelo. Solución: limita el análisis a un subdirectorio o usa una herramienta local-first con embeddings locales.

Preguntas frecuentes

¿Un knowledge graph sustituye a leer el código?

No. Te da el mapa para saber dónde mirar y qué depende de qué, pero la regla de no commitear código que no puedes explicar sigue en pie. El grafo acelera la comprensión, no la reemplaza.

¿Funciona en repos grandes?

Sí, y es justo donde más aporta. Por encima de unas 30.000 líneas Claude Code pierde el mapa mental con grep; un grafo o una búsqueda semántica vía MCP devuelven solo lo relevante y ahorran contexto.

¿Necesito una base de datos vectorial?

Depende de la herramienta. Understand-Anything genera un JSON, sin servicios externos. Opciones como cocoindex corren local con embeddings propios. Solo MCP como claude-context piden una vector DB y embeddings, con un coste de unos pocos euros al mes según el volumen.

Cierre

Hemos visto que el vibe coding no falla por generar rápido, sino por desplegar lo que no entiendes, y que un knowledge graph del código es la herramienta más directa para cerrar esa brecha. La clave está en mapear antes de tocar, complementar el grafo con dependencias y tests, y recordar que los números bonitos de reducción de tokens son auto-reportados. El grafo te da el mapa, pero el juicio sobre los edge cases sigue siendo tuyo.

¿Has usado Understand-Anything u otra herramienta de code graph para entender un repo heredado? Cuéntame qué tal te ha ido en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo entro en cómo medir si tu suite de tests realmente protege ese código generado, con mutation testing.

Crea una Claude Skill que genera Word con tu plantilla

Sergio Márquez — Sun, 07 Jun 2026 08:00:01 GMT

Crea una Claude Skill que genera Word con tu plantilla

TL;DR: Una Claude Skill es una carpeta con un archivo SKILL.md que enseña a Claude un flujo repetitivo. En este artículo construimos una skill que genera documentos Word (.docx) respetando tu plantilla de marca: misma tipografía, mismos colores, mismo membrete, sin copiar y pegar. Verás la anatomía de una skill, cómo decide Claude activarla y cómo rellenar plantillas con docxtpl, además de qué cambia cuando lo llevas a producción.

El problema: cada informe empieza desde cero

Generar un .docx con IA es fácil. Generar uno que respete tu plantilla corporativa, con su portada, su pie de página y su tipografía exacta, es otra cosa. Lo normal es que el agente devuelva un Word genérico y acabes ajustando estilos a mano cada vez.

Ese ajuste manual es justo el tipo de tarea que una Claude Skill resuelve bien: un procedimiento que repites, con reglas claras y un formato de salida fijo. En lugar de explicarle a Claude cómo es tu marca en cada conversación, lo encapsulas una vez y lo reutilizas. Esto importa porque convierte un flujo frágil (depende de que recuerdes pegar las instrucciones) en uno reproducible y compartible con tu equipo.

¿Qué es una Claude Skill?

Una Claude Skill es una carpeta con instrucciones, scripts y recursos que Claude descubre y carga bajo demanda para realizar mejor una tarea concreta. El único archivo obligatorio es SKILL.md, que contiene metadatos (frontmatter YAML) y las instrucciones en Markdown.

La idea de fondo es la misma que separa un buen diseño de uno enredado: cada pieza tiene una responsabilidad. Si te interesa ese principio aplicado a software, lo desarrollé en la guía sobre separación de responsabilidades. Una skill aplica esa misma lógica al conocimiento del agente: instrucciones por un lado, plantillas por otro, código ejecutable aparte.

Anatomía de una skill

La estructura típica de una skill orientada a documentos es esta:

brand-docx/
├── SKILL.md          # obligatorio: instrucciones + frontmatter
├── scripts/          # opcional: código Python/Bash que Claude ejecuta
│   └── fill_template.py
├── references/       # opcional: docs que Claude lee solo si las necesita
│   └── brand-rules.md
└── assets/           # opcional: plantillas, logos, fuentes para la salida
    ├── plantilla.docx
    └── logo.png

SKILL.md: el cerebro. Define qué hace la skill y cuándo activarla.
scripts/: lógica determinista (rellenar la plantilla, validar el XML).
references/: documentación extensa que solo se carga cuando hace falta.
assets/: tu plantilla .docx, el logo y las fuentes de marca.

Cómo decide Claude activar tu skill

El campo description del frontmatter es lo que selecciona la skill. Claude no carga la skill entera de entrada: arranca solo con un índice ligero (nombre y descripción de cada skill), lee el SKILL.md completo cuando la tarea encaja, y abre los archivos de references/ o ejecuta los scripts/ solo si los necesita.

Esto se llama progressive disclosure (revelado progresivo) y es la razón de que puedas tener muchas skills sin saturar el contexto. Según la documentación de Anthropic, el índice inicial cuesta unos cientos de tokens frente a las decenas de miles que costaría cargar toda la documentación. Si te preocupa cuánto contexto consumes (y debería, lo expliqué en por qué cruzar los 200k tokens vacía tu presupuesto), este diseño juega a tu favor.

La recomendación oficial de Anthropic es mantener el SKILL.md por debajo de 500 líneas. Si crece más, mueve los detalles a references/.

Implementación paso a paso

1. Crea la carpeta y el SKILL.md

En Claude Code, las skills viven en ~/.claude/skills/ (personales) o .claude/skills/ (del proyecto). El nombre de la carpeta es el nombre del comando. Empieza por el frontmatter, que es lo que de verdad importa:

---
name: brand-docx
description: >
  Genera documentos Word (.docx) con la plantilla de marca de la empresa.
  Úsala cuando el usuario pida un informe, memo, carta o propuesta en Word,
  mencione .docx, plantilla corporativa, membrete o estilo de marca.
---

# Generar Word con plantilla de marca

Cuando el usuario pida un documento Word, NO formatees a mano.
Usa siempre la plantilla en assets/plantilla.docx y el script de relleno.

Fíjate en la description: incluye términos disparadores naturales ("informe", "memo", "plantilla corporativa", ".docx"). Cuantas más variantes reales metas, mejor acierta Claude al decidir si la skill aplica. Es el mismo cuidado que pones al escribir un buen CLAUDE.md sin ambigüedades, pero a nivel de tarea en vez de proyecto.

2. Elige el enfoque técnico correcto

Aquí está la decisión clave. No hay un único modo de producir un .docx, y elegir mal te complica la vida. Esta es la comparativa de los cuatro enfoques habituales:

Enfoque	Cuándo usarlo	Pros	Contras
docx-js (Node)	Crear documentos nuevos desde cero	Control total del layout, generación server-side	No parte de tu plantilla visual; reconstruyes estilos
python-docx	Crear o editar con estilos definidos	API clara en Python, manejo de tablas y texto	Replicar una marca exacta requiere trabajo
docxtpl	Rellenar TU plantilla con datos	Respeta la marca al 100%, usa placeholders Jinja2	Necesitas preparar la plantilla con variables
unpack/pack XML	Editar OOXML a bajo nivel	Acceso a todo (tracked changes, comentarios)	Frágil, verboso, fácil de romper

Para nuestro caso (respetar una plantilla de marca), docxtpl gana sin discusión. Un .docx es por dentro un ZIP con XML, y reconstruir tu marca desde cero con código es perder el tiempo cuando ya tienes el diseño hecho. La skill oficial docx de Anthropic, de hecho, usa docx-js para crear y un flujo de unpack/pack para editar; nosotros aprovechamos la plantilla que ya existe.

3. Prepara la plantilla con placeholders

Abre tu plantilla.docx en Word y, donde quieras texto dinámico, escribe variables con sintaxis Jinja2: {{ titulo }}, {{ cliente }}, {{ fecha }}. Mantén la tipografía y los estilos intactos; docxtpl solo sustituye el texto de los marcadores.

4. El script de relleno

El script vive en scripts/fill_template.py y hace una sola cosa: cargar la plantilla, inyectar el contexto y guardar el resultado.

# Rellena la plantilla de marca con los datos y guarda el .docx final
from docxtpl import DocxTemplate
import json, sys

# El contexto llega como JSON desde Claude (titulo, cliente, fecha, secciones...)
contexto = json.loads(sys.argv[1])

doc = DocxTemplate("assets/plantilla.docx")   # plantilla con estilos de marca
doc.render(contexto)                            # sustituye {{ variables }}
doc.save("salida.docx")                         # conserva fuentes y membrete
print("Documento generado: salida.docx")

Dependencia no estándar: docxtpl (instálala con pip install docxtpl; arrastra python-docx y jinja2). En el SKILL.md indica a Claude que invoque este script en vez de formatear a mano, y que pase el contexto como JSON. El resultado: un Word idéntico a tu marca con el contenido que pidas.

Caso real: propuestas comerciales

El escenario donde esto brilla es el de documentos recurrentes con estructura fija y contenido variable: propuestas comerciales, informes de estado, cartas de contratación. En equipos de producto, una persona redacta el fondo y la marca se aplica sola.

El flujo queda así: pides a Claude "genera una propuesta para el cliente X con estos tres entregables", la skill se activa por la description, Claude redacta el contenido, construye el JSON de contexto y ejecuta el script. Sale un .docx listo para enviar. El antes era media hora peleándote con estilos; el después son segundos. Si además alimentas el contenido desde documentos existentes, el patrón conecta bien con un pipeline de extracción y preparación de datos con Python.

En Producción

El salto del tutorial a producción tiene aristas que conviene conocer antes de confiarle la skill a un equipo.

Rendimiento y coste: la generación del .docx es local y casi instantánea; el coste real son los tokens que Claude gasta redactando el contenido. Gracias al progressive disclosure, tener la skill instalada no suma apenas contexto hasta que se usa. En un uso normal de desarrollador, hablamos de unos pocos euros al mes en API, no de cientos.
Manejo de errores: valida el contexto antes de renderizar. Si falta una variable que la plantilla espera, docxtpl falla o deja huecos. Define valores por defecto y un esquema claro de qué campos son obligatorios.
Versionado: trata la skill como código. Guárdala en el repo bajo .claude/skills/, revisa los cambios en pull request y comparte una sola fuente de verdad. Así evitas que cada persona tenga su propia copia divergente de la plantilla.
Aislamiento: las skills pueden ejecutar código, así que revisa qué scripts instalas de terceros. Una skill maliciosa es código con permisos. Si quieres entender cómo encajan skills, memoria y seguridad como sistema, lo traté en el artículo sobre agent harness.

Errores comunes y depuración

Error: la skill no se activa nunca. Causa: la description es vaga o le faltan términos disparadores. Solución: añade frases naturales que un usuario diría de verdad ("propuesta en Word", "informe con membrete").
Error: el índice de contenidos sale vacío o desactualizado. Causa: un TOC en Word no se recalcula al generar el archivo. Solución: avisa de que hay que abrir el documento y pulsar actualizar campos; no es un bug de la skill.
Error: los estilos de la plantilla se pierden. Causa: usaste un enfoque que reconstruye el documento (docx-js) en vez de rellenar la plantilla. Solución: vuelve a docxtpl sobre assets/plantilla.docx.
Error: las comillas tipográficas se rompen. Causa: mezcla de comillas rectas y curvas en el XML. Solución: normaliza el texto del contexto antes de renderizar.

Preguntas frecuentes

¿Una Claude Skill funciona solo en Claude Code?

No. El formato SKILL.md funciona en Claude Code, en claude.ai y a través de la API. Anthropic ofrece skills preconstruidas para Word, Excel, PowerPoint y PDF, y puedes crear las tuyas en cualquiera de esos entornos.

¿Cuál es la diferencia entre SKILL.md y CLAUDE.md?

CLAUDE.md guarda contexto persistente del proyecto que se carga siempre; un SKILL.md describe un flujo de trabajo y solo se carga cuando la tarea lo necesita. Usa CLAUDE.md para hechos del proyecto y skills para procedimientos repetibles.

¿Necesito saber programar para crear una skill?

Para una skill de instrucciones puras, no: basta un SKILL.md con reglas claras. Para generar Word con plantilla sí conviene un script corto en Python, pero el propio Claude puede escribirlo y mantenerlo por ti.

Cierre

Hemos visto cómo una skill convierte un flujo manual y frágil (formatear cada Word a mano) en uno reproducible: una carpeta con SKILL.md, una plantilla en assets/ y un script con docxtpl que respeta tu marca al detalle. La clave está en cuidar la description para que Claude active la skill en el momento justo, y en elegir el enfoque técnico correcto en lugar de reconstruir estilos desde cero. Versiónala como código y tendrás una pieza que todo el equipo reutiliza sin duplicar lógica.

¿Has empaquetado ya algún flujo repetitivo en una skill? Cuéntame qué automatizaste en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo le daremos una vuelta a cómo compartir skills entre proyectos sin que se conviertan en un vertedero de carpetas.

Claude Code: cruzar 200k tokens te vacía el presupuesto

Sergio Márquez — Sat, 06 Jun 2026 08:00:01 GMT

Claude Code: cruzar 200k tokens te vacía el presupuesto

TL;DR: En Claude Code, cruzar los 200k tokens de contexto no activa ningún cargo mágico, pero sí dispara el consumo por turno: cada mensaje reenvía toda la conversación, así que una sesión a 400k cuesta varias veces más por turno que una a 80k. El premium 2x por contexto largo se retiró en marzo de 2026, pero el problema sigue ahí porque es volumen, no multiplicador. Aquí tienes cómo controlar el contexto con settings.json y comandos para que no se te vaya el presupuesto sin darte cuenta.

El problema: tu sesión engorda y tú no lo ves

El patrón es siempre el mismo. Abres Claude Code por la mañana, arrancas una tarea, lees diez ficheros, lanzas tests, iteras. A media tarde sigues en la misma sesión y, de repente, tu presupuesto mensual está al 40% un martes cualquiera. Nadie tocó el modelo. Nadie hizo nada raro. Lo que pasó es que el contexto creció hasta superar los 200k tokens y empezaste a pagar (en tokens o en límites de uso) por arrastrar toda esa conversación en cada turno.

El caso que disparó las alarmas en la comunidad esta semana es claro: un usuario configuró CLAUDE_CODE_DISABLE_1M_CONTEXT=1 esperando blindarse, y aun así Sonnet 4.6 le fundió todo el crédito extra al superar los 200k. La variable no siempre actúa donde crees. Vamos a entender por qué pasa esto y cómo cortarlo de raíz.

¿Qué es el contexto facturable en Claude Code?

El contexto es todo lo que el modelo "ve" en cada turno: el system prompt, tu CLAUDE.md, cada fichero leído, cada resultado de herramienta y cada mensaje previo. El contexto crece de forma lineal: cada turno reenvía completo todo lo acumulado más lo nuevo. No es memoria gratis; es input que se procesa (y se tarifica o se descuenta de tu límite) en cada llamada.

Hasta hace poco había dos ventanas según el modelo: la estándar de 200k tokens y la ampliada de 1M (un millón) de tokens, disponible en Opus 4.6, 4.7, 4.8 y Sonnet 4.6. La diferencia importaba porque cruzar 200k te metía en territorio de contexto largo. Si quieres una base sobre cómo se acumula y dispara el gasto, lo desarrollé en cómo medir tokens y coste de Claude Code en VS Code.

La verdad incómoda: el premium 2x ya no existe (pero el coste sí)

Aquí hay que ser honesto, porque circula mucha desinformación. El 13 de marzo de 2026 Anthropic eliminó el recargo del 2x por contexto largo para Opus 4.6/4.7/4.8 y Sonnet 4.6. La ventana de 1M es GA a tarifa estándar. Según la documentación oficial de pricing de Claude, estos modelos incluyen la ventana de 1M "at standard pricing", sin multiplicador.

Entonces, ¿por qué se sigue vaciando el presupuesto al cruzar 200k? Por una razón puramente aritmética:

El coste escala con el volumen. Sin multiplicador, un turno a 400k de contexto lee unas 5 veces más tokens que un turno a 80k. Cinco veces más input procesado por turno significa, a grandes rasgos, cinco veces más coste por turno. No hay premium; hay masa.
Los límites de suscripción se consumen igual. En Pro o Max, tu cupo no mide "número de turnos", mide tokens. Un contexto hinchado quema tu límite semanal mucho más rápido aunque cada token valga lo estándar.
La caché ayuda, pero sobre una base mayor. El descuento del 90% en cache reads sigue, pero el 90% se aplica a un volumen mucho más grande. 90% de mucho sigue siendo más que 90% de poco.

La conclusión práctica: 200k no es un peaje, es un punto donde tu sesión deja de ser barata sin que ningún aviso te lo grite.

200k vs 1M: cuándo te interesa cada ventana

Aspecto	Ventana 200k	Ventana 1M
Coste por turno bajo	Sí, mientras compactes	Crece rápido con el contexto
Riesgo de quemar límites	Bajo	Alto en sesiones largas
Espacio usable real	~167k (buffer de ~33k reservado)	Hasta ~1M
Cuándo conviene	El 90% de tu trabajo diario	Auditar un codebase entero en una pasada
Modelo recomendado	Sonnet 4.6 / Opus	Opus (Sonnet rinde mal a 1M)

El dato clave: en la mayoría de sesiones reales el contexto pico ronda 80k-120k antes de compactar. Casi nunca necesitas la ventana de 1M; activarla solo te expone a hinchar la sesión.

Implementación: blinda tu contexto en 4 pasos

1. Fija el contexto en 200k y baja el umbral de auto-compactación

Estas dos variables, en tu settings.json, son la base. Desactivan la ventana de 1M y fuerzan la compactación al 80% en vez de esperar al límite.

// settings.json — vuelve a 200k y compacta antes de que sea tarde
{
  "env": {
    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80"
  }
}

Si trabajas mucho con configuración de Claude Code, revisa también que tu CLAUDE.md no esté inflando el contexto base; lo traté en cómo auditar tu CLAUDE.md con Opus 4.8.

2. Vigila el número con `/context`

Antes de seguir teorizando, mide. El comando /context te dice exactamente dónde estás:

# Muestra el uso real de contexto de la sesión
/context
# Salida tipo: 142k/200k tokens  -> aún en ventana estándar
# Si ves 320k/1000k -> estás en 1M y pagando volumen

Si la salida muestra /1000k, la ventana de 1M está activa aunque creyeras haberla desactivado. Esa es la señal de que tu env no se está aplicando donde toca.

3. Compacta pronto y limpia entre tareas

Dos hábitos cambian tu factura más que cualquier setting:

/compact al 50% o tras cada tarea cerrada. No esperes al auto-compact: cuando salta tarde, ya pagaste el pico.
/clear entre trabajos no relacionados. Una sesión nueva arranca con prefijo fresco. Arrastrar exploración vieja no solo cuesta, también ensucia el razonamiento del modelo.

4. Si estás en Pro, controla `/extra-usage`

En Pro, la ventana de 1M no es automática: se activa con /extra-usage. El problema es que mucha gente la activó "para probar" y se olvidó. Revisa tu estado y desactívala si no la necesitas hoy.

Caso real: la sesión maratón que costó de más

En escenarios reales de equipos de producto, el patrón típico es una sesión de refactor que dura tres horas. Sin compactar, el contexto trepa de 90k a 350k mientras el modelo relee los mismos ficheros en cada turno. A tarifa estándar, sin ningún premium, esa sesión consumió el equivalente a varias sesiones limpias, simplemente porque cada uno de los últimos 40 turnos arrastró 350k de input.

El arreglo no fue cambiar de modelo ni de plan. Fue trocear el refactor en sub-tareas con /clear entre ellas y compactar al 80%. Mismo trabajo, fracción del gasto. Si vienes de otros entornos, esto conecta con buenas prácticas de separación de responsabilidades: tareas acotadas, contextos acotados.

En Producción

Cuando esto deja de ser tu sesión personal y pasa a ser un equipo o workflows programados, los números se multiplican. Consideraciones reales:

Coste: en Max 20x (unos 180€/mes) un solo usuario disciplinado puede gastar el 30% del cupo; el mismo flujo sin control de contexto se va por encima del límite y empuja a pagar extra usage pay-as-you-go. La diferencia entre ambos escenarios es solo higiene de contexto.
Workflows automatizados: si lanzas tareas programadas, cada una debería arrancar en sesión limpia. Una sesión persistente que acumula contexto entre ejecuciones es una fuga garantizada.
Equipos: estandariza el settings.json con las dos variables en el repo. Un CLAUDE_CODE_DISABLE_1M_CONTEXT=1 compartido evita sorpresas en la factura del equipo.
Escalabilidad: la ventana de 1M es una herramienta puntual para auditar un codebase entero, no un modo de trabajo por defecto. Trátala como una excepción explícita.

Para entender qué otros factores disparan el gasto más allá del contexto, complementa esto con las 5 cosas que provocan cache miss y suben tu factura.

Errores comunes y depuración

Error: pusiste CLAUDE_CODE_DISABLE_1M_CONTEXT=1 y sigues viendo /1000k → Causa: la variable no se cargó en el entorno donde corre Claude Code (la pusiste en una shell, pero el proceso usa otra) o un flag de sesión la sobrescribe. Solución: fíjala en settings.json dentro de env, no solo en tu shell, y reinicia la sesión. Verifica con /context.

Error: "Usage credits required for 1M context" bloquea todo en Pro pese a tener cupo → Causa: es un bug reportado (GitHub issue #65514) donde el error salta antes de procesar el modelo, lo que hace inútiles tanto --model como la variable de entorno. Solución: a junio de 2026 sigue siendo un fallo abierto; el workaround es no activar /extra-usage y, si ya lo activaste, abrir sesión nueva sin él. Actualiza Claude Code a la última versión, porque las regresiones de harness se cuelan a menudo.

Error: el auto-compact salta tarde y te empuja por encima del umbral → Causa: el buffer de compactación reserva ~33k tokens (16,5%) y el disparo por defecto llega cuando ya pagaste el pico. Solución: baja el umbral con CLAUDE_AUTOCOMPACT_PCT_OVERRIDE y, sobre todo, compacta tú a mano antes.

Preguntas frecuentes

¿Sigue habiendo un recargo del 2x al pasar de 200k en 2026?

No. Anthropic retiró el premium por contexto largo el 13 de marzo de 2026 para Opus 4.6/4.7/4.8 y Sonnet 4.6. La ventana de 1M va a tarifa estándar. El gasto extra al cruzar 200k viene del volumen de tokens por turno, no de un multiplicador.

¿Qué hace exactamente `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`?

Devuelve la sesión a la ventana de 200k en lugar de 1M, así el contexto no puede hincharse hasta el millón de tokens. Para que funcione debe estar en el entorno real del proceso, idealmente en settings.json, y conviene verificar con /context que ves /200k.

¿Me conviene la ventana de 1M para mi trabajo diario?

Casi nunca. La mayoría de sesiones pican entre 80k y 120k de contexto antes de compactar y jamás se acercan a 200k. Reserva la ventana de 1M para casos puntuales, como auditar un codebase grande en una sola pasada, y usa Opus para ello porque Sonnet rinde mal a esa escala.

Lo que te llevas

Hemos visto que el famoso "peaje de los 200k" ya no es un recargo, sino pura aritmética de volumen: cada turno arrastra todo el contexto, y un contexto grande sale caro turno tras turno aunque la tarifa sea estándar. La defensa no es un truco, es higiene: fija la ventana en 200k, baja el umbral de auto-compactación, compacta pronto y limpia entre tareas. Con eso, una sesión maratón vuelve a costar lo que debería.

Si quieres afinar más, el siguiente paso natural es decidir cuándo subir el esfuerzo de razonamiento sin disparar el gasto, algo que desgloso en cómo usar los niveles de effort en Claude Code. ¿Has tenido un susto en la factura por contexto acumulado? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo entro en cómo orquestar sesiones largas sin perder el hilo ni el presupuesto.

Agent harness: por qué tu Claude Code necesita uno

Sergio Márquez — Fri, 05 Jun 2026 08:00:01 GMT

Agent harness: por qué tu Claude Code necesita uno

TL;DR: Un agent harness es todo lo que rodea al modelo dentro de un agente de código: el system prompt, las herramientas, la orquestación, la memoria y las verificaciones. La fórmula que resume 2026 es Agente = Modelo + Harness. En esta guía verás qué es un agent harness, por qué Claude Code y Codex dependen de él más que del modelo, y cómo diseñar el tuyo con hooks, skills y un patrón de planificar, ejecutar y verificar.

El problema: el modelo ya no es el cuello de botella

La distancia entre los modelos punteros en los leaderboards estáticos se está cerrando. Y sin embargo, dos personas con el mismo Opus 4.8 obtienen resultados muy distintos en la misma tarea. La diferencia no está en el modelo, está en lo que lo envuelve.

El dato que lo deja claro: en el Terminal-Bench, el mismo modelo de Anthropic corriendo dentro de Claude Code puntúa muy por debajo de ese modelo corriendo en otros harnesses. LangChain documentó cómo subieron su agente del Top 30 al Top 5 de Terminal-Bench 2.0 cambiando solo el harness, sin tocar el modelo. Esa es la señal del momento: esta semana han aparecido a la vez varios "meta-harnesses" sobre Claude Code y Codex con decenas de miles de estrellas en GitHub, justo cuando todos chocan con el mismo muro.

El muro tiene nombre. Los agentes de largo recorrido fallan por una razón simple: cada nueva ventana de contexto es amnesia. El modelo se descarrila tras cincuenta pasos, se detiene antes de terminar o "completa" una tarea que no pasa los tests. El harness es la disciplina que evita justo eso.

¿Qué es un agent harness?

Un agent harness es todo lo que forma parte de un agente excepto el modelo: el system prompt, el mecanismo de recuperación de código, las herramientas, los hooks, la memoria persistente y la orquestación de subagentes. El término viene de los tests de software, donde el harness es el andamiaje que permite probar un componente de forma aislada.

Birgitta Böckeler lo formalizó en Martin Fowler (02/04/2026) con una ecuación limpia: Agente = Modelo + Harness. Philipp Schmid (05/01/2026) lo lleva más lejos con una analogía útil: el harness es el sistema operativo y el agente es la aplicación que corre encima. El modelo aporta la inteligencia; el harness es el sistema que hace esa inteligencia fiable y reutilizable.

Inner harness vs outer harness

Conviene separar dos capas, porque solo controlas una:

Inner harness (el que viene de fábrica): system prompt, herramientas nativas, retrieval de código y la orquestación interna. Lo trae Claude Code o Codex y no lo tocas.
Outer harness (el que construyes tú): tus reglas, tu CLAUDE.md, tus hooks, tus skills y tu memoria de proyecto. Aquí es donde un desarrollador gana o pierde la partida.

Construir el outer harness es una forma concreta de ingeniería de contexto. Si gestionar ese contexto entre sesiones te resulta caótico, la disciplina de las tres capas de memoria que evitan el vertedero de contexto es el primer ladrillo del harness.

El patrón clave: planificar, ejecutar, verificar

El patrón de harness más estudiado de 2026 es el diseño de tres agentes de Anthropic, presentado en abril de 2026 para tareas autónomas de varias horas. Separa el trabajo en tres roles distintos:

Planificación: un agente produce una especificación (un spec en JSON, por ejemplo) que un humano revisa antes de tocar código.
Generación: otro agente implementa contra ese plan, avanzando commit a commit.
Evaluación: un tercer agente verifica el resultado contra el plan y contra criterios de calidad externos.

¿Por qué separarlos en lugar de pedirle al mismo agente que se autoevalúe? Porque los modelos puntúan en positivo cuando corrigen su propio trabajo. Addy Osmani lo resume bien: separar generación de evaluación es "GANs para prosa". El humano revisa en las fronteras entre agentes, no vigilando cada token. Es el principio clásico de separación de responsabilidades aplicado a agentes: un rol planea, otro ejecuta, otro juzga.

Este patrón también se conoce como Plan-Execute-Verify (PEV), y su diferencia con el clásico "genera y comprueba" es arquitectónica: PEV impone barreras con puertas en cada transición, no tests pegados al final.

Hooks: la capa que convierte intención en regla

Hay una frase que captura el valor del harness: los hooks son lo que separa "le dije al agente que hiciera X" de "el sistema obliga a que se haga X". Un hook que corre tu suite de tests tras cada paso y devuelve el error al modelo crea un bucle de autocorrección que no depende de la buena voluntad del agente. Si quieres montar estos controles sin tocar tu flujo, los patrones de configuración sobre tu CLAUDE.md son el punto de partida.

Los meta-harnesses: cuando alguien envuelve el wrapper

Aquí está la novedad de la semana. Han aparecido proyectos que empaquetan todo este andamiaje para que no lo reinventes en cada repo. Dos lideran la conversación:

Meta-harness	Enfoque	Piezas clave	Plataformas
ruflo (ruvnet, antes Claude Flow)	Swarms coordinados con "hive mind" y un agente reina que reparte trabajo	Memoria auto-aprendida, federación entre máquinas, servidor MCP, metodología SPARC	Claude Code, Codex
oh-my-openagent (omo)	Agentes de disciplina, orquestación paralela y "verified completion"	Skills, hooks, routing multi-modelo, `/init-deep` para memoria jerárquica, palabra mágica `ultrawork`	OpenCode, Codex (vía LazyCodex)

ruflo trae la metodología SPARC (Specification, Pseudocode, Architecture, Refinement, Completion): el swarm sabe en qué fase está y cómo pasar el trabajo a la siguiente, justo para el problema de "le pedí una feature y se fue por las ramas". omo, por su parte, ataca codebases grandes generando un AGENTS.md jerárquico con /init-deep que deja "landmarks" cerca del código que importa, y exige que la tarea pase una QA antes de darse por hecha. La instalación es de una línea:

# Instala el harness de ruflo sobre tu proyecto (añade .claude/, .claude-flow/ y CLAUDE.md)
npx ruflo@latest init

# Empaqueta omo como harness de Codex con memoria de proyecto y verified completion
npx lazycodex-ai install

Un aviso honesto: muchos de estos harnesses son jóvenes y se mueven rápido (omo iba por la v4.5.1 el 26/05/2026, con un refactor a "Multi-Harness Agent OS" en curso). En escenarios reales conviene quedarse con los patrones reutilizables (swarms, PEV, memoria jerárquica, verified completion) antes que casarte con una dependencia que cambia cada semana.

Caso práctico: cuándo te compensa montar un harness

El harness no siempre vale la pena. La regla práctica que uso: cuanto más larga y menos determinista es la tarea, más harness necesitas.

Tarea corta y mecánica (renombrar, un fix puntual): el inner harness de Claude Code sobra. Montar swarms aquí es overhead.
Refactor de varias horas sobre un repo grande: aquí el outer harness paga solo. Un agente que planifica el spec, otro que ejecuta commit a commit y un hook que corre los tests evita que el modelo "termine" algo roto.
Equipo con varios servicios: es donde encajan la federación y la memoria compartida de un meta-harness, para que los agentes de un repo conozcan los contratos de otro.

La decisión de modelo es secundaria a esto. De hecho, con un buen harness puedes bajar a un modelo más barato para la fase de generación y reservar el caro para planificar. Si todavía calibras eso a ojo, esta guía sobre cuándo subir el effort y cuándo no en Claude Code se complementa bien con el enfoque de harness.

En Producción

Lo que cambia entre el tutorial y un harness que aguanta trabajo real:

Coste: un harness de tres agentes multiplica las llamadas. Planificar, generar y evaluar por separado puede triplicar el consumo de tokens frente a un único agente. Para proyectos pequeños y medianos, presupuesta el outer harness con cabeza: un flujo con swarms agresivos se va con facilidad de 10 a 40 euros al mes en API si lo dejas suelto.
Latencia: los swarms paralelos van más rápido en wall-clock, pero las barreras del patrón PEV (esperar a que termine la planificación antes de generar) añaden tiempo. No metas barreras donde no necesitas el resultado completo de la fase anterior.
Manejo de errores: el valor del harness está en el bucle de verificación. Un hook que corre tests y devuelve el error al modelo convierte fallos anecdóticos en regresiones detectables. Sin ese bucle, solo tienes más agentes equivocándose en paralelo.
Seguridad y trazabilidad: interponer un meta-harness afecta a la caché de prompts y a las trazas. Mide antes y después: más coordinación no equivale a mejor resultado si pierdes visibilidad de qué hizo cada agente.
Curación del contexto: inyectar demasiada memoria o demasiadas herramientas degrada las respuestas antes de que el agente empiece. Las skills, como primitiva del harness, resuelven esto con divulgación progresiva: cargan solo el front-matter al inicio y el resto bajo demanda.

Errores comunes y depuración

Error: el agente "completa" la tarea pero el código no pasa los tests. Causa: el harness deja que el mismo agente se autoevalúe y se da el aprobado. Solución: separa generación de evaluación en agentes distintos y mete un hook que corra la suite de verdad.
Error: el agente se enrosca horas sin cerrar el prompt. Causa: no hay plan explícito ni puertas entre fases, así que itera sin criterio de "hecho". Solución: aplica PEV con un spec escrito y una condición de done antes de generar.
Error: respuestas peores justo después de instalar un meta-harness. Causa: demasiadas herramientas y memoria cargadas en el contexto inicial (context rot). Solución: usa skills con carga diferida y curar qué se persiste; menos es más.
Error: regresiones raras al actualizar el harness o cambiar una tool. Causa: el modelo está post-entrenado con un harness concreto y se sobreajusta a primitivas como str_replace o apply_patch. Solución: valida cambios de harness con tareas pequeñas antes de adoptarlos en serio.

Preguntas frecuentes

¿Cuál es la diferencia entre un agent harness y un framework de agentes?

Un framework como LangGraph o CrewAI te da bloques para construir un agente desde cero. Un agent harness es la capa de andamiaje que envuelve a un agente ya existente como Claude Code o Codex: prompts, hooks, memoria y orquestación que hacen su comportamiento predecible. Puedes usar un meta-harness sin escribir un framework propio.

¿Necesito ruflo u omo para tener un harness?

No. Tu CLAUDE.md, tus reglas, tus hooks y una skill bien hecha ya son un outer harness funcional. ruflo y omo solo empaquetan patrones avanzados (swarms, federación, verified completion) para que no los montes a mano. Empieza por lo simple y escala cuando la tarea lo pida.

¿Por qué el mismo modelo rinde distinto en Claude Code y en otro harness?

Porque los modelos actuales se post-entrenan junto al harness, en un bucle de co-entrenamiento. El modelo se vuelve mejor en las acciones que su harness considera importantes (operaciones de filesystem, bash, planificación). Cambiar el harness, o incluso una tool, puede mover varios puestos en un benchmark sin tocar el modelo.

Conclusión

Hemos visto que el modelo dejó de ser el factor decisivo y que el harness (todo lo que lo envuelve) es donde se gana la fiabilidad. La fórmula Agente = Modelo + Harness explica por qué el mismo Opus puntúa distinto según dónde corra, y el patrón de planificar, ejecutar y verificar con roles separados es la pieza que evita que tu agente se descarrile en tareas largas. Los meta-harnesses como ruflo y omo empaquetan esos patrones, pero lo que de verdad importa es quedarte con la idea, no con la dependencia: define el spec, separa quién genera de quién juzga, y deja que los hooks impongan la regla.

¿Has montado tu propio outer harness sobre Claude Code o Codex, o ya estás probando uno de estos meta-harnesses? Cuéntame qué patrones te funcionan en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo desmonto el patrón de swarms con agente reina y cuándo compensa frente a un único agente bien dirigido.

Cursor vs Claude Code: subagents y skills en 2026

Sergio Márquez — Wed, 03 Jun 2026 08:00:01 GMT

Cursor vs Claude Code: subagents y skills en 2026

TL;DR: Cursor ya trae subagents y skills, las dos primitivas que hicieron grande a Claude Code. Pero copiarlas no iguala el resultado: cada herramienta gana en un terreno distinto.

Cursor brilla en desarrollo dentro de un repo con contexto visual y agentes en paralelo (hasta 8 en background sobre git worktrees).
Claude Code manda en terminal, multi-repo, CI/CD y automatización headless.
Las skills usan el mismo formato SKILL.md, pero la portabilidad real entre Cursor y Claude Code aún no es perfecta.

El problema: dos agentes que ahora se parecen demasiado

Hasta hace poco la decisión Cursor vs Claude Code era sencilla: Cursor era el editor con IA, Claude Code el agente de terminal. Esa frontera se ha borrado. Cursor incorporó subagents y skills, justo las piezas que diferenciaban a Claude Code, y la pregunta cambia: si ambos tienen las mismas primitivas, ¿cuál elijo y para qué?

Esto importa porque construir skills y flujos sobre un agente es una inversión de tiempo. Si eliges mal, parte de ese trabajo no se mueve contigo. La respuesta no es fanboyismo, es entender dónde gana cada uno y qué se queda atrapado al cambiar.

¿Qué es un subagente?

Un subagente es una instancia de agente separada que se ejecuta en su propia ventana de contexto, hace una tarea acotada y devuelve solo un resumen al hilo principal. Esto mantiene limpia la conversación principal y permite paralelizar trabajo.

En Cursor, los subagents corren en contextos aislados y soporta hasta 8 agentes en background simultáneos, cada uno en su propio worktree de Git. Claude Code añade dos cosas encima de la base: un fork experimental que hereda toda la conversación y reutiliza la caché del prompt padre (arranca más barato que un subagente nuevo), y un agente Explore de solo lectura fijado al modelo rápido Haiku.

¿Qué es una skill?

Una skill es una carpeta con un archivo SKILL.md que el agente carga bajo demanda cuando su descripción de una línea encaja con la tarea, sin que tengas que repetir instrucciones. Dejas de reprommptear y empiezas a componer.

La diferencia con meter todo en un CLAUDE.md gigante es clave: la skill solo entra en contexto cuando hace falta. Es el mismo principio de separación de responsabilidades aplicado al contexto del agente: cada pieza con su trabajo, cargada cuando toca.

# SKILL.md: el agente la descubre por la descripcion y la carga sola
---
name: changelog-writer
description: Genera el changelog a partir de los commits desde el ultimo tag
---
Lee los commits con git log, agrupa por tipo (feat, fix, chore)
y redacta entradas en formato Keep a Changelog.

Cursor vs Claude Code: tabla comparativa

Criterio	Cursor	Claude Code
Interfaz	IDE visual (árbol de archivos, pestañas, terminal a la vista)	CLI / terminal, un solo panel
Subagents	Hasta 8 en paralelo, aislados en git worktrees	Subagents + fork experimental, agente Explore en Haiku
Skills	Formato SKILL.md, scope por proyecto	Formato SKILL.md, scope global y por proyecto
Mejor para	Features en un repo, mucho tooling de UI, iteración visual	Multi-repo, CI/CD, scripting, ejecución headless
Coste	Suscripción con requests incluidas (rango ~20€/mes)	Pago por uso o plan de tarifa plana, más caro por tarea equivalente
Portabilidad de skills	Limitada: scope de proyecto, hay que copiarlas en cada repo	Amplia: estándar SKILL.md compatible con varios agentes

Portabilidad: el detalle que decide tu inversión

La buena noticia: el formato SKILL.md está convergiendo. Una skill básica (revisión de código, tests, automatización de Git, documentación) funciona igual en Claude Code, Codex, OpenClaw, Gemini y Cursor copiando la carpeta al directorio correcto de cada agente.

La letra pequeña: las features avanzadas no viajan. El context: fork de Claude Code (ejecutar una skill como subagente con contexto aislado) lo ignoran otros agentes. Cursor usa scope solo-proyecto, así que las skills personales hay que copiarlas en cada repositorio. A junio de 2026, la portabilidad mejora pero no es transparente: escribe tus skills para el agente que más uses y asume conversión manual si migras.

# La misma skill instalada en varios agentes: el formato viaja, las features avanzadas no
cp -r changelog-writer ~/.claude/skills/    # Claude Code (scope global)
cp -r changelog-writer .cursor/skills/      # Cursor (scope por proyecto)
cp -r changelog-writer ~/.codex/skills/     # Codex CLI

¿Cuándo usar cada uno en producción?

La regla práctica que sigo: elige por dónde vive la tarea, no por marketing. Trabajo de feature dentro de un único codebase con mucho contexto visual encaja en Cursor. Tareas que cruzan repos, se integran con pipelines o corren sin GUI van a Claude Code.

En equipos de producto es común usar ambos en tándem: Cursor para el desarrollo activo del día (construir features, iterar con subagents viendo los diffs) y Claude Code para las operaciones de fondo (scripts de despliegue, cambios multi-repo, lotes nocturnos, integración con herramientas de gestión). No es un o esto o lo otro. Si vienes de elegir entre modelos, la lógica es la misma que en comparar Opus y Sonnet según la tarea: la herramienta sigue al trabajo.

En Producción

Coste real por tarea, no por mes. En una prueba publicada con tres cambios de código equivalentes, Claude Code costó alrededor de cuatro veces más que Cursor para el mismo trabajo (unos 7-8€ frente a 2€ aproximadamente). El número exacto da igual; la lección sí importa: con muchas iteraciones diarias, la diferencia se acumula. Vigila tu factura y compacta el historial a menudo, igual que harías para evitar los cache miss que disparan el coste de tokens.

Paralelismo con cabeza. 8 subagents en paralelo suena a velocidad, pero cada uno consume contexto y dinero. Para refactors quirúrgicos o debugging fino, un solo agente con control humano sale mejor que un enjambre que falla en cascada y luego hay que auditar.

Lock-in operativo. Las skills con scope de proyecto de Cursor no son tu librería global. Si construyes 20 skills ahí y migras, las recreas. En Claude Code, una skill global se reutiliza entre proyectos desde el primer día. Más que el modelo, lo que pesa es cómo montas el flujo: la configuración manda sobre la herramienta elegida.

Integraciones. Si tu agente depende de servidores MCP o herramientas externas, define contratos claros antes de paralelizar; un subagente que llama a una integración frágil multiplica el fallo. Aplica lo mismo que en contratos para MCP que no revientan.

Errores comunes y depuración

Error: copias una skill de Claude Code a Cursor y no se activa. Causa: usaba context: fork o rutas globales que Cursor ignora. Solución: elimina las directivas específicas y colócala en .cursor/skills/ del proyecto.
Error: factura disparada tras activar subagents. Causa: varios agentes explorando en paralelo, cada uno quemando contexto. Solución: reserva el paralelismo para tareas realmente independientes (tests, research) y usa un solo agente para debugging.
Error: el subagente devuelve un resumen pobre y pierdes detalle. Causa: tarea mal acotada, el subagente destila demasiado. Solución: dale un objetivo concreto y pídele que devuelva artefactos (diffs, rutas), no prosa.

Preguntas frecuentes

¿Las skills de Claude Code funcionan en Cursor?

Las skills básicas en formato SKILL.md sí, copiando la carpeta a .cursor/skills/. Las que usan features propias de Claude Code, como context: fork, no se traducen y hay que adaptarlas a mano.

¿Cursor reemplaza a Claude Code?

No. Cursor gana en desarrollo dentro de un IDE con contexto visual; Claude Code gana en terminal, multi-repo y automatización headless. Muchos equipos usan los dos a la vez según el tipo de tarea.

¿Cuántos subagents puede correr Cursor en paralelo?

Hasta 8 agentes en background simultáneos, cada uno aislado en su propio git worktree, trabajando de forma autónoma mientras sigues programando.

Conclusión

Hemos visto que Cursor ha cerrado el hueco de features con subagents y skills, pero la decisión sigue siendo de contexto, no de checklist. Cursor encaja en el desarrollo visual dentro de un repo; Claude Code, en terminal, automatización y trabajo multi-repo. La clave está en la portabilidad: el formato SKILL.md viaja, las features avanzadas y el scope no, así que escribe tus skills pensando en el agente que más usas y asume algo de conversión si cambias. Y recuerda que el coste por tarea, no la cuota mensual, es lo que de verdad pesa con uso intensivo.

¿Has montado un flujo con los dos a la vez o has migrado skills entre ellos? Cuéntame qué se rompió en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo desmonto el hype de los meta-harnesses multi-agente que orquestan enjambres de agentes encima de Claude Code: cuándo aportan y cuándo solo suman coste.

Opus 4.8 rompe tu CLAUDE.md: audítalo antes de seguir

Sergio Márquez — Tue, 02 Jun 2026 08:00:01 GMT

Opus 4.8 rompe tu CLAUDE.md: audítalo antes de seguir

TL;DR: Opus 4.8 ya es el modelo por defecto en Claude Code y reinterpreta directivas de tono, verbosidad y obediencia que llevaban meses funcionando en tu CLAUDE.md. Las instrucciones blandas ("por favor", "intenta") ahora se tratan como sugerencias que el modelo puede ignorar, y el agente cuestiona más tus órdenes. Aquí tienes un checklist concreto para auditar tu CLAUDE.md hoy, separar reglas duras de preferencias y testear los cambios sin quemar una sesión productiva.

El problema: el mismo CLAUDE.md, otro comportamiento

Actualizas Claude Code, sigues con tu flujo de siempre, y de repente el agente responde distinto. Más verboso en unas tareas, más contestón en otras, y a veces se planta y discute una instrucción que antes ejecutaba sin rechistar. No has tocado tu CLAUDE.md. El que ha cambiado es el modelo que lo lee.

Según la documentación de Anthropic sobre Opus 4.8, los cambios de comportamiento "no son breaking changes de la API, pero pueden requerir actualizar tus prompts". Tu CLAUDE.md es un prompt. Uno que se inyecta en cada sesión, así que cualquier desajuste se multiplica por cada tarea que lanzas.

Esto importa porque el coste de no auditarlo es real: tareas mecánicas que se llenan de explicaciones, refactors automáticos que se interrumpen para pedir confirmación, y pipelines que esperaban respuestas concisas y reciben párrafos. Si te interesa el fondo de por qué la configuración pesa más que el modelo que elijas, lo desarrollé en esta guía sobre coding agents en 2026.

¿Qué cambió en Opus 4.8 que afecta a tu CLAUDE.md?

Tres cambios concretos rompen instrucciones heredadas. Ninguno es un bug. Son decisiones de diseño que chocan con cómo escribíamos CLAUDE.md para 4.7 y anteriores.

Effort en "high" por defecto. La documentación de Anthropic confirma que el parámetro de effort arranca en high en todas las superficies, incluido Claude Code. Más razonamiento por defecto significa respuestas más elaboradas, justo lo contrario de lo que pide una regla "sé conciso".
Push-back constructivo. El system prompt del modelo lo dice explícito: Claude está dispuesto a cuestionar y ser honesto, "pero de forma constructiva". En la práctica, el agente discute más tus atajos cuando detecta que algo no encaja.
Más honestidad sobre su propio trabajo. Anthropic destaca que 4.8 es bastante menos propenso a pasar por alto sus propios fallos. Eso es bueno, pero implica que ya no traga instrucciones débiles solo por complacerte.

La consecuencia clave: Opus 4.8 distingue mejor entre una orden y una sugerencia. Una directiva escrita en tono suave la lee como preferencia opcional, no como regla.

¿Por qué falla una instrucción blanda en CLAUDE.md?

Una instrucción blanda es la que usa verbos de cortesía o condicionales en lugar de imperativos directos. Frases como "por favor intenta ser breve" o "estaría bien que uses type hints" funcionaban en 4.7 porque el modelo tendía a obedecer literalmente. Opus 4.8 las interpreta como lo que gramaticalmente son: peticiones suaves que puede priorizar o no según el contexto.

El patrón problemático más común son las listas largas de prohibiciones ("no hagas X, no hagas Y, no uses Z..."). Cuando mezclas quince "don'ts" sin jerarquía, el modelo no sabe cuáles son innegociables y cuáles son orientativas. Y con un agente que ahora cuestiona más, esa ambigüedad se traduce en interrupciones o en incumplimientos selectivos.

El patrón que funciona: reglas duras vs preferencias

Separa lo que debe cumplirse siempre de lo que es orientativo, y márcalo visualmente. Es la misma lógica de la separación de responsabilidades aplicada a tu configuración: cada bloque tiene un único propósito y un único nivel de obligatoriedad.

Tipo	Lenguaje	Ejemplo
Regla dura	Imperativo, mayúsculas para lo crítico, sin condicionales	"NUNCA hagas commit sin confirmación explícita"
Preferencia	Orientativo, agrupado aparte y etiquetado como tal	"Preferencia: respuestas concisas salvo en revisiones de arquitectura"

Antes (instrucción blanda que 4.8 puede ignorar):

# Débil: el modelo lo lee como sugerencia opcional
- Por favor, intenta no usar cat/grep, estaría bien usar rg/fd.

Después (regla dura inequívoca):

# Fuerte: imperativo claro, sin margen de interpretación
## Reglas (obligatorias)
- NUNCA uses cat/grep/find. Usa SIEMPRE rg/fd/bat.
- NO hagas commit ni push sin confirmación explícita.

## Preferencias (orientativas)
- Respuestas directas y sin preámbulo cuando la tarea es mecánica.

El mismo principio aplica a cualquier stack. En reglas para Python o TypeScript, marca lo innegociable como bloque imperativo:

# Regla dura para el agente, no comentario decorativo
# OBLIGATORIO: toda función pública lleva type hints y docstring.
# OBLIGATORIO: no captures Exception genérica, usa el tipo concreto.

Checklist de auditoría de tu CLAUDE.md

Recorre tu archivo con esta lista. Cada punto es un patrón que se volvió contraproducente con 4.8.

Caza las frases de cortesía. Busca "por favor", "intenta", "estaría bien", "si puedes". Conviértelas en imperativos o muévelas a un bloque de preferencias.
Separa reglas de preferencias. Dos secciones distintas con encabezados claros. No mezcles obligatorio con orientativo en la misma lista.
Reduce las listas de "don'ts". Si tienes diez prohibiciones, quédate con las tres críticas en mayúsculas y reformula el resto como criterio positivo ("haz X" en vez de "no hagas Y").
Revisa las reglas de verbosidad. Con effort en high por defecto, una sola línea "sé conciso" no basta. Especifica cuándo: "respuestas breves en tareas mecánicas, detalle solo en decisiones de arquitectura". Si dudas sobre el nivel de razonamiento, repasa cuándo subir el effort a max y cuándo no.
Comprueba que las reglas siguen siendo válidas. Una regla que dependía de que el modelo "obedeciera ciego" puede sobrar ahora que cuestiona mejor. No acumules basura: tu CLAUDE.md es la capa que más conviene mantener curada, como expliqué al hablar de las tres capas de memoria en Claude Code.

Cómo testear los cambios sin perder la sesión

No edites a ciegas y reces. Valida con un prompt de control antes de meter el CLAUDE.md nuevo en una tarea larga. El objetivo es ver cómo interpreta el agente tus reglas, no si resuelve la tarea.

Un prompt de validación rápido que uso:

# Pide al agente que te explique cómo entiende tus propias reglas
"Lee mi CLAUDE.md. Lista qué consideras reglas obligatorias
y qué consideras preferencias orientativas. No ejecutes nada."

Si el agente clasifica como "preferencia" algo que tú das por obligatorio, ahí tienes el desajuste. Para cambios delicados, abre dos sesiones, una con el CLAUDE.md viejo y otra con el nuevo, lánzales la misma tarea pequeña y compara. Es el mismo enfoque de medir en lugar de intuir que apliqué para detectar si Claude se ha vuelto más tonto: una comparativa side-by-side vale más que cualquier sensación.

En Producción

Lo que cambia entre el tutorial y un flujo real: en pipelines automatizados con Claude Code, la verbosidad extra de 4.8 no es solo molesta, cuesta tokens y puede romper parsers que esperaban salidas escuetas. Si un script tuyo lee la respuesta del agente, audita primero las reglas de formato.

Coste: effort high por defecto consume más tokens por turno que el default de 4.7 en la misma tarea. Para trabajo mecánico (boilerplate, tests repetitivos), baja el effort de forma explícita en la sesión en lugar de pelearte con el CLAUDE.md.
Manejo de errores: el push-back significa más interrupciones para confirmar. En flujos desatendidos, define en reglas duras qué decisiones puede tomar solo el agente y cuáles requieren parar. La ambigüedad aquí se paga en tareas a medias.
Escalabilidad: si gestionas varios proyectos, no tengas un CLAUDE.md monolítico distinto por repo con las mismas reglas copiadas. Centraliza las reglas duras globales y deja en cada proyecto solo lo específico.
Versiona el cambio: guarda el CLAUDE.md anterior antes de auditar. Si el comportamiento empeora, vuelves en segundos en vez de reconstruir de memoria.

Un trade-off honesto: este enfoque de reglas duras frente a preferencias funciona muy bien para equipos pequeños y proyectos propios. No lo he probado con CLAUDE.md compartidos por equipos grandes donde cada persona añade su capa, ahí la disciplina de mantenerlo curado es el verdadero cuello de botella.

Errores comunes y depuración

Error: el agente ignora una regla que considerabas crítica. Causa: estaba redactada en tono suave o enterrada en una lista de "don'ts". Solución: reescríbela en imperativo, mayúsculas para lo innegociable, en una sección de reglas separada.
Error: respuestas demasiado largas en tareas triviales. Causa: effort high por defecto más una regla de concisión vaga. Solución: concreta cuándo aplicar brevedad y baja el effort en la propia sesión para trabajo mecánico.
Error: el agente se planta y discute en mitad de un refactor automático. Causa: el push-back de 4.8 sin reglas claras sobre autonomía. Solución: define explícitamente qué puede decidir solo y dónde debe parar.

Preguntas frecuentes

¿Tengo que reescribir todo mi CLAUDE.md desde cero?

No. La mayoría del contenido sigue siendo válido. El trabajo es de auditoría puntual: reformular instrucciones blandas a imperativos y separar reglas duras de preferencias. Tirar el archivo entero a la basura es desperdiciar meses de contexto curado.

¿Puedo volver a Opus 4.7 si no quiero auditar ahora?

Sí, puedes seguir seleccionando 4.7 en Claude Code mientras tu CLAUDE.md está muy optimizado para ese modelo. Es una solución temporal razonable si dependes de respuestas muy concisas en pipelines automatizados y no tienes tiempo de auditar hoy.

¿Por qué Opus 4.8 me cuestiona más que antes?

Es comportamiento de diseño. El system prompt del modelo lo describe como push-back constructivo, y Anthropic mejoró su honestidad para que no ignore problemas que detecta. Con reglas claras sobre su margen de autonomía, esas interrupciones bajan mucho.

Conclusión

Hemos visto cómo Opus 4.8 reinterpreta tu CLAUDE.md: el effort en high infla la verbosidad, el push-back hace que cuestione más, y las instrucciones blandas pasan de órdenes a sugerencias opcionales. La clave no está en escribir más reglas, sino en escribirlas mejor: imperativos inequívocos para lo innegociable, un bloque aparte para las preferencias, y un prompt de validación que te diga cómo entiende el agente tus propias reglas antes de jugártela en una sesión larga.

Empieza hoy por lo barato: caza las frases de cortesía y separa reglas de preferencias. Es media hora de trabajo que te ahorra días de fricción. ¿Has notado a tu Claude Code más parlanchín o más contestón tras el salto a 4.8? Cuéntame qué regla se te rompió en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo entro en cómo medir el coste real por tarea de Opus frente a Codex en sesiones largas, que es la otra cara de este cambio de default.

Cuánto gasta tu Claude Code: tokens y coste en VS Code

Sergio Márquez — Mon, 01 Jun 2026 08:00:01 GMT

Cuánto gasta tu Claude Code: tokens y coste en VS Code

TL;DR

Un dashboard de uso de Claude Code te muestra cuántos tokens consumes, cuánto cuesta cada sesión y cuánto te queda de límite, sin salir de VS Code. No hay una extensión oficial de Anthropic para esto, pero el Marketplace está lleno de extensiones de comunidad que leen tus ficheros de sesión locales y lo pintan en una barra de estado. Lo nativo y oficial vive en el comando /usage, la statusline y OpenTelemetry. Aquí ves cuál usar según si quieres un vistazo rápido, histórico para presupuestar o un panel de equipo.

El problema: programas a ciegas sobre tu factura

Claude Code consume tokens en cada turno y no pone un contador grande delante de ti. Con un plan de suscripción gastas cupo de unas ventanas de uso; con la API gastas euros directos. En ambos casos el dolor es el mismo: te enteras de que ibas rápido cuando ya te han cortado a mitad de tarea o cuando llega el cargo.

En mi experiencia migrando flujos de trabajo a agentes de código, el consumo no es lineal ni intuitivo. Un refactor de varios ficheros con razonamiento alto puede gastar en diez minutos lo que una mañana entera de preguntas cortas. Sin un dashboard de uso de Claude Code dentro del editor, ese gasto es invisible hasta que duele.

Medir el consumo no es contabilidad opcional. Es parte del flujo: te dice qué prompts disparan el gasto, cuándo conviene bajar de modelo y cuánto margen real te queda antes de un límite.

¿Qué es la observabilidad de consumo en Claude Code?

La observabilidad de consumo es la capacidad de ver, en tiempo real o de forma histórica, cuántos tokens y cuánto coste genera tu uso de Claude Code. Se apoya en un dato que ya existe en tu máquina: cada sesión queda registrada en ficheros JSONL dentro de ~/.claude/projects/, con los tokens de entrada, salida, creación de caché y lectura de caché, y el modelo usado en cada turno.

Esa es la clave que casi nadie aprovecha. No necesitas un servicio externo para saber lo que gastas, porque el registro está en local. Las herramientas que verás abajo se limitan a leer esos ficheros y presentarlos de forma legible, o a exportar las mismas métricas por un canal estándar.

Lo nativo: el comando /usage y la statusline

Antes de instalar nada, Claude Code ya trae dos formas oficiales de mirar el gasto.

El comando /usage (con sus alias /cost y /stats) es el camino más directo. Dentro de una sesión te muestra el coste estimado, los tokens, la duración y los cambios de código. En planes Pro, Max, Team y Enterprise añade además barras de límite de plan, con la ventana de 5 horas y el cap semanal, y atribuye el uso reciente a skills, subagentes, plugins y servidores MCP. Las teclas d y w alternan entre las últimas 24 horas y los últimos 7 días.

Hay un matiz importante: ese euro o dólar es una estimación local calculada desde los tokens, no tu factura. Solo cuenta el historial de esa máquina, así que no incluye otros dispositivos ni el uso de claude.ai con la misma cuenta.

La statusline nativa deja el dato siempre a la vista. Recibe por stdin un JSON con cost.total_cost_usd y context_window.used_percentage, entre otros campos, y lo pintas debajo del prompt. Como mantiene totales acumulados de respuestas ya finalizadas, suele ser más fiable para el agregado de sesión que leer el JSONL en crudo. Contexto y coste van de la mano, y por eso conviene tenerlos juntos: lo desarrollé al hablar de las capas de memoria y contexto en Claude Code, porque cuanto más llenas la ventana, más pagas por turno.

Extensiones de VS Code que sí existen (todas de comunidad)

Anthropic no publica una extensión oficial de tokens, pero la comunidad ha llenado ese hueco. Casi todas leen los mismos JSONL locales y los pintan dentro del editor. Estas son las verificadas a fecha de este artículo (junio de 2026), con su ID exacto del Marketplace, porque varias tienen nombres casi idénticos:

Extensión (ID Marketplace)	Qué te da	Fuente de datos
Claude Code Usage Dashboard `man-vu.claude-code-usage-dashboard`	Barra de estado más panel analítico: rate limits, coste equivalente a API, tokens, caché y distribución por modelo y proyecto	JSONL local; una llamada de red solo para el rate limit
Claude Code Usage Monitor `suzuki0430.ccusage-vscode`	Coste de hoy en la barra, refresco cada 30 s, tabla de los últimos 7 días. Funciona en VS Code y Cursor	JSONL local (inspirada en ccusage)
Claude Code Usage `growthjack.claude-code-usage`	Coste de hoy y de la sesión, cuota de 5 h y semanal, advisor opcional. Multi-idioma con español parcial. MIT	Logs locales, estima por precio público
Claude Code Dashboard `jspw.claude-code-dashboard`	Pestañas Overview, Charts, Search e Insights: tendencia de 30 días, heatmap, hot files, búsqueda de prompts. AGPL-3.0	Todo local, sin API key
Clusage `Ajax1029.clusage`	Gasto del día, cuota 5 h/semanal real, reset timer y panel de 6 secciones. Refresco por file-watcher	JSONL local + headers de rate limit vía OAuth

El detalle que separa a unas de otras es de dónde sacan la cuota. Las que muestran el límite real de 5 horas y semanal (como Clusage o el dashboard de man-vu) hacen una llamada mínima a api.anthropic.com para leer los headers anthropic-ratelimit- usando el token OAuth de tu ~/.claude/.credentials.json. Las demás solo estiman coste multiplicando tokens por precio público.

ccusage: el histórico que sí presupuesta

ccusage, de ryoppippi, es la herramienta de línea de comandos de comunidad que se ha vuelto el estándar de facto. Lee tus JSONL locales y agrega el gasto por día, mes, sesión y bloques de 5 horas. No es una extensión de editor, pero varias de las de arriba la usan como motor por debajo.

Se ejecuta sin instalación previa con npx:

# Resumen de consumo por dia leyendo los ficheros locales de sesion
npx ccusage@latest daily

# Bloques de 5h: mapea la ventana de uso y te dice cuanto queda en la actual
npx ccusage@latest blocks

El modo blocks es el más útil con suscripción, porque dibuja la ventana de facturación de 5 horas y el burn rate. El desglose por modelo (--breakdown) te enseña negro sobre blanco cuánto cuesta tirar de Opus frente a Sonnet, una decisión que toqué al comparar cuándo elegir Opus o Sonnet en Claude Code. Estima el coste con el pricing de LiteLLM, así que conviene usar siempre @latest para que los precios estén al día.

También trae su propia statusline (ccusage statusline), que muestra coste de sesión, del día y del bloque, burn rate con colores y porcentaje de contexto usado, todo en la barra inferior.

Para un panel de equipo: OpenTelemetry

Si quieres un dashboard standalone, con gráficas históricas y agregado de varias personas, el camino oficial es la exportación por OpenTelemetry (OTEL). Claude Code emite métricas, eventos y traces (estos en beta) sin SDK ni wrapper, solo con variables de entorno:

# Activa la telemetria y exportala por OTLP a tu colector
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Las métricas tienen nombres exactos: claude_code.token.usage (desglosado por tipo input, output, cacheRead y cacheCreation, y por usuario, equipo y modelo) y claude_code.cost.usage en dólares, además de líneas de código, commits y pull requests. Las recoges en Prometheus o Grafana; existe incluso un dashboard publicado en Grafana Labs (ID 25255) listo para consumir estas métricas.

Dos avisos prácticos. El primero: hay una latencia normal de unos 75 a 90 segundos antes de ver datos, porque Claude Code exporta cada 60 segundos y Prometheus scrapea cada 15. El segundo: el contenido sensible (prompts, parámetros de Bash, bodies de la API) está desactivado por defecto, lo cual está bien, pero tenlo en cuenta si esperabas verlo.

Extensión de editor frente a panel standalone

La elección de fondo es esta: extensión dentro de VS Code si quieres el número donde ya trabajas y te basta con el día y la sesión, o dashboard OTEL standalone si necesitas historial, comparativas y agregado de varios usuarios para FinOps. No son excluyentes. Lo habitual en solitario es ccusage o una extensión para el día a día, y OTEL solo cuando hay un equipo que presupuestar.

En Producción

Cuando esto deja de ser un experimento y se vuelve tu forma de trabajar diaria, importan los números reales.

Suscripción frente a API: los planes son Pro a 20 $ al mes (unos 18 €), Max 5x a 100 $ (unos 92 €) y Max 20x a 200 $ (unos 184 €). Con suscripción no pagas por token sino cupo, así que el dato que importa no es el coste en euros, es cuánto cupo te queda. Max no es otro modelo, es más margen sobre los mismos modelos.
Coste de API: el output cuesta 5 veces el input en todos los modelos actuales, y los descuentos de verdad vienen del Batch API (un 50% menos) y del prompt caching (hasta un 90% menos sobre el input cacheado). Para un desarrollador con proyectos pequeños y medianos, un gasto razonable suele moverse entre 10 y 50 € al mes. Las cifras exactas por modelo cambian con cada versión, así que verifícalas en la página oficial de Anthropic, que advierte que están sujetas a cambio.
Doble límite simultáneo: una ventana móvil de 5 horas más un cap semanal (vigente desde agosto de 2025), con un sub-límite más estricto para Opus. Al tocar cualquiera de los dos se bloquean los prompts hasta el reset, sin override manual. Y el pool es compartido entre Claude Code y claude.ai con la misma cuenta. Ojo, estos límites se mueven mes a mes: trata cualquier número como caducable.
El gasto lo dispara la configuración, no el modelo: el nivel de razonamiento, el tamaño del contexto y los fallos de caché pesan más que la etiqueta del modelo. Lo desarrollé en por qué la configuración pesa más que el modelo en los coding agents y, en concreto sobre factura, en las cosas que disparan tu factura por cache miss en Claude Code.

Errores comunes y depuración

Error: el euro que muestra /usage o una extensión no cuadra con tu factura. Causa: todas estas cifras son estimaciones por precio público multiplicado por token, no facturación. Con suscripción el uso va incluido en la cuota. Solución: para facturación autoritativa usa el Console web de Anthropic; con plan de suscripción mira tokens y porcentaje de cupo, no euros.

Error: Claude Code te cobra a tarifa API aunque tengas plan Max. Causa: tienes ANTHROPIC_API_KEY exportada en el shell, y Claude Code la detecta y factura por token ignorando la suscripción. Solución: quita esa variable del entorno cuando uses tu plan; el extra de pago por token puede costar varios euros por hora con Opus.

Error: una extensión que solo lee JSONL reporta menos consumo del real. Causa: Claude Code escribe el JSONL durante el streaming, así que muchas entradas tienen input_tokens en 0 o 1 y hay duplicados por requestId. Solución: usa herramientas que deduplican por requestId, o fíate de la statusline y del comando nativo para el agregado de sesión.

Preguntas frecuentes

¿Hay un dashboard oficial de uso de Claude Code en VS Code?

No. A junio de 2026 Anthropic no publica una extensión oficial de tokens. Lo oficial es el comando /usage, la statusline y la exportación por OpenTelemetry. Para un panel dentro del editor tienes extensiones de comunidad como las de man-vu, suzuki0430 o GrowthJack, y para histórico por consola, ccusage.

¿Estas herramientas envían mi código a algún servidor?

Las basadas en JSONL y ccusage procesan todo en local. Algunas hacen una llamada mínima a la API solo para leer tus límites de cuota usando el token OAuth que ya tienes. Si montas OpenTelemetry hacia un colector remoto, ahí sí sale tráfico de tu máquina, aunque el contenido sensible va desactivado por defecto.

¿Cómo sé cuánto me queda de límite con un plan Max?

El comando /usage muestra barras con la ventana de 5 horas y el cap semanal en planes de suscripción. Para verlo siempre en el editor, una extensión que lea los headers de rate limit, como Clusage, te da el porcentaje y el tiempo de reset sin abrir otra ventana.

Lo que te llevas

Hemos visto que el dato de consumo ya está en tu máquina y que medirlo es cuestión de elegir la lente adecuada: /usage y la statusline para lo nativo, una extensión de comunidad si quieres el panel dentro de VS Code, ccusage para presupuestar con histórico y OpenTelemetry cuando hay un equipo detrás. La clave está en convertir el gasto en algo visible, porque lo que no se mide se dispara sin avisar, y la mitad de los sustos vienen de detalles tontos como una ANTHROPIC_API_KEY olvidada en el shell.

Si trabajas con razonamiento alto, el siguiente paso natural es cruzar este consumo con cuándo merece la pena subir el esfuerzo, algo que tienes en cuándo subir el effort a max en Claude Code y cuándo no. ¿Ya vigilas tus tokens o programas a ciegas? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_.

Claude Code 2.1.158: la regresión del harness que parece bug de Opus

Sergio Márquez — Sun, 31 May 2026 08:00:01 GMT

Claude Code 2.1.158: la regresión del harness que parece bug de Opus

TL;DR: Las versiones 2.1.154 a 2.1.158 de Claude Code tienen una regresión real en la capa cliente (harness) que corrompe la entrega de resultados de tool_use al modelo. Los comandos se ejecutan una vez, pero los resultados llegan vacíos, tarde o fuera de orden, y el modelo reacciona con lecturas duplicadas, llamadas inventadas y gasto excesivo de tokens. No es Opus 4.8 volviéndose tonto. El fix temporal es fijar la versión a 2.1.157 con npm install -g @anthropic-ai/claude-code@2.1.157 hasta que Anthropic publique una versión limpia.

El síntoma que despista: parece el modelo, es el cliente

Esta semana se ha repetido el mismo patrón en foros: gente actualizando a Opus 4.8, abriendo Claude Code y notando comportamientos raros. Lecturas repetidas del mismo archivo, llamadas a herramientas que se reintentan sin motivo, instrucciones del system prompt ignoradas y facturas hinchadas sin tarea que lo justifique.

El reflejo natural es culpar al modelo. Es lo que más cambió y lo que más se nota en marketing. Pero el cliente CLI también cambió, y mal. Los reportes en el repositorio oficial de Anthropic ya lo confirman como regresión: en versión 2.1.157 todo fluye normal y, tras el auto-update a 2.1.158, el mismo Opus 4.8 entra en bucles de tool calls redundantes (issue #63935).

El bug no está en lo que el modelo decide, sino en lo que el modelo recibe. Ese matiz cambia toda la depuración.

¿Qué es el harness y por qué importa?

El harness es la capa cliente que envuelve al LLM. En Claude Code es el binario CLI: gestiona el bucle de mensajes, ejecuta tool calls (Bash, Read, MCP), recoge los resultados y los empaqueta de vuelta al modelo en el siguiente turno.

Cuando el harness funciona, el modelo ve una conversación coherente: pidió leer un archivo, el archivo aparece, decide qué hacer. Cuando el harness falla, el modelo ve agujeros: pidió leer 4 archivos, aparecen 2, los otros llegan tarde con el orden cambiado. Ante datos rotos, un modelo bien entrenado intenta reparar la situación: relee, reintenta, inventa pruebas (\"echo PROBE\") y termina quemando tokens en reconstruir un canal que él no controla.

Si quieres una analogía útil del tipo de capas que componen un agente, lo tienes desglosado en skills y subagentes como ladrillos base.

Cómo identificar la regresión en tu sesión

Antes de tocar nada, comprueba la versión:

# Versión actual del cliente Claude Code
claude --version

Si estás entre 2.1.154 y 2.1.158, son candidatas a regresión confirmada. Los síntomas concretos descritos en los reportes oficiales:

Tool results vacíos en la UI: ves (No content) o cadenas tipo "start..." donde debería haber el contenido del archivo, aunque wc -c confirma que el archivo se generó bien.
Lecturas tardías y fuera de orden: cuatro echo en paralelo (P1 a P4) llegan en orden P1, P3, P4, P2.
Llamadas duplicadas a Read: el modelo lee el mismo archivo dos o tres veces porque la primera lectura no llegó.
Errores 400 "thinking blocks cannot be modified" en sesiones que pasan por bridge o wakeup (issue #63394, específicamente en 2.1.154).
Gasto de tokens desproporcionado para una tarea trivial.

Si ves dos o más de estos síntomas, no es paranoia: estás dentro del bug.

Workaround: fijar 2.1.157 sin romper tu configuración

La instalación bajo demanda de una versión concreta vía npm es trivial. Lo importante es no perder tu CLAUDE.md, tus settings.json, hooks ni MCP servers.

Paso 1: respaldo rápido

# Respaldo del directorio de configuración global antes de tocar nada
cp -r ~/.claude ~/.claude.backup-$(date +%Y%m%d)

Paso 2: instalar la versión limpia

# Fija el cliente en la última versión sin regresión conocida
npm install -g @anthropic-ai/claude-code@2.1.157
claude --version  # Debe imprimir 2.1.157

La configuración vive en ~/.claude/ y en el CLAUDE.md de cada repo. Ninguno se toca al reinstalar el binario. Si tu setup además depende de CLAUDE.md bien estructurado, conviene revisar las tres capas de memoria de Claude Code para no mezclar reglas globales con reglas de proyecto.

Paso 3: bloquear el auto-update

El problema viene de que Claude Code se auto-actualiza al iniciar sesión. Si vuelve a saltar a 2.1.158, repites el bug. La solución es desactivar el auto-update temporalmente:

# Variable de entorno que desactiva el auto-update mientras dure el incidente
export DISABLE_AUTOUPDATER=1
# Persistir en tu shell config (~/.bashrc o ~/.zshrc)
echo 'export DISABLE_AUTOUPDATER=1' >> ~/.zshrc

El coste real del workaround: renunciar a Opus 4.8

2.1.157 funciona, pero es anterior al soporte completo de Opus 4.8. Es decir, el workaround tiene un coste: te quedas en Opus 4.7 o Sonnet 4.6 mientras Anthropic publica un fix.

Opción	Modelo disponible	Riesgo	Recomendado para
Quedarte en 2.1.158	Opus 4.8	Alto: tool_result inestables	Tareas one-shot cortas sin tool use intensivo
Bajar a 2.1.157	Opus 4.7 / Sonnet 4.6	Bajo	Sesiones largas con muchos Read/Bash/MCP
Esperar a 2.1.159+	Opus 4.8	Variable	Si tu trabajo aguanta 24-72h en pausa

Si tu workflow vive de subagentes con muchas tool calls paralelas, bajar es lo sensato. Si trabajas mayoritariamente conversacional, puedes quedarte en 2.1.158 con cuidado.

En Producción

Para equipos que tienen a Claude Code metido en pipelines o CI, el riesgo no es solo "se gasta más". Es que un agente que recibe tool_result corruptos puede tomar decisiones sobre datos inventados. Un agente que cree haber leído un archivo cuando en realidad la respuesta llegó vacía puede sobrescribirlo con la versión que él imagina.

Tres medidas prácticas que recomiendo para no volver a comerte una regresión a ciegas:

Pinear versión en CI: en entornos donde Claude Code corre desatendido (cron, hooks de release), nunca uses la última. Fija una versión validada.
Canary mínimo: un script que ejecuta un prompt fijo con tool calls predecibles (leer 3 archivos, hacer 1 grep) y compara la salida con un golden output. 30 segundos al día y detectas la próxima regresión antes de quemar tokens.
Telemetría de tokens: si tu gasto diario sube 30% sin que la carga de trabajo haya cambiado, sospecha del cliente antes que del modelo. La explicación más probable es un bucle de tool calls duplicadas, no un "modelo más caro".

Este tipo de disciplina ya la cubrí en un post anterior sobre medir la degradación de Claude en vez de intuirla. El canary aplica igual aquí, solo que mide al cliente, no al modelo.

Errores Comunes y Depuración

Error: "tool_use sin tool_result correspondiente" → Causa: el harness perdió la respuesta entre paralelos → Solución: redirige el comando a un archivo temporal (cmd > /tmp/x 2>&1) y luego Read /tmp/x en un turno separado.
Error: 400 messages.N.content.M: thinking blocks cannot be modified → Causa: regresión específica de 2.1.154 en sesiones con replay (wakeup, subagentes en background) → Solución: bajar a 2.1.152 o subir a 2.1.157 según hayas validado, y evitar continuaciones desatendidas hasta el fix.
Error: el modelo reintenta el mismo Read con offset distinto sin necesidad → Causa: tool_result llegó vacío o fuera de orden → Solución: ejecutar /clear, bajar a 2.1.157 y reintentar.
Error: el modelo dispara un sleep 20; echo burst_flush por su cuenta → Causa: intento del propio modelo de desbloquear el canal de tool_result → Solución: tratar como confirmación de regresión, no como bug del modelo.

Preguntas Frecuentes

¿Cómo distingo regresión del harness de regresión del modelo?

Una regresión del modelo se nota igual en distintos clientes (CLI, API directa, Workbench). Una regresión del harness solo se nota desde Claude Code CLI y desaparece al bajar la versión del cliente sin tocar el modelo. Si Opus 4.8 funciona normal por API pero se vuelve loco en Claude Code 2.1.158, es harness.

¿Puedo seguir usando Opus 4.8 con 2.1.157?

Parcialmente. 2.1.157 no tiene el soporte completo de las features nuevas de 4.8 (Fast mode, algunas variantes de contexto extendido), pero el modelo en sí responde por la API. Para la mayoría de tareas de coding diarias, Sonnet 4.6 o Opus 4.7 desde 2.1.157 son una alternativa estable hasta el fix.

¿Por qué Anthropic no ha tirado la versión rota?

Versiones publicadas en npm rara vez se despublican por compatibilidad y trazabilidad. Lo habitual es marcar la última versión limpia como recomendada y publicar una nueva por encima con el fix. Tu trabajo como usuario es saber a qué versión bajar, no esperar a que la rota desaparezca sola.

Cierre

El patrón se repetirá. Modelos nuevos, clientes que se actualizan a la par, y regresiones que se confunden con "el modelo está peor". La lección práctica es separar capas: cuando algo va raro, lo primero es claude --version, no abrir un debate sobre si Opus 4.8 ha degradado. Y si tu workflow vive de Claude Code, pinear versiones en entornos críticos deja de ser paranoia para convertirse en higiene básica.

¿Te ha tocado esta semana y has perdido horas pensando que era el modelo? Cuéntamelo en Twitter @sergiomarquezp_. El próximo post va sobre cómo montar el canary mínimo de tool calls para detectar este tipo de regresiones antes de que te coman la tarde.

Opus 4.8 llega a GitHub Copilot: ¿sigue valiendo Claude Code?

Sergio Márquez — Sat, 30 May 2026 08:00:01 GMT

Opus 4.8 llega a GitHub Copilot: ¿sigue valiendo Claude Code?

TL;DR: Anthropic ha habilitado Claude Opus 4.8 como modelo GA en GitHub Copilot el 28/05/2026. Para quien ya paga Claude Code, esto abre dos preguntas: cuándo conviene cada cliente y cómo evitar pagar dos veces por el mismo modelo. La respuesta corta: Copilot gana en edición visual dentro del IDE, Claude Code CLI sigue mandando en tareas largas con memoria, hooks y skills.

Qué ha cambiado esta semana

Hasta el 28 de mayo, si querías Opus 4.8 con un flujo de pago razonable tenías dos opciones: la suscripción de Anthropic con Claude Code, o la API directa midiendo cada token. GitHub Copilot ofrecía GPT y modelos de Anthropic más antiguos, pero no la última versión.

Con el cambio, Opus 4.8 aparece en el selector de modelos de VS Code para todos los planes de Copilot (Individual, Business y Enterprise). No hay que instalar nada extra: actualizas la extensión, abres el chat y eliges el modelo. Eso significa que un equipo que ya paga Copilot puede probar el modelo top de Anthropic sin sumar otra factura.

El detalle importante: es el mismo modelo, no la misma experiencia. Y ahí es donde la decisión deja de ser obvia.

¿Qué pierdes al usar Opus 4.8 en Copilot en lugar de Claude Code?

El modelo es idéntico. Lo que cambia es el envoltorio: cómo se construye el prompt, qué contexto se inyecta y qué herramientas tiene disponibles. En Claude Code, varias piezas que afectan al resultado final no existen en Copilot:

Memoria de sesión persistente: Claude Code mantiene contexto entre sesiones via ~/.claude/projects/. Copilot reinicia con cada conversación nueva.
Slash commands y skills: /clear, /context, /compact y los skills personalizados son exclusivos del CLI.
Hooks pre/post tool-use: si tienes un hook que bloquea ejecuciones peligrosas o registra costes, eso no se traslada a Copilot.
Subagentes nativos: lanzar varios agentes especializados en paralelo es propio de Claude Code 2.x.

A cambio, Copilot ofrece algo que el CLI no replica bien: edición inline en el IDE con diff visual, autocompletado en línea y un panel integrado con tu workspace. Si tu flujo es revisar archivo, sugerir cambios, aplicar diff, Copilot va más rápido.

Tabla de decisión rápida

Tarea	Mejor opción	Por qué
Refactor multi-archivo	Claude Code CLI	Memoria de sesión + subagentes
Autocompletado en línea	Copilot + Opus 4.8	Latencia menor, integración nativa
Revisar PR completo	Empate, depende del tamaño	PR pequeño: Copilot. PR grande: CLI con git history
Tareas con hooks de seguridad	Claude Code CLI	Hooks no existen en Copilot
Scripting y automatización	Claude Code CLI	Modo headless y skills
Explicar fragmento de código	Copilot + Opus 4.8	Más rápido, contexto del archivo abierto

Cómo comparar en el mismo PR (sin engañarte)

La trampa al comparar Copilot y Claude Code con el mismo modelo es que cada cliente añade un system prompt distinto y diferente contexto auto-inyectado. Para una comparativa honesta, sigue este protocolo:

Define la tarea por escrito en un archivo task.md con criterios de éxito medibles (tests que pasan, métricas, output esperado).
Crea dos ramas idénticas desde el mismo commit base: copilot-opus y cc-opus.
Ejecuta la misma tarea en cada cliente con el mismo prompt pegado desde el task.md.
Mide tres cosas: tiempo total hasta diff válido, número de iteraciones humanas necesarias, tokens consumidos (en Claude Code via /context, en Copilot via el dashboard de uso).
Compara los diffs con git diff copilot-opus cc-opus y revisa qué solución es más mantenible.

En pruebas con tareas medianas (refactor de un servicio FastAPI de unas 400 líneas), Claude Code suele necesitar menos iteraciones porque arrastra contexto entre turnos. Copilot va más rápido en cambios localizados a un archivo. La diferencia real no es el modelo, es la configuración del cliente.

En Producción

Costes y double-billing

Si tu equipo paga las dos suscripciones, el riesgo es claro: usar Opus 4.8 en Copilot para tareas que tu sesión de Claude Code ya está cubriendo. Antes de habilitarlo, define una política simple:

Copilot + Opus 4.8: para edición durante coding session activa en el IDE.
Claude Code CLI: para tareas largas, scripting, revisión de PRs y todo lo que necesite memoria.
API directa: para pipelines automatizados y volúmenes altos con prompt caching agresivo.

Latencia y rate limits

Opus 4.8 en Copilot pasa por la infraestructura de GitHub, que añade su propia capa de rate limiting. Para equipos con varios devs en horas pico, esto puede notarse. Claude Code CLI va directo a Anthropic con los límites de tu plan personal o de equipo.

Privacidad del código

En ambos casos el código sale de tu máquina hacia un proveedor externo. Si tienes restricciones legales o IP sensible, revisa los acuerdos de tratamiento de datos de cada uno: GitHub Copilot Business y Enterprise no entrenan con tu código; Anthropic tampoco con sus planes de pago. Documéntalo antes de habilitar el modelo en repos críticos.

Errores comunes

Error: pruebo Opus 4.8 en Copilot, sale flojo, conclusión: el modelo está peor. Causa: comparas el modelo en dos clientes con system prompts distintos. Solución: usa la API directa con system prompt vacío para validar el modelo en sí.
Error: habilitar Opus 4.8 en Copilot y mantener el mismo plan de Claude Code Max sin política de uso. Causa: no se ha definido qué se hace en cada cliente. Solución: política escrita y revisión de uso mensual.
Error: asumir que skills y MCP funcionan en Copilot. Causa: Copilot tiene su propio ecosistema de extensiones, no carga skills de Claude Code. Solución: replicar la lógica como una extensión de VS Code o mantener esos flujos en el CLI.

Preguntas frecuentes

¿Puedo usar mi suscripción de Anthropic dentro de Copilot?

No. Copilot factura su propio consumo de Opus 4.8 dentro del plan de GitHub. Las suscripciones son independientes y no se pueden vincular en una sola cuenta.

¿Opus 4.8 en Copilot tiene el mismo límite de contexto que en Claude Code?

El modelo soporta el mismo tamaño de contexto (200K tokens según la documentación oficial de Anthropic a 30/05/2026), pero Copilot puede recortar el contexto efectivo por límites internos del cliente. En Claude Code CLI tienes control directo via /context.

¿Merece la pena migrar todo de Claude Code a Copilot?

No, salvo que tu flujo sea casi exclusivamente edición visual en VS Code. Para tareas que requieren memoria larga, hooks o automatización por script, el CLI sigue siendo superior. Lo razonable es usar ambos según la tarea.

Cierre

Que Opus 4.8 llegue a Copilot no mata Claude Code, lo redefine. Copilot gana en edición visual e integración con el IDE; Claude Code mantiene la ventaja en sesiones largas, memoria persistente y automatización. La decisión inteligente para 2026 no es elegir uno, es definir cuándo usas cada cual y medirlo con tu propio consumo de tokens.

Si dependes de configuración avanzada, conviene seguir invirtiendo en tu memoria de Claude Code y en skills y subagentes, porque esas piezas no se replican fácilmente en Copilot. Aplica la misma lógica de separación de responsabilidades que usarías en tu arquitectura: cada herramienta para lo que mejor hace.

¿Ya has probado Opus 4.8 en Copilot? Cuéntame en Twitter @sergiomarquezp_ qué patrón estás siguiendo para no pagar dos veces el mismo modelo.

Claude Opus 4.8 en Claude Code: qué cambia el lunes

Sergio Márquez — Fri, 29 May 2026 08:00:01 GMT

Claude Opus 4.8 en Claude Code: qué cambia el lunes

TL;DR

Anthropic lanzó Claude Opus 4.8 el 28/05/2026 con Fast Mode activo por defecto. Lo vas a notar en tres sitios: respuestas hasta 2,5 veces más rápidas dentro del CLI, factura por sesión un 40-60% más baja según el tipo de uso, y un cambio de comportamiento en refactors largos que ya no necesitan saltar a Sonnet. Esta guía cubre qué activar, qué dejar quieto y cómo medirlo en tu propio proyecto sin tragarte el marketing.

Por qué este cambio te afecta sí o sí

Opus 4.8 ya es el modelo por defecto en Claude Code, GitHub Copilot y Windsurf desde el 28/05/2026. No hay flag que activar: en cuanto tu CLI sube a v2.1.156 o superior, tus prompts pasan por el nuevo modelo. Si llevabas semanas afinando un CLAUDE.md contra Opus 4.7, todas tus suposiciones de coste y latencia están desactualizadas.

El problema real no es la actualización en sí. Es que muchos workflows asumían que Opus era caro para tareas iterativas y delegaban a Sonnet 4.6 con /model. Esa heurística ahora está rota y conviene revisarla antes de aplicar tus rutinas de siempre.

¿Qué es Fast Mode en Claude Opus 4.8?

Fast Mode es una optimización del pipeline de inferencia que mantiene la calidad de Opus 4.7 con una latencia 2,5 veces menor. No es un modelo distinto ni un downgrade automático: es Opus completo respondiendo más rápido gracias a cambios en el serving de Anthropic.

Se activa solo cuando la tarea cabe en su ventana óptima (prompts cortos a medios, sin razonamiento extendido). Para tareas con extended thinking o cadenas de tool use muy largas, el comportamiento vuelve al de Opus normal sin que tengas que cambiar nada.

Cambio 1: latencia perceptible desde el primer prompt

El primer cambio que vas a notar es velocidad. Una iteración típica de "lee este archivo, propón un fix, aplica el patch" pasa de 8-12 segundos a 3-5 segundos. La sensación es la de Sonnet 4.6 sin perder el razonamiento de Opus.

Esto tiene un efecto secundario importante: tienes menos tiempo para leer el plan antes de que el agente ejecute. Si trabajabas con --plan o confiando en que el delay te daba margen para abortar, ya no. Conviene ajustar el workflow a checkpoints explícitos en lugar de depender de la pausa natural.

Cambio 2: factura real (qué mirar en /cost)

Anthropic anuncia 3x más barato por millón de tokens. La rebaja real en tu factura depende de cómo uses el CLI. Estos son los rangos que veo en sesiones reales desde el 28/05/2026:

Tipo de sesión	Ahorro real estimado
Sesión corta (5-10 prompts)	20-30%
Sesión media (refactor 1-2h)	40-55%
Sesión larga con cache hit alto	50-65%

La clave está en el cache de prompts. Si tu CLAUDE.md es estable y no rompes el cache a mitad de sesión, Opus 4.8 amplifica el ahorro. El análisis previo sobre qué dispara los cache miss en Claude Code sigue siendo válido con este modelo.

Para medirlo en tu proyecto, ejecuta /cost al final de cada sesión y compara con el histórico de la semana anterior. No te fíes del marketing: comprueba tu propio uso.

Cambio 3: comportamiento en refactors largos

Aquí está el cambio que casi nadie está contando. Tareas multi-paso que con Opus 4.7 conviene partir o delegar a Sonnet (refactorizar un servicio completo, migrar tests de Jest a Vitest) ahora encajan en Opus 4.8 sin disparar el coste.

El motivo es la combinación de menor coste por token y mejor manejo de contexto medio. En una migración de DTOs de un proyecto Spring Boot con 40 archivos:

Con Opus 4.7: tres sesiones y cambio manual de modelo a Sonnet para iterar.
Con Opus 4.8: una sesión, sin tocar el modelo, mismo resultado final.

Si tu flujo de configuración de agentes incluía heurísticas para alternar Opus y Sonnet, revísalas. La regla "Opus piensa, Sonnet ejecuta" pierde sentido para muchos casos prácticos.

En Producción

Qué ajustar en tu CLAUDE.md

No hace falta tocar nada para usar Opus 4.8: ya es el default. Pero hay tres ajustes que recomiendo aplicar la primera semana:

# Fijar modelo de forma explicita (reproducibilidad entre devs)
model: claude-opus-4-8

# Techo de coste por sesion para que un bucle largo no se descontrole
max_session_cost_eur: 5

# Subagents desactivados por defecto; activar solo en tareas exploratorias
subagents:
  enabled: false

El límite de coste es el más importante. Con la nueva facilidad para correr tareas largas, es trivial dejarse una sesión olvidada consumiendo cache misses. Ponle techo desde el principio.

Qué se rompe al actualizar

Scripts atados a respuestas determinísticas: Fast Mode introduce ligera variabilidad en respuestas cortas. Si tenías regex parseando salida del CLI, valídalas.
Hooks con timeouts agresivos: si tu settings.json esperaba latencias de Opus 4.7, las nuevas son más cortas y algunos hooks pueden disparar antes de tiempo.
Benchmarks internos: tu evaluación de "Claude Code en mi repo" hay que repetirla. Los números antiguos no aplican.

Costes estimados (datos de finales de mayo 2026)

Para una sesión típica de 2h sobre un repo de 50k LOC, la factura por sesión cae de aproximadamente 8-10€ con Opus 4.7 a 3-4€ con Opus 4.8 en mi propio uso. No es un benchmark formal: es el rango que observo desde el día del cambio. Ajusta según tu volumen y haz tu propia medición antes de prometérselo a tu equipo.

Errores Comunes y Depuración

Error: respuestas más cortas que con Opus 4.7 → Causa: Fast Mode tiende a ser conciso cuando detecta una pregunta directa → Solución: pide explícitamente "explica paso a paso" o sube el effort en el prompt.

Error: latencias inconsistentes entre prompts → Causa: el modelo alterna entre Fast Mode y modo normal según la complejidad → Solución: es comportamiento esperado. Si necesitas latencia estable, fuerza extended thinking con un prompt explícito.

Error: /cost muestra valores raros tras la actualización → Causa: el cálculo de cache amortizado cambia con el nuevo pricing → Solución: ignora la primera sesión post-update, los siguientes números son fiables.

Preguntas Frecuentes

¿Puedo volver a Opus 4.7 si no me convence?

Sí. En CLAUDE.md fija model: claude-opus-4-7. Anthropic mantiene 4.7 disponible durante el periodo de transición, aunque el pricing antiguo ya no aplica si lo usas como modelo no-default.

¿Fast Mode afecta a la calidad del código generado?

En tareas cortas o medias no se nota diferencia. En refactors largos con dependencias cruzadas, Opus 4.8 mantiene la calidad de 4.7. Donde sí pierde algo es en razonamiento abstracto puro (lógica formal, matemática), donde conviene activar extended thinking manualmente.

¿Merece la pena migrar workflows que usaban Sonnet por coste?

En muchos casos sí. Si tu razón para usar Sonnet 4.6 era ahorrar en iteraciones largas, Opus 4.8 cubre ese caso por defecto. Sonnet sigue teniendo sentido para tareas masivas con bajo razonamiento (generación de fixtures, boilerplate repetido).

Decisión: ¿activar o esperar?

Ya está activado, no hay decisión sobre activación. La decisión real es cuánto reorganizar tu flujo. La recomendación práctica es esperar 48-72h de uso real antes de tocar el CLAUDE.md: mide con /cost, observa si los hooks se quejan y ajusta solo los puntos donde notes regresión.

Hemos visto que Opus 4.8 acelera el CLI sin sacrificar calidad y abarata sesiones largas hasta un 60% según el patrón de uso. La clave está en revisar las heurísticas de cambio de modelo y poner un techo duro de coste por sesión. Si quieres profundizar en cómo estructurar la memoria en Claude Code para aprovechar el cache, o entender por qué skills y subagentes siguen siendo el ladrillo base con el nuevo modelo, esos posts complementan esta guía.

¿Has notado el cambio en tu factura desde el 28/05/2026? Cuéntamelo en Twitter @sergiomarquezp_. En el siguiente post analizo cómo orquestar subagents bajo Opus 4.8 sin que el coste se multiplique por 15.

VS Code multi-agente: Claude, Codex y Copilot con MCP

Sergio Márquez — Thu, 28 May 2026 08:00:02 GMT

VS Code multi-agente: Claude, Codex y Copilot con MCP

TL;DR

VS Code dejó de ser el IDE de un solo asistente. Con MCP (Model Context Protocol) como capa común, Claude Code, Codex y Copilot conviven en paneles separados, comparten tools y permiten cambiar de agente sin salir del editor. El riesgo principal: dos agentes trabajando sobre el mismo repo pisan archivos si no coordinas sesiones. Aquí va el setup mínimo, cuándo usar cada agente y los patrones que evitan conflictos.

Por qué este cambio importa ahora

Hasta hace poco, elegir agente de código era elegir IDE. Cursor estaba pegado a Anthropic-friendly, Copilot vivía en VS Code, y Claude Code en su CLI. Microsoft ha formalizado un giro: VS Code ahora es el hogar de múltiples agentes con MCP como protocolo común.

El resultado práctico: puedes lanzar Claude Code para refactorizar un módulo grande, dejarlo en background, y pedir a Copilot un autocompletado puntual en el mismo proyecto sin cambiar de ventana. La consecuencia menos obvia es que cambia tu forma de organizar tareas: el agente deja de ser una elección estratégica y pasa a ser una decisión táctica por tarea.

¿Qué es MCP en una frase?

MCP (Model Context Protocol) es un protocolo abierto creado por Anthropic que permite a cualquier agente de IA acceder a herramientas externas (bases de datos, APIs, sistemas de archivos) de forma uniforme. A mayo de 2026, lo soportan nativamente Claude, mediante adaptadores oficiales Codex y Copilot, y la lista crece cada semana.

Si quieres ir más profundo en cómo blindar esas integraciones, el post sobre contratos para MCP en Claude Code cubre el patrón de validación que evita que un cambio del servidor reviente el agente.

El stack en VS Code: paneles, sesiones y agentes

La integración tiene tres piezas que conviene distinguir antes de tocar configuración:

Paneles de agente: cada agente vive en su panel lateral con su propio historial. El atajo por defecto es Ctrl+Alt+I para abrir el panel activo.
Sesiones background: puedes dejar a Claude Code trabajando mientras editas o usas Copilot inline. Las sesiones largas no bloquean el editor.
MCP servers compartidos: si añades un servidor MCP (por ejemplo GitHub o Postgres), está disponible para todos los agentes que lo soporten.

La clave conceptual: MCP es la capa común, pero cada agente sigue teniendo su propio system prompt y sus propios tools nativos. Por eso un mismo modelo responde distinto según quién lo invoque.

Cuándo usar cada agente

Esta es la tabla que uso para decidir sin pensarlo dos veces:

Tarea	Agente recomendado	Por qué
Refactor grande multi-archivo	Claude Code	Sesiones largas, contexto extendido, ejecución autónoma
Autocomplete inline mientras escribes	Copilot	Latencia mínima, integración nativa con el cursor
Análisis exploratorio o algorítmico	Codex	Reasoning fuerte en problemas matemáticos o de complejidad
Code review semiautomático	Claude Code + skills	Reglas reutilizables en SKILL.md, aplicables a todo el repo

Si todavía no has separado responsabilidades entre skills y subagentes, el artículo sobre skills y subagentes como ladrillo base es buena lectura previa.

Setup mínimo: añadir un MCP server compartido

Configurar un MCP server en VS Code requiere un archivo de definición que todos los agentes compatibles leen. Ejemplo para conectar una Postgres local:

// .vscode/mcp.json — define un MCP server local accesible a Claude y Copilot
{
  "servers": {
    "postgres-local": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/dev"
      ],
      "env": {}
    }
  }
}

Tras guardar el archivo y recargar la ventana (Ctrl+Shift+P → Reload Window), ambos agentes ofrecen los tools del servidor (query, schema, list-tables) sin configuración adicional. Si manejas Postgres desde Node, en su día expliqué cómo usar Prisma para gestionar bases de datos; combinar Prisma con un MCP server te da un agente que entiende tu schema sin tener que explicárselo.

El riesgo real: dos agentes, un repo

El conflicto más habitual aparece cuando ejecutas dos agentes en paralelo sobre los mismos archivos. Claude Code edita auth.py mientras Copilot Chat propone cambios en el mismo fichero desde otro panel. Resultado: el último que guarda machaca al anterior, y el git diff queda incoherente.

Patrones que evitan el problema:

Worktrees git: cada agente trabaja en su worktree, sobre la misma base pero con archivos físicos distintos. Eliminas el conflicto a nivel filesystem.
División por capa: Claude para backend, Copilot para frontend. Sin solape físico, sin riesgo.
Sesiones secuenciales: termina la sesión de un agente antes de empezar la del otro si comparten ficheros. Menos óptimo, más seguro.

Para casos donde necesitas aislar al agente del resto del sistema, el post sobre sandbox para agentes de código explica las opciones de aislamiento que ya están listas para producción.

En producción

Algunas consideraciones cuando quieres llevar este flujo a un equipo real, no solo a tu setup personal:

Coste duplicado: Claude Code (suscripción Max o API) más Copilot (10-19€/mes) suma rápido. En escenarios reales, conviene auditar uso de cada agente antes de pagar ambos. Si el 80% del valor lo aporta uno, cancela el otro.
Política de secretos: cada MCP server puede exponer credenciales si no aíslas el entorno. Usa .env separado por proyecto y revisa permisos del servidor antes de exponerlo a un agente que puede ejecutar comandos.
Logs y auditoría: VS Code centraliza logs de agentes en Output → Agent Activity. Es el primer sitio donde mirar tras un postmortem si un agente toca lo que no debe.
Reglas compartidas: con 2-3 devs basta convenir quién usa qué agente. En equipos de 10+, conviene reglas explícitas en CLAUDE.md y AGENTS.md versionados, una capa que conecta con la idea de separación de responsabilidades aplicada a herramientas, no solo a clases.

Errores comunes y depuración

Error: el MCP server no aparece en Claude Code → Causa: el archivo está en .vscode/mcp.json pero Claude Code lee de ~/.claude/mcp.json por defecto → Solución: duplica la definición o usa un enlace simbólico.
Error: Copilot ignora cambios hechos por Claude en background → Causa: el caché interno de Copilot no se invalida cuando otro proceso modifica el archivo → Solución: Ctrl+Shift+P → Reload Window tras sesiones largas.
Error: conflict markers en git tras usar ambos agentes → Causa: edición concurrente sin worktree → Solución: divide el trabajo en worktrees separados por agente o usa la opción de checkpoints del propio VS Code antes de cada sesión.
Error: el agente lee secretos del proyecto vecino → Causa: workspace multi-root con un .env compartido → Solución: separa workspaces, nunca compartas .env entre proyectos con agentes activos.

Preguntas frecuentes

¿Sustituye VS Code multi-agente a Cursor?

Depende del flujo. Cursor sigue ganando en inline editing fluido y composer multi-archivo cuando trabajas a alta velocidad. VS Code multi-agente gana cuando ya pagas Copilot y quieres añadir Claude Code o Codex sin cambiar de editor, especialmente en equipos donde VS Code ya es estándar.

¿Necesito licencia separada para cada agente?

Sí. Cada agente factura por su lado: Copilot vía GitHub, Claude Code vía Anthropic (suscripción Max o API), Codex vía OpenAI. VS Code es solo el contenedor, no incluye créditos ni descuento por usar varios agentes juntos.

¿Funciona MCP con todos los modelos a la vez?

A mayo de 2026, MCP es estándar para Claude (nativo) y compatible con Codex y Copilot mediante adaptadores oficiales. Modelos open-source como Llama o Qwen necesitan un wrapper adicional, y la cobertura de tools varía según la implementación.

Cierre

VS Code como hub multi-agente cambia menos el modelo y más el flujo de trabajo. La pregunta ya no es qué agente uso, sino cómo dividir las tareas entre ellos sin pisarte. Si vienes de una sesión única con Claude Code, empieza añadiendo Copilot solo para autocompletado, mantén Claude para sesiones largas y mide si tu factura conjunta compensa el ahorro de tiempo real.

El siguiente paso natural es configurar MCP servers privados para tu equipo sin exponer secretos, algo que conecta con todo lo que hemos visto sobre arquitectura de agentes. ¿Has probado ya combinar agentes en VS Code? Cuéntamelo en Twitter @sergiomarquezp_ o en los comentarios del blog.

Google mata Gemini CLI el 18 de junio: ¿migras a Claude Code?

Sergio Márquez — Wed, 27 May 2026 08:00:01 GMT

Google mata Gemini CLI el 18 de junio: ¿migras a Claude Code?

TL;DR: El 19 de mayo de 2026 Google anunció que Gemini CLI dejará de servir peticiones el 18 de junio de 2026 para usuarios Pro, Ultra y gratuitos, forzando la migración a Antigravity CLI. Si tu workflow depende de Gemini CLI, tienes menos de un mes para auditar scripts, decidir entre Antigravity CLI o Claude Code, y mover hooks, skills y configuración de MCP a la nueva estructura.

Contexto: lo que dice exactamente Google

El anuncio oficial del Google Developers Blog del 19/05/2026 fija una fecha de corte muy concreta. A partir del 18 de junio de 2026, Gemini CLI y las extensiones IDE de Gemini Code Assist dejarán de servir peticiones para tres tipos de cuenta: Google AI Pro, Google AI Ultra y usuarios del plan gratuito de Gemini Code Assist for individuals. La misma fecha aplica a Gemini Code Assist for GitHub: no habrá nuevas instalaciones en organizaciones y las peticiones existentes dejarán de atenderse en las semanas siguientes.

El reemplazo se llama Antigravity CLI, ya disponible desde el día del anuncio. Comparte el mismo agent harness que Antigravity 2.0 (el IDE de Google) y se promociona como más rápido por estar escrito en Go.

Hay una excepción clara: clientes enterprise con Gemini Code Assist Standard, Enterprise o uso vía Google Cloud API keys no están afectados. Para todos los demás, el 18 de junio es una fecha real en el calendario.

¿Qué es Antigravity CLI?

Antigravity CLI es el CLI agéntico de Google que sustituye a Gemini CLI. Mantiene las primitivas que ya conocías (Skills, Hooks, Subagents y Extensions, ahora rebautizadas como plugins) pero cambia rutas de configuración y comportamiento de algunos comandos. Está construido en Go en lugar de Node.js, lo que reduce el tiempo de arranque, y añade workflows asíncronos para lanzar refactors largos en segundo plano sin bloquear la terminal.

La parte importante: comparte arnés con Antigravity 2.0 desktop, así que las actualizaciones futuras se aplican a ambas superficies a la vez. La parte incómoda: vuelves a depender de un producto Google que el propio vendor ha demostrado ser capaz de matar con menos de un mes de aviso.

¿Realmente usas Gemini CLI? Audita primero

Antes de elegir destino, comprueba si esta deprecación te afecta de verdad. Una auditoría rápida en tu máquina o repos:

Busca el binario: which gemini o gemini --version.
Revisa configuraciones globales en ~/.gemini/settings.json y por workspace en .gemini/settings.json.
Grepea pipelines de CI/CD en busca de gemini o gemini-cli (GitLab CI, GitHub Actions, scripts en Makefile).
Revisa extensiones IDE: VS Code, JetBrains. La extensión Gemini Code Assist entra también en la deprecación.

Si no aparece nada, ya está, sigue con tu vida. Si aparece en scripts de generación de tests, refactors automáticos o cualquier pipeline programático, toca decidir.

Antigravity CLI vs Claude Code: comparativa honesta

La pregunta real no es si migrar, sino a dónde. Esta tabla resume el estado a 27/05/2026 según documentación oficial y reportes activos en los foros de Google AI Developers:

Aspecto	Antigravity CLI	Claude Code
Estado	GA (mayo 2026), heredero forzado de Gemini CLI	GA, iteración estable durante 2026
Lenguaje base	Go	Node.js
Migración desde Gemini CLI	Migración asistida de extensiones a plugins	Manual: reescribir skills y hooks
MCP	`mcp_config.json` separado, campo `serverUrl`	MCP nativo, configuración por proyecto
Memoria persistente	Heredada de Gemini CLI (context files)	CLAUDE.md + ecosistema (claude-mem, engram)
Vendor risk	Alto (Google ya mató Gemini CLI y Antigravity IDE)	Medio (Anthropic invierte en el producto)
Limitaciones reportadas	Sin sandbox ni imagen de contenedor custom, cuota restrictiva	Coste de tokens en uso intensivo

Las quejas activas en el foro oficial de Google sobre Antigravity CLI son consistentes: falta de sandbox, ausencia de soporte para contenedores custom y cuotas más restrictivas que las de Gemini CLI. No es bloqueante, pero conviene saberlo antes de migrar a ciegas.

Plan A: migrar a Antigravity CLI (camino oficial)

Si eliges quedarte en el ecosistema Google, la migración es razonablemente directa. La documentación oficial vive en antigravity.google/docs/gcli-migration. Los puntos críticos:

Extensiones a plugins: al primer arranque, Antigravity CLI ofrece migrar tus extensiones. La mayoría se convierten 1:1, pero los temas custom no están soportados.
Skills: los globales pasan de ~/.gemini/skills/ a ~/.gemini/antigravity-cli/skills/. Los de workspace cambian de .gemini/skills/ a .agents/skills/.
MCP servers: dejan de vivir inline en settings.json. Pasan a un fichero separado: global en ~/.gemini/antigravity-cli/mcp_config.json, workspace en .agents/mcp_config.json. Atención al campo: usa serverUrl, no url.
Hooks y subagents: portables sin cambios estructurales.

Ejemplo mínimo de configuración MCP en el formato nuevo:

{
  "mcpServers": {
    "github": {
      "serverUrl": "https://api.github.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  }
}

Cópialo a .agents/mcp_config.json y verifica con /mcp dentro de Antigravity CLI.

Plan B: saltar a Claude Code

Si lo que te interesa es reducir vendor risk o consolidar tu workflow en un CLI que ya tiene tracción seria en la comunidad, Claude Code es la alternativa más directa. La migración no es 1:1 (las skills y hooks no se traducen automáticamente) pero el modelo mental es muy similar. Si vienes comparando ambos CLIs, ya tengo cubiertos varios patrones de terminal entre Gemini CLI y Claude Code que aceleran el cambio.

Pasos mínimos para empezar:

Instala Claude Code (npm install -g @anthropic-ai/claude-code) y autentica con tu plan Pro o Max.
Crea un CLAUDE.md en la raíz del proyecto. Aquí va el contexto que antes vivía en .gemini/settings.json o en los context files. La memoria de Claude Code se organiza en tres capas y conviene entenderlas antes de copiar todo en un solo fichero.
Reescribe tus skills más usadas como skills de Claude Code o como slash commands. La traducción suele ser directa: prompt + instrucciones + ejemplos.
Reconfigura MCP servers en el formato nativo de Claude Code (no es compatible con el JSON de Antigravity).
Si tenías hooks pre/post commit en Gemini CLI, mira la documentación equivalente de hooks en Claude Code antes de reescribirlos.

En producción: lo que cambia entre tutorial y realidad

Migrar el entorno local es la parte fácil. Los frentes que se rompen en producción y nadie cuenta:

Pipelines CI/CD. Cualquier job que invoque gemini dejará de funcionar el 18 de junio. Cámbialo antes y pinea versiones explícitas del nuevo CLI.
Quotas y coste. Antigravity CLI tiene cuotas más restrictivas que Gemini CLI según reportes del foro oficial. Si dependes de Pro o Ultra, mide tu consumo antes de mover producción. Claude Code, por su parte, factura por tokens y el cache miss puede disparar la factura sin avisar.
Imágenes Docker. Si tu pipeline construye un contenedor con Gemini CLI preinstalado, cambia el Dockerfile ya. Antigravity CLI no comparte binario ni layout de ficheros.
Sandbox. Antigravity CLI no soporta sandbox ni imágenes custom de contenedor a fecha de hoy. Si esto es bloqueante para ti, Claude Code es mejor opción.
Variables de entorno. Las API keys de Gemini CLI no funcionan tal cual. Antigravity CLI usa autenticación distinta; revisa el flujo de login en la primera ejecución.

Errores comunes durante la migración

Error: los skills no aparecen en Antigravity CLI tras la migración. Causa: sigues con skills en .gemini/skills/. Solución: mueve la carpeta a .agents/skills/.
Error: MCP servers no se conectan tras pasar el JSON. Causa: usaste url en lugar de serverUrl. Solución: renombra el campo y reinicia el CLI.
Error: pipeline de CI rompe con command not found: gemini después del 18/06. Causa: el binario dejó de funcionar contra la API. Solución: actualizar la imagen base del runner y el comando.
Error: tema custom de Gemini CLI no se aplica en Antigravity. Causa: los temas no están en la lista de componentes migrables. Solución: recrearlo manualmente cuando el soporte llegue, o aceptar el tema por defecto.

Preguntas frecuentes

¿Soy enterprise y uso Gemini Code Assist Standard, me afecta?

No. Si tu organización tiene una licencia Gemini Code Assist Standard o Enterprise, o usas Google Cloud API keys, Gemini CLI seguirá soportado después del 18 de junio. La deprecación afecta solo a planes Pro, Ultra, gratuitos y Code Assist for individuals.

¿Antigravity CLI es 100% compatible con mis skills y hooks de Gemini CLI?

Casi. Skills, hooks, subagents y MCP servers son funcionalmente equivalentes, pero las rutas de fichero cambian y los temas custom no migran. La primera ejecución de Antigravity CLI ofrece un asistente que convierte la mayoría de extensiones a plugins de forma automática.

¿Tiene sentido saltar a Claude Code si ya uso Gemini CLI sin problemas?

Depende del riesgo que asumas. Google mató Gemini CLI con menos de un mes de aviso y antes había soft-deprecado Antigravity IDE. Si tu equipo depende del CLI para tareas críticas, diversificar hacia Claude Code reduce dependencia de un proveedor que ha demostrado iterar matando productos públicos.

Cierre

La deprecación de Gemini CLI no es una noticia más. Es un recordatorio de que los CLIs agénticos siguen siendo infraestructura volátil y de que apostar todo el workflow a un único proveedor tiene coste real. El 18 de junio es la fecha que importa: antes de ese día conviene tener auditado el uso, decidido el camino (Antigravity CLI por compatibilidad, Claude Code por estabilidad) y migrados los pipelines críticos. La elección entre uno u otro CLI debería pesar menos que la configuración real que pongas encima, que es lo que define la productividad del día a día.

¿Has migrado ya algún proyecto desde Gemini CLI? Cuéntame qué te encontraste en los comentarios o en Twitter @sergiomarquezp_. El próximo post compara lado a lado los subagents de Claude Code con la nueva implementación que acaba de aterrizar en Cursor 2.4.

Opus 4.7 vs Sonnet 4.6 en Claude Code: cuál elegir y cuándo

Sergio Márquez — Tue, 26 May 2026 08:00:01 GMT

Opus 4.7 vs Sonnet 4.6 en Claude Code: cuál elegir y cuándo

TL;DR

A mayo de 2026, Claude Code mantiene tres modelos vivos: Opus 4.7 (estándar, 200k de contexto), Opus 4.7 con ventana 1M y Sonnet 4.6. Opus 4.7 gana en refactors complejos y razonamiento profundo, la variante 1M solo paga su coste cuando navegas repos gigantes, y Sonnet 4.6 domina edición rápida, debugging y tareas donde el coste por token manda. Este artículo es el árbol de decisión que uso cada día para no quemar factura en tareas donde Sonnet hace el mismo trabajo.

Por qué importa elegir bien el modelo en Claude Code

La factura mensual cambia entre un 40% y un 60% según el reparto de modelos que hagas en una semana normal. No es un detalle de optimización, es la diferencia entre 25€ y 45€ mensuales en uso personal intenso, o un múltiplo en equipos.

El comando /model dentro de Claude Code es trivial. Lo que no es trivial es saber cuándo bajar a Sonnet sin perder calidad, o cuándo el contexto extendido de 1M tokens compensa el extra de coste. Aquí es donde la mayoría tira del modelo más potente por defecto y termina pagando un sobrecoste innecesario.

Los tres modelos en una tabla

Modelo	Contexto	Punto fuerte	Coste relativo	Latencia
Opus 4.7	200k tokens	Razonamiento profundo, refactors	Alto	Media
Opus 4.7 (1M)	1M tokens	Repos enormes, auditorías	Muy alto	Alta
Sonnet 4.6	200k tokens	Edición rápida, debugging	Bajo (~1/5 de Opus)	Baja

El coste relativo viene de la facturación pública de Anthropic: Sonnet 4.6 está aproximadamente a una quinta parte del precio por millón de tokens de Opus 4.7. La variante 1M aplica un recargo por encima del umbral de 200k tokens de contexto.

Qué hace bien Opus 4.7 (y qué no)

Opus 4.7 es el modelo al que recurres cuando la tarea requiere mantener varios hilos de razonamiento simultáneos: refactor que toca 8 archivos con dependencias circulares, diseño de arquitectura, migración entre frameworks, debugging donde el error está a dos saltos del síntoma.

Lo que no hace bien Opus 4.7 es ser eficiente con tareas pequeñas. Pedirle que renombre una variable o añada un endpoint trivial gasta tokens caros para un output que Sonnet daría idéntico. En mi flujo personal, el 60-70% de las interacciones diarias no necesitan Opus.

La configuración de effort en Claude Code añade otra dimensión: Opus 4.7 con effort medio suele ser más predecible que con effort máximo activado en tareas creativas, donde el modelo se desvía buscando soluciones elegantes en lugar de aplicar la obvia.

Cuándo activar Opus 4.7 con ventana 1M

La variante 1M no es "Opus pero mejor". Es Opus con un coste extra por tokens por encima de 200k y, según los reportes de la comunidad en r/ClaudeCode, con atención más dispersa cuando el contexto está realmente lleno.

Usa 1M cuando:

Auditas un repo grande sin saber dónde está el problema (más de 50 archivos relevantes).
Migras una librería que toca prácticamente todo el proyecto.
Necesitas cargar varios PDFs o transcripciones largas en una sola sesión.

No uses 1M cuando:

Tu CLAUDE.md y memoria persistente ya filtran bien el contexto relevante.
La tarea cabe en 50k tokens (la mayoría de features de día a día).
Estás iterando rápido: el modelo es perceptiblemente más lento.

El antipatrón aquí es cargar todo "por si acaso". El contexto largo no es gratis ni en coste ni en calidad: cuanta más información irrelevante metes, más se diluye la atención del modelo en lo que importa. Si tu setup de memoria en Claude Code está bien estratificado, casi nunca necesitas 1M.

El caso fuerte de Sonnet 4.6

Sonnet 4.6 sigue siendo, a fecha de hoy, el caballo de batalla razonable para la mayoría del trabajo diario en Claude Code. Estos son los escenarios donde lo prefiero sin pensarlo:

Edición puntual: añadir un campo a un endpoint, escribir un test unitario, corregir un mensaje de log.
Debugging con stack trace claro: cuando ya tienes la pista, no necesitas el cerebro de Opus.
Generación de boilerplate: CRUDs, DTOs, schemas Pydantic, configuración de Docker.
Sesiones largas iterativas: el coste se acumula, y la latencia baja de Sonnet hace que el flujo no se atasque.

Donde Sonnet 4.6 flaquea es en tareas que requieren mantener múltiples constraints en mente a la vez. Si la primera respuesta del modelo es "claramente equivocada en algo que el contexto deja claro", es síntoma de que necesitas Opus.

Recetas concretas por tipo de tarea

Estas son las reglas que aplico en mi flujo de trabajo con coding agents en 2026:

Refactor que toca 1-3 archivos → Sonnet 4.6.
Refactor que toca 4+ archivos con lógica cruzada → Opus 4.7.
Diseño de arquitectura o decisiones de stack → Opus 4.7 con effort alto.
Debugging con causa obvia → Sonnet 4.6.
Debugging donde el bug está en el "espacio entre archivos" → Opus 4.7.
Generación de tests → Sonnet 4.6 salvo lógica de negocio compleja.
Auditoría de seguridad o performance en repo grande → Opus 4.7 1M.
Documentación, READMEs, comentarios → Sonnet 4.6.

En Producción

Cuando Claude Code es parte de un flujo de equipo o de CI/CD, la elección de modelo tiene más implicaciones:

Coste por iteración: cada ciclo de PR review automatizado con Opus 4.7 puede costar entre 0,20€ y 0,80€ según el tamaño del diff. En un equipo con 30 PRs diarios, son 200-500€ mensuales solo en revisión. Mover esa carga a Sonnet 4.6 con escalada manual a Opus cuando el reviewer lo pida suele recortar un 70% del gasto.

Cache de prompts: cambiar de modelo a mitad de sesión invalida el cache. Si estás iterando en una feature, fija un modelo al inicio. Las cinco acciones que disparan cache miss en Claude Code incluyen este caso y son fáciles de evitar con disciplina.

Determinismo: Opus 4.7 es más propenso a explorar alternativas, lo que en producción significa diffs que no siempre se parecen entre ejecuciones similares. Para tareas que se repiten (como generación de migraciones a partir de schemas), Sonnet 4.6 da resultados más estables.

Sesiones largas: en jornadas de más de 4 horas sobre el mismo proyecto, mezclar modelos es realista. Yo abro con Opus 4.7 para diseñar el approach, bajo a Sonnet 4.6 para implementar y solo vuelvo a Opus si aparece un bloqueo conceptual.

Errores comunes al elegir modelo

Error: "Uso siempre Opus por seguridad" → Causa: miedo a perder calidad → Solución: medir output real con la misma tarea en ambos modelos durante una semana. La mayoría descubre que el 60-70% de tareas son indistinguibles.
Error: "Activo 1M para todo" → Causa: confundir contexto disponible con contexto necesario → Solución: usar research-first para explorar repos grandes antes de cargar todo en el modelo.
Error: "Cambio de modelo cuando una respuesta no me gusta" → Causa: tratar el modelo como variable independiente → Solución: revisar primero el prompt y el contexto. El cambio de modelo invalida cache y casi nunca soluciona prompts mal formulados.
Error: "Sonnet falla, paso a Opus en la misma sesión" → Causa: ignorar la pérdida de cache → Solución: si vas a escalar, cierra la sesión y abre una nueva con el contexto mínimo necesario.

Preguntas Frecuentes

¿Cómo cambio de modelo en Claude Code?

Con el comando /model dentro de la sesión. Se abre un selector con los modelos disponibles según tu plan. El cambio aplica al siguiente mensaje y rompe el cache de prompts de la sesión actual.

¿Merece la pena Opus 4.7 1M sobre el Opus 4.7 estándar?

Solo si tu tarea real requiere más de 200k tokens de contexto cargado simultáneamente. Para el 90% del trabajo diario, el Opus 4.7 estándar con un CLAUDE.md bien escrito y memoria persistente bien configurada rinde mejor y cuesta menos.

¿Sonnet 4.6 sirve para escribir código en producción?

Sí, sin reservas para tareas dentro de su perfil: edición puntual, boilerplate, debugging con causa clara, generación de tests. El criterio para escalar a Opus es la complejidad del razonamiento requerido, no el destino del código.

Cierre

La pregunta no es "qué modelo es mejor", sino "qué modelo es adecuado para esta tarea concreta". Opus 4.7 brilla en razonamiento profundo, la variante 1M solo paga su coste en repos enormes, y Sonnet 4.6 sigue siendo el motor razonable de la mayoría del trabajo diario. La diferencia entre una factura controlada y una explosiva está en aplicar el criterio antes de cada sesión, no después.

El siguiente paso natural es medir: durante una semana, anota qué modelo usaste para cada tarea y revisa el resultado. Vas a descubrir que ya estás pagando Opus para cosas que Sonnet resolvía igual de bien.

¿Cómo decides tú entre Opus y Sonnet cada día? Cuéntamelo en Twitter @sergiomarquezp_ o en los comentarios. En el próximo post toca cómo combinar selección de modelo con effort y memoria persistente para flujos largos sin perder contexto.

Cache miss en Claude Code: 5 cosas que disparan tu factura

Sergio Márquez — Mon, 25 May 2026 08:00:01 GMT

Cache miss en Claude Code: 5 cosas que disparan tu factura

TL;DR

Claude Code usa prompt cache para no cobrarte dos veces por el mismo contexto. Cuando un cache hit pasa a ser cache miss, esos tokens cuestan 12,5 veces más. Editar CLAUDE.md a mitad de sesión, cambiar de modelo o reordenar tus tools son acciones que invalidan el cache sin avisar. Aquí están las cinco causas más comunes y cómo medir tu hit rate en tiempo real.

Por qué el cache importa en tu factura mensual

Microsoft canceló sus licencias internas de Claude Code en mayo de 2026 cuando vieron que el billing por tokens se les disparaba. La causa no era el modelo, era el patrón de uso: sesiones largas con cambios constantes que reventaban el prompt cache.

Anthropic factura los tokens cacheados a un precio mucho menor que los normales. Según los precios publicados a fecha de mayo de 2026, un cache hit sobre prefix matching cuesta aproximadamente la décima parte de un token sin cache, y la escritura inicial al cache supone un sobrecoste único. En la práctica, la diferencia entre trabajar con cache caliente y romperlo continuamente es de unos 12,5x en coste real sobre los mismos tokens de contexto.

Para un desarrollador con uso intensivo (3-5 horas diarias), esto puede significar pasar de 15-25€/mes a más de 200€/mes con el mismo trabajo.

¿Qué es el prompt cache de Claude Code?

El prompt cache es el mecanismo por el que la API de Anthropic guarda un prefijo de tu conversación (system prompt, definiciones de tools, archivos cargados) durante 5 minutos. Si la siguiente petición empieza igual byte a byte, no paga el coste completo de procesar esos tokens.

Claude Code aprovecha esto automáticamente: cada turno reenvía todo el contexto previo y deja que el sistema reutilice lo que coincide desde el inicio. El cache funciona por prefix matching: si cambias un solo carácter en los primeros tokens, todo lo posterior se invalida.

Esta es la regla que casi nadie tiene clara: el cache es posicional. Modificar algo al principio del contexto invalida el resto, aunque ese resto no haya cambiado.

Las 5 acciones que rompen el cache sin que te enteres

1. Editar CLAUDE.md a mitad de sesión

El archivo CLAUDE.md se carga en los primeros tokens de la sesión. Si lo modificas mientras estás trabajando (añadir una convención, corregir un typo, ajustar instrucciones), invalidas todo el prefijo desde ese punto. La siguiente petición pagará tokens completos por todo el contexto que ya tenías cacheado.

En mi flujo de trabajo, mantengo CLAUDE.md estable durante sesiones largas y aplico cambios solo al arrancar una nueva sesión. Si necesito ajustar algo crítico, asumo el coste de un cache reset pero lo hago consciente.

2. Cambiar de modelo a media conversación

Pasar de Sonnet 4.6 a Opus 4.7 con /model en mitad de una sesión es una de las acciones más caras. El cache está vinculado al modelo: cambiar de modelo equivale a empezar de cero. Todo el contexto se recalcula a precio completo en el nuevo modelo.

El patrón sano es decidir el modelo al inicio de la tarea. Si vas a investigar y planificar, arranca con Opus; si vas a iterar código, Sonnet. Cambiar mid-task casi siempre sale más caro que terminar la tarea con el modelo equivocado.

3. Reordenar o añadir definiciones de tools/MCP servers

Las definiciones de tools (incluidos los MCP servers conectados) viven en el system prompt. Si activas un MCP server nuevo a mitad de sesión, las definiciones se insertan en el prefijo y todo lo que viene después deja de hacer match.

Para entender mejor cómo estructurar integraciones MCP estables, te recomiendo leer mi guía sobre contratos para MCP en Claude Code: el principio clave es declarar todos los servers al inicio aunque no los uses, en vez de conectarlos sobre la marcha.

4. Cargar archivos grandes en orden inconsistente

Cuando Claude Code lee archivos con la tool Read, los inyecta en el contexto en el orden en que los pides. Si en la siguiente petición lees los mismos archivos en otro orden, el cache se rompe en el punto de divergencia.

Este detalle es invisible: tú no controlas el orden directamente, pero los prompts del estilo lee X, Y, Z producen un orden distinto a revisa Y, X, Z. La regla práctica es delegar a Claude la decisión de qué leer y dejar que su propio orden se mantenga consistente entre turnos.

5. Compactar contexto manualmente con /compact

El comando /compact resume la conversación previa y reemplaza el historial original. Es útil cuando te quedas sin ventana, pero rompe el cache de todo lo anterior: el resumen es texto nuevo que no coincide con el prefijo cacheado.

Si tu tarea va a ser larga, planifica el compact al inicio de un bloque (no a mitad). Para tareas que duran días, considera estrategias de memoria persistente, en línea con lo que describo en el artículo sobre las tres capas de memoria en Claude Code.

Tabla resumen: causas, impacto y mitigación

Acción	Impacto	Mitigación
Editar CLAUDE.md	Invalida todo el prefijo	Solo entre sesiones
Cambiar modelo	Reset total del cache	Decidir modelo al inicio
Añadir MCP server	Invalida desde tools	Declarar todos al arranque
Orden de lectura inconsistente	Cache miss parcial	Delegar el orden a Claude
/compact manual	Reset de historial	Planificar al inicio del bloque

Cómo medir tu hit rate en tiempo real

Anthropic devuelve métricas de cache en cada respuesta de la API. Claude Code las expone en el statusline y en los logs. Para inspeccionar los headers manualmente desde un script Python:

# Mide cache_read vs cache_creation para detectar miss rates altos
import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": "Eres un asistente tecnico. Responde en espanol.",
        "cache_control": {"type": "ephemeral"}
    }],
    messages=[{"role": "user", "content": "Hola"}]
)

usage = response.usage
print(f"Cache read: {usage.cache_read_input_tokens}")
print(f"Cache write: {usage.cache_creation_input_tokens}")
print(f"Tokens nuevos: {usage.input_tokens}")

La métrica clave es la ratio cache_read_input_tokens / (cache_read + input_tokens). Por debajo del 70% tienes un problema de invalidación. Por encima del 90% estás optimizado.

En Producción

Cuando trabajas en proyectos reales con Claude Code, estas son las consideraciones extra que importan:

TTL del cache es de 5 minutos. Si dejas la sesión idle más tiempo, el cache expira y la siguiente petición paga completo. Para tareas pausadas, considera cerrar sesión y reabrirla con CLAUDE.md actualizado en vez de mantener una sesión zombie.
El cache es por endpoint y región. Si tu cliente cambia de región (algo que no suele pasar pero ocurre con failovers), pierdes el cache.
Coste real vs coste percibido. El dashboard de Anthropic muestra tokens, no eficiencia de cache. Calcula tu hit rate manualmente al menos una vez por semana para detectar drift.
Equipos pequeños: en proyectos de 2-3 personas, una convención compartida sobre cuándo se permite tocar CLAUDE.md ahorra fácilmente 30-40% del coste mensual.

Si trabajas con varios agentes (Claude Code, Codex, Gemini), recuerda que el cache no se comparte entre proveedores. Cada uno tiene su propia estrategia y métricas.

Errores Comunes y Depuración

Error: Factura disparada sin cambios aparentes en el uso. Causa: alguien del equipo modificó CLAUDE.md y nadie reinició sesiones. Solución: versionar CLAUDE.md en git y avisar al equipo antes de cualquier cambio.
Error: Hit rate del 30% en sesiones cortas. Causa: Claude Code está leyendo archivos en orden distinto cada turno porque el prompt es ambiguo. Solución: dar instrucciones claras sobre alcance y dejar que Claude planifique la lectura.
Error: Cache miss tras cambiar de Sonnet a Opus. Causa: esperado, el cache es por modelo. Solución: evitar el cambio de modelo a media tarea; si es imprescindible, asume el coste como parte de la planificación.
Error: Tokens marcados como cache write pero nunca cache read. Causa: sesiones demasiado cortas o pausas mayores de 5 minutos entre turnos. Solución: trabajar en bloques continuos o usar cache_control: {"type": "ephemeral", "ttl": "1h"} donde aplique.

Preguntas Frecuentes

¿El prompt cache de Claude Code es lo mismo que el cache de OpenAI?

No exactamente. Anthropic usa cache opt-in con cache_control explícito y soporta hasta 4 breakpoints por petición. OpenAI tiene cache automático sin control granular. En la práctica, el de Anthropic es más predecible si sabes lo que haces, pero exige diseñar bien la jerarquía de tu system prompt.

¿Merece la pena pagar el cache write si solo voy a hacer un par de peticiones?

No. La escritura al cache tiene un sobrecoste único de aproximadamente 1,25x el precio de un token normal. Si haces menos de 3-4 turnos con el mismo prefijo, sale más caro escribir al cache que pagar tokens normales. Por eso Claude Code aplica cache solo a partir de cierto umbral de contexto.

¿Puedo extender el TTL del cache más allá de 5 minutos?

Sí, Anthropic ofrece un TTL extendido de 1 hora (configurable con cache_control: {"type": "ephemeral", "ttl": "1h"}) que tiene un sobrecoste mayor en la escritura pero compensa para sesiones largas con pausas. A fecha de mayo de 2026, esta opción está disponible para clientes con uso intensivo.

Cierre

El cache de Claude Code es probablemente la palanca más importante para controlar coste en proyectos reales, y la menos visible. Entender que es posicional, que es por modelo y que cualquier edición al prefijo lo invalida cambia cómo organizas tus sesiones. Mantén CLAUDE.md estable, decide el modelo al inicio, declara todos los MCP servers al arranque y mide tu hit rate al menos una vez por semana.

El siguiente paso natural es decidir qué meter en ese CLAUDE.md estable y qué dejar fuera. Si quieres profundizar en arquitectura de contexto, el artículo sobre cómo la config pesa más que el modelo es el complemento directo, y el de separación de responsabilidades aplica también aquí: separa lo estable de lo cambiante.

¿Has medido alguna vez tu hit rate de cache? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. En el próximo post veremos cómo automatizar la medición con un hook que avise cuando el hit rate baje del 70%.

¿Claude se ha vuelto más tonto? Mídelo, no lo intuyas

Sergio Márquez — Fri, 22 May 2026 08:00:01 GMT

TL;DR: Durante marzo y abril de 2026, miles de developers sintieron que Claude Code razonaba peor. Tenían razón, y el postmortem oficial de Anthropic lo confirmó dos meses tarde. La lección práctica no es migrar de herramienta por una corazonada: es montar un eval ligero, un puñado de tareas fijas que ejecutas cada semana, y medir la degradación del modelo con datos en vez de intuición.

El problema: dos meses discutiendo si el modelo había empeorado

Si usas Claude Code a diario, marzo de 2026 fue raro. Tareas que antes salían a la primera empezaron a necesitar tres intentos. El agente leía menos archivos antes de editar, repetía pasos y elegía el arreglo más simple en lugar del correcto. La queja se extendió por Reddit y GitHub durante semanas, y la respuesta inicial de Anthropic fue que su investigación no mostraba problemas generalizados.

El 23/04/2026 llegó el postmortem. Anthropic confirmó tres cambios reales en la capa de producto, no en los pesos del modelo, que combinados degradaron la experiencia:

El 04/03/2026 bajaron el reasoning effort por defecto de high a medium para reducir latencia. Lo revirtieron el 07/04.
El 26/03/2026 un bug de caché borraba el historial de razonamiento en cada turno en lugar de una sola vez. Eso explicaba la sensación de olvido y repetición.
Una restricción de verbosidad redujo el razonamiento sostenido sobre código.

Todo quedó corregido en la versión 2.1.116, publicada el 20/04/2026. El detalle incómodo: durante dos meses, quien pagaba por la herramienta no tenía forma de saber qué estaba cambiando. Solo tenía una corazonada. Es la prueba de que la capa que rodea al modelo pesa tanto como el modelo en sí.

¿Qué es la degradación percibida de un modelo?

La degradación percibida es la sensación de que un modelo responde peor sin que tengas una medida objetiva que lo confirme. Mezcla tres ingredientes y conviene separarlos:

Cambios reales: como los tres del postmortem de abril.
Variación de tus propios prompts: el repo crece, el contexto cambia, tus instrucciones no son idénticas entre días.
Sesgo de expectativa: si esperas un fallo, lo encuentras.

El problema no es la sensación. El problema es decidir en base a ella. Medir lo que no ves de un modelo es la misma lógica que aplicamos al interpretar modelos de IA con herramientas de explicabilidad: sin instrumentación, opinas; con instrumentación, sabes.

¿Qué es un eval ligero (golden prompt)?

Un eval ligero es un conjunto pequeño y fijo de tareas representativas que ejecutas de forma periódica para detectar cambios de comportamiento en un modelo. No es un benchmark académico. Son 5 a 10 tareas de tu trabajo real, repetibles en minutos, con una métrica simple. Su valor está en una sola cosa: te da un punto de comparación entre el Claude de hoy y el de la semana pasada.

Cómo montar tu propio eval en 5 pasos

Elige 5-10 tareas representativas de lo que haces de verdad: un refactor típico, un test, un bugfix conocido.
Congela el prompt exacto. Sin variaciones. Si cambias la instrucción, cambias el experimento.
Registra el entorno: modelo, versión de Claude Code y reasoning effort. Sin esto no hay comparación posible.
Define métricas simples: ¿compila?, ¿pasan los tests?, número de iteraciones, archivos leídos por edición.
Ejecuta cada semana y guarda el resultado con fecha. La tendencia es la señal, no el dato suelto.

Una forma cómoda de guardarlo es un fichero por tarea. Lo importante es que el entorno quede anotado:

// Plantilla de tarea golden: congela el prompt y registra el entorno en cada ejecucion
{
  "tarea": "refactor-endpoint-pagos",
  "prompt": "Refactoriza el endpoint /pagos extrayendo la validacion a un servicio",
  "modelo": "claude-opus-4-7",
  "claude_code": "2.1.116",
  "reasoning_effort": "high",
  "fecha": "2026-05-22",
  "metricas": { "compila": true, "tests_ok": true, "iteraciones": 2 }
}

Cuando algo huela raro, ejecutas el eval, comparas con la última tirada limpia y tienes una respuesta, no una discusión.

Caso real: los números de AMD y el tic de "vete a dormir"

Stella Laurenzo, directora senior de IA en AMD, hizo justo esto a gran escala. Analizó 6.852 sesiones de Claude Code y más de 230.000 llamadas a herramientas. Los datos eran claros: la lectura de archivos cayó de 6,6 veces a 2 veces por fichero antes de editar, las ediciones puntuales se sustituyeron por reescrituras completas, y el coste mensual del equipo se disparó por los bucles de reintento. Un benchmark comunitario también mostró caídas de precisión, aunque su metodología fue cuestionada después.

No necesitas 6.852 sesiones. Diez tareas fijas bastan para ver una tendencia. La diferencia entre AMD y el resto de la comunidad no fue la intuición, fue tener datos para llevar el problema a un issue de GitHub.

Cuidado con confundir un fallo con una manía. Por las mismas fechas, Claude empezó a decir a la gente que se fuera a dormir a mitad de sesión. Según Sam McAllister, de Anthropic, es un "tic de carácter": el modelo no sabe qué hora es y replica patrones de su entrenamiento sobre el descanso. Eso no es degradación, es una rareza cosmética. Un eval te ayuda precisamente a separar una regresión real de un tic sin importancia.

En Producción

Llevar esta idea al día a día tiene matices que el tutorial se salta:

Coste: un eval de 10 tareas son unos minutos de cómputo y unos céntimos de API por tirada. Barato comparado con perseguir un fantasma o cambiar de stack.
Fija la versión: anota modelo, versión de Claude Code y reasoning effort en cada ejecución. El bug de marzo bajó el effort sin avisar; si no lo registras, no lo detectas. Conviene tener claro cuándo subir el effort a max y cuándo no.
No migres por una corazonada: cambiar de herramienta cuesta tiempo de aprendizaje real. Mide primero, decide después.
Automatízalo: el eval gana cuando corre solo. Un hook que lance checks automáticos sin tocar tu flujo puede disparar la tirada tras cada actualización.

Errores comunes y depuración

Error: "lo noto más tonto" pero no puedes demostrarlo. Causa: no tienes baseline. Solución: guarda el resultado de tu eval con fecha y versión desde hoy, aunque ahora todo funcione.
Error: el eval da resultados distintos cada semana sin que cambie el modelo. Causa: el prompt o el contexto del repo varían entre tiradas. Solución: congela el prompt y usa un repo de prueba estable.
Error: el modelo "olvida" a mitad de sesión. Causa: puede ser gestión de contexto, no el modelo, como el bug de caché de marzo. Solución: revisa tu capa de memoria y contexto en Claude Code antes de culpar al modelo.

Preguntas frecuentes

¿Anthropic degrada los modelos a propósito?

No. En el postmortem de abril de 2026, Anthropic negó el "nerfeo" y atribuyó la caída a tres cambios en la capa de producto y un bug de caché, no a los pesos del modelo. Los problemas se corrigieron en la versión 2.1.116.

¿Por qué Claude me dice que me vaya a dormir?

Es un "tic de carácter" según Anthropic, no una señal de degradación. El modelo no recibe la hora real y replica patrones de su entrenamiento sobre el descanso. La propia empresa dice estar trabajando en suavizarlo en futuros modelos.

¿Cuántas tareas necesito en un eval ligero?

Entre 5 y 10 tareas representativas bastan para detectar una tendencia. Más tareas dan más señal, pero cuestan más tiempo y más API. Empieza pequeño y amplía solo si una tarea concreta te da dudas.

La diferencia entre tener razón a tiempo y tenerla tarde

Hemos visto que la sensación de que Claude empeora mezcla cambios reales, variación de tus prompts y sesgo de expectativa, y que el postmortem de abril dio la razón a quien se quejaba, pero con dos meses de retraso. La diferencia entre tener razón a tiempo y tenerla tarde es un eval ligero: diez tareas fijas, una métrica simple y la versión anotada. Con eso dejas de discutir por intuición y empiezas a decidir con datos.

El siguiente paso natural es convertir ese eval en un check automático que corra en cada actualización de Claude Code, para enterarte de una regresión el mismo día y no seis semanas después. ¿Tienes ya un eval propio para tus herramientas de IA? Cuéntame cómo lo mides en los comentarios o en Twitter @sergiomarquezp_.

Vibe Coding desde el móvil con Claude Code: 7 reglas

Sergio Márquez — Thu, 21 May 2026 08:00:01 GMT

Vibe Coding desde el móvil con Claude Code: 7 reglas

Desarrollar un proyecto entero desde el móvil suena a humo. Hasta que ves cómo lo hace alguien que lleva una década escribiendo código y descubres que el truco no está en el teléfono, sino en las reglas.

TL;DR: vibe coding desde el móvil con Claude Code

El vibe coding desde el móvil consiste en dirigir a Claude Code con instrucciones en lenguaje natural y sin revisar el código generado, usando la app o el navegador del teléfono como única interfaz.
Funciona porque Claude Code on the web ejecuta cada sesión en una máquina virtual aislada en la nube, así que el riesgo de un comando destructivo queda contenido.
La diferencia entre un desastre y un proyecto que avanza son 7 reglas escritas en el CLAUDE.md: plan obligatorio, tests como red de seguridad y límites claros sobre qué no tocar.

El problema: dirigir un agente sin ver el editor

En octubre de 2025 Anthropic lanzó Claude Code on the web y la integración con la app móvil. La promesa: arrancar una tarea desde el teléfono, que el agente trabaje en una VM en la nube y seguir la conversación mientras ejecuta.

El problema real aparece cuando intentas hacer esto sin disciplina. En el móvil no hay editor, no hay diff cómodo, no hay terminal con scroll infinito. Si tu forma de trabajar depende de leer cada línea que escribe el agente, el móvil te bloquea.

La pregunta no es "¿puedo programar desde el móvil?". Es "¿qué tiene que ser cierto para que delegar a ciegas no acabe en un incendio?". Y la respuesta está en cómo configuras el agente antes de pulsar enviar.

¿Qué es el vibe coding desde el móvil?

El vibe coding desde el móvil es delegar la implementación completa de una funcionalidad a un agente de código a través del teléfono, describiendo el resultado deseado en lenguaje natural y validando por comportamiento, no por inspección del código.

Claude Code on the web es la versión que corre cada sesión en un sandbox aislado en la infraestructura de Anthropic, accesible desde claude.ai/code o la app móvil. El aislamiento es la pieza que cambia las reglas del juego: un agente que se equivoca en una VM efímera no toca tu máquina ni tu entorno local.

Esto no convierte el "no leer el código" en algo gratis. Lo convierte en una decisión deliberada, válida para side projects y prototipos, arriesgada para sistemas con usuarios reales. La frontera la pones tú.

Las 7 reglas para delegar de verdad

Estas reglas viven en el CLAUDE.md del proyecto. El agente las lee al arrancar cada sesión, también en la nube. Son el equivalente a un onboarding para un compañero que no te puede preguntar nada.

1. Plan mode obligatorio antes de tocar nada

La regla más importante. El agente debe presentar un plan y esperar tu aprobación antes de editar archivos. Desde el móvil, leer un plan de cinco puntos es viable; revisar 300 líneas de diff, no.

La documentación oficial de Claude Code recomienda plan mode cuando el cambio afecta a varios archivos o no conoces bien el código. Trabajando a ciegas, esa condición se cumple siempre. Si quieres profundizar en cómo explorar antes de actuar, el enfoque de investigar primero un repositorio antes de modificarlo encaja perfecto aquí.

2. El CLAUDE.md es la única interfaz de control

Sin editor, tu único punto de control persistente es el archivo de contexto. Ahí defines el stack, las convenciones y los límites. Un CLAUDE.md mínimo y preciso vale más que diez prompts improvisados.

# Reglas del agente
- Plan mode SIEMPRE antes de editar. Sin plan aprobado, no tocas codigo.
- Stack fijo: FastAPI + PostgreSQL. No anadas dependencias sin pedir permiso.
- Cada cambio necesita tests. Si no pasan, la tarea no se cierra.
- NUNCA toques: .env, migraciones de BD, ramas de produccion.
- Commits atomicos en formato conventional commits.

Como ya conté al hablar de que la configuración pesa más que el modelo elegido, un agente potente con instrucciones vagas rinde peor que uno modesto con reglas claras.

3. Tests automáticos como red de seguridad

Si no vas a leer el código, los tests son tu forma de leerlo. La regla: cada cambio incluye tests y el agente no cierra la tarea hasta que pasan en verde. Tú no validas el código, validas que el comportamiento esperado se cumple.

Esto cambia el contrato. En lugar de "escribe esta función", pides "esta función debe cumplir estos casos" y dejas que el agente itere hasta lograrlo.

4. Hooks que bloquean lo que no compila ni pasa el linter

Los hooks ejecutan comandos automáticamente tras cada acción del agente. Configurados bien, son un control de calidad que no depende de tu vigilancia.

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write",
        "hooks": [{ "type": "command",
          "command": "npm run lint && npm test" }] }
    ]
  }
}

Si el linter o los tests fallan, el agente recibe el error y corrige sin que tú intervengas. Es la misma idea que desarrollé sobre automatizar checks con hooks sin tocar tu flujo, llevada al extremo del trabajo móvil.

5. Una tarea = una sesión = un PR

El alcance pequeño es innegociable. Una sesión móvil debe producir un cambio acotado y revisable: un endpoint, un bug, un componente. Nada de "refactoriza todo el módulo".

Con tareas pequeñas, si algo sale mal el blast radius es mínimo y revertir es un git revert. Con tareas enormes, un error a ciegas se vuelve imposible de auditar después.

6. Reglas de "no toques" explícitas

El agente necesita saber qué territorio está prohibido. Secretos, archivos .env, migraciones de base de datos, ramas de producción y configuración de CI. Cualquier acción sobre esas zonas exige confirmación expresa.

Esta regla convierte "delegación total" en "delegación con límites", que es lo único sostenible. El agente es autónomo dentro de un perímetro que tú dibujas.

7. Confía, pero pide resúmenes en lenguaje natural

No leer el código no significa no entender qué pasó. Pide al agente que, al terminar, explique en tres frases qué cambió y por qué. Ese resumen es lo que revisas desde el móvil.

Si el resumen no tiene sentido o contradice lo que pediste, ahí es cuando abres el portátil. El resumen es el sensor que te avisa de cuándo dejar de confiar.

Caso real: arreglar un bug desde el tren

En escenarios reales, este flujo brilla en situaciones concretas. Imagina un side project, un blog personal o una API pequeña, con un bug reportado mientras estás fuera de casa.

Abres la app, describes el síntoma: "el endpoint /posts devuelve 500 cuando el parámetro tag está vacío". El agente entra en plan mode, propone reproducir el error con un test, corregir la validación y verificar. Apruebas. Trabaja en la VM, los hooks ejecutan el linter y la suite, el resumen final confirma el fix.

Tú nunca leíste el código. Leíste el plan, el resumen y el verde de los tests. Para un proyecto de bajo riesgo, eso es suficiente. Para el sistema de facturación de tu trabajo, no: ahí el código se revisa, sí o sí.

En Producción

El salto del side project al trabajo serio cambia varias cosas. Conviene tenerlas claras antes de delegar a ciegas en algo que importa.

Coste: Claude Code on the web está incluido en los planes Pro y Max de Claude, que rondan los 17 a 100 € al mes según el nivel. El consumo móvil no añade un coste aparte, pero las sesiones largas agotan los límites de uso igual que en escritorio.
Manejo de errores: los hooks y los tests son tu control sólido de errores. Sin ellos, delegar a ciegas es apostar. Con ellos, un fallo se detecta antes de llegar al merge.
Límites del modelo: el agente en la nube no ve tu entorno local ni servicios privados salvo que los expongas. Tareas que dependen de infraestructura interna no son candidatas para el móvil.
Qué cambia frente al tutorial: en producción real el "no leer el código" desaparece. El flujo móvil sirve para arrancar, planificar y avanzar; la revisión humana del diff sigue siendo obligatoria antes de tocar algo con usuarios.

Una capa de contexto bien diseñada ayuda a que las sesiones cortas no pierdan el hilo. Si trabajas en proyectos de varios días, vale la pena entender las tres capas de memoria que evitan el vertedero de contexto en Claude Code.

Errores comunes y depuración

Error: el agente edita archivos sin presentar plan. Causa: la regla de plan mode está como sugerencia, no como obligación. Solución: redacta la regla en imperativo y mayúsculas ("SIEMPRE", "NUNCA"), y activa plan mode también desde la sesión.

Error: los tests pasan pero el comportamiento es incorrecto. Causa: el agente escribió tests que validan su propia implementación errónea. Solución: define tú los casos de prueba críticos en el prompt o en el CLAUDE.md, no dejes que el agente decida qué probar.

Error: la sesión móvil se queda sin contexto a mitad de tarea. Causa: tarea demasiado grande para una sola sesión. Solución: aplica la regla 5, parte el trabajo en cambios pequeños e independientes.

Error: el agente toca un archivo de configuración sensible. Causa: la lista de "no toques" no incluía ese archivo. Solución: amplía la regla 6 y, en proyectos con secretos, apóyate en el aislamiento del sandbox como segunda barrera.

Preguntas frecuentes

¿Es seguro programar desde el móvil sin leer el código?

Es razonable para side projects y prototipos de bajo riesgo, gracias al sandbox aislado de Claude Code on the web. Para sistemas con usuarios reales, el código debe revisarse antes del merge: el móvil sirve para avanzar, no para saltarse el control humano.

¿Necesito una app de terceros para usar Claude Code en el móvil?

No. La app oficial de Claude y claude.ai/code permiten lanzar y seguir sesiones desde el teléfono. La interfaz es básica, una terminal en el navegador, pero suficiente para leer planes y resúmenes. Las apps de terceros añaden UI más cómoda, no capacidades nuevas.

¿Qué modelo conviene usar para trabajar a ciegas?

Para planificación y tareas complejas, un modelo de razonamiento alto reduce errores que no vas a detectar leyendo. Vale la pena revisar cuándo subir el nivel de razonamiento en Claude Code y cuándo no, porque más esfuerzo también significa más coste y latencia.

Conclusión

Hemos visto que el vibe coding desde el móvil no es magia ni humo: es la consecuencia de mover el control del editor al CLAUDE.md. Las 7 reglas, plan obligatorio, archivo de contexto como interfaz, tests, hooks, alcance pequeño, zonas prohibidas y resúmenes en lenguaje natural, son lo que separa delegar de abdicar.

La clave está en entender qué proyectos toleran este flujo. Un side project y un sistema en producción no juegan con las mismas cartas, y confundirlos es el error caro. El móvil te da velocidad para arrancar y avanzar; la revisión humana sigue siendo el freno que decides cuándo soltar.

¿Has probado a delegar una tarea completa a Claude Code desde el móvil? Cuéntame qué reglas te funcionaron en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo veré cómo encadenar varias de estas sesiones móviles en un flujo de trabajo diario sin perder el control.

Effort en Claude Code: cuándo subir a max y cuándo no

Sergio Márquez — Wed, 20 May 2026 08:00:01 GMT

TL;DR: El effort level en Claude Code controla cuánto razona el modelo antes de actuar. Con Claude Opus 4.7 hay cinco niveles (low, medium, high, xhigh y max) y Claude Code usa xhigh por defecto en todos los planes. Subir a max no mejora casi nada en tareas normales y dispara el gasto de tokens; lo rentable es ajustar el effort por tipo de tarea con el comando /effort.

El modelo no es la única palanca que eliges

En Claude Code llevas tiempo decidiendo entre Opus y Sonnet según la tarea. Desde Claude Opus 4.7 hay una segunda palanca, igual de importante y mucho menos visible: el effort level, es decir, cuánto razonamiento le dejas gastar al modelo antes de responder.

El problema es que casi nadie la toca. Claude Code trae un valor por defecto, funciona, y la mayoría seguimos a lo nuestro. Pero ese valor por defecto está pensado para el caso medio, no para tu tarea concreta. Renombrar una variable y refactorizar tres módulos no necesitan el mismo presupuesto de razonamiento, y pagarlos igual significa o ir lento de más o gastar tokens de más.

Ajustar el effort por tipo de tarea es una de esas decisiones de workflow que cuestan diez segundos y se notan toda la sesión. Igual que vimos al explicar por qué la configuración pesa más que el modelo elegido, aquí el ajuste fino importa tanto como la elección grande.

¿Qué es el effort level en Claude Code?

El effort level es el dial que le dice a Claude cuánto trabajo invertir en una respuesta: más razonamiento, más llamadas a herramientas, más exploración y más comprobaciones. Subir el effort no cambia el modelo, cambia cuánto piensa ese modelo antes y durante la tarea.

Con Opus 4.7 hay cinco niveles: low, medium, high, xhigh y max. Opus 4.6 y Sonnet 4.6 solo exponen cuatro (low, medium, high y max): xhigh es nuevo de 4.7.

Conviene no confundir el effort con el extended thinking. En Opus 4.7 el pensamiento es adaptativo: se activa o no, sin presupuesto fijo de tokens. El effort es la palanca de alto nivel; el thinking adaptativo es la mecánica que hay debajo.

¿Qué cambió con xhigh en Opus 4.7?

xhigh es un nivel intermedio entre high y max, pensado para coding agéntico y flujos largos con muchas herramientas. Da margen al modelo para explorar, retroceder y razonar a lo largo de muchos pasos sin pagar la latencia completa de max.

El detalle que se pasa por alto: en Claude Code, Opus 4.7 usa xhigh por defecto en todos los planes. En Opus 4.6 y Sonnet 4.6 el defecto es high, o medium en los planes Pro y Max. Si actualizaste de 4.6 a 4.7 y notaste respuestas más lentas o más caras, parte de eso es el salto silencioso del valor por defecto.

Anthropic también recoge que el nivel low de Opus 4.7 rinde aproximadamente como el medium de Opus 4.6. Toda la escala se ha desplazado hacia arriba, así que los niveles ya no significan lo mismo que antes de la actualización.

Cómo cambiar el effort level paso a paso

El control principal dentro de Claude Code es el comando /effort, uno más de los slash commands de Claude Code. Lo ejecutas y eliges nivel de una lista.

# Fija el nivel de razonamiento; persiste entre sesiones
/effort xhigh

# Sube a max solo para la tarea actual (max no persiste)
/effort max

# Deja que Claude Code decida el nivel por ti
/effort auto

Tu elección se guarda entre sesiones, con una excepción: max solo aplica a la sesión actual. Es deliberado, max no está pensado para vivir ahí de forma fija.

Para fijarlo fuera de la sesión interactiva tienes la variable de entorno y el flag de la CLI:

# Arranca Claude Code con un effort por defecto
CLAUDE_CODE_EFFORT_LEVEL=high claude

# O directamente con el flag de la CLI
claude --effort high

Y si quieres dejarlo escrito en la configuración del proyecto, en settings.json:

{
  "effortLevel": "high"
}

Qué nivel usar según la tarea

Nivel	Cuándo usarlo
`low`	Tareas cortas, acotadas y sensibles a latencia que no exigen inteligencia: lookups, formateo, renombrados.
`medium`	Trabajo sensible al coste que admite ceder algo de calidad a cambio de gastar menos tokens.
`high`	Mínimo recomendable para trabajo que sí exige inteligencia, o para gastar menos que xhigh.
`xhigh`	Mejor resultado para la mayoría de tareas de código y agénticas. Defecto recomendado en Opus 4.7.
`max`	Puede ayudar en tareas muy exigentes, pero con rendimientos decrecientes y tendencia a sobrepensar. Pruébalo antes de adoptarlo.

Un día normal: cuándo bajo y cuándo subo el effort

En la práctica, el effort no se toca una vez y se olvida: se mueve con el tipo de trabajo. Un patrón que funciona en el día a día es tratar el nivel como parte del enunciado de la tarea, no como una preferencia fija.

Para tareas mecánicas (ajustar imports, renombrar, escribir un test trivial, formatear un JSON) bajo a low o medium. Son cosas donde correcto y rápido gana a perfecto y lento, y el modelo no necesita explorar nada.

Para el grueso del trabajo de código (implementar una feature, depurar un bug con varias hipótesis, refactor de varios archivos) me quedo en xhigh, el defecto. Es el punto donde el modelo explora y verifica sin irse de presupuesto.

Reservo max para lo que de verdad lo pide: un bug que se resiste, una decisión de arquitectura con muchos caminos, una revisión donde un fallo sale caro. Y lo activo con /effort max sabiendo que se queda en esa sesión. La regla mental es simple: el effort debería seguir a la dificultad de la tarea, no a tu ansiedad por que salga bien.

En producción: coste, latencia y límites

Lo que en el tutorial es un dial más, en producción es una línea de tu factura. Opus 4.7 cuesta alrededor de 4,60€ por millón de tokens de entrada y 23€ por millón de salida. El effort no cambia ese precio por token, cambia cuántos tokens se gastan.

Y la diferencia no es pequeña. Una prueba pública que recorrió las cinco tiers con los mismos problemas de código encontró que el coste por tarea puede variar hasta 2,7 veces entre el nivel más barato y el más caro. Para un desarrollador que gasta entre 10 y 50€ al mes en API, elegir mal el effort de forma sistemática mueve ese rango de forma perceptible.

Tres cosas a tener en cuenta antes de fijar un nivel:

Latencia. Más effort es más tiempo de respuesta. En tareas interactivas, max puede romper tu ritmo a cambio de una mejora marginal.
Sobrepensar. Anthropic avisa de que max tiene rendimientos decrecientes y tiende a sobreanalizar. Más razonamiento no es siempre mejor razonamiento.
Tokens y tokenizer. Opus 4.7 razona más en los turnos tardíos de sesiones agénticas y usa un tokenizer nuevo que mapea el mismo texto a entre un 0 y un 35% más de tokens que 4.6. El gasto sube por dos vías a la vez.

En sesiones largas esto se nota especialmente: si trabajas en horas pico y sesiones largas, un effort alto consume tu cuota antes. Y si te preocupa el contexto, recuerda que gestionar la memoria en capas es una palanca distinta y complementaria: el effort regula cuánto piensa el modelo, la memoria regula con qué piensa.

Errores comunes al ajustar el effort

Error: dejar max como nivel fijo por si acaso. Causa: asumir que más razonamiento siempre da mejor resultado. Solución: usa xhigh como base y sube a max puntualmente con /effort max; no persiste a propósito.

Error: respuestas más lentas y caras tras actualizar a Opus 4.7. Causa: el defecto en Claude Code subió de high a xhigh, sumado al tokenizer nuevo. Solución: si tu trabajo tolera algo menos de profundidad, baja a high con /effort high.

Error: CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING no hace nada. Causa: esa variable controlaba el thinking de presupuesto fijo de 4.6; en Opus 4.7 el pensamiento es adaptativo y la variable se ignora. Solución: gestiona la profundidad con /effort; para desactivar el thinking por completo, usa MAX_THINKING_TOKENS=0.

Preguntas frecuentes

¿Cuál es el mejor effort level para programar en Claude Code?

Para la mayoría de tareas de código, xhigh, que es el defecto en Opus 4.7. Anthropic recomienda empezar en high o xhigh y reservar max para problemas concretos muy exigentes.

¿El effort level cambia el precio por token?

No. El precio por token de Opus 4.7 es fijo. El effort cambia cuántos tokens se consumen: más effort significa más razonamiento y más tokens de salida, así que la factura sube aunque la tarifa no.

¿Se puede usar xhigh con Sonnet 4.6?

No. xhigh es exclusivo de Opus 4.7. Opus 4.6 y Sonnet 4.6 solo exponen low, medium, high y max.

Lo que me llevo

El effort en Claude Code es una decisión de workflow diaria, no un ajuste que tocas una vez. Hemos visto que con Opus 4.7 hay cinco niveles, que xhigh es el punto dulce para coding y que max rara vez compensa fuera de problemas concretos. La clave está en hacer que el effort siga a la dificultad real de la tarea: bajar en lo mecánico, quedarse en xhigh para el grueso y subir a max solo cuando un fallo sale caro.

Si interiorizas eso, dejas de pagar razonamiento que no necesitas y de ir lento donde sí lo necesitas. ¿Has medido cuánto te cambia la factura según el effort? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo le toca el turno a los task budgets de la API, la otra forma de controlar el gasto de tokens en runs largos.

Memoria en Claude Code: las 3 capas que evitan el vertedero

Sergio Márquez — Tue, 19 May 2026 08:00:01 GMT

Memoria en Claude Code: las 3 capas que evitan el vertedero

TL;DR: La memoria útil en Claude Code no consiste en guardar todo lo que ocurre, sino en separar tres capas (decisiones duraderas, reglas estables y contexto efímero) y descartar activamente lo que no cambia la siguiente respuesta. Si lo haces bien, retomas trabajo al día siguiente sin reexplicar el repo ni arrastrar una conversación infinita.

El problema: tu memoria es un trastero, no una biblioteca

Llevo meses observando un patrón en sesiones largas con Claude Code: el agente empieza fino, toma buenas decisiones, y a las 3 horas responde con respuestas más genéricas, repite preguntas que ya tenían respuesta y olvida convenciones que dejaste claras al principio. La reacción habitual es guardar más cosas (todo el historial, todos los archivos tocados, todos los resúmenes). El resultado: peor todavía.

El problema no es que falte memoria. Es que no toda la información tiene el mismo valor operativo. Guardar el contenido entero de cada sesión es como guardar todas las notas adhesivas que has escrito en tu vida: técnicamente tienes la información, pero recuperarla cuesta más que volver a generarla.

El enfoque que mejor me ha funcionado, y que coincide con lo que están empujando los harnesses serios en 2026, es tratar la memoria como un sistema de tres capas con políticas distintas de escritura y recuperación.

Las tres capas de memoria operativa

No son arbitrarias. Cada una responde a una pregunta diferente y vive en un sitio distinto.

Capa	Qué guarda	Vida útil	Dónde vive
Reglas estables	Convenciones, stack, no-hacer	Meses	`CLAUDE.md`, hooks
Memoria persistente	Decisiones, bugs resueltos, descubrimientos	Semanas-meses	Plugin de memoria (Engram, claude-mem)
Contexto efímero	Estado de la tarea actual	Una sesión	Ventana de contexto

La clave: cada capa tiene una política de descarte distinta. La capa efímera muere al cerrar la sesión y no pasa nada. La persistente se poda cuando algo deja de ser cierto. Las reglas solo cambian cuando el equipo decide explícitamente cambiarlas.

Capa 1: reglas estables

Aquí va lo que siempre es cierto en tu proyecto: lenguaje, framework, convenciones de naming, qué herramientas usar (rg en vez de grep, fd en vez de find), qué nunca hacer sin confirmación. Esta capa tiene que ser corta, declarativa y leerse al principio de cada sesión. Si crece más allá de 200 líneas, ya no es regla estable, es novela.

Una regla estable se justifica por sí sola, sin contexto. Ejemplo válido: "Conventional commits format only". Ejemplo inválido: "En la migración del lunes decidimos usar X porque Y discutió con Z". Eso último pertenece a la capa 2.

Si trabajas con varios proyectos, esta capa se complementa muy bien con un archivo de configuración bien pensado para coding agents, donde el peso real está en la configuración, no en el modelo elegido.

Capa 2: memoria persistente (decisiones y descubrimientos)

Esta es la capa que la mayoría infla mal. La pregunta correcta no es "¿qué pasó?" sino "¿qué cambiaría mi siguiente respuesta saber esto?". Si la respuesta es "nada", no lo guardes.

Lo que sí merece persistir:

Decisiones de arquitectura: por qué se descartó una opción (no solo cuál se eligió).
Bugs resueltos con causa raíz: el síntoma se olvida, la causa raíz evita repetir el error.
Restricciones del entorno: "PM2 corre como ubuntu, nunca sudo", "este endpoint tiene rate limit de 10 req/s".
Preferencias del usuario validadas en conflicto: "prefiero patches mínimos, no refactor preventivo".

Lo que no merece persistir y mucha gente guarda igualmente: resúmenes de qué archivos se tocaron (eso está en git log), pasos de debugging que terminaron en el fix (el fix está en el código), listas de comandos ejecutados, transcripciones de la conversación.

Capa 3: contexto efímero

Es la ventana de contexto activa: archivos abiertos, salida de tests reciente, el plan de la tarea actual. Esta capa muere y debe morir al cerrar la sesión. Intentar persistirla entera es lo que convierte la memoria en vertedero.

La regla operativa: al terminar una tarea, antes de cerrar, comprime la capa 3 en una o dos entradas para la capa 2 (decisiones tomadas, bugs encontrados) y deja morir el resto. Si tu plugin de memoria captura automáticamente toda la sesión, configúralo para que pase por un filtro de relevancia antes de escribir.

Implementación práctica en 4 pasos

Voy a aterrizarlo en un flujo concreto que uso a diario. Asume Claude Code con un plugin de memoria tipo Engram, pero el patrón es portable a Codex, OpenClaw o Gemini CLI.

Paso 1: define tu CLAUDE.md como contrato, no como diario

Una sección por tipo de regla, máximo 2-3 frases por sección. Si necesitas justificar mucho una regla, probablemente no es regla, es decisión (capa 2).

## Rules
- NEVER add Co-Authored-By to commits
- Use rg/fd/bat, never grep/find/cat
- No auto-commit without explicit confirmation

## Stack
- Python 3.12, FastAPI, Pydantic v2
- Postgres 16, no ORM (raw SQL via asyncpg)

Paso 2: protocolo de guardado proactivo

Configura el agente para que llame al plugin de memoria inmediatamente después de eventos disparadores: decisión tomada, bug arreglado con causa raíz identificada, convención nueva acordada. No esperes al final de la sesión, porque para entonces el contexto ya se ha diluido.

El formato que mejor recupera después es este:

# Plantilla mínima para una entrada de memoria útil
title: "Migración auth: descartado JWT por sesiones server-side"
type: decision
content: |
  What: Se eligió sesiones en Redis sobre JWT.
  Why: Necesidad de revocación inmediata (compliance).
  Where: módulo auth/, ADR-007.
  Learned: JWT funciona si no necesitas revocación rápida.

Ese campo "Why" es lo que hace que la entrada sirva dentro de 3 meses cuando alguien pregunte por qué no se usó JWT. Si te interesa el patrón general detrás de este tipo de decisiones de seguridad, escribí sobre cuándo JWT sí encaja en Spring Boot.

Paso 3: recuperación selectiva, no historial completo

Cuando empiezas una sesión nueva, lo que no quieres es que el agente cargue las últimas 10 sesiones enteras en contexto. Lo que quieres es búsqueda semántica sobre la capa 2 con las keywords de la tarea actual.

En la práctica: al abrir una tarea de "añadir endpoint de pagos", el agente busca en memoria persistente términos como "pagos", "stripe", "webhook" y trae solo las 3-5 entradas más relevantes. Si no hay nada relevante, no inyecta nada. Esto reduce el contexto inicial de ~15k tokens (cargar todo) a ~2k tokens (solo lo que aplica).

Paso 4: poda activa

Una memoria que solo crece se vuelve ruido. Revisa la capa 2 cada 2-4 semanas y borra entradas que ya no son ciertas. Una entrada de tipo decisión queda obsoleta si la decisión cambió. Una entrada de bugfix queda obsoleta si el módulo donde vivía fue reescrito.

Esto no es opcional: sin poda, en 6 meses tu sistema de memoria devuelve resultados contradictorios y el agente empieza a tomar decisiones basadas en restricciones que ya no existen.

En Producción

Los detalles que cambian entre el tutorial y el uso real:

Coste de tokens: cargar todo el historial en cada sesión te puede salir entre 20€ y 60€ al mes extra en API de Opus, solo por contexto que el modelo nunca usa. La recuperación selectiva lo baja a un par de euros.
Latencia: cada 10k tokens extra en contexto añaden entre 1 y 3 segundos de tiempo hasta la primera respuesta. Multiplica eso por 50 mensajes al día y notas la diferencia.
Privacidad: la capa 2 va a almacenamiento persistente (local o cloud). No guardes ahí secretos, tokens, ni fragmentos de código propietario sensible. Si tu plugin va a un servicio gestionado, revisa qué se envía.
Múltiples proyectos: separa los namespaces de memoria por proyecto. Una decisión válida en el proyecto A puede ser exactamente lo contrario en el proyecto B.
Equipo: si varios desarrolladores comparten configuración, la capa 1 (CLAUDE.md) va al repo. La capa 2 es personal por defecto, aunque algunos equipos comparten un subconjunto de decisiones (ADRs) en un repo común.

Una práctica que aprendí a las malas: versiona tu CLAUDE.md. Cuando una regla cambia, el commit cuenta el porqué. Si lo tratas como código (lo es), evitas que alguien borre una regla crítica sin contexto. Esto se conecta directo con el principio de separación de responsabilidades: cada capa de memoria responde a una pregunta distinta y se gestiona con un proceso distinto.

Errores Comunes y Depuración

Error: El agente repite preguntas que ya tenían respuesta en sesiones anteriores.
Causa: La memoria persistente existe pero la búsqueda no encuentra la entrada relevante. Suele ser problema de keywords pobres o de que la entrada se guardó sin el campo "Why".
Solución: Revisa las últimas 10 entradas de memoria. Si tienen títulos genéricos ("reunión", "fix bug"), reescríbelas con títulos descriptivos que incluyan el dominio.

Error: El contexto inicial de cada sesión supera los 10k tokens sin haber hecho nada.
Causa: El plugin de memoria está inyectando todo, sin filtro de relevancia.
Solución: Configura un límite duro (top-5 entradas, máximo 2k tokens) en la inyección automática. Permite búsqueda manual para el resto.

Error: El agente toma decisiones basadas en restricciones que ya no existen.
Causa: Falta de poda. Decisiones antiguas se recuperan como si fueran actuales.
Solución: Añade campo de fecha a cada entrada y filtra por antigüedad en la búsqueda. Programa una revisión mensual de la capa 2.

Error: CLAUDE.md creció hasta 600 líneas y el agente lo ignora.
Causa: Pusiste decisiones en la capa de reglas. Las decisiones envejecen, las reglas no.
Solución: Mueve toda decisión contextual a la capa 2. Deja en CLAUDE.md solo afirmaciones permanentes sobre el proyecto.

Preguntas Frecuentes

¿Qué plugin de memoria uso para la capa 2?

En 2026 los más maduros son Engram (mejor para sesiones técnicas con search semántico) y claude-mem (más simple, captura pasiva). Si empiezas, prueba uno durante dos semanas y mide cuántas veces la recuperación te ahorra trabajo real. Si la respuesta es "casi nunca", probablemente el problema está en cómo escribes las entradas, no en el plugin.

¿Debo guardar el contenido de los archivos que tocó el agente?

No. Los archivos están en el repo y git log ya tiene el historial. Guardar copias en memoria duplica fuente de verdad y crea inconsistencias en cuanto el código cambie. Guarda solo la decisión detrás del cambio, no el cambio en sí.

¿Cómo migro si ya tengo meses de memoria desordenada?

No la migres entera. Filtra por las últimas 4-8 semanas, revisa entrada por entrada y conserva solo lo que pase el test "¿esto cambiaría una decisión futura?". Lo demás, archívalo o bórralo. En mi experiencia, queda menos del 20% del volumen original, y el sistema funciona mejor.

Cierre

La memoria útil en Claude Code no es un problema de almacenamiento, es un problema de criterio editorial. Separar reglas, decisiones y contexto efímero te da tres palancas distintas con políticas distintas, y eso es lo que diferencia retomar una tarea al día siguiente en dos minutos de pasar veinte reexplicando el repo.

Lo más difícil no es montar el sistema, es la disciplina de descartar. Cada entrada que guardas "por si acaso" empeora la recuperación de las entradas que sí importan. Si tu primera reacción al ver un bug interesante es "esto hay que guardarlo", pregúntate primero si la causa raíz cambia una decisión futura. Si no, el commit ya lo cuenta.

¿Cómo gestionas la memoria entre sesiones de Claude Code? ¿Qué entradas has terminado borrando porque generaban más ruido que ayuda? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. En el próximo post toca cómo conectar esta arquitectura de memoria con hooks que la mantengan limpia sin trabajo manual.

Coding agents 2026: la config pesa más que el modelo elegido

Sergio Márquez — Mon, 18 May 2026 08:00:02 GMT

Coding agents 2026: la config pesa más que el modelo elegido

TL;DR: La diferencia real entre un coding agent que ahorra horas y uno que las quema no está en el modelo. Está en su configuración, sus plugins y la cadencia con la que el equipo detrás libera mejoras. Esta guía explica cómo tratar la superficie operativa de Claude Code, Cline o Gemini CLI como parte del stack, con 4 ajustes accionables y una tabla comparativa de cadencia de releases.

El problema: cambiar de modelo cada semana ya no aporta

En los últimos meses he visto un patrón repetido. Alguien prueba Opus 4.7, luego salta a Gemini 3, después vuelve a Sonnet 4.6, y concluye que "todos rinden parecido". La conclusión es correcta, pero el diagnóstico no.

Lo que diferencia un flujo productivo de otro frustrante en 2026 no es el modelo subyacente. Es la configuración del agente: cómo está su archivo de reglas, qué plugins tiene activos, qué hooks ejecuta y con qué frecuencia recibe mejoras del equipo que lo mantiene. El modelo es el motor; la config y los plugins son la caja de cambios.

Los releases recientes de CLI agents (Cline saltando varias versiones menores en semanas, Gemini CLI publicando integraciones MCP nuevas, Claude Code añadiendo plugins de memoria y sandbox) apuntan claramente a que la batalla se está jugando en la capa operativa, no en el ranking de benchmarks.

¿Qué es la superficie operativa de un coding agent?

La superficie operativa es todo lo que rodea al modelo y determina cómo se comporta en tu repo concreto. Tiene tres capas:

Configuración estable: archivos tipo CLAUDE.md, .cursorrules o GEMINI.md con reglas que cambian pocas veces al mes.
Plugins y herramientas: servidores MCP, hooks, slash commands, skills y subagentes que extienden capacidades.
Cadencia de releases: la frecuencia con la que el equipo mantenedor publica mejoras, parches de seguridad y soporte para nuevos modelos.

Las tres se mueven a ritmos distintos y deben tratarse como artefactos del stack, no como detalles de usuario. Si dejas que envejezcan, el agente empezará a oler raro aunque el modelo no cambie.

Tres palancas que pesan más que el modelo

1. Reglas claras en el archivo de configuración

Un CLAUDE.md bien escrito reduce más alucinaciones que subir un escalón de razonamiento. Si quieres profundizar en cómo estructurarlo, hay una guía sobre separación de responsabilidades en arquitectura de software que aplica casi tal cual a cómo separar reglas, contexto operativo y memoria efímera.

Reglas que funcionan en mi flujo diario:

Idioma de comunicación y de código (no es lo mismo).
Stack canónico del proyecto (versiones de runtime, frameworks, formato de commits).
Comandos prohibidos o que requieren confirmación (rm, push, force).
Cómo verificar antes de afirmar ("si no estás seguro, investiga primero").

2. Plugins MCP elegidos por contrato, no por hype

Cada servidor MCP añade tokens de definición al contexto en cada turno. Activar 10 MCP "por si acaso" degrada el rendimiento del agente más que cambiar de modelo. La regla que aplico: cada MCP activo debe tener un contrato claro (entradas, salidas, errores) y un uso semanal verificable. El patrón se explica con más detalle en contratos para MCP en Claude Code.

Empieza con dos o tres MCP esenciales (sistema de archivos, git, base de datos del proyecto) y añade más solo cuando el dolor justifique los tokens.

3. Cadencia de releases del agente, no del modelo

Un agente con releases semanales corrige fugas de contexto, ajusta defaults y suma integraciones más rápido de lo que cualquier modelo nuevo puede compensar. Aquí es donde la elección de CLI tiene impacto duradero.

Tabla comparativa: cadencia y superficie operativa

CLI Agent	Cadencia típica	Config principal	Extensibilidad
Claude Code	Semanal o bisemanal	`CLAUDE.md` + `settings.json`	MCP, hooks, skills, slash commands, plugins
Cline (VS Code)	Semanal (v3.x activa)	Reglas en UI + workspace	MCP, modos, custom instructions
Gemini CLI	Bisemanal	`GEMINI.md` + extensiones	MCP, extensiones oficiales
Codex CLI	Mensual	`AGENTS.md`	Sandbox, herramientas básicas

Ninguno es objetivamente mejor. Lo importante es que sepas en qué punto de la cadencia estás y qué piezas de la superficie operativa usas de verdad.

Implementación: 4 ajustes con impacto inmediato

1. Auditar el archivo de reglas cada dos semanas

Abre tu CLAUDE.md y marca tres cosas: reglas que nunca se han disparado, reglas duplicadas o contradictorias, y huecos donde el agente repite los mismos errores. Borra lo muerto, fusiona lo redundante, añade lo que falta.

Pequeño ejemplo de bloque que reduce ida y vuelta:

# Define el comportamiento por defecto antes de cualquier acción destructiva

## Confirmación obligatoria

- Cualquier comando con `rm`, `git push --force`, `DROP`, o modificación de .env
  requiere mostrar el comando y esperar "sí" explícito.
- No usar `--no-verify` salvo petición directa.

2. Revisar plugins MCP activos cada release

Cuando tu CLI publique una nueva versión, comprueba si añadió MCP oficiales que sustituyen a los tuyos. Muchas integraciones caseras de hace tres meses ya tienen alternativa mantenida con menos tokens.

3. Suscribirte al changelog (no solo al modelo)

Sigue el repositorio o feed RSS del CLI. Los cambios de defaults (tamaño de contexto, nivel de razonamiento, política de auto-aceptación) suelen explicar cambios de comportamiento que de otro modo atribuyes al modelo. Esta es la misma idea que aparece en cómo leer benchmarks de coding agents sin caer en el hype: separa la señal del ruido antes de cambiar nada.

4. Versionar la configuración con el proyecto

El CLAUDE.md del proyecto debe vivir en el repo, no en tu home. Así cuando un compañero clona, hereda las reglas. Y cuando algo deja de funcionar, git blame te dice quién y cuándo lo cambió. Si trabajas en un monorepo con microservicios, este patrón se beneficia de la disciplina que recomiendo en microservicios con arquitectura hexagonal: contratos explícitos por capa.

Aplicación práctica: el caso del agente que "empeoró"

Hace unas semanas un flujo de revisión de PRs con Claude Code empezó a generar comentarios genéricos. La sospecha inmediata fue el modelo. Tras 20 minutos de revisión, el culpable fue un MCP añadido el sábado anterior que metía 4.000 tokens en cada turno y empujaba parte de las reglas del CLAUDE.md fuera del contexto efectivo.

Desactivar ese MCP devolvió la calidad. El modelo nunca cambió. La lección: antes de culpar al modelo, audita la superficie operativa.

En Producción

Cuando un coding agent forma parte del flujo de un equipo, la superficie operativa deja de ser preferencia personal y empieza a tener implicaciones de coste y riesgo. Algunas consideraciones:

Coste por turno: cada plugin MCP activo se paga en tokens. Un agente con 8 MCP activos puede costar 2 o 3 veces más por sesión que uno con 3.
Compatibilidad con releases: nuevas versiones del CLI pueden romper hooks o skills caseras. Versionar la config y leer el changelog antes de actualizar evita sorpresas en sprints.
Reversibilidad: mantener el settings.json en git permite hacer rollback en segundos cuando una release introduce defaults dañinos.
Visibilidad de cambios: si tres personas tocan el CLAUDE.md sin coordinación, las reglas entran en conflicto. Tratar la config como código requiere review igual que el resto.

En presupuestos típicos de desarrollador individual (10-50€ al mes en uso de APIs), reducir el número de MCP activos puede recortar el gasto entre un 20% y un 40% sin perder calidad percibida.

Errores comunes y depuración

Error: el agente ignora reglas claras del CLAUDE.md → Causa: el archivo de reglas está siendo truncado por exceso de contexto inicial (MCPs cargados). Solución: mover reglas críticas al inicio del archivo y desactivar MCPs no usados esta semana.
Error: comportamiento distinto entre dos compañeros con el mismo CLI → Causa: configuración global en ~/.claude sobrescribe el proyecto. Solución: auditar el config global y mover reglas específicas del proyecto a su repo.
Error: tras actualizar el CLI, hooks dejan de ejecutarse → Causa: cambio en formato del settings.json en release reciente. Solución: revisar el changelog de la versión instalada y migrar hooks al nuevo esquema.
Error: el agente da respuestas más cortas y menos útiles desde hace días → Causa: defaults de nivel de razonamiento cambiados silenciosamente o sesión arrastrando contexto sucio. Solución: sesión nueva más verificación explícita de configuración de razonamiento.

Preguntas frecuentes

¿Es mejor invertir tiempo en configurar el agente o en aprender prompts mejores?

Configurar el agente tiene ROI más alto a medio plazo. Un buen CLAUDE.md aplica a todas las conversaciones futuras, mientras que un prompt mejor solo aplica a esa tarea. Invierte en config primero, en prompts después.

¿Cuántos MCP es razonable tener activos?

Entre 3 y 6 para la mayoría de proyectos. Cada MCP activo añade entre 500 y 3.000 tokens de definiciones por turno. Más de 8 suele indicar acumulación por hype, no por necesidad real.

¿Debería actualizar siempre a la última versión del CLI?

No automáticamente. Lee el changelog primero, en especial los cambios de defaults y de formato de config. Espera 48 horas si tienes flujos críticos: los releases minor a veces traen regresiones que se corrigen en patch.

Cierre

Hemos visto cómo la superficie operativa de un coding agent (su archivo de reglas, sus plugins y la cadencia con la que recibe mejoras) suele explicar mejor la calidad del flujo diario que la elección de modelo. La clave está en tratar esa superficie como código de primera clase: versionada, revisada y auditada con la misma seriedad que el resto del stack.

El siguiente paso natural es estandarizar esta config entre proyectos sin que se vuelva rígida. Eso lo abordaré en un próximo post sobre plantillas reutilizables de configuración para coding agents.

¿Has notado que tu agente cambia de comportamiento sin que tú toques nada? Cuéntame en Twitter @sergiomarquezp_ qué ajuste de config te ha dado más resultado este mes.

Contratos para MCP en Claude Code: integraciones que no revientan

Sergio Márquez — Sun, 17 May 2026 08:00:01 GMT

Contratos para MCP en Claude Code: integraciones que no revientan

TL;DR: Antes de conectar otro servidor MCP o CLI a Claude Code, define un contrato mínimo con cinco piezas: esquema de entrada validado, esquema de salida estable, errores tipados, idempotencia y límites explícitos. Sin ese contrato, el agente improvisa, los flujos largos se rompen a mitad de tarea y depurar se vuelve adivinar.

Por qué tus integraciones MCP fallan a mitad de flujo

El patrón se repite: añades un servidor MCP nuevo, las primeras tres llamadas funcionan y a la cuarta el agente recibe un JSON con un campo opcional cambiado, no sabe qué hacer y empieza a alucinar parámetros. Lo mismo pasa con CLIs envueltos en Bash: un día devuelven la tabla en stdout, al siguiente lo mezclan con stderr y la salida ya no es parseable.

El problema rara vez es el modelo. Es que la integración no tiene un contrato. Una herramienta sin contrato es como una API REST sin documentación: puede funcionar en happy path, pero cualquier desviación rompe el flujo. Y en sesiones largas con Claude Code, donde una sola tarea encadena 20 o 30 llamadas a tools, la probabilidad de desviación se acumula.

Aquí el contrato no es un documento Markdown decorativo. Es código ejecutable que el servidor MCP impone y que el agente puede leer en su tool definition. Cuando existe, el agente sabe qué pedir, qué esperar y cómo recuperarse. Cuando no existe, improvisa.

¿Qué es un contrato en una integración MCP o CLI?

Un contrato de integración es la especificación verificable de cómo una tool acepta entradas, devuelve salidas y comunica errores. Tiene tres propiedades: es estable entre versiones, es validable automáticamente y es autodescriptivo en la definición de la tool.

En MCP esto se traduce en un inputSchema JSON Schema en la declaración del tool, una estructura de respuesta documentada y códigos de error consistentes. En CLIs externos invocados desde Claude Code, se traduce en flags estables, formato de salida fijo (idealmente --json) y exit codes con significado.

La diferencia entre una integración con contrato y una sin contrato no se nota en la demo. Se nota en la sesión número 30 cuando el agente lleva 40 minutos en una tarea y de repente no sabe interpretar una salida que ha cambiado de formato. Este principio entronca con la separación de responsabilidades clásica: el contrato es la frontera donde la responsabilidad de validar pasa de un lado a otro.

Los 5 elementos del contrato mínimo

Elemento	Qué define	Cómo se verifica
Esquema de entrada	Tipos, campos obligatorios y rangos	JSON Schema validado antes de ejecutar
Esquema de salida	Estructura estable que el modelo puede parsear	Tipado en código, tests de regresión
Errores tipados	Códigos discretos con causa accionable	Enum de errores documentado
Idempotencia	Qué llamadas se pueden repetir sin efectos	Marcado explícito en la descripción
Límites	Timeouts, tamaño máximo, rate limits	Enforced en el servidor, no solo documentado

Cualquiera de los cinco que falte se convierte en el punto por donde el flujo se rompe. Y normalmente se rompe al sexto turno, no al primero, lo que dificulta atribuir la causa.

Implementación paso a paso de un MCP con contrato

Voy a mostrarlo con un servidor MCP en Python usando el SDK oficial. La tool busca tickets en un sistema interno y devuelve metadatos. Caso simple, pero suficiente para ver los cinco elementos en acción.

1. Define el esquema de entrada con validación estricta

Lo primero es declarar exactamente qué acepta la tool. Sin campos abiertos tipo extra: dict que invitan a alucinar.

# Esquema de entrada validado: el agente solo puede pasar query y status, nada mas.
from pydantic import BaseModel, Field
from typing import Literal

class SearchTicketsInput(BaseModel):
    query: str = Field(min_length=2, max_length=200, description="Texto a buscar en titulo o descripcion")
    status: Literal["open", "closed", "any"] = Field(default="any")
    limit: int = Field(default=10, ge=1, le=50)

Los Literal y los rangos no son cosméticos. Convierten errores silenciosos del agente (pasar status="pending" porque le sonó bien) en errores de validación con mensaje claro.

2. Define el esquema de salida estable

El agente va a leer la respuesta turno a turno. Si los campos cambian o aparecen nulls inesperados, empieza a improvisar.

# Salida tipada: el agente sabe que campos esperar siempre, sin opcionales sorpresa.
class Ticket(BaseModel):
    id: str
    title: str
    status: Literal["open", "closed"]
    updated_at: str  # ISO 8601, no datetime crudo

class SearchTicketsOutput(BaseModel):
    results: list[Ticket]
    total: int
    truncated: bool

El campo truncated es importante: comunica al agente que hay más resultados sin mentir con un total. Esto evita que pida "todos" cuando ya devolviste el máximo.

3. Errores tipados, no excepciones genéricas

Si la búsqueda falla, el agente necesita saber por qué para decidir si reintentar, cambiar la query o abandonar.

# Errores discretos: cada codigo le dice al agente que hacer despues.
class TicketError(BaseModel):
    code: Literal["AUTH_EXPIRED", "RATE_LIMITED", "INVALID_QUERY", "BACKEND_DOWN"]
    message: str
    retry_after_seconds: int | None = None

Un AUTH_EXPIRED le dice al agente que pida credenciales. Un RATE_LIMITED con retry_after_seconds le permite esperar y reintentar sin spammear. Un Exception: connection refused sin estructura, en cambio, lo deja a oscuras.

4. Marca idempotencia explícitamente en la descripción

En la tool definition del MCP, la descripción no es decorativa: el agente la usa para razonar.

# La descripcion comunica al agente que esta llamada es segura de reintentar.
TOOL_DESCRIPTION = """Busca tickets por texto. Idempotente: repetir la misma query devuelve el mismo resultado.
Usala libremente para refinar busquedas. NO modifica estado."""

Cuando una tool sí muta estado, marcarlo igual de explícito: "No idempotente: cada llamada crea un nuevo registro". El agente ajusta su estrategia de reintentos en consecuencia.

5. Aplica límites en el servidor, no solo en el prompt

Decirle al agente "no pidas más de 50 resultados" en CLAUDE.md es una sugerencia. Forzarlo en el esquema y en la lógica es un contrato. Si el agente envía limit=200, el servidor lo rechaza con un error tipado y el agente aprende en una iteración.

Wrapper para CLIs externos con el mismo contrato

Si tu integración es un CLI invocado vía Bash, el contrato vive en un script wrapper. El patrón es el mismo: validar entrada, normalizar salida a JSON, mapear exit codes a errores tipados.

# Wrapper que da contrato a un CLI legacy con salida inconsistente.
import subprocess

def run_legacy_tool(query: str) -> dict:
    if len(query) < 2:
        return {"data": None, "error": {"code": "INVALID_QUERY", "message": "query too short"}}
    result = subprocess.run(["legacy-cli", "--query", query], capture_output=True, text=True, timeout=30)
    if result.returncode == 0:
        return {"data": parse_legacy_output(result.stdout), "error": None}
    return {"data": None, "error": map_exit_code(result.returncode, result.stderr)}

Este patrón es lo que evita que Claude Code lea stdout mezclado con warnings y empiece a inventar campos. La salida siempre tiene la misma forma: {data, error}. El agente nunca tiene que adivinar.

En Producción

Coste por turno: cada tool definida en MCP consume tokens del contexto del agente, en algunos casos varios miles por turno. Definir contratos compactos (descripciones concisas, esquemas planos, sin campos opcionales innecesarios) reduce el impacto. Es un equilibrio: el contrato debe ser preciso pero no verboso.

Versionado: trata el contrato como API pública. Cambios incompatibles requieren versión nueva (search_tickets_v2) y migración planificada. Romper un esquema sin avisar deja agentes en producción haciendo llamadas que ya no funcionan.

Observabilidad: loguea cada llamada con el esquema validado, el resultado y el tiempo. Sin trazas, depurar por qué el agente eligió mal una tool en el turno 23 es imposible.

Defensa frente a alucinación: aunque la validación rechace entradas malformadas, el agente puede alucinar nombres de tools que no existen o flags inventadas. Esta defensa complementa los contratos cerrando ese vector.

Secretos en el contrato: nunca incluyas credenciales en los esquemas de entrada. El agente puede loguearlas o reenviarlas. Inyecta secretos en el servidor desde variables de entorno, fuera del flujo del modelo. La misma lógica del secret scanning en GitHub MCP aplica aquí.

Errores comunes y depuración

Error: el agente pasa parámetros que no existen. Causa: el esquema acepta additionalProperties: true. Solución: configurar el esquema en modo estricto, rechazando campos extra.
Error: la tool funciona aislada pero falla en flujos largos. Causa: salida no idempotente sin marcar como tal. Solución: documentar idempotencia y, si no lo es, exigir un request_id en la entrada.
Error: el agente reintenta una llamada que falló por auth y agota el rate limit. Causa: error genérico tipo Exception. Solución: devolver AUTH_EXPIRED tipado para que el agente no reintente.
Error: respuestas masivas saturan el contexto. Causa: sin límite de salida. Solución: paginar con limit obligatorio y campo truncated en la respuesta.
Error: cambias el esquema en producción y los agentes activos rompen. Causa: contrato no versionado. Solución: tool con sufijo _v2, deprecación gradual.

Preguntas Frecuentes

¿Necesito un contrato si solo uso MCPs oficiales?

Los MCPs oficiales (GitHub, Linear, Notion) ya traen contratos razonables. El problema aparece con servidores propios, wrappers de CLIs internos o forks rápidos. Ahí es donde el contrato te salva la sesión.

¿Cómo verifico que mi MCP cumple su propio contrato?

Tests con casos límite: entradas vacías, tamaños máximos, errores forzados. Pydantic o JSON Schema validators se integran bien en CI. La misma lógica de hooks en Claude Code sirve para validar contratos en cada cambio.

¿Pasar a JSON Schema estricto rompe agentes existentes?

Puede pasar si tu agente venía pasando campos extra. Despliega primero en modo permisivo logueando rechazos, ajusta los prompts del agente y después activa modo estricto. Migración en dos pasos, sin sorpresas.

Cierre

Un contrato bien definido convierte una integración frágil en infraestructura. Los cinco elementos (entrada validada, salida estable, errores tipados, idempotencia explícita, límites en el servidor) no son opcionales si quieres que Claude Code complete tareas largas sin improvisar. El esfuerzo inicial se paga en la primera sesión de cuatro horas que no se rompe.

La regla práctica que me ha funcionado: antes de añadir una tool nueva a CLAUDE.md, escribe primero el contrato y los tests. Si no puedes especificarlo, probablemente el agente tampoco podrá usarlo bien. La próxima entrega del blog cubrirá cómo combinar estos contratos con slash commands para crear flujos verificables de extremo a extremo.

¿Has tenido integraciones MCP que fallaban a mitad de flujo y resolviste con contratos más estrictos? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_.

Research-first en Claude Code: explora repos grandes sin romper nada

Sergio Márquez — Sat, 16 May 2026 08:00:01 GMT

Research-first en Claude Code: explora repos grandes sin romper nada

TL;DR

Research-first es un patrón de trabajo con agentes de código donde, antes de tocar nada, Claude Code investiga la estructura del repo, las convenciones y los tests relacionados. Después planificas el cambio y solo entonces ejecutas. En repos grandes esto reduce ediciones a ciegas, archivos huérfanos y regresiones silenciosas. La regla simple: explorar, planificar, ejecutar, en ese orden y como fases separadas.

El problema: agentes que editan antes de entender

En un repo de cinco archivos da igual el orden. Pides un cambio, el agente lo hace y revisas. En un repo con cientos de módulos, ese mismo flujo falla de formas concretas: el agente duplica utilidades que ya existen, ignora un decorador estándar del proyecto, toca un archivo marcado como deprecated o introduce dependencias que el equipo ya descartó.

La causa raíz casi nunca es el modelo. Es que le pediste ejecutar sin darle tiempo a entender. Y como Claude Code obedece, ejecuta. Por eso los repos más serios que se están publicando últimamente alrededor de harnesses de agentes empujan la misma idea: research-first. Primero investiga, luego cambia.

¿Qué es research-first?

Research-first es un workflow donde el agente realiza una fase explícita de exploración del repositorio antes de proponer o aplicar cambios. No es leer un archivo y editar otro. Es una fase separada con su propio objetivo: producir un mapa mental verificable de la zona del código que vas a tocar.

La diferencia clave frente al flujo improvisado:

Sin research-first: el agente abre el archivo que mencionaste, deduce el resto y empieza a escribir.
Con research-first: el agente devuelve primero qué módulos están implicados, qué convenciones aplican, qué tests cubren la zona y qué efectos colaterales esperar. Tú decides si esa lectura es correcta antes de seguir.

Las tres fases del flujo

El patrón se descompone en tres etapas con criterios de salida claros. Si una fase no produce su entregable, no pasas a la siguiente.

Fase	Objetivo	Entregable
Exploración	Mapear la zona del repo afectada	Lista de archivos relevantes + convenciones detectadas
Planificación	Decidir qué cambiar y en qué orden	Plan numerado con pasos atómicos y riesgos
Ejecución	Aplicar el cambio y verificar	Diff aplicado + tests pasando

Fase 1: Exploración

El objetivo aquí no es resolver el problema, es entenderlo. Un prompt útil para arrancar:

Antes de cambiar nada, investiga:
1. ¿Qué módulos tocan el flujo de autenticación?
2. ¿Qué convenciones de testing usa el repo (pytest, fixtures, mocks)?
3. ¿Qué archivos están marcados como deprecated o legacy?
Devuelve solo la respuesta. No edites código todavía.

Lo importante es la última línea. Sin ella, Claude Code tiende a saltar directo a la edición. Con ella, devuelve un informe que puedes leer en treinta segundos y validar.

Fase 2: Planificación

Con el mapa en la mano, pides un plan. No código, plan. Pasos numerados, atómicos y reversibles:

Basándote en la investigación anterior, dame un plan paso a paso
para migrar la validación de tokens al nuevo middleware.
Cada paso debe ser aplicable y testeable por separado.

Aquí descubres pronto si el agente entendió mal algo. Es mucho más barato corregir un plan que un diff de 400 líneas.

Fase 3: Ejecución

Solo cuando el plan está validado, autorizas la ejecución. Y preferiblemente paso a paso, no "haz los siete pasos". Después de cada paso, ejecutas tests y revisas.

Cómo configurar research-first en tu día a día

Tres ajustes concretos que reducen la fricción del patrón:

CLAUDE.md con convenciones del repo: si el agente sabe que usas pytest, FastAPI y arquitectura por capas, no necesita descubrirlo cada vez. Esto encaja con la idea de separar responsabilidades en arquitectura: el CLAUDE.md documenta las fronteras, el agente las respeta.
Subagente de exploración: define uno cuyo único trabajo sea investigar sin permisos de escritura. Así no hay forma de que se cuele en la fase 3 antes de tiempo.
Plan mode antes de cada cambio grande: usar el modo de planificación de Claude Code como puerta entre la fase 2 y la 3 obliga al check humano.

Aplicación práctica: migrar un módulo en un repo monolítico

Caso típico: tu repo tiene un módulo de notificaciones que se llama desde quince sitios, y quieres migrarlo a una nueva interfaz. Sin research-first, pides a Claude Code que migre el módulo y el agente empieza a tocar imports. A los diez minutos tienes tests rotos en sitios que no esperabas.

Con research-first, el flujo cambia:

Exploración: pides la lista de los quince sitios, qué firma usan y qué tests los cubren. Validas que la lista esté completa.
Planificación: pides un plan donde cada paso migre una llamada y deje el resto funcionando. Revisas el orden.
Ejecución: aplicas paso a paso. Si el paso tres rompe algo, lo revierte y replanteas, sin haber tocado los pasos cuatro al quince.

Este patrón también ayuda cuando trabajas en otras arquitecturas modulares. Si vienes de armar microservicios con Node.js y Express o de aplicar arquitectura hexagonal en Java y Spring, la fase de exploración es donde el agente confirma qué capa toca y cuál no.

En Producción

Algunas consideraciones que aparecen cuando llevas research-first más allá del proyecto personal:

Coste por sesión: la fase de exploración consume tokens. En un repo grande puedes gastar entre 10.000 y 40.000 tokens solo investigando. Compensa cuando el cambio es no trivial, no para arreglar un typo.
Caducidad del informe: el mapa que produjo el agente refleja el repo en ese momento. Si pasas tres días sin tocar la tarea y mientras tanto alguien hizo merge, vuelve a explorar antes de planificar.
Permisos por fase: en producción real, el subagente explorador no debería tener permisos de escritura. Eso fuerza la separación y evita que ejecute por accidente.
Verificación humana: el plan debe pasar por una revisión rápida tuya antes de ejecutar. No es burocracia, es el único punto donde tu juicio entra en el flujo.

Errores comunes

Error: el agente empieza a editar en la fase 1 → Causa: el prompt no prohíbe explícitamente la escritura → Solución: añade "no edites código todavía" al cierre del prompt y, si puedes, retira permisos de escritura al subagente.
Error: el plan tiene pasos no atómicos ("refactorizar el módulo X") → Causa: pediste un plan sin restricciones de granularidad → Solución: exige que cada paso sea aplicable y testeable por separado.
Error: la exploración devuelve solo lo obvio → Causa: el agente buscó por nombre de archivo en vez de por símbolo o por uso → Solución: pide explícitamente que use búsqueda de referencias y grep por función, no solo por nombre de fichero.
Error: tras ejecutar, los tests pasan pero algo se rompió en runtime → Causa: la fase 1 no incluyó tests de integración → Solución: añade explícitamente al prompt de exploración "qué tests de integración cubren esta zona".

Preguntas frecuentes

¿Research-first no es lento para tareas pequeñas?

Sí, y por eso no lo apliques siempre. Para cambios de menos de 20 líneas o tareas que tocan un solo archivo, el flujo directo gana. Research-first paga cuando el cambio cruza módulos, toca interfaces compartidas o el repo tiene más de unos cuantos miles de líneas.

¿Cómo se relaciona research-first con los subagentes?

Encajan bien. El subagente de exploración es el ejecutor natural de la fase 1: contexto aislado, sin permisos de escritura y con un objetivo único. Esto reduce el ruido en tu sesión principal y mantiene separadas la investigación y la edición.

¿Sirve research-first si trabajo con bases de datos o frontend?

Sí. En frontend, la fase de exploración mapea componentes, props compartidas y stores. En backend con DB, identifica modelos relacionados y migraciones recientes. Si estás trabajando con un ORM, la fase de exploración debería incluir el esquema actual; por ejemplo, cuando usas Prisma para gestionar bases de datos en Node.js, conviene que el agente revise el schema antes de tocar queries.

Cierre

Research-first no es una técnica avanzada, es disciplina de orden. La diferencia entre un agente de código que mete bugs y uno que aporta valor real en repos serios suele estar en si exploró antes de ejecutar. Las tres fases (explorar, planificar, ejecutar) son baratas de adoptar y caras de saltarse cuando el repo crece.

Si estás empezando con Claude Code, prueba aplicar el patrón en tu próxima tarea no trivial: bloquea la edición en la primera fase, revisa el plan antes de autorizar y ejecuta paso a paso. La sensación de control al final del cambio es notable.

¿Cómo aplicas tú la fase de investigación con agentes de código? Cuéntamelo en los comentarios o escríbeme por Twitter en @sergiomarquezp_. En el próximo post entraré en cómo encajar este patrón con worktrees aislados para probar varias rutas sin ensuciar tu rama principal.

Skills y subagentes: el ladrillo base de los agentes IA

Sergio Márquez — Fri, 15 May 2026 08:00:01 GMT

Skills y subagentes: el ladrillo base de los agentes IA

TL;DR: Las skills empaquetan pasos, checks y formato en una unidad reutilizable que cualquier harness moderno (Claude Code, Codex, OpenClaw) entiende. Combinadas con subagentes, convierten tareas repetidas en piezas auditables: dejas de copiar prompts entre proyectos y empiezas a versionar workflows como código. En este artículo verás la anatomía de una skill, cuándo conviene un subagente en su lugar y qué cambia al llevarlas a producción.

¿Por qué las skills ya no son un extra?

Durante 2025 las skills eran un detalle de Claude Code. En 2026 el panorama cambió: Codex incorporó skills experimentales, OpenClaw las soporta nativamente y los nuevos harnesses como oh-my-openagent tratan skills y subagentes como ciudadanos de primera clase. El estándar SKILL.md ya funciona como interfaz común entre herramientas.

El efecto práctico es simple: si escribes una skill bien hecha hoy, sirve mañana en otro harness sin reescribirla. Eso convierte el trabajo de afinar prompts en algo capitalizable, no en arena que se cuela entre los dedos al cambiar de cliente o de modelo.

Hay un cambio cultural detrás. Antes el debate giraba en torno a qué prompt uso. Ahora gira en torno a qué tareas vale la pena empaquetar. Las skills son la respuesta operativa a esa segunda pregunta.

¿Qué es una skill?

Una skill es un archivo Markdown autocontenido que describe cómo ejecutar una tarea concreta, incluyendo pasos, validaciones y formato de salida esperado. El harness la carga bajo demanda (progressive disclosure) cuando detecta que el contexto la requiere, no en cada turno.

La diferencia clave con un prompt suelto es que la skill vive en disco, se versiona en git y puede invocarse con un nombre estable. No depende del estado de la conversación ni de que recuerdes su redacción exacta.

¿Qué es un subagente?

Un subagente es un agente secundario que el harness lanza con un contexto aislado para resolver una subtarea específica y devolver solo el resultado relevante. No hereda tu historial ni contamina el contexto principal al volver.

Skills y subagentes son piezas distintas pero complementarias. Una skill describe cómo hacer algo. Un subagente describe quién lo hace en una sesión aparte.

Anatomía de una skill bien hecha

La estructura mínima que funciona en Claude Code, Codex y OpenClaw es la misma: frontmatter YAML con metadata y cuerpo Markdown con instrucciones. Ejemplo de una skill para revisar pull requests de Python:

---
name: python-pr-review
description: Revisa un PR de Python aplicando checks de tipado, tests y estilo antes de aprobar
type: review
---

## Pasos

1. Lee el diff completo con `git diff main...HEAD`.
2. Verifica que cada función nueva tenga type hints.
3. Comprueba que hay tests para cada rama lógica añadida.
4. Ejecuta `ruff check .` y `mypy .` y reporta errores con línea.

## Formato de salida

- **Veredicto**: APROBADO | CAMBIOS PEDIDOS | RECHAZADO
- **Bloqueantes**: lista de issues que impiden merge
- **Sugerencias**: mejoras opcionales

Tres cosas hacen que esta skill sea reutilizable de verdad:

Pasos numerados: el agente no improvisa el orden, lo que reduce variabilidad entre ejecuciones.
Comandos explícitos: ruff, mypy, git diff. Si el harness tiene tool use, sabe exactamente qué ejecutar.
Formato de salida fijo: el resultado es parseable y comparable entre PRs.

Fíjate en lo que no hay: lenguaje motivacional, ejemplos largos, ni explicaciones de por qué importa cada paso. Una skill no es documentación, es un contrato de ejecución.

Skills vs subagentes: cuándo usar cada uno

La regla práctica que aplico en mi flujo diario:

Situación	Skill	Subagente
Tarea corta, contexto compartido necesario	Sí	No
Búsqueda que devuelve mucho ruido	No	Sí
Pasos repetibles con formato fijo	Sí	No
Tareas paralelas independientes	No	Sí
Refactor que toca varios archivos	Sí	Opcional
Investigación cross-repo	No	Sí

El criterio simple: si necesitas el resultado dentro de tu contexto principal, skill. Si necesitas aislar para no contaminar tu sesión, subagente. Muchas tareas combinan ambos: una skill que internamente lanza subagentes para fases pesadas.

Para profundizar en cómo organizar tu colección y decidir qué tareas merecen pieza propia, hay un análisis previo sobre construir tu librería de Claude Skills que complementa esta anatomía.

Implementación paso a paso

Convertir una tarea repetida en skill sigue siempre el mismo patrón. Lo aplico cada vez que detecto que estoy explicándole al agente el mismo procedimiento por tercera vez.

Identifica la tarea: que sea repetible, con entrada y salida claras. Si no sabes describirla en una frase, todavía no está madura para skill.
Documenta los pasos manualmente: escribe el procedimiento como si se lo explicaras a alguien nuevo. Sin abstracciones.
Define el formato de salida: estructura fija, secciones nombradas, campos esperados.
Crea el archivo: .claude/skills/nombre-skill.md con frontmatter name, description, type.
Pruébala en frío: en una sesión nueva, sin contexto previo, pídele al agente que la aplique a un caso real.
Itera el wording: cada vez que el agente falle, ajusta los pasos o el formato. No la descripción.

El paso 5 es el que más se salta la gente. Si tu skill solo funciona cuando tu sesión ya tiene el contexto cargado, no es una skill, es un atajo personal. Para skills funcionando bien, conviene tener hooks que ejecuten checks automáticos sin depender de que el agente recuerde lanzarlos.

En producción

Llevar skills a un equipo introduce problemas que no aparecen en uso individual. Estos son los que me he encontrado:

Versionado y compatibilidad. Una skill que funciona con Opus 4.7 puede degradarse en Sonnet 4.6 si depende de razonamiento extendido. Anota en el frontmatter qué modelo testaste y cuándo. Cuando cambie el modelo, vuelve a validar antes de asumir que sigue funcionando.

Coste real. Cada skill cargada suma tokens al system prompt. Con 30-40 skills activas estás añadiendo 5-10k tokens por turno, aunque el harness use progressive disclosure. Audita qué skills están realmente activas y elimina las que no usas hace meses.

Conflictos entre skills. Si tienes python-pr-review y strict-type-review, el agente puede aplicar las dos a la vez y generar salidas duplicadas. Define qué skills son mutuamente excluyentes en su descripción.

Drift silencioso. Una skill que ayer funcionaba puede romperse porque cambió la API de una herramienta que invoca. Sin tests, no te enteras hasta que un PR sale mal revisado. Una opción ligera es ejecutar un caso canónico semanalmente y comparar el output con uno fijado.

El aislamiento también importa. Si tu skill modifica archivos, ejecutarla dentro de un sandbox para agentes evita que un error contamine tu rama principal. Y para integraciones con servicios externos, conviene revisar prácticas de secret scanning en GitHub MCP antes de que una skill suba credenciales por descuido.

Errores comunes y depuración

Error: La skill se ignora aunque la nombres explícitamente. Causa: el frontmatter no tiene name o la descripción es genérica y el harness no la indexa bien. Solución: asegúrate de que description menciona palabras concretas de la tarea, no metafrases tipo "ayuda con código".

Error: La salida varía entre ejecuciones con el mismo input. Causa: el formato de salida está descrito en prosa, no como estructura. Solución: usa headers Markdown fijos (## Veredicto, ## Bloqueantes) y bullets con nombre de campo.

Error: Funciona en local pero falla cuando otro miembro del equipo la usa. Causa: depende de herramientas o paths específicos de tu máquina. Solución: lista en la skill las dependencias necesarias (ruff, mypy, etc.) y haz que falle pronto si no están instaladas.

Error: La skill aplica pasos que ya no son válidos. Causa: drift por cambios externos sin revisión. Solución: anota fecha de última revisión en el frontmatter y agenda revisión trimestral.

Preguntas frecuentes

¿Cuántas skills es razonable tener?

Entre 10 y 25 skills cubren la mayoría de tareas repetidas de un developer individual. Pasar de 40 suele indicar que estás convirtiendo en skill cosas que solo usas una vez al mes. Mejor borrar y recrear cuando vuelvan a hacer falta.

¿Una skill puede llamar a otra?

Depende del harness. Claude Code y OpenClaw permiten referenciar otras skills por nombre dentro del cuerpo. Codex todavía no compone skills automáticamente. Si necesitas composición fiable, modela las dependencias como pasos explícitos dentro de la skill principal.

¿Skills o subagentes para tareas largas?

Subagentes. Una tarea de varias horas con búsquedas, lecturas y razonamiento profundo contamina tu contexto principal si la ejecutas inline. Lánzala en un subagente que devuelva solo el resultado final estructurado, y deja la skill como envoltorio que define el formato de invocación.

Cierre

Hemos visto que una skill bien hecha no es un prompt vitaminado, sino una unidad ejecutable con contrato de entrada y salida. La clave está en empaquetar solo lo que repites y en mantenerlo auditable: si dentro de seis meses no entiendes para qué sirve una skill, bórrala. Los subagentes complementan ese patrón cuando el aislamiento de contexto importa más que la compartición de estado.

Mi recomendación: empieza con tres skills (review, debugging, setup) y nada más. Cuando una de ellas falle en producción, ajústala antes de crear la cuarta. El siguiente paso natural es definir una política clara de qué promover a memoria persistente y qué dejar como skill, algo que tocaré en próximas entradas.

¿Has empezado a versionar tus skills o sigues con prompts sueltos? Cuéntamelo en Twitter @sergiomarquezp_.

Sandbox para agentes de código: aísla Claude Code y Codex

Sergio Márquez — Thu, 14 May 2026 08:00:01 GMT

Sandbox para agentes de código: aísla Claude Code y Codex

TL;DR: Un sandbox para agentes de código es un entorno de ejecución aislado (microVM, contenedor o sandbox del sistema operativo) que limita qué archivos, red y procesos puede tocar tu agente. En 2026, con OpenAI lanzando sandbox nativo para Codex en Windows y Claude Code permitiendo restringir directorios y permisos, dejar que un agente toque tu repo sin aislamiento ya no es aceptable. Esta guía explica los niveles de aislamiento, cuándo aplicar cada uno y cómo configurarlos sin romper tu flujo.

El problema: agentes con autonomía, máquina sin límites

Los agentes de código pasaron de "asistentes que sugieren" a "procesos que ejecutan". Claude Code escribe ficheros, lanza comandos, instala dependencias. Codex hace lo mismo desde Windows o macOS. Y la mayoría corre con el mismo usuario que tu sesión: acceso completo a tu home, tus llaves SSH, tu .env, tu historial de bash.

El patrón clásico que me he encontrado en proyectos reales es este: instalas un agente, pruebas con --dangerously-skip-permissions "para no pelearme con los prompts", y a las dos semanas tu agente está leyendo carpetas que no debería tocar. No es paranoia: es el modelo de amenaza que estás aceptando por defecto.

Las dos señales del mercado que cambian la conversación en mayo de 2026:

OpenAI publicó el sandbox nativo de Codex para Windows con restricted tokens, ACLs de filesystem y usuarios sandbox dedicados. Y lo hizo open source.
Docker Sandboxes ya empaqueta agentes de código dentro de microVMs con su propio daemon Docker aislado del host.
Claude Code permite restringir directorios permitidos y configurar redes desde su modo sandbox.

El mensaje es claro: si delegas tareas largas o tocas código sensible, el aislamiento ya es requisito, no extra.

¿Qué es un sandbox para agentes de código?

Un sandbox para agentes de código es un entorno de ejecución que aplica límites explícitos sobre filesystem, red, procesos y credenciales para que el agente solo pueda operar dentro de un perímetro definido. La frontera puede estar en el sistema operativo (procesos con tokens restringidos), en un contenedor (Docker, gVisor) o en una máquina virtual ligera (microVM como Firecracker).

Tres niveles a memorizar:

Nivel	Tecnología	Aislamiento	Cuándo usarlo
Ligero	Sandbox nativo (Claude Code, Codex Windows)	Tokens restringidos, ACLs, directorios permitidos	Tareas locales en tu repo de trabajo
Medio	Contenedor (Docker, devcontainers)	Filesystem propio, red controlada	Dependencias raras o repos no confiables
Fuerte	microVM (Firecracker, Docker Sandboxes)	Kernel propio, hardware boundary	Código no auditado, agentes con shell libre

Una regla simple: cuanto más autónomo es el agente, más fuerte debería ser el aislamiento.

Por qué ahora: el patrón se está estandarizando

Hasta hace poco, hablar de sandbox para un agente local sonaba a sobre-ingeniería. En 2026 ha cambiado por tres motivos concretos:

Tareas largas: los agentes ya operan minutos u horas sin supervisión. Un descuido se acumula.
Tool use real: con MCP, los agentes invocan APIs externas, escriben archivos y ejecutan binarios. La superficie crece.
Multi-agente: si corres dos agentes en paralelo, necesitas que cada uno tenga su propio worktree y workspace.

OpenAI, al abrir el código del sandbox de Codex en Windows, ha dado un empujón claro: "esto es lo mínimo que un agente debería tener". Y el resto del ecosistema está copiando el patrón.

Implementación paso a paso

1. Restringe directorios en Claude Code

El nivel más barato y útil. En tu settings.json defines qué rutas puede tocar el agente:

{
  "sandbox": {
    "enabled": true,
    "allowedDirectories": ["/home/sergio/proyectos/mi-app"],
    "networkAccess": "restricted"
  }
}

Con esto Claude Code no puede leer tu home, tus claves SSH ni otros proyectos. Si necesitas que toque rutas específicas, añádelas explícitamente.

2. Usa worktrees aislados por tarea

Antes de delegar una tarea larga, crea un worktree dedicado. Así el agente no toca tu rama de trabajo y puedes descartar todo si sale mal:

# Crea un worktree aislado para la tarea del agente
git worktree add ../mi-app-agent-task feature/refactor-auth
cd ../mi-app-agent-task
claude  # arranca el agente solo aquí

Es un patrón compatible con cualquier nivel de sandbox y resuelve el 80% de los problemas de "el agente me tocó algo que no debía".

3. Sube a contenedor cuando no confíes en el código

Si trabajas con un repo cliente o con dependencias que no has auditado, mete el agente en un devcontainer. Docker provee el aislamiento, el agente cree que tiene libertad y tu host se mantiene limpio.

{
  "name": "claude-sandbox",
  "image": "mcr.microsoft.com/devcontainers/python:3.12",
  "mounts": ["source=${localWorkspaceFolder},target=/workspace,type=bind"],
  "runArgs": ["--network=bridge", "--cap-drop=ALL"]
}

La clave: --cap-drop=ALL y red controlada. El agente puede hacer lo que quiera dentro, pero no escapa.

4. microVM para tareas críticas

Si el agente va a ejecutar código no auditado o ataca un repo público, usa Docker Sandboxes o un proveedor cloud como E2B. Cada sesión arranca en una microVM con su propio kernel, su propio daemon Docker y red proxyficada. Es la única defensa real contra escapes de contenedor.

En Producción

Lo que aprendes cuando dejas de ser un tutorial y empiezas a delegar trabajo real:

Coste: microVMs cuestan más en tiempo de arranque (segundos vs milisegundos) y en RAM. Para tareas cortas locales no compensa.
Red: bloquear todo es atractivo, pero los agentes necesitan npm, pip, GitHub. Permite hosts concretos, no "todo o nada".
Credenciales: nunca montes tu ~/.ssh ni tu .env raíz dentro del sandbox. Inyecta solo lo que la tarea necesita, por variable de entorno temporal.
Logs y rollback: graba qué comandos lanza el agente. Sin auditoría, el sandbox solo limita el daño, no te dice qué pasó.
Concurrencia: si corres dos agentes en paralelo, dales sandboxes separados. Compartir filesystem es el camino más rápido a una pisada.

Si te interesa profundizar en cómo organizar permisos y rollback en estos flujos, escribí sobre guardrails en Claude Code con Security beta y cómo definirlos sin romper la productividad.

Errores comunes y depuración

Error: el agente falla con "permission denied" al instalar paquetes → Causa: sandbox bloquea escritura en /usr → Solución: usa un virtualenv dentro del directorio permitido.
Error: Docker no funciona dentro del sandbox de Claude Code → Causa: el sandbox local y Docker son incompatibles por diseño → Solución: usa un devcontainer en lugar del sandbox nativo cuando necesites Docker.
Error: el agente pide aprobación constantemente → Causa: permisos demasiado estrictos → Solución: añade hooks pre-aprobados para comandos seguros en lugar de bajar el nivel global de aislamiento. Cubrí el patrón en hooks en Claude Code para checks automáticos.
Error: --dangerously-skip-permissions sin sandbox → Causa: es la combinación que más daño hace, da control total → Solución: nunca uses esa bandera fuera de un contenedor o microVM.

Aplicación práctica: un flujo real con Claude Code

El setup que uso para tareas medianas, donde el agente puede tirar varias horas:

Worktree dedicado con la rama de la tarea.
Sandbox nativo de Claude Code apuntando solo a ese worktree.
Red restringida: permito github.com, npmjs.com, pypi.org y poco más.
.env con secretos falsos durante la sesión; los reales solo cuando el merge se cierra.
Hooks que validan que el agente no toque carpetas fuera del worktree.

Para entender por qué este aislamiento conecta con otras decisiones del flujo (memoria, contexto, secrets), el secret scanning en GitHub MCP resuelve el lado de "qué hago si el agente se trae una clave por accidente". Y si tu agente toca infraestructura, las reglas de separación de responsabilidades en arquitectura aplican igual: separar capas, separar permisos.

Preguntas frecuentes

¿Necesito un sandbox si solo uso Claude Code en proyectos personales?

Sí, al menos el nivel ligero. Aunque el riesgo de fuga sea bajo, restringir directorios evita que un comando mal interpretado borre archivos en otra carpeta del home. El coste de activarlo es un campo en settings.json.

¿Cuál es la diferencia entre devcontainer y sandbox nativo?

El sandbox nativo limita procesos y rutas en tu sistema operativo sin virtualización. El devcontainer es un contenedor Docker completo: aísla filesystem, red y dependencias, pero arranca más lento y consume más recursos. Devcontainer gana cuando trabajas con código no confiable; sandbox nativo gana en velocidad para tu trabajo diario.

¿microVMs como Firecracker rompen el flujo del agente?

Casi nada, si los integras bien. La latencia extra es de segundos al iniciar, no en cada turno. Para tareas cortas no compensa; para sesiones largas o multi-agente sí, porque el aislamiento entre sesiones es real.

Conclusión

Hemos visto que un sandbox para agentes de código no es paranoia, sino el coste lógico de delegar más autonomía. La pieza simple es restringir directorios y red en Claude Code o Codex. La pieza fuerte es subir a microVM cuando el agente toca código que no controlas. Lo importante es elegir el nivel adecuado al riesgo de cada tarea, no aplicar el más alto siempre.

Si vas a delegar más trabajo a tu agente en los próximos meses, empieza por restringir directorios hoy y graba qué comandos lanza tu agente. El siguiente salto natural es combinar sandbox con políticas de memoria persistente, donde decides qué del trabajo aislado promocionas al contexto duradero.

¿Cómo tienes configurado el aislamiento de tu agente? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_.

Por qué cambié de claude-mem a Engram en Claude Code

Sergio Márquez — Wed, 13 May 2026 16:15:41 GMT

Por qué cambié de claude-mem a Engram en Claude Code

TL;DR: Hace dos días recomendé claude-mem como mejor opción de memoria persistente para Claude Code. Sigue siendo verdad para mucha gente. Pero en mi setup acabé migrando a Engram porque salto entre Claude Code, Codex y Gemini CLI varias veces a la semana, y necesitaba una capa de memoria que no estuviera atada a un solo agente. Aquí qué cambió, cómo decidí, y cuándo cada opción gana.

El contexto del cambio

Hace dos días publiqué una guía sobre memoria persistente en Claude Code donde recomendaba claude-mem como la opción más madura para uso individual. El argumento era sólido: hooks bien integrados, compresión progresiva en 3 capas, cero fricción si tu workflow vive dentro de Claude Code.

Lo importante no es qué dije entonces. Es qué cambió.

He estado trasteando con claude-mem y con Engram en paralelo, en el mismo proyecto, sobre los mismos archivos, para comparar honestamente. Y aunque claude-mem sigue siendo la opción más amigable para empezar, en mi día a día acabó perdiendo. La razón no es técnica en abstracto: es de workflow.

Lo que cambió en mi día a día

En las últimas semanas he ido moviendo cada vez más tareas fuera de Claude Code. Codex para revisiones cruzadas con GPT-5.5, Gemini CLI para tareas con contexto muy grande (1M tokens), Cursor para edits rápidos con autocomplete. Esto no es porque Claude Code me funcione peor: es porque cada agente tiene un sweet spot distinto y al final del día acabo saltando entre tres o cuatro durante la misma tarea.

El problema con claude-mem es que es un plugin de Claude Code. Sus hooks se enganchan al ciclo de vida del agente: SessionStart, PostToolUse, Stop. Si paso a Codex a mitad de tarea, esos hooks no se disparan ahí. Si pido a Gemini que mire un repo gigante, ese trabajo no entra en mi memoria. Tengo varias memorias paralelas, una por agente, con duplicación y huecos.

Engram resuelve esto desde otro ángulo: no es un plugin de un agente, es un binario Go que expone un servidor MCP. Cualquier cliente que hable MCP (Claude Code, Codex, Gemini CLI, Cursor, VS Code, Windsurf) lee y escribe contra la misma base SQLite local. La memoria deja de estar atada a un proceso concreto y empieza a comportarse como un servicio compartido.

Comparativa práctica: claude-mem vs Engram

Eje	claude-mem	Engram
Captura	Automática vía hooks	Explícita vía `mem_save`
Almacenamiento	SQLite + índice vectorial	SQLite + FTS5 (full-text)
Coste por observación	Tokens de tu cuenta (compresión SDK)	Cero después del setup
Portabilidad	Claude Code only	Cualquier agente MCP
Fricción inicial	Cero (plugin + reinicio)	Baja (`brew install` + setup por agente)
Privacidad	`~/.claude-mem/`, local	`~/.engram/`, local
Compresión	Sí, progresiva 3 capas	No, full-text indexing
Búsqueda	Vector similarity	FTS5 + BM25

Cada fila es una decisión real. Te explico las cuatro que más pesaron en mi caso.

1. Captura automática vs explícita

claude-mem captura todo automáticamente. Cada tool call, cada edit, cada read. Cómodo si no quieres pensar, ruidoso porque acaba guardando observaciones que no merecen el espacio y consumiendo tokens incluso cuando lo que hiciste no merece guardarse.

Engram te obliga a llamar mem_save explícitamente. Eso suena a trabajo extra, pero en la práctica trae un protocolo de memoria que se inyecta en cada conversación: "guarda decisiones, bugfixes, descubrimientos, convenciones". El propio agente aprende cuándo es relevante. El ruido baja, la señal sube.

2. Compresión SDK vs full-text

claude-mem usa el agent SDK de Claude para comprimir observaciones. Cada compresión gasta tokens. En proyectos activos puedes acabar pagando consumo solo por construir tu memoria. Es invisible hasta que miras la cuenta.

Engram indexa full-text con FTS5 de SQLite. Búsquedas BM25, sin embeddings, sin compresión, sin coste por observación más allá del espacio en disco. Una vez instalado, gastar tokens en guardar memoria deja de ser un coste recurrente.

3. Portabilidad

Esta es la que decidió el cambio. Mi flujo real:

Lunes: arranco una migración en Claude Code → guardo decisiones
Miércoles: pido revisión cruzada a Codex (GPT-5.5) → el modelo no ve mi memoria de Claude
Viernes: vuelvo a Claude Code → tengo que reinyectar contexto manualmente

Con Engram, esa rotura desaparece. Codex lee la misma base de datos, ve las decisiones del lunes, propone revisiones informadas. El miércoles deja de ser un punto de fricción.

4. Memory Protocol (la skill)

Engram trae un detalle no obvio: una skill llamada Memory Protocol que se inyecta en cada conversación de Claude Code. Es un prompt corto que le obliga al agente a:

Guardar tras cada decisión, bugfix, descubrimiento o convención.
Buscar memoria antes de empezar trabajo sobre un tema que pudo haberse tocado antes.
Hacer mem_session_summary al cerrar sesión.

Esto convierte la memoria de "algo que tengo que recordar usar" a "algo que pasa por defecto". Reduce la fricción explícita y compensa la falta de captura automática.

Cuándo claude-mem sigue siendo la mejor opción

No quiero pintar Engram como universalmente superior. No lo es. Tres escenarios donde claude-mem sigue ganando:

Tu workflow vive 100% en Claude Code. Si no saltas a otros agentes, la portabilidad de Engram es valor que no usas, y la captura automática de claude-mem es comodidad pura.
Quieres lo mínimo de fricción inicial. claude-mem es un /plugin install y listo. Engram pide un binario instalado más setup por agente, aunque sea breve.
Confías más en la compresión semántica que en full-text. Si tus observaciones son largas y matizadas, el vector store de claude-mem puede recuperar mejor que el FTS5 de Engram en queries vagas.

Si te encajan dos de los tres, quédate con claude-mem.

Setup: cómo correr Engram en paralelo a claude-mem

No es una migración hard. Es una transición de uso: el flujo nuevo va a Engram, el viejo se consulta donde está. claude-mem y Engram conviven sin tocarse — guardan en directorios distintos (~/.claude-mem/ vs ~/.engram/), así que puedes tener los dos activos en Claude Code mientras decides.

1. Instalar el binario

En macOS:

brew install gentleman-programming/tap/engram

Otras plataformas (Linux, Windows): ver docs/INSTALLATION.md del repo. Es un binario Go autocontenido, sin Node ni Python.

2. Registrarlo en Claude Code

claude plugin marketplace add Gentleman-Programming/engram
claude plugin install engram

El plugin registra automáticamente el servidor MCP, los hooks de sesión y la skill Memory Protocol. Reinicia Claude Code y las tools (mem_save, mem_search, mem_session_summary, etc.) están disponibles en cualquier conversación. No tocas ~/.claude/settings.json a mano.

3. Registrarlo en otros agentes

Una línea por agente:

engram setup codex
engram setup gemini-cli
code --add-mcp '{"name":"engram","command":"engram","args":["mcp"]}'   # VS Code

Cursor, Windsurf y resto en docs/AGENT-SETUP.md. Todos apuntan al mismo SQLite local, así que la memoria es la misma sin replicación manual.

4. Cómo se ve una llamada `mem_save` real

Engram expone 19 tools MCP. La que vas a usar el 80% del tiempo es mem_save. Estructura recomendada con bloque What/Why/Where/Learned:

title:   "Migrated auth from sessions to JWT"
type:    "decision"
content: |
  **What**: Replaced express-session with jsonwebtoken across the auth middleware.
  **Why**: Session storage no escala entre múltiples instancias (Hetzner load balancer).
  **Where**: src/middleware/auth.ts, src/routes/login.ts.
  **Learned**: httpOnly + secure flags obligatorios en la cookie del refresh token. Rotación de refresh va por endpoint aparte.

Cuando la semana siguiente arrancas una sesión y preguntas "qué hicimos con auth", mem_search con "JWT auth middleware" te trae esa observación con su contexto completo. Es la diferencia entre empezar de cero y arrancar donde lo dejaste.

El plugin además incluye la skill Memory Protocol que se inyecta como instrucción de sistema: obliga a guardar tras decisiones/bugfixes/descubrimientos y a hacer mem_session_summary antes de cerrar. La fricción de "tengo que acordarme de llamarlo" se evapora.

El matiz que no va en ninguna comparativa

Hay una verdad que ningún cuadro comparativo captura: ningún plugin de memoria persistente reemplaza tu CLAUDE.md.

CLAUDE.md fija reglas estáticas que tú escribes a conciencia: convenciones de proyecto, restricciones, principios. La memoria persistente captura decisiones dinámicas que toma el agente. Son capas complementarias. Sin lo primero, lo segundo se desboca; sin lo segundo, lo primero envejece.

Esto vale para claude-mem, para Engram y para cualquier sistema futuro. Tiempo de aprendizaje, que no tiempo perdido.

Preguntas frecuentes

¿Engram es gratis?

Sí. Binario open source (MIT), corre 100% local. Hay una versión Cloud opt-in (engram serve) para sincronizar entre máquinas, pero no es necesaria para uso individual.

¿Puedo usar los dos a la vez?

Sí, sin conflicto. claude-mem guarda en ~/.claude-mem/, Engram en ~/.engram/. Ningún proceso pisa al otro. La única "duplicación" es que en Claude Code tienes dos capas simultáneas escuchando. En proyectos serios yo dejé claude-mem solo para histórico, pero esa es una decisión personal.

¿Y si Engram introduce un bug en una tarea crítica?

Mismo riesgo que claude-mem: estás dejando que un proceso externo modifique tu workflow. Ambos son maduros pero relativamente nuevos. La salvaguarda real es no apoyarte en la memoria persistente para decisiones críticas: usarla como apoyo, no como fuente única de verdad. Toda decisión load-bearing debe vivir también en CLAUDE.md o en un ADR del repo.

Si quieres entender el problema desde cero antes de elegir, el post original sobre claude-mem sigue siendo la mejor introducción. Este post es el siguiente paso: qué pasa cuando tu workflow se reparte entre varios agentes.

Y si tu workflow ya vive en varios agentes, prueba Engram durante una semana en paralelo. Si la memoria empieza a viajar contigo entre Claude, Codex y Gemini, ya sabes qué decidir.

Repos: github.com/Gentleman-Programming/engram (Engram, MIT) · github.com/thedotmack/claude-mem (claude-mem, Apache 2.0). Ambos open source, ambos locales por defecto.

Memoria multiagente: qué promover y qué no en Claude Code

Sergio Márquez — Wed, 13 May 2026 08:00:01 GMT

Memoria multiagente: qué promover y qué no en Claude Code

TL;DR: La memoria persistente entre agentes en Claude Code acelera handoffs, pero arrastra supuestos viejos y errores si no decides qué se promueve y qué queda temporal. En esta guía verás cuándo conviene activar memoria compartida, qué criterios usar para promover observaciones y qué riesgos aparecen cuando dos o más agentes leen del mismo almacén.

El problema: contexto compartido no es lo mismo que contexto correcto

Llevo varios meses usando Claude Code con plugins de memoria persistente para no reexplicar el proyecto en cada sesión. Funciona bien cuando trabajas solo. El día que añadí un segundo agente para revisar PRs, la cosa se torció: el revisor citaba decisiones de arquitectura que ya habíamos descartado dos semanas antes.

El problema no era el modelo. Era que la memoria guardaba todo como si fuera verdad permanente, sin distinguir entre una decisión final y una idea desechada a mitad de discusión.

Si estás moviendo tu flujo de prompts sueltos a un sistema con memoria reutilizable (Claude Code, claude-mem, MCPs tipo Engram), la pregunta clave deja de ser "¿cómo guardo contexto?" y pasa a ser "¿qué se promueve a memoria y qué debe quedarse temporal?".

¿Qué es la memoria persistente multiagente?

La memoria persistente multiagente es una capa de almacenamiento compartida entre varios agentes de IA que sobrevive a la sesión, captura decisiones y contexto, y los inyecta selectivamente cuando otro agente retoma el trabajo.

En la práctica se implementa de tres maneras distintas:

Archivos locales tipo CLAUDE.md o MEMORY.md versionados en el repo.
Plugins MCP con base de datos local (Engram, claude-mem) que indexan observaciones por tipo y proyecto.
Servicios externos como Mem0 o Letta con API propia y permisos por agente.

Cada opción tiene un coste distinto y una superficie de error distinta. La parte interesante no es la tecnología: es la política de qué guardar.

Por qué importa antes de añadir un segundo agente

Cuando trabajas con un solo agente, la memoria persistente es casi siempre ganancia neta: te ahorra reexplicar el stack, las convenciones y las decisiones. El propio agente que escribió la memoria es el que la lee.

Con dos o más agentes (por ejemplo, uno que implementa y otro que revisa), aparecen tres problemas que no existían:

Sesgo heredado: el agente B confía en lo que escribió A sin verificar que sigue siendo cierto.
Decisiones obsoletas como verdades: ideas descartadas quedan registradas como "decisión" y se citan meses después.
Permisos opacos: un agente con scope reducido lee observaciones generadas por otro con scope mayor.

El patrón es el mismo problema que vivimos en bases de datos compartidas hace 20 años, solo que ahora el lector es probabilístico y no te lanza un error si interpreta mal.

Criterio práctico: qué promover a memoria

Después de bastantes iteraciones, el filtro que mejor me funciona es preguntar tres cosas antes de guardar algo:

Pregunta	Si la respuesta es...	Acción
¿Es verificable releyendo el código?	Sí	No guardar. Que el agente lo lea cuando lo necesite.
¿Sigue siendo cierto dentro de 3 meses?	Probablemente no	Marcar como temporal con fecha de caducidad.
¿Lo aplicaría otro agente sin contexto extra?	Sí	Promover a memoria persistente con el porqué.

Regla simple: guarda decisiones y restricciones, no estado. El código ya es el estado.

Tipos de memoria que sí merecen persistencia

Decisiones de arquitectura con el motivo (por qué FastAPI y no Django, no qué endpoints existen).
Convenciones del proyecto que no están en linters (formato de commits, naming de tests).
Restricciones del entorno (la VPS solo tiene 4 GB de RAM, la API tiene rate limit de 60 req/min).
Preferencias del usuario validadas (rechazos repetidos, patrones aceptados).

Tipos que mejor dejar fuera

Listado de archivos o rutas (el agente las descubre con fd o rg).
Resúmenes de commits o PRs recientes (git log ya existe).
Estado en curso de una tarea (eso va en plan o todo, no en memoria).
Recetas de debugging puntuales (el fix está en el commit; la memoria envejece mal).

Estructura mínima de un registro de memoria

Para que un segundo agente pueda usar una observación sin contaminarse, cada registro necesita al menos cuatro campos. Esto es lo que uso con claude-mem y plugins similares:

---
name: feedback-tests-integracion
type: feedback
created: 2026-05-13
expires: never
scope: backend-api
---
Los tests de migraciones deben hitear PostgreSQL real, no mocks.

**Why:** En 2025-Q4 una migración pasó tests mockados y rompió producción.
**How to apply:** Solo en tests con prefijo `test_migration_*`. El resto pueden mockar.

Los campos scope y expires son los que cambian todo cuando entra un segundo agente. Sin scope, un agente de frontend recibe restricciones de backend que no le aplican. Sin expires, las decisiones temporales se vuelven permanentes por inercia.

Gobernanza entre agentes: tres patrones que funcionan

Patrón 1: memoria por scope, no global

Cada agente lee solo el subconjunto de memoria que le aplica. Si tienes un agente implementador y uno revisor, no comparten todo: el revisor lee convenciones y restricciones, no las preferencias de estilo del implementador.

En Claude Code esto se traduce en tener varios CLAUDE.md por subdirectorio o usar el campo scope de tu plugin de memoria.

Patrón 2: promoción explícita, no automática

Muchos plugins capturan todo lo que pasa y lo guardan. Cómodo, pero peligroso. El patrón que mejor envejece es promoción explícita: el agente propone guardar algo, el humano confirma. La fricción es el feature, no el bug.

Si tu plugin no soporta esto, una alternativa barata: dejar que el agente escriba en un archivo candidatos.md y revisarlo al final del día antes de moverlo a MEMORY.md.

Patrón 3: caducidad por defecto

Todo registro nuevo tiene caducidad de 30 días salvo que lo marques como expires: never. Suena radical, pero fuerza a renovar lo que sigue siendo útil y a tirar lo que no. Las decisiones reales no envejecen mal porque las renuevas al usarlas.

En producción

Cuando llevas esto a un equipo o a un flujo serio, aparecen consideraciones que no ves en el tutorial:

Coste de tokens: cada observación cargada en el contexto cuesta. Una memoria de 500 entradas mal filtradas puede consumir 8.000 tokens por turno sin que el agente las necesite. Mide cuánta memoria entra realmente en el system prompt.
Versionado: si la memoria vive en archivos del repo, va a Git y tiene historial. Si vive en una base local, necesitas un backup. Yo prefiero la primera opción cuando se puede, por lo mismo que defendí en su día la separación de responsabilidades: el código y las decisiones que lo gobiernan deberían viajar juntos.
Permisos: si un agente tiene acceso de escritura a memoria global, cualquier prompt injection puede plantar observaciones falsas. Trata la memoria como input no confiable y revísala periódicamente.
Rollback: ten un mecanismo para "olvidar" una observación cuando descubres que está mal. git revert funciona si la memoria está en archivos.

El presupuesto de tokens es donde más fácil se descontrola: en un proyecto medio con tres agentes y memoria mal podada, he visto fácil 15-20€ extra al mes solo en contexto repetido.

Errores comunes y depuración

Error: el agente cita una decisión que ya cambiamos → Causa: registro sin fecha o sin supersedes. → Solución: cuando una decisión reemplaza a otra, marca la anterior como obsoleta en lugar de borrarla; deja la traza.
Error: dos agentes guardan la misma observación con palabras distintas → Causa: no hay deduplicación semántica. → Solución: revisa periódicamente con un agente dedicado a fusionar duplicados, o usa un plugin que detecte candidatos al guardar.
Error: el agente revisor aplica reglas que no le tocan → Causa: scope global por defecto. → Solución: marca scope explícito en cada observación y filtra en el cargador.
Error: la memoria crece sin parar → Causa: ningún proceso poda. → Solución: revisión mensual con un slash command que liste observaciones no usadas en N días.

Preguntas frecuentes

¿Necesito un plugin MCP o me basta con CLAUDE.md?

Para proyectos pequeños o de una persona, un buen CLAUDE.md versionado en el repo cubre el 80% de los casos. El plugin MCP empieza a compensar cuando tienes varios agentes, varios proyectos o quieres búsqueda semántica sobre el histórico.

¿Qué pasa si dos agentes escriben memoria a la vez?

Depende del backend. Los plugins serios usan transacciones; los que escriben en archivo plano pueden corromper datos. Si trabajas con paralelismo real, verifica que tu plugin de memoria soporta escritura concurrente antes de confiarle decisiones importantes.

¿Cuánta memoria es demasiada?

No hay número mágico, pero si tu memoria consume más del 10% del contexto del modelo en cada turno, estás cargando demasiado. Mide y poda. Es preferible que el agente lea código que cargar mil observaciones por si acaso.

Cierre

La memoria persistente multiagente no es un upgrade gratuito sobre la sesión única. Resuelve el problema de reexplicar contexto, pero introduce uno nuevo: decidir qué merece sobrevivir a la sesión y qué debe morir con ella. La regla que mejor envejece es promoción explícita, scope por agente y caducidad por defecto.

Si ya tienes un flujo con varios agentes y memoria compartida, esta semana prueba a auditar tus últimas 50 observaciones con las tres preguntas del filtro: cuántas son verificables releyendo el código, cuántas seguirán siendo ciertas en tres meses y cuántas aplicaría otro agente sin contexto extra. Las respuestas suelen sorprender.

¿Cómo gestionas tú la memoria entre agentes? Cuéntamelo en Twitter @sergiomarquezp_. En el próximo post entraremos en cómo aplicar este mismo criterio cuando la memoria viene de un MCP externo con permisos finos.

Gemini CLI y Claude Code: 5 patrones de terminal en 2026

Sergio Márquez — Tue, 12 May 2026 08:00:01 GMT

Gemini CLI y Claude Code: 5 patrones de terminal en 2026

TL;DR

Gemini CLI ha vuelto a coger tracción en GitHub y Hacker News con guías muy prácticas de uso agentic en terminal. Si trabajas con Claude Code, no hace falta cambiar de herramienta: hay cinco patrones (gestión de contexto, MCP, hooks de shell, perfiles por proyecto y verificación previa) que puedes adoptar hoy y que mejoran tiempo de respuesta, fiabilidad y coste por sesión.

Por qué mirar a Gemini CLI si usas Claude Code

El movimiento alrededor de Gemini CLI en mayo de 2026 no es solo ruido. El repositorio oficial de Google supera las 100k estrellas y aparecen guías como "Gemini CLI tips and tricks for agentic coding" con cientos de votos en Hacker News. Esto no convierte a Claude Code en obsoleto, pero sí señala dónde la comunidad está afinando ergonomía.

En mi flujo diario con Claude Code en repos enterprise (Python/FastAPI y Java/Spring), he ido tomando ideas de la conversación de Gemini CLI sin renunciar a Anthropic. La clave: los patrones de CLI son portables entre agentes. Lo que cambia es el motor.

¿Qué es un patrón de terminal agentic?

Un patrón de terminal agentic es una convención reutilizable que estructura cómo invocas, supervisas y verificas un agente de código desde la línea de comandos. No es un comando suelto: es una manera de organizar contexto, herramientas y validaciones para que la sesión no dependa de improvisar cada vez.

Patrón 1: contexto comprimido al arrancar

Gemini CLI insiste mucho en abrir cada sesión con un "contexto base" mínimo: arquitectura, convenciones y decisiones activas. Claude Code ya lo soporta vía CLAUDE.md, pero la gente suele dejarlo crecer sin control.

El patrón útil es comprimir el CLAUDE.md a menos de 200 líneas con secciones fijas: stack, convenciones, scripts críticos, lo que está fuera de alcance. Si necesitas detalle, lo invocas bajo demanda con un @ a un fichero específico, igual que harías con --all-files en Gemini CLI. Para profundizar en cómo estructurar el archivo, este post sobre separación de responsabilidades aplica también al diseño del contexto.

Patrón 2: MCP como capa de herramientas, no como atajo

Gemini CLI normalizó hablar de servidores MCP con configuración explícita y permisos por proyecto. En Claude Code la tentación es enchufar MCP a saco (GitHub, filesystem, Notion, base de datos) y dejar que el agente decida. Mala idea: cada herramienta extra suma tokens a cada turno y aumenta la superficie de error.

El patrón que sigo en producción:

Un MCP por dominio del proyecto, no por capricho.
Permisos de escritura desactivados por defecto. Si el agente quiere escribir, te pregunta.
Auditoría: revisar settings.json antes de cada sprint largo.

Ejemplo mínimo de configuración local de Claude Code con MCP filesystem en solo lectura:

{
  "mcpServers": {
    "fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"],
      "env": { "MCP_READ_ONLY": "true" }
    }
  }
}

Esa variable MCP_READ_ONLY evita escrituras inesperadas durante exploración. Si trabajas con repos sensibles, complementa con secret scanning en GitHub MCP.

Patrón 3: hooks de shell para validar antes de aceptar

Una de las ideas más copiables de la comunidad Gemini CLI es ejecutar verificaciones en shell antes de que el agente proponga el siguiente paso. Claude Code lo permite mediante hooks definidos en settings.json.

Lo que uso para evitar commits con tests rotos:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "command": "pytest -q --maxfail=1 || exit 2"
      }
    ]
  }
}

Si los tests fallan, el hook devuelve código 2 y Claude Code aborta el commit antes de ejecutarlo. La validación sucede fuera del modelo, lo que evita falsas confirmaciones.

Patrón 4: perfiles de configuración por tipo de tarea

Gemini CLI fomenta tener perfiles distintos para "explorar" vs "editar". El patrón equivalente en Claude Code es alternar configuraciones según objetivo:

Modo	Modelo	Permisos	Cuándo usarlo
Exploración	Sonnet rápido	Solo lectura	Entender repo, buscar bugs
Edición	Opus 4.7	Lectura/escritura local	Refactor, feature nueva
Revisión	Sonnet	Solo lectura + git diff	Code review previo a PR

Los tres modos viven en perfiles distintos de settings.json. Cambiar entre ellos cuesta menos que tunear un único archivo gigante. Si vas a trabajar varias horas seguidas, planifícate como en este post sobre sesiones largas en horas pico.

Patrón 5: verificación con un segundo agente

La comunidad de Gemini CLI popularizó el uso de un "crítico" separado: un agente que revisa el output del agente principal antes de aceptarlo. En Claude Code, lo más cercano son los subagentes que dispara Task.

Mi patrón mínimo: cuando el agente principal acaba un refactor grande, lanzo un subagente con prompt corto del tipo "revisa el diff contra los tests existentes y los principios SOLID, devuelve solo los riesgos en menos de 200 palabras". El subagente no comparte el contexto sucio del principal, así que detecta cosas que el otro ya daba por buenas.

En producción

Adoptar estos patrones tiene coste real. Hooks mal escritos rompen flujos enteros. MCP mal configurados disparan tokens por turno. Perfiles duplicados se desincronizan con el tiempo. Lo que aplico al subir a producción interna:

Coste API: con cinco MCP activos noté un aumento de aproximadamente 30 a 40% en tokens por turno. Bajar a dos o tres lo dejó plano.
Latencia: hooks que llaman a pytest añaden segundos. Para repos grandes, conviene un subset rápido (tests unitarios) en lugar del suite completo.
Rollback: versiona settings.json en git. Cuando un cambio rompe el flujo, el git revert es la salida más limpia.
Equipo: documenta perfiles en el README del repo, no solo en tu home. Los compañeros no leen tu dotfiles.

Si trabajas con pipelines más complejos, esta lógica conecta con lo que escribí sobre preparación de datos con Python y LangChain: los patrones de validación previa aplican igual.

Errores comunes y depuración

Error: el hook bloquea siempre el commit aunque los tests pasen. Causa: códigos de salida mal interpretados. Solución: asegura que el hook devuelve 0 en éxito y 2 (no 1) en fallo bloqueante.
Error: el agente ignora MCP filesystem. Causa: ruta relativa mal resuelta al lanzar Claude Code desde otra carpeta. Solución: usa rutas absolutas o variables de entorno.
Error: el subagente revisor no ve el diff. Causa: el principal no commiteó los cambios antes de invocarlo. Solución: stage previo con git add -p y pasa el diff explícito en el prompt.

Preguntas frecuentes

¿Tengo que elegir entre Gemini CLI y Claude Code?

No. Son agentes CLI con motores distintos, pero los patrones de terminal son portables. Puedes usar Gemini CLI para exploración rápida y Claude Code para edición sin que se pisen.

¿Cuántos MCP servers son razonables en una sesión?

En mi experiencia, dos o tres por proyecto. Más de cinco activos a la vez aumenta tokens por turno entre 30 y 40% sin aportar valor proporcional. Activa MCP bajo demanda cuando sea posible.

¿Los hooks ralentizan mucho la sesión?

Depende del comando. Un linter o un subset de tests unitarios añade segundos y compensa. Lanzar la suite completa en cada commit rompe el ritmo: usa CI para esa parte.

Cierre

Hemos visto cómo cinco patrones de Gemini CLI (contexto comprimido, MCP disciplinado, hooks de shell, perfiles por tarea y verificación con segundo agente) encajan en el día a día de Claude Code sin cambiar de herramienta. La clave está en tratar el CLI como una superficie operativa, no como un chat con autocompletado.

¿Has copiado algún patrón entre agentes CLI que te haya ahorrado tiempo? Cuéntamelo en Twitter @sergiomarquezp_. En el próximo post toca llevar esta idea un paso más allá: cómo orquestar dos agentes CLI distintos en el mismo repo sin que se pisen los cambios.