Category: AI

  • GPT-5.6 vía API: guía práctica para developers

    GPT-5.6 vía API: guía práctica para developers

    Actualizas el string del modelo en tu código. gpt-5.5 pasa a gpt-5.6. Compilas, despliegas, todo responde igual… hasta que llega la factura de OpenAI y el costo por output es seis veces más alto que la semana pasada.

    No rompiste nada. Elegiste mal el modelo.

    GPT-5.6 no es un modelo — es una familia de tres, con nombres que no explican nada hasta que entiendes el sistema detrás. Si vienes de GPT-5.5 o evalúas moverte desde Claude, migrar sin leer la letra pequeña te puede salir caro. Literalmente.

    Esta es la guía que me hubiera gustado tener el día del lanzamiento: qué es cada variante, cómo llamarlas desde la API con TypeScript, qué cambia con Programmatic Tool Calling, y si vale la pena tocar tu stack si ya construyes con Claude Code.

    Qué es realmente GPT-5.6 (y por qué el nombre importa)

    OpenAI cambió el sistema de versionado con este lanzamiento. El número —5.6— identifica la generación. El nombre —Sol, Terra o Luna— identifica el nivel de capacidad, y cada nivel puede avanzar a su propio ritmo sin esperar un salto de versión completo.

    Tres variantes, disponibles desde el 9 de julio de 2026 en ChatGPT, Codex y la API:

    • Sol — el modelo insignia. Máxima capacidad de razonamiento.
    • Terra — el punto medio. Buen rendimiento a mejor precio.
    • Luna — el económico. Para volumen alto y tareas simples.

    Los tres comparten ventana de contexto: 1.05M tokens de entrada, 128K tokens de salida como máximo. La diferencia no está en cuánto texto aguantan — está en cuánto "piensan" antes de responder.

    Cómo llamar a GPT-5.6 desde la API

    Cada variante tiene su propio slug: gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna. Si usas el alias gpt-5.6 a secas, apunta a Sol por defecto.

    import OpenAI from "openai";
    
    const client = new OpenAI();
    
    const response = await client.responses.create({
      model: "gpt-5.6-terra",
      reasoning: { effort: "medium" },
      input: "Resume los cambios de este PR en 3 bullets técnicos.",
    });
    
    console.log(response.output_text);
    

    Nota el endpoint: responses.create, no chat.completions.create. GPT-5.6 usa la Responses API para razonamiento y tool-calling. Chat Completions sigue funcionando, pero no tiene acceso a las funciones nuevas de esta generación.

    El parámetro que de verdad mueve la aguja del costo es reasoning.effort. Acepta none, low, medium, high, xhigh y max, con medium por defecto. Si vienes de GPT-5.5, la recomendación de OpenAI es probar un nivel por debajo del que ya usabas. GPT-5.6 suele mantener la calidad con menos tokens de razonamiento, y eso es directamente menos costo por request.

    Hay un segundo parámetro, reasoning.mode, que acepta "pro" para forzar que el modelo trabaje más antes de devolver una única respuesta final. Resérvalo para tareas donde una respuesta mediocre te cuesta más que los tokens extra. Piensa en debugging de un incidente en producción, no en un endpoint de autocompletado.

    Programmatic Tool Calling: la función que cambia cómo diseñas agentes

    Esto es lo más relevante si ya construyes agentes con function calling. Antes, cada llamada a una tool implicaba un round-trip completo: el modelo pide la tool, tú la ejecutas, le devuelves el resultado, el modelo decide el siguiente paso. En un workflow con cinco o seis tools, eso son cinco o seis idas y vueltas completas al modelo.

    Programmatic Tool Calling elimina la mayoría de esos round-trips.

    Con Programmatic Tool Calling, GPT-5.6 escribe JavaScript que se ejecuta en un sandbox V8 aislado —sin acceso a red— y coordina varias llamadas a tools dentro de un mismo turno:

    // prStatusSchema y coverageSchema son schemas de Zod definidos aparte, omitidos aquí por brevedad
    const response = await client.responses.create({
      model: "gpt-5.6-sol",
      tools: [
        { type: "function", name: "get_pr_status", parameters: prStatusSchema },
        { type: "function", name: "get_test_coverage", parameters: coverageSchema },
      ],
      input: "Revisa el PR #482 y dime si está listo para mergear.",
    });
    

    Internamente, el modelo puede generar algo como esto y ejecutarlo sin volver a consultarte:

    const [status, coverage] = await Promise.all([
      tools.get_pr_status({ pr: 482 }),
      tools.get_test_coverage({ pr: 482 }),
    ]);
    

    Sin round-trips intermedios. OpenAI reporta reducciones de consumo de tokens de entre 38% y 63.5% en workflows de tools con clientes tempranos, según la documentación oficial de Programmatic Tool Calling. Si tu agente encadena varias tools de forma predecible —no necesitas el juicio del modelo entre cada paso— esta es la razón concreta para migrar a la Responses API si aún no lo has hecho.

    Ojo: esta función solo existe en la Responses API. Chat Completions no la soporta.

    Valida la salida con Zod, no confíes en el string

    Cuando le pides a GPT-5.6 —o a cualquier LLM— que devuelva JSON, vas a recibir respuestas que casi cumplen tu schema. Ese "casi" es el problema en producción.

    import { z } from "zod";
    
    const AnalisisDiffSchema = z.object({
      resumen: z.string(),
      cambiosBreaking: z.boolean(),
      archivosAfectados: z.array(z.string()),
    });
    
    const response = await client.responses.create({
      model: "gpt-5.6-terra",
      input: `Analiza este diff y responde en JSON: ${diff}`,
    });
    
    const analisis = AnalisisDiffSchema.parse(JSON.parse(response.output_text));
    

    Si el modelo devuelve un campo de más, uno de menos, o un tipo equivocado, parse lanza el error ahí mismo — no seis pasos después, cuando ya rompiste el pipeline de otro sistema. Es exactamente el patrón que trabajo en el curso de Zod para TypeScript: la validación no es opcional cuando la fuente de tus datos es un modelo probabilístico.

    Precios: Sol, Terra, Luna, y dónde entra Claude

    Modelo Input Output Contexto
    GPT-5.6 Sol $5 $30 1.05M / 128K salida
    GPT-5.6 Terra $2.50 $15 1.05M / 128K salida
    GPT-5.6 Luna $1 $6 1.05M / 128K salida
    Claude Sonnet 5 (hasta 31 ago 2026) $2 $10 1M / 128K salida
    Claude Sonnet 5 (desde 1 sep 2026) $3 $15 1M / 128K salida

    Con estos números, Terra es el punto de comparación real contra Claude Sonnet 5 — ambos apuntan al mismo caso de uso: producción, buen razonamiento, sin pagar precio de flagship. Sol solo se justifica cuando el problema es genuinamente difícil: razonamiento largo, agentes con muchos pasos, código complejo donde una respuesta mediocre cuesta más en debugging que en tokens.

    Una advertencia sobre comparar precios "por token" entre proveedores: no son manzanas con manzanas. Claude Sonnet 5 estrenó un tokenizer nuevo que genera hasta 30% más tokens para el mismo texto que su versión anterior, según la documentación oficial de Claude. El precio por millón de tokens no te dice el costo real de tu prompt — para eso necesitas correr tus prompts reales contra ambos modelos y medir.

    Cuándo quedarte en Claude Code y cuándo meter GPT-5.6 en tu stack

    Si ya tienes armado tu stack de IA agéntica alrededor de Claude Code, no hay ninguna urgencia de migrar todo. El ecosistema de agentes, skills y MCP que ya tienes montado no se traslada gratis a otro proveedor — cambiar de modelo no es cambiar un string, es revalidar todo el comportamiento agéntico que dependía de ese modelo específico.

    Donde sí tiene sentido meter GPT-5.6 en tu stack:

    • Tareas de alto volumen y baja complejidad. Usa Luna. Es una fracción del costo de Sol o de Claude Sonnet 5 para clasificación, extracción o resúmenes cortos.
    • Workflows con muchas tool calls predecibles. Programmatic Tool Calling puede recortar tu factura de forma directa, sin tocar la lógica de negocio.
    • Comparar output real en tu caso de uso. Nada reemplaza correr el mismo prompt contra Terra y contra Claude Sonnet 5 con tus datos reales, no con benchmarks genéricos.

    Este tipo de decisión —qué modelo, para qué tarea, con qué presupuesto— es exactamente el criterio que trabajamos en el curso Construye con IA: no se trata de casarte con un proveedor, se trata de construir producto sin quemar presupuesto en la elección equivocada.

    Qué hacer hoy

    Sin escribir una línea de producto nuevo, puedes:

    1. Correr tu endpoint más caro contra gpt-5.6-terra con reasoning.effort: "low" y comparar costo y calidad contra tu modelo actual.
    2. Si tu agente encadena tres o más tools por turno, prueba Programmatic Tool Calling en un flujo de staging y mide la reducción real de tokens.
    3. Añade un schema de Zod a cualquier endpoint que hoy confíe en el JSON crudo de un LLM.

    Ninguno de estos tres pasos te compromete a nada. Son experimentos de una tarde que te dan datos reales en lugar de benchmarks de marketing.

    Si quieres ver estos patrones aplicados en proyectos completos —no solo snippets sueltos— en Dominicode Labs están el código y las decisiones de arquitectura detrás de cada integración.

    Preguntas frecuentes

    ¿Qué significa que GPT-5.6 tenga tres variantes (Sol, Terra, Luna)?

    OpenAI separó el número de versión del nivel de capacidad. El 5.6 es la generación; Sol, Terra y Luna son niveles de capacidad que pueden evolucionar en su propio calendario, sin esperar a un salto de versión completo.

    ¿Qué variante de GPT-5.6 debo usar por defecto en producción?

    Depende del caso de uso. Terra es el punto de equilibrio para la mayoría de aplicaciones de producción. Sol solo se justifica en tareas de razonamiento largo o agentes con muchos pasos. Luna sirve para volumen alto y tareas simples, donde el costo por token importa más que el techo de capacidad.

    ¿GPT-5.6 es más barato o más caro que Claude Sonnet 5?

    Depende de la variante. Terra ($2.50 input / $15 output por millón de tokens) queda cerca del precio estándar de Claude Sonnet 5 ($3 / $15 desde el 1 de septiembre de 2026). Sol es notablemente más caro. Luna es la opción más económica de las dos familias. Compara con tus prompts reales, no solo con la tabla de precios — los tokenizers no son iguales entre proveedores.

    ¿Necesito reescribir mi código si vengo de GPT-5.5?

    En parte. El endpoint de la Responses API se mantiene, pero OpenAI recomienda tratar la migración como un ajuste de reasoning.effort, no solo un cambio de string en el nombre del modelo. Probar un nivel de esfuerzo por debajo del que usabas suele mantener la calidad con menos costo.

    ¿Programmatic Tool Calling funciona con Chat Completions?

    No. Es una función exclusiva de la Responses API. Si tu integración sigue en Chat Completions, no tienes acceso a esta función ni a otras capacidades nuevas de la generación GPT-5.6.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Guía: Cómo desplegar Hermes Agent en Railway con Git-Ops

    Guía: Cómo desplegar Hermes Agent en Railway con Git-Ops

    Configurar y administrar un servidor VPS no es para todo el mundo. A muchos desarrolladores les encanta la idea de tener un agente autónomo de IA corriendo las 24 horas del día, pero les horroriza la idea de tener que conectarse por SSH, gestionar firewalls, renovar certificados de seguridad o actualizar dependencias de Linux.

    Tienen toda la razón. Si tu foco es construir el comportamiento de tu agente, tu tiempo no debería perderse gestionando sistemas operativos en consolas oscuras.

    Para los desarrolladores que quieren un despliegue profesional sin fricciones, la solución moderna se llama Railway.

    Hoy te quiero enseñar paso a paso cómo desplegar Hermes Agent en Railway mediante Git-Ops (despliegue automático al hacer push en GitHub) y cómo configurar volúmenes persistentes para que tu agente no pierda su memoria. Como vimos en nuestra guía de despliegue de Hermes Agent en un VPS con Docker Compose, las arquitecturas persistentes son clave para evitar la amnesia agéntica, pero Railway nos permite implementarlo con un solo clic.


    Las ventajas de Railway para la Era Agéntica

    Railway es una plataforma de nube (PaaS) que elimina la complejidad de la infraestructura. Para proyectos agénticos con frameworks como Hermes, aporta ventajas críticas:

    1. Git-Ops Nativo: Cada vez que haces git push a tu rama principal en GitHub, Railway compila la nueva versión, realiza los tests y redespliega de forma automática.
    2. Volúmenes Persistentes Sencillos: Permite montar un disco duro virtual en caliente con un solo clic, permitiendo que tu base de datos SQLite y tus nuevas Skills sobrevivan a los despliegues.
    3. Escalabilidad de recursos: Puedes ajustar la CPU y la RAM del contenedor de tu agente desde un panel visual intuitivo sin reiniciar servidores.

    Paso 1: Preparar tu Repositorio en GitHub

    Ollama y Hermes Agent se pueden empaquetar de forma muy sencilla en un contenedor Docker. Para desplegar en Railway, necesitas un repositorio de GitHub (puede ser privado) con tres archivos clave:

    1. El archivo Dockerfile

    Este archivo indica a Railway cómo compilar la imagen de tu agente:

    # Usar la imagen oficial de Hermes Agent
    FROM nousresearch/hermes-agent:latest
    
    # Directorio de trabajo
    WORKDIR /app
    
    # Copiar archivos de configuración y la carpeta de habilidades
    COPY hermes.config.json ./
    COPY skills/ ./skills/
    
    # Variables de entorno por defecto
    ENV NODE_ENV=production
    
    # Ejecutar el agente en segundo plano usando el archivo de configuración
    CMD ["hermes", "start", "--config", "hermes.config.json"]
    

    2. El archivo hermes.config.json

    Aquí declaras el comportamiento de tu agente y los canales activos (ej. Telegram):

    {
      "agent": {
        "name": "RailwayGuard",
        "persistence": {
          "provider": "sqlite",
          "path": "/app/data/memory.db"
        }
      }
    }
    

    (Nota que la ruta de la base de datos apunta a /app/data, que es donde montaremos el disco duro persistente).


    Paso 2: Configurar las Variables de Entorno en Railway

    Una vez que conectas tu repositorio de GitHub a tu proyecto en el panel de Railway, la plataforma detectará el Dockerfile e iniciará la compilación. Antes de que termine, debes ir a la pestaña Variables de tu servicio y añadir tus credenciales y tokens privados:

    • OPENROUTER_API_KEY: Tu clave para acceder a los LLMs (como Claude 3.5 Sonnet).
    • TELEGRAM_BOT_TOKEN: El token de tu bot de control.
    • TELEGRAM_ADMIN_CHAT_ID: Tu identificador de chat para evitar que extraños den órdenes a tu agente.
    • NOTION_API_KEY: Si usas Notion como CRM o base de datos externa vía MCP.

    Paso 3: Configurar el Volumen Persistente (Crucial)

    Por defecto, los contenedores de Railway son efímeros. Si haces un cambio en tu código y realizas un nuevo deploy, Railway destruirá el contenedor viejo y levantará uno nuevo. Si no configuras persistencia, tu agente olvidará todas las conversaciones pasadas y las habilidades que haya auto-aprendido.

    Para evitar la amnesia agéntica:

    1. En el panel visual de tu servicio en Railway, haz clic en Settings.
    2. Desplázate hasta la sección Volumes y haz clic en Add Volume.
    3. Configura el Mount Path (ruta de montaje) exactamente como: /app/data.
    4. Guarda los cambios.

    A partir de este momento, Railway mantendrá un disco de almacenamiento persistente montado en esa carpeta. Aunque realices 50 despliegues al día por Git-Ops, la base de datos de memoria del agente quedará intacta.

    Este flujo de Git-Ops y persistencia en la nube es la base de las automatizaciones avanzadas que implementamos en el curso de Construye con IA y que exploramos a nivel de producción en el nuevo curso de Agentes IA Autónomos en Producción con Hermes Agent.


    Conclusión: La nube sin dolores de cabeza

    El paradigma de Git-Ops te permite centrarte en mejorar las instrucciones, prompts y scripts de tu agente de IA localmente. Con hacer un push en tu rama de Git, Railway se encarga de compilar, asegurar la persistencia en disco y poner tu sistema agéntico a operar las 24 horas del día sin necesidad de gestionar servidores manualmente.

    Si quieres debatir con otros desarrolladores senior sobre cómo optimizar tus despliegues en la nube y compartir arquitecturas de automatización con IA, te espero en Dominicode Labs.


    Preguntas Frecuentes (FAQ)

    ¿Cómo gestiona Railway las actualizaciones de Skills autogeneradas?

    Si tu agente genera una nueva habilidad a través del Self-Improving Loop, este script se guardará en la carpeta local /skills. Para evitar perderlas al redesplegar, se recomienda mapear la carpeta /app/skills a otro volumen persistente de Railway o configurar un script de backup que sincronice estas habilidades con tu repositorio de forma segura.

    ¿Railway tiene algún costo para este tipo de despliegues?

    Railway ofrece un modelo de pago por consumo bastante económico (a partir de una tarifa plana básica de $5 USD al mes que incluye créditos de cómputo). Dado que la inferencia de lenguaje se hace a través de APIs externas, el consumo de CPU y RAM de Hermes Agent en Railway es mínimo y se mantendrá dentro de los límites más bajos.

    ¿Cómo puedo verificar que el volumen persistente funciona?

    Puedes realizar una prueba conversacional con tu bot en Telegram, pedirle que recuerde un dato específico, realizar un redespliegue de tu servicio desde el panel de Railway y volver a preguntarle. Si el agente recuerda el dato previo, significa que tu base de datos SQLite se está leyendo correctamente desde el volumen montado en /app/data.

    ¿Se pueden usar sandboxes de Docker efímeros en Railway?

    Sí, pero requiere configurar soporte para Docker-in-Docker (DinD) en las variables del servicio de Railway para permitir que el agente levante contenedores hijos de diagnóstico de manera aislada y segura, tal como se detalla en el módulo avanzado de despliegue del curso.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Self-Improving Loop: Enseña habilidades a tu agente de IA

    Self-Improving Loop: Enseña habilidades a tu agente de IA

    Estaba cansado de tener que crear APIs e integraciones cada vez que quería que mi agente de IA resolviera un nuevo problema técnico en mi servidor. Cada vez que aparecía un error inédito en los logs, me tocaba sentarme a abrir el código, programar un script a medida en Python, testearlo localmente, hacer commit y volver a desplegar.

    El proceso era lento, repetitivo y manual. Es decir, todo lo contrario a lo que se supone que debe ser un sistema agéntico inteligente.

    Entonces decidí implementar el bucle de auto-aprendizaje en producción.

    La primera vez que falló una conexión a la base de datos, el agente me contactó por Telegram preguntando cómo repararlo. Le respondí con un comando simple en lenguaje natural. El agente levantó su entorno, ejecutó la orden, validó el resultado y escribió un script en su base de datos. Me respondió: "Entendido. Skill guardada para la próxima vez".

    Nunca más me volvió a molestar por esa caída. Hoy te quiero explicar en detalle cómo funciona el Self-Improving Loop en Hermes Agent y cómo puedes usarlo para que tus agentes programen sus propias herramientas.


    La anatomía del Bucle de Auto-Mejora

    En los frameworks tradicionales como LangChain o CrewAI, las herramientas (Tools) que tiene un agente son estáticas. Si no programaste una herramienta para leer archivos de Excel, el agente jamás podrá hacerlo.

    El Self-Improving Loop en Hermes Agent rompe este límite. Si el agente se encuentra con un problema para el cual no tiene herramientas asociadas, entra en un estado de espera y abre un canal conversacional con el desarrollador o administrador (por ejemplo, a través de Telegram o Slack).

    Este proceso sigue tres fases clave:

    1. La Solicitud de Instrucción: El agente detecta un fallo y te envía el contexto y los logs de error preguntando cómo proceder.
    2. La Validación en Sandbox: Cuando le indicas la solución (ej: "corre este comando para liberar el puerto"), el agente ejecuta la instrucción en su contenedor de Docker seguro para verificar que el código no da errores.
    3. La Auto-Redacción de la Skill: Si la validación es exitosa, el agente utiliza su modelo de lenguaje interno para empaquetar esa solución en una función reutilizable (una Skill), la guarda en su disco y la registra para futuros usos.

    Cómo se escribe y registra una Skill en caliente

    Una Skill en Hermes Agent no es un bloque de texto plano. Es un archivo de código estructurado y documentado (usualmente en Python o Node.js) que se guarda directamente en el volumen de almacenamiento persistente del agente.

    Por ejemplo, si le enseñas a tu agente a resetear un puerto bloqueado en Linux, el agente escribirá automáticamente un script en su carpeta de habilidades:

    # skills/reset_port.py
    import subprocess
    
    def reset_port(port_number):
        """
        Habilidad autogenerada para resetear puertos bloqueados.
        Llamada automáticamente cuando se detecta un puerto en uso.
        """
        try:
            cmd = f"fuser -k {port_number}/tcp"
            subprocess.run(cmd, shell=True, check=True)
            return f"Puerto {port_number} liberado con éxito."
        except Exception as e:
            return f"Error liberando el puerto: {str(e)}"
    

    La próxima vez que ocurra la caída, el agente no consultará al administrador ni le enviará una alerta. Escaneará sus Skills locales, identificará que reset_port es la herramienta idónea mediante búsqueda vectorial semántica y resolverá el incidente de forma 100% autónoma.

    Este tipo de flujos reactivos autogenerados son los que marcan la diferencia entre un script básico y la verdadera ingeniería agéntica de producción que enseñamos en el curso de Construye con IA.


    La importancia de la persistencia de datos

    Para que este bucle funcione en producción, tu contenedor del agente no puede ser efímero. Si destruyes el contenedor al actualizar tu servidor, el agente perderá todas las Skills que ha auto-programado a lo largo del tiempo.

    Por eso es vital mapear un volumen físico del servidor host a la carpeta /app/skills del agente, tal como detallamos en nuestro post sobre cómo configurar Docker Sandboxing en Hermes Agent. De esta forma, las nuevas capacidades de tu agente quedan blindadas contra reinicios y despliegues Git-Ops.


    Enseña a tu agente a trabajar por ti

    El objetivo final de la IA no es que pases todo el día chateando con ella en una ventana web. El objetivo es delegar tareas de largo recorrido para que el sistema se auto-corrija y aprenda mientras tú te enfocas en diseñar mejores especificaciones.

    En el nuevo [curso de Agentes IA Autónomos en Producción con Hermes Agent]([ENLACE PENDIENTE]) dedicamos una sección práctica completa a construir este bucle de auto-aprendizaje, permitiendo que tu agente DevOps de guardia amplíe sus herramientas de forma interactiva desde Telegram.

    Si quieres debatir sobre arquitectura de software y el futuro del desarrollo agéntico con otros ingenieros senior, te espero en Dominicode Labs.


    Preguntas Frecuentes (FAQ)

    ¿Qué es el Self-Improving Loop (Bucle de Auto-Mejora)?

    Es la capacidad nativa de Hermes Agent para generar, testear y almacenar nuevas herramientas de ejecución de forma dinámica en tiempo de ejecución. Permite que el agente pase de ser un sistema estático a un agente adaptativo que aprende de su experiencia y de la retroalimentación del programador.

    ¿Cómo aprende el agente a usar una nueva Skill?

    Cuando el agente guarda una nueva Skill, genera una descripción semántica de su funcionamiento. Antes de realizar cualquier acción posterior, el agente realiza una búsqueda vectorial para ver si el problema coincide con la descripción de alguna de sus Skills almacenadas, utilizándola si es pertinente.

    ¿Dónde se guardan las habilidades autogeneradas?

    Se guardan como archivos de script independientes en el directorio local /skills del agente. En producción, esta carpeta debe estar mapeada a un volumen persistente de Docker para asegurar que no se pierdan al reiniciar o actualizar el contenedor del agente.

    ¿Es seguro dejar que el agente escriba su propio código?

    Es seguro siempre que se cumplan dos reglas críticas: primero, que el código se ejecute y valide en un sandbox aislado (Docker Container); segundo, que el agente exija aprobación en dos pasos del administrador antes de aplicar cualquier Skill correctiva que involucre escrituras o borrados en el servidor real.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Cómo correr LLMs locales en 2026: Guía de hardware y modelos

    Cómo correr LLMs locales en 2026: Guía de hardware y modelos

    El mes pasado vi la factura de API de OpenAI de un desarrollador independiente que estaba probando un agente de traducción automática de bases de datos. Había consumido $842 USD en un solo fin de semana debido a un bucle infinito de prompts que devoró el contexto de su modelo repetidamente.

    Casi le da algo.

    La experimentación con agentes de IA es el futuro, pero depender ciegamente de APIs en la nube puede ser una ruina financiera para desarrolladores independientes o empresas con políticas estrictas de privacidad.

    Hoy te quiero explicar cómo configurar tu entorno para correr LLMs locales en 2026, analizando qué hardware necesitas realmente y qué modelos de código abierto superan a las opciones comerciales para desarrollo local.


    Por qué el desarrollo local es el estándar en 2026

    Hasta hace poco, correr un modelo en tu propio ordenador era una experiencia frustrante: los modelos pequeños de 7B parámetros eran lentos, "alucinaban" demasiado y carecían de capacidades de razonamiento para escribir código complejo.

    En 2026, la situación ha cambiado radicalmente por tres factores:

    1. Eficiencia en la cuantización: Gracias a formatos avanzados de compresión (como GGUF y EXL2), un modelo de 8B o 14B parámetros mantiene el 98% de su precisión consumiendo la mitad de VRAM.
    2. Capacidad de razonamiento nativa: Modelos como Llama 3.3, Qwen 2.5 Coder y la serie DeepSeek R1 en local ofrecen razonamiento avanzado sin salir de tu máquina.
    3. Privacidad absoluta: Tus datos de código, logs de clientes y bases de datos nunca viajan por internet.

    Correr modelos locales es la mejor forma de testear tus agentes y automatizaciones antes de desplegarlos a producción en la nube.


    El Hardware que necesitas (VRAM es el único rey)

    El error más común al planificar un entorno local de IA es invertir en procesadores rápidos (CPU) o grandes cantidades de memoria RAM convencional. Para la IA, la velocidad del procesamiento y la latencia dependen de la VRAM (Memoria de Vídeo) de tu tarjeta gráfica.

    Aquí tienes la matriz de hardware recomendada según tu presupuesto y objetivos en 2026:

    Nivel Hardware Mínimo Capacidad de Modelos
    Básico (Estudiante) GPU de 8GB VRAM (RTX 4060) o Mac M-Series (16GB RAM) Llama 3.2 3B / Qwen 2.5 Coder 7B (Cuantizados)
    Sweet Spot (Developer) GPU de 16GB VRAM (RTX 4080 / 4070Ti) o Mac M-Series (36GB RAM) Llama 3.1 8B / Qwen 2.5 Coder 14B (Precisión Completa)
    Avanzado (Enterprise) 2x GPU de 24GB VRAM (RTX 3090/4090) o Mac Studio (64GB+ RAM) Llama 3.3 70B / DeepSeek R1 32B (Razonamiento Completo)

    Si eres usuario de Mac, la memoria unificada de Apple Silicon funciona como VRAM. Un Mac Mini o Macbook Pro con 36GB o 64GB de RAM unificada es una de las soluciones más eficientes y silenciosas para correr agentes locales.


    Los mejores modelos locales para Developers en 2026

    Si tu objetivo principal es escribir código, configurar bases de datos o crear agentes DevOps, no uses modelos genéricos. Estos son los reyes del código abierto en 2026:

    • Qwen 2.5 Coder (7B y 14B): Es el rey indiscutible para autocompletado y edición en IDEs como Cursor o VS Code. Supera a muchos modelos propietarios en sintaxis de TypeScript, Python y Rust.
    • Llama 3.1 (8B) / Llama 3.3 (70B): La opción de Meta es la más estable para agentes conversacionales que requieren memoria semántica persistente o integrarse con herramientas externas.
    • DeepSeek R1 (Versiones destiladas de 8B o 14B): Excelente para resolución de bugs complejos y optimización de algoritmos que requieren pasos de pensamiento lógico antes de emitir una respuesta.

    Setup de Arranque Rápido con Ollama

    La forma más sencilla de empezar hoy es utilizar Ollama, una herramienta que gestiona los modelos locales en segundo plano y expone una API compatible con OpenAI para que puedas conectarla a cualquier aplicación.

    1. Descarga Ollama de su sitio oficial.
    2. Ejecuta en tu terminal el modelo deseado:
      ollama run qwen2.5-coder:7b
      
    3. Conecta tus agentes o herramientas de desarrollo apuntando la API Base a: http://localhost:11434/v1.

    Este es exactamente el flujo de base local que enseñamos a configurar y optimizar en nuestro curso de Construye con IA para evitar costes recurrentes de API durante el desarrollo de productos.


    Conclusión: Controla tus costes de desarrollo

    Depender exclusivamente de la nube no solo te hace vulnerable a caídas de red y cambios de precios de API, sino que limita tu velocidad de experimentación. Al aprender a correr LLMs locales, desbloqueas pruebas infinitas y seguras, las cuales son ideales para testear el bucle agéntico o agentic loop sin costes de API.

    Si quieres debatir sobre configuraciones de hardware personalizadas, benchmarks de modelos en local y cómo conectar estos LLMs a tus pipelines de producción, te espero en Dominicode Labs.


    Preguntas Frecuentes (FAQ)

    ¿Se pueden correr LLMs locales en 2026 sin tarjeta gráfica (GPU)?

    Sí, herramientas como Ollama y Llama.cpp admiten ejecución en CPU utilizando la memoria RAM del sistema. Sin embargo, la velocidad de generación (tokens por segundo) será extremadamente lenta en comparación con una GPU, lo que los hace poco prácticos para flujos de desarrollo ágiles.

    ¿Qué es la cuantización de un modelo de IA?

    Es un proceso de compresión matemática que reduce la precisión de los pesos del modelo (por ejemplo, de 16 bits a 4 u 8 bits). Esto reduce drásticamente el uso de VRAM y memoria, permitiendo correr modelos grandes en tarjetas gráficas de gama media con una pérdida de precisión casi imperceptible.

    ¿Ollama es compatible con herramientas como Cursor o VS Code?

    Sí, Ollama expone un servidor local compatible con la especificación de API de OpenAI. Puedes configurar tu editor de código o framework de agentes favorito para que use la URL http://localhost:11434 como proveedor personalizado y consuma tus modelos locales de forma directa.

    ¿Qué modelo local es mejor para desarrollo de software en 2026?

    Para autocompletado y redacción de código rápido, Qwen 2.5 Coder (en sus variantes de 7B o 14B) ofrece el mejor rendimiento en relación al consumo de recursos. Para tareas complejas de depuración o lógica pesada, las variantes cuantizadas de DeepSeek R1 son la opción recomendada.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Hermes Agent: Cómo capturar y calificar leads de forma autónoma

    Hermes Agent: Cómo capturar y calificar leads de forma autónoma

    Hace unos meses, un domingo por la tarde, me di cuenta de que mi bot de Telegram había calificado a tres desarrolladores interesados en entrar a Dominicode Labs. No solo respondió a sus dudas técnicas sobre el stack de la comunidad, sino que guardó sus datos en mi base de datos de Notion y me envió un resumen limpio por correo a las 8:00 PM.

    Yo estaba cenando con mi familia. El bot hizo el 80% del trabajo de captación de forma autónoma.

    La mayoría de los marketers y creadores de contenido siguen perdiendo el tiempo configurando integraciones complejas en Zapier que se rompen constantemente, o usando chatbots interactivos de árbol de decisión que aburren a cualquiera en dos segundos.

    Hoy te quiero explicar cómo utilizar Hermes Agent en marketing para dejar atrás las herramientas rígidas y poner a funcionar agentes de IA que capturan, califican e informan sobre prospectos de forma autónoma las 24 horas del día. En mi post anterior te hablé de qué es Hermes Agent y cómo funciona su bucle de auto-aprendizaje, pero hoy nos enfocaremos puramente en negocio.


    El problema de los “chatbots de marketing” tradicionales

    Los chatbots tradicionales de marketing funcionan con flujos rígidos: “Si el usuario pulsa A, muestra B”. Son frustrantes para el usuario porque no toleran variaciones y se rompen en cuanto alguien hace una pregunta fuera del guión.

    Por otro lado, los frameworks de IA tradicionales (como conectar simplemente la API de OpenAI a un webhook) no tienen memoria persistente. Si el usuario vuelve al día siguiente, el sistema no recuerda lo que hablaron, obligándolo a empezar de cero.

    Utilizar Hermes Agent en marketing cambia las reglas del juego gracias a dos pilares fundamentales: memoria multi-usuario persistente y protocolo MCP (Model Context Protocol).

    Calificación conversacional sin formularios

    Nadie quiere rellenar un formulario de 10 campos para ver si tu producto encaja con lo que busca. Pero a todo el mundo le gusta hablar con un sistema inteligente que responda al instante.

    Con Hermes Agent, puedes programar al agente para que mantenga una conversación fluida sobre las necesidades del usuario. A medida que chatea, el agente extrae información de valor de forma natural:

    • El stack tecnológico del prospecto
    • El tamaño de su proyecto o presupuesto
    • Su principal problema actual

    En lugar de forzar un interrogatorio, el agente califica al lead mientras responde sus dudas reales sobre tu plataforma o servicio.

    Sincronización en caliente vía MCP (Model Context Protocol)

    Una vez que el agente ha recopilado el perfil del usuario, no necesitas complicados flujos de automatización externos. A través de la integración nativa del estándar abierto Model Context Protocol (MCP) de Hermes Agent con Notion, el agente escribe directamente en tu CRM o base de datos.

    Aquí tienes una muestra de cómo se configura el flujo de almacenamiento en Notion dentro del entorno de Hermes:

    {
      "tools": [
        {
          "name": "notion-mcp-server",
          "command": "npx -y @modelcontextprotocol/server-notion",
          "env": {
            "NOTION_API_KEY": "tu_api_key",
            "NOTION_DATABASE_ID": "tu_db_id"
          }
        }
      ]
    }
    

    El agente decide de forma autónoma cuándo ha recogido suficientes datos del prospecto para activar la herramienta de Notion y registrar la fila con los datos limpios y estructurados.


    El Bucle de Venta y Calificación Autónoma

    Imagina este flujo operando en tu canal de soporte o comunidad de Telegram:

    1. Interacción Inicial: Un usuario pregunta en Telegram si tu curso cubre despliegues en Railway.
    2. Consulta a la Base de Conocimientos: El agente lee tu catálogo de productos y le explica qué módulos cubren Railway.
    3. Calificación: El agente le pregunta qué tipo de aplicaciones quiere desplegar.
    4. Registro: El usuario responde y el agente registra el lead en Notion como “Interés en DevOps/Railway”.
    5. Briefing diario (Cron): A las 9:00 PM, una tarea programada interna de Hermes te envía un correo a ti (el administrador) con la lista de leads cualificados listos para el seguimiento comercial.

    Esta arquitectura de agentes de marketing no solo ahorra horas de gestión manual, sino que mejora drásticamente la tasa de conversión al dar respuestas de alto nivel técnico al instante. Esta es la potencia que enseñamos a construir en el curso de Construye con IA, aplicando IA a la resolución de problemas de negocio reales.


    Da el salto a la automatización agéntica

    Dejar que una IA interactúe con tus clientes potenciales puede dar cierto vértigo al principio. Por eso Hermes Agent incluye sandboxes locales y la opción de configurar alertas interactivas para que el agente te pida confirmación antes de enviar ciertos mensajes o realizar acciones críticas.

    En el próximo [curso de Agentes IA Autónomos en Producción con Hermes Agent] dedicamos una sección entera a construir este Operador Autónomo de Comunidad, conectándolo a Telegram y Notion paso a paso.

    Si quieres debatir con otros ingenieros de software sobre cómo implementar estos sistemas agénticos para capturar leads y escalar operaciones en tus propios proyectos, te espero en Dominicode Labs.


    Preguntas Frecuentes (FAQ)

    ¿Cómo ayuda Hermes Agent en marketing y ventas?

    A diferencia de los chatbots interactivos sencillos, Hermes Agent gestiona conversaciones completas con memoria a largo plazo. Puede responder dudas técnicas sobre tus productos, calificar a los prospectos haciendo preguntas contextuales y guardar automáticamente sus perfiles en herramientas como Notion sin necesidad de usar Zapier.

    ¿Qué ventajas tiene el uso de MCP (Model Context Protocol) en marketing?

    El protocolo MCP permite al agente conectarse directamente a bases de datos, repositorios de contenido o herramientas de mensajería usando un estándar seguro y unificado. Esto significa que tu agente de marketing puede consultar en tiempo real tus guías de producto o actualizar tu base de datos de leads de forma nativa.

    ¿Se puede configurar el agente para que trabaje en varios canales como Telegram y Discord?

    Sí. Al desacoplar la lógica del agente del canal de mensajería, Hermes Agent puede usar el mismo motor conversacional y base de conocimiento para atender usuarios en Telegram, Discord o mediante un chat embebido en tu web, manteniendo la consistencia de la información.

    ¿El agente puede enviar informes o briefings comerciales automáticamente?

    Sí, Hermes Agent cuenta con un planificador de tareas Cron integrado. Esto te permite programar al agente para que realice tareas offline, como recopilar todos los prospectos calificados del día y enviarte un resumen detallado por email o Slack a una hora fija todas las noches.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Hermes Agent: Por qué los chatbots ya no bastan en producción

    Hermes Agent: Por qué los chatbots ya no bastan en producción

    Hace unas semanas dejé corriendo un script para monitorear una base de datos en Railway. A las 3:00 AM la base de datos se cayó debido a un pico de memoria. El sistema clásico me habría enviado una alerta al móvil despertándome. Pero yo no quería una alerta a esa hora; quería que se solucionara.

    El problema con los chatbots tradicionales y los scripts de juguete es que son pasivos y no tienen memoria real a largo plazo ni capacidad de ejecución autónoma. Se quedan bloqueados esperando que un humano les diga qué hacer, o simplemente repiten el mismo error una y otra vez.

    Ahí es donde entra la verdadera IA agéntica y frameworks como Hermes Agent. Con un agente autónomo de larga duración (Long-Running Autonomous Agent) operando en un bucle agéntico o agentic loop, el sistema no solo detecta el fallo: levanta un sandbox, diagnostica el problema y, si es necesario, aprende cómo arreglarlo para la próxima vez.

    Hoy te quiero hablar en detalle de este framework de código abierto (desarrollado con la colaboración del equipo de Nous Research) que está cambiando las reglas del juego al permitir crear agentes que realmente operan de forma autónoma las 24 horas del día.


    ¿Qué hace diferente a Hermes Agent?

    Si has intentado crear agentes con frameworks como LangChain o CrewAI, te habrás dado cuenta de que están diseñados para responder preguntas en un bucle síncrono. Están muy bien para flujos sencillos, pero fallan en producción por tres motivos:

    1. Carecen de autonomía real de largo recorrido: No pueden correr en segundo plano esperando eventos o triggers temporales (Crons).
    2. Su memoria es efímera: Si se reinicia el servidor, el agente olvida todo lo que ha aprendido o discutido con los usuarios.
    3. No pueden aprender solos: No generan nuevas capacidades a partir de su experiencia.

    Hermes Agent soluciona esto de raíz mediante una arquitectura diseñada específicamente para ejecutarse en entornos como Docker, VPS o plataformas de nube como Railway.

    El Bucle de Auto-Mejora (Self-Improving Loop)

    La característica más potente de Hermes Agent es su capacidad de auto-mejora. En lugar de limitarse a usar las herramientas que el programador le define estáticamente, Hermes puede crear nuevas Skills (habilidades) dinámicamente.

    Imagina que tu agente DevOps de auto-sanación encuentra un error inédito en los logs de producción. Al no saber cómo solucionarlo, te envía un mensaje por Telegram: “Detectado error X en Railway. No tengo herramientas para solucionarlo. ¿Cómo procedo?”

    Tú le respondes con la solución o el comando a ejecutar. El agente ejecuta la orden dentro de un sandbox seguro de Docker para validar que funciona. Pero lo más importante: escribe un script (una nueva Skill), lo guarda en su base de datos y lo registra.

    La próxima vez que ocurra ese error exacto, el agente no te preguntará. Usará la Skill que él mismo generó y resolverá el problema de forma autónoma. Esta es exactamente la lógica que exploramos en profundidad en el curso de Construye con IA para pasar de simples prompts a automatizaciones reales.

    Memoria persistente multi-capa

    Un agente autónomo en producción necesita recordar quién eres, qué problemas ha resuelto y qué configuraciones ha cambiado en el servidor.

    Hermes implementa un sistema de almacenamiento persistente en disco (o volúmenes de Docker). Esto permite que, aunque el contenedor se reinicie o se actualice mediante Git-Ops en Railway, el agente no sufra de “amnesia”. Mantiene:

    • Memoria episódica: Registros de ejecuciones pasadas y sus resultados.
    • Memoria semántica: Una base de conocimiento vectorial que consulta antes de tomar decisiones complejas.
    • Memoria de conversación: El historial exacto con cada usuario, ideal para canales como Telegram o Discord.

    Cómo estructurar un Agente de Auto-Sanación

    Para que un agente opere de manera segura en tu infraestructura, nunca debes darle acceso directo al sistema operativo anfitrión. Hermes Agent utiliza Docker Sandboxes por defecto.

    Aquí tienes un flujo conceptual de cómo se define la configuración de un agente autónomo de diagnóstico con Hermes:

    {
      "agent": {
        "name": "DevOpsGuard",
        "model": "anthropic/claude-3-5-sonnet",
        "sandbox": {
          "provider": "docker",
          "image": "node:20-alpine",
          "volumes": ["/var/run/docker.sock:/var/run/docker.sock"]
        },
        "persistence": {
          "path": "./data/memory"
        }
      }
    }
    

    Al iniciarse, el agente arranca el contenedor Docker. Cada vez que necesite ejecutar un comando de diagnóstico (como un ping, un script de Node.js o una query a la base de datos), lo hará de forma aislada dentro de ese contenedor. Si el script falla o hace algo inesperado, tu servidor principal sigue estando 100% a salvo.


    El futuro es de los agentes de largo recorrido

    El desarrollo de software con IA ha dejado atrás los simples chats interactivos. Si quieres ir más allá de los juguetes y construir sistemas que operen, monitoricen y solucionen problemas de forma autónoma en Railway o en tu propio VPS, necesitas entender este cambio de paradigma.

    Pronto lanzaremos el nuevo [curso de Agentes IA Autónomos en Producción con Hermes Agent], donde construiremos paso a paso un operador de comunidad en Telegram conectado a Notion mediante MCP y un agente de guardia DevOps que se auto-sana.

    Si quieres empezar a aplicar estas arquitecturas agénticas avanzadas hoy mismo en tus proyectos y discutir estos patrones con otros developers senior, te espero en Dominicode Labs.


    Preguntas Frecuentes (FAQ)

    ¿Qué es Hermes Agent y quién lo desarrolla?

    Hermes Agent es un framework de código abierto desarrollado originalmente con la colaboración del equipo de Nous Research. Está diseñado específicamente para construir agentes de IA autónomos de largo recorrido (Long-Running Autonomous Agents) que poseen memoria persistente y la capacidad de adquirir nuevas habilidades.

    ¿Cómo funciona el Bucle de Auto-Mejora (Self-Improving Loop) en Hermes?

    Funciona combinando la interacción del agente con el entorno y la retroalimentación del desarrollador. Cuando el agente se enfrenta a una tarea para la cual no tiene una herramienta predefinida, puede recibir instrucciones en lenguaje natural, probar la solución en un entorno aislado, empaquetar esa solución en un script de código (Skill) y guardarlo en su almacenamiento persistente para futuras ocasiones.

    ¿Por qué se utiliza Docker Sandbox en la ejecución de agentes?

    Se utiliza por motivos de seguridad y control de entorno. Los agentes autónomos pueden generar y ejecutar código en tiempo real. Ejecutar este código dentro de un contenedor Docker aislado (sandbox) garantiza que cualquier fallo, script infinito o acción no deseada no afecte al servidor principal ni ponga en riesgo la infraestructura del sistema.

    ¿Es Hermes Agent adecuado para entornos de producción DevOps?

    Sí, gracias a su integración con APIs de infraestructura (como Railway o Kubernetes), su soporte nativo para volúmenes Docker persistentes y su programador de tareas Cron integrado. Esto lo hace ideal para tareas continuas como monitoreo de logs, auto-sanación de servicios caídos e informes diarios de estado.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Claude Managed Agents: cuándo delegarle el harness a Anthropic

    Claude Managed Agents: cuándo delegarle el harness a Anthropic

    Llevaba tres semanas construyendo lo mismo que ya había construido dos veces antes: mi propio harness para correr Claude Managed Agents — el nombre que Anthropic le da a un agente que opera solo, durante horas, sin que nadie lo esté mirando.

    Un agent loop que decide cuándo llamar a una tool y cuándo parar.

    Un sandbox donde ese agente puede correr comandos de shell sin tumbar mi máquina — ni la de un cliente.

    Una capa de persistencia para que la sesión sobreviva si el proceso se cae a mitad de una tarea de cuarenta minutos.

    Reintentos cuando una tool falla a medio camino. Un sistema de eventos para poder decirle "espera, cambia esto" sin que el agente pierda todo el contexto acumulado.

    Nada de eso es difícil por separado. Lo difícil es que todo tenga que funcionar junto, de forma confiable, mientras el agente corre solo durante horas y tú estás durmiendo.

    Ahí es exactamente donde entra Claude Managed Agents: la apuesta de Anthropic de que la mayoría de equipos no debería tener que resolver ese problema de infraestructura por su cuenta.


    Messages API vs Claude Managed Agents: dos formas distintas de construir

    Anthropic te da dos caminos para construir con Claude, y elegir mal el camino te cuesta semanas.

    El primero es la Messages API: prompting directo al modelo. Tú decides el system prompt, tú implementas el loop que decide qué tool llamar, tú montas el sandbox donde esa tool corre. Control total — y responsabilidad total sobre cada pieza.

    Tú resuelves, además, qué pasa cuando el proceso se reinicia a mitad de tarea. Nada de eso viene resuelto de fábrica.

    El segundo camino son los Claude Managed Agents: un harness pre-construido y configurable que corre en infraestructura gestionada por Anthropic.

    En vez de montar tú el agent loop, la ejecución de tools y el runtime, obtienes un entorno donde Claude puede leer archivos, correr comandos, navegar la web y ejecutar código de forma segura — sin operar tú ni una línea de esa infraestructura.

    Ya escribí sobre qué significa en la práctica construir tu propio harness de agentes: agent loop, tool execution, memoria, checkpoints. Todo lo que Managed Agents te ahorra construir desde cero.

    Los 4 conceptos que necesitas entender

    Managed Agents se organiza alrededor de cuatro piezas:

    • Agent — el modelo, el system prompt, las tools, los servidores MCP y las skills. Se define una sola vez y se referencia por ID en tantas sesiones como necesites.
    • Environment — dónde corren las sesiones: un sandbox en la nube gestionado por Anthropic, o un sandbox self-hosted en tu propia infraestructura.
    • Session — una instancia del agente corriendo dentro de un environment, ejecutando una tarea concreta y generando outputs.
    • Events — los mensajes que se intercambian entre tu aplicación y el agente: turnos de usuario, resultados de tools, actualizaciones de estado.

    El flujo, de principio a fin

    1. Creas un agente (modelo + system prompt + tools + MCP servers + skills). Se crea una vez y se reutiliza.
    2. Creas un environment: sandbox en la nube o self-hosted.
    3. Inicias una sesión que referencia ese agente y ese environment.
    4. Envías events y recibes respuestas en streaming vía server-sent events. Claude ejecuta tools de forma autónoma; el historial completo se persiste server-side y puedes recuperarlo entero cuando quieras.
    5. Puedes "steerear" — dirigir — o interrumpir al agente a mitad de ejecución simplemente enviando eventos adicionales.

    Conceptualmente, el flujo se ve algo así (pseudo-código, no la sintaxis exacta del SDK):

    // Flujo conceptual — no es sintaxis literal del SDK
    const agent = await client.agents.create({
      model: "claude-...",
      systemPrompt: "Eres un agente de investigación de incidentes...",
      tools: ["bash", "file_edit", "web_search"],
      mcpServers: [datadogMcp, githubMcp],
    });
    
    const environment = await client.environments.create({
      type: "cloud_sandbox", // o "self_hosted"
    });
    
    const session = await client.sessions.create({
      agentId: agent.id,
      environmentId: environment.id,
    });
    
    const stream = client.sessions.sendEvent(session.id, {
      type: "user_message",
      content: "Investiga por qué el deploy de ayer rompió el checkout",
    });
    
    for await (const event of stream) {
      // tool_call, tool_result, status_update...
    }
    

    Out-of-the-box tienes Bash, operaciones de archivos (lectura, escritura, edición, glob, grep), web search y fetch, y servidores MCP para conectar tool providers externos.

    El harness también trae prompt caching y compaction integrados — dos cosas que, si construyes tu propio loop, terminas resolviendo tú mismo tarde o temprano. Todo esto también está disponible en Claude Platform on AWS, con algunas diferencias de disponibilidad de features.


    Cuándo tiene sentido delegar el harness (y cuándo no)

    No todo agente necesita esto. La documentación oficial es clara sobre las señales, y las convertí en una matriz de decisión:

    Señal Managed Agents Tu propio harness (Agent SDK / Claude Code)
    La tarea corre minutos u horas con múltiples llamadas a tools Resuelto de fábrica Construyes scheduler, retries y timeouts tú mismo
    Necesitas sandboxes seguros con paquetes preinstalados y acceso de red Cloud environment gestionado Lo montas y mantienes tú
    Compliance exige que el sandbox corra en tu propia infraestructura Self-hosted environment Ya lo tienes si construiste el tuyo desde cero
    Necesitas sesiones stateful — filesystem persistente e historial entre interacciones Nativo Lo implementas a mano
    Quieres runs recurrentes en un cron schedule Scheduled deployments Montas tu propio orquestador
    Necesitas control fino sobre hooks, skills, checkpoints y cada paso del loop No es el objetivo de la herramienta Aquí gana el Agent SDK o Claude Code
    Zero Data Retention o HIPAA BAA son un requisito duro No elegible actualmente Depende de cómo lo construyas tú

    Si tu caso de uso cae casi entero en la columna izquierda, delegar el harness te ahorra semanas de trabajo de infraestructura. Si cae en la derecha, seguir construyendo con el Agent SDK o Claude Code — donde tienes control total sobre hooks, skills y checkpoints — sigue siendo la decisión correcta.


    Las 3 features que cambiaron el juego en mayo 2026

    El 19 de mayo de 2026, en el evento "Code with Claude", Anthropic anunció tres features nuevas sobre esta base.

    No están todas en el mismo punto de madurez, y eso importa antes de decidir si construyes sobre ellas hoy.

    Dreaming — memoria que se auto-mejora entre sesiones (research preview)

    Dreaming es un proceso programado que revisa las sesiones de tu agente y sus memory stores, extrae patrones y cura las memorias para que tus agentes mejoren con el tiempo.

    La idea central: un agente individual no detecta los patrones que emergen a través de decenas de sesiones. Dreaming sí. Saca a la luz errores recurrentes y los workflows en los que tus agentes convergen una y otra vez — algo especialmente efectivo en escenarios de larga duración y multi-agente.

    Tú eliges: actualizaciones automáticas de memoria, o revisión manual antes de que los cambios se apliquen. Dreaming se combina con la feature Memory (ya disponible de forma general): los agentes capturan aprendizaje mientras trabajan, y Dreaming lo refina entre sesiones.

    Estado actual: research preview, con acceso vía formulario de solicitud. No es algo que actives hoy sin pedir permiso.

    Outcomes — un grader que evalúa sin el sesgo del propio agente (public beta)

    Outcomes te deja escribir una rúbrica describiendo qué es el éxito para una tarea. Un grader separado evalúa el output contra esos criterios en su propia ventana de contexto — así que no está influenciado por el razonamiento que el agente ya generó para justificarse a sí mismo. Cuando algo no está bien, el grader señala qué cambiar y el agente hace otro intento.

    Esta es, para mí, la feature con más impacto inmediato de las tres.

    Los números que publica Anthropic en sus benchmarks internos: hasta 10 puntos porcentuales de mejora en éxito de tarea, +8.4% en generación de archivos .docx y +10.1% en .pptx. No es marginal.

    Esto es exactamente la misma disciplina que defiendo en el libro de Spec-Driven Development: especificar qué es "éxito" antes de ejecutar, no después. Outcomes lo formaliza a nivel de infraestructura — la rúbrica es tu spec, el grader es quien la hace cumplir.

    Es especialmente útil para tareas que necesitan cobertura exhaustiva y detallada, o calidad subjetiva difícil de verificar con un test automatizado — voz de marca, guías de diseño. Soporta webhooks para enterarte cuando la tarea termina, sin hacer polling.

    Estado: public beta. Puedes usarlo hoy.

    Multiagent Orchestration — un líder, especialistas en paralelo, un filesystem compartido (public beta)

    Aquí el patrón es distribuir trabajo complejo entre agentes especializados que trabajan en paralelo, con un agente líder coordinando y manteniendo contexto compartido.

    El líder delega tareas a especialistas — cada uno con su propio modelo, prompt y tools. Todos comparten un filesystem, y los eventos son persistentes: los agentes recuerdan lo que hicieron antes, incluso entre sesiones distintas. Puedes seguir la traza completa en Claude Console: qué acción tomó cada agente, en qué secuencia, con qué razonamiento.

    El ejemplo oficial que da Anthropic es concreto: un agente líder de investigación con subagentes analizando en paralelo el historial de deploys, los logs de errores, las métricas y los tickets de soporte — cada uno especializado en su fuente, todos alimentando la misma conclusión.

    Estado: public beta. También disponible hoy, aunque con menos tiempo de maduración en producción que Outcomes.


    El detalle que no puedes ignorar: datos y compliance

    Managed Agents es stateful por diseño. Eso es justo lo que lo hace útil — sesiones long-running que se resumen limpiamente tras una pausa, con historial de conversación, estado del sandbox y outputs guardados server-side.

    Y esa misma característica tiene una consecuencia que no puedes pasar por alto: actualmente Managed Agents no es elegible para Zero Data Retention (ZDR) ni para HIPAA BAA.

    Si trabajas en un contexto regulado — salud, finanzas, cualquier cliente que exija ZDR contractualmente — esto descarta Managed Agents para esa carga de trabajo específica, al menos por ahora.

    Lo que sí tienes: puedes borrar sesiones y archivos en cualquier momento vía la API. No es lo mismo que ZDR, pero es un control real que deberías usar activamente si trabajas con datos sensibles dentro de un environment gestionado.

    Si tu producto necesita ZDR o HIPAA, la Messages API con tu propio harness sigue siendo el camino — al menos hasta que Anthropic mueva esta pieza.


    Qué significa esto para tu forma de trabajar con agentes

    Claude Code, Routines y Managed Agents son tres capas de automatización distintas, no tres versiones de lo mismo — y Managed Agents completa la tercera.

    Claude Code es la capa donde tú controlas cada paso: escribes el prompt, revisas el diff, decides cuándo commitear.

    Routines — de lo que ya hablé en este post sobre Claude Code y Routines — dispara automáticamente una tarea puntual: un trigger, una tarea, un resultado.

    Managed Agents es la infraestructura completa y autónoma: memoria que se auto-mejora con Dreaming, verificación de calidad integrada con Outcomes, coordinación multi-agente sin que tú operes el runtime.

    Cada capa reduce cuánto tienes que operar tú mismo, a cambio de menos control fino. Esa es la transacción real — no "automatización buena vs automatización mala".

    Messages API Claude Managed Agents
    Qué es Prompting directo, tú construyes el loop Harness pre-construido sobre infraestructura gestionada
    Quién opera el agent loop y el sandbox Anthropic
    Persistencia de estado entre sesiones La implementas tú Nativa (sessions stateful)
    Mejor para Casos específicos, latencia baja, control total Tareas largas, asíncronas, multi-tool, multi-sesión
    Madurez Estable, uso general Beta — header managed-agents-2026-04-01

    Sé honesto sobre algo: esto sigue siendo beta. Todos los endpoints requieren ese header (el SDK lo configura solo).

    Dentro de la beta, MCP tunnels y Dreaming están en un research preview todavía más limitado — hay que solicitar acceso. Es una superficie que sigue moviéndose, no una API congelada lista para apostar tu negocio entero sin plan B.

    Si estás en el punto de pasar de "prototipo que funciona en mi máquina" a "producto que alguien más usa", esta es exactamente la conversación que trabajamos en el curso de Construye con IA: qué construyes tú y qué le delegas a la infraestructura de Anthropic.


    La pregunta correcta no es "self-hosted o managed"

    Construir un harness de agentes confiable es un problema de infraestructura, no solo de prompting. Lo aprendí de la forma cara: reconstruyendo el mismo agent loop tres veces antes de aceptarlo.

    Claude Managed Agents es la apuesta de Anthropic de que la mayoría de equipos no debería tener que resolver ese problema por su cuenta. Y para tareas largas, asíncronas, con necesidad de sandboxes seguros y memoria que mejora sola, tienen razón.

    Pero la pregunta que de verdad importa no es "self-hosted o managed" en abstracto. Es qué tan crítico es el control fino sobre tu harness para tu caso específico.

    Si la respuesta es "necesito controlar cada hook, cada skill, cada checkpoint" — sigue construyendo el tuyo. Si la respuesta es "necesito que esto simplemente funcione durante seis horas sin que yo lo esté mirando" — deja que Anthropic cargue con esa infraestructura.

    Si quieres discutir esto con otros developers que ya están probando Managed Agents en proyectos reales, en Dominicode Labs es exactamente el tipo de conversación que tenemos cada semana.


    Preguntas frecuentes sobre Claude Managed Agents

    ¿Qué son los Claude Managed Agents?

    Es un harness de agentes pre-construido y configurable que corre en infraestructura gestionada por Anthropic.

    En vez de que tú implementes el agent loop, el sandbox de ejecución de tools y la persistencia de estado, Anthropic te da un entorno donde Claude puede leer archivos, correr comandos, navegar la web y ejecutar código de forma segura, organizado alrededor de cuatro conceptos: Agent, Environment, Session y Events.

    ¿En qué se diferencian de construir mi propio agente con la Messages API?

    Con la Messages API tú controlas todo: el system prompt, el loop que decide qué tool llamar, el sandbox donde corre, y qué pasa si el proceso se cae a mitad de tarea.

    Con Managed Agents esa infraestructura la opera Anthropic — tú defines el agente y el environment, y el harness se encarga de la ejecución, el streaming vía eventos, la persistencia y, opcionalmente, el self-hosting del sandbox.

    ¿Qué es "Dreaming" en Claude Managed Agents?

    Es un proceso programado que revisa las sesiones de un agente y sus memory stores para extraer patrones que un agente individual no puede detectar por sí solo, y curar las memorias para que el agente mejore entre sesiones.

    Se puede configurar para aplicar cambios automáticamente o para requerir revisión manual. Actualmente está en research preview, con acceso vía formulario de solicitud — no es de disponibilidad general.

    ¿Qué es "Outcomes" y cómo mejora la calidad del output?

    Outcomes te deja definir una rúbrica de éxito para una tarea. Un grader independiente — con su propia ventana de contexto, sin el sesgo del razonamiento que el agente ya generó — evalúa el output contra esa rúbrica y le pide otro intento si no cumple.

    En benchmarks internos de Anthropic, esto mejoró el éxito de tarea hasta en 10 puntos porcentuales, con mejoras específicas de +8.4% en .docx y +10.1% en .pptx. Está en public beta, disponible hoy.

    ¿Qué es "Multiagent Orchestration" en Claude Managed Agents?

    Es el modelo donde un agente líder distribuye trabajo complejo entre varios agentes especializados que trabajan en paralelo, cada uno con su propio modelo, prompt y tools.

    Todos comparten un filesystem y los eventos son persistentes, así que el equipo de agentes recuerda lo que hizo antes. Está en public beta, con trazabilidad completa de cada acción disponible en Claude Console.

    ¿Puedo usar Claude Managed Agents en producción hoy?

    Puedes usarlo hoy, pero con matices importantes. Todo el sistema de Managed Agents está en beta y requiere el header managed-agents-2026-04-01 (el SDK lo configura automáticamente).

    Outcomes y Multiagent Orchestration están en public beta y son razonablemente estables. Dreaming y MCP tunnels están en un research preview más limitado, con acceso solicitado por formulario. Evalúa cada feature por separado antes de apostar tu producto entero a ella.

    ¿Managed Agents cumple con HIPAA o Zero Data Retention (ZDR)?

    No, actualmente no. Managed Agents es stateful por diseño — guarda historial de conversación, estado del sandbox y outputs server-side para que las sesiones long-running se puedan resumir limpiamente — y eso lo hace no elegible para ZDR ni para un HIPAA BAA.

    Sí puedes borrar sesiones y archivos en cualquier momento vía la API, pero si tu carga de trabajo exige ZDR o HIPAA de forma contractual, tu propio harness sobre la Messages API sigue siendo el camino correcto por ahora.


    Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

  • Claude Code hooks: guardrails, logging y automatización para tus agentes

    Claude Code hooks: guardrails, logging y automatización para tus agentes

    Hook PreToolUse para Bash: bloquea rm -rf y loguea todo

    set -euo pipefail

    Leer el JSON de entrada desde stdin

    INPUT=$(cat)

    Extraer el comando que Claude quiere ejecutar

    COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')

    Timestamp para el log

    TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
    LOG_FILE="${CLAUDE_PROJECT_DIR:-$HOME}/.claude/bash-audit.log"

    Loguear el comando (siempre, antes de cualquier decisión)

    echo "[$TIMESTAMP] CMD: $COMMAND" >> "$LOG_FILE"

    Patrones peligrosos que bloqueamos sin excepciones

    BLOCKED_PATTERNS=(
    "rm -rf /"
    "rm -rf ~"
    "rm -rf *"
    "rm -rf ."
    ":(){ :|:& };:"
    "dd if=/dev/zero"
    "> /dev/sda"
    "mkfs."
    )

    for PATTERN in "${BLOCKED_PATTERNS[@]}"; do
    if echo "$COMMAND" | grep -qE "$PATTERN"; then
    echo "[$TIMESTAMP] BLOCKED: $COMMAND" >> "$LOG_FILE"
    echo "Comando bloqueado por hook de seguridad: patrón destructivo detectado ('$PATTERN')" >&2
    exit 2
    fi
    done

    Todo bien — salida silenciosa, flujo normal

    exit 0

    
    Ahora la configuración en `.claude/settings.json`:
    
    ```json
    {
      "hooks": {
        "PreToolUse": [
          {
            "matcher": "Bash",
            "hooks": [
              {
                "type": "command",
                "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/bash-guard.sh",
                "timeout": 10
              }
            ]
          }
        ]
      }
    }
    

    Dale permisos de ejecución al script:

    chmod +x .claude/hooks/bash-guard.sh
    

    A partir de aquí, cada vez que Claude intente ejecutar un comando Bash, el hook se dispara primero. Si detecta un patrón peligroso, Claude recibe el mensaje de error en stderr y no ejecuta nada. Si todo está limpio, el agente continúa sin ninguna interrupción visible.

    El archivo bash-audit.log crece con cada comando ejecutado. En una sesión de trabajo normal con un agente activo, ese log te cuenta la historia completa de lo que hizo Claude — sin tener que scrollear el historial de conversación.


    Añadir una notificación cuando el agente termina

    Si lanzas tareas largas y quieres saber cuándo terminan sin estar mirando la pantalla, el hook Stop es lo que necesitas.

    {
      "hooks": {
        "Stop": [
          {
            "hooks": [
              {
                "type": "command",
                "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/notify-done.sh",
                "timeout": 5
              }
            ]
          }
        ]
      }
    }
    
    #!/bin/bash
    # .claude/hooks/notify-done.sh
    # Notificación de escritorio cuando Claude termina una tarea
    
    # En macOS
    if command -v osascript &> /dev/null; then
      osascript -e 'display notification "Claude ha terminado la tarea" with title "Claude Code"'
    fi
    
    # En Linux con notify-send
    if command -v notify-send &> /dev/null; then
      notify-send "Claude Code" "El agente ha terminado la tarea"
    fi
    
    exit 0
    

    El hook Stop no tiene matcher porque no hay herramientas que filtrar — aplica siempre que Claude decide parar. Si necesitas que Claude continúe trabajando hasta que se cumpla alguna condición (por ejemplo, todos los tests en verde), haz que el script devuelva exit 2 y escribe en stdout un JSON con {"hookSpecificOutput": {"additionalContext": "Los tests aún fallan. Corrígelos antes de terminar."}} para que Claude sepa qué debe hacer a continuación. El stderr en Stop hooks no interrumpe el flujo.


    Cuándo usar hooks, cuándo CLAUDE.md y cuándo sub-agentes

    Esta es la pregunta que más se repite cuando alguien empieza a añadir capas de control a sus agentes.

    Usa CLAUDE.md para instrucciones de comportamiento en lenguaje natural: convenciones de código, qué herramientas preferir, cómo formatear los commits. Es lo primero que Claude lee. Es contexto, no control.

    Usa hooks cuando necesitas una garantía técnica que no dependa de que Claude interprete bien una instrucción. Un rm -rf bloqueado por un hook es un rm -rf bloqueado, siempre, independientemente de cómo estaba redactado el prompt. Un rm -rf "prohibido" en CLAUDE.md es una sugerencia que Claude puede ignorar bajo presión de contexto.

    Usa sub-agentes cuando necesitas razonamiento sobre una situación: revisar si el código generado cumple los requisitos de arquitectura, validar que una migración de base de datos es correcta antes de ejecutarla, resumir los resultados de diez herramientas en paralelo. Los sub-agentes piensan. Los hooks no necesitan pensar — esa es su ventaja.

    La regla general: hooks para lo que debe ser determinista, sub-agentes para lo que requiere juicio.


    Preguntas frecuentes

    ¿Los hooks se ejecutan con cada mensaje del usuario o solo cuando Claude usa herramientas?

    Depende del tipo de hook. PreToolUse y PostToolUse solo se disparan cuando Claude invoca una herramienta — no con cada mensaje de texto. UserPromptSubmit se dispara con cada mensaje enviado, antes de que Claude lo procese. Stop se dispara cuando Claude decide terminar, no cuando el usuario escribe algo.

    ¿Puedo tener hooks diferentes para proyectos distintos?

    Sí. Los hooks en .claude/settings.json (dentro del proyecto) solo aplican a ese proyecto. Los hooks en ~/.claude/settings.json aplican a todos tus proyectos. Si hay configuraciones en ambos archivos, se combinan. En caso de conflicto en el mismo evento, la configuración más específica (proyecto) tiene precedencia.

    ¿Un hook puede modificar lo que Claude va a hacer, no solo bloquearlo?

    Sí, en PreToolUse. Puedes devolver por stdout un JSON con hookSpecificOutput.updatedInput para reemplazar los argumentos que Claude iba a usar. Por ejemplo, si Claude quiere ejecutar rm -rf build, puedes interceptarlo y devolver rm -rf build/ (con trailing slash) para que solo borre el contenido del directorio, no el directorio en sí. Esta capacidad es poderosa — úsala con cuidado.

    ¿Hay alguna forma de ver qué hooks están activos en mi sesión?

    Sí. Escribe /hooks en el prompt de Claude Code y se abre una vista en el navegador con todos los hooks configurados, organizados por evento, con su matcher y tipo de handler. Es de solo lectura, pero es la forma más rápida de auditar qué está activo.

    ¿Los hooks se pueden desactivar sin borrarlos?

    Sí. Añade "disableAllHooks": true en cualquiera de los archivos de settings. Solo los settings de usuario y proyecto pueden desactivar hooks definidos en esos mismos niveles — los hooks de configuración administrada (managed settings) requieren intervención del administrador.

    ¿Hay límite en cuántos hooks puedo configurar?

    No hay un límite documentado en el número de hooks. Sí hay un timeout por hook (por defecto 600 segundos para comandos, 30 para prompts). Si un hook supera el timeout, se cancela como error no bloqueante (igual que un exit 1) — el flujo continúa pero el hook no tuvo efecto.


    Lo que cambia cuando añades hooks a tu workflow

    La primera semana que empecé a usar hooks en mis propios agentes, lo que más me sorprendió no fue la seguridad — fue la visibilidad.

    El archivo de log de comandos Bash me reveló patrones que no había visto antes. Claude ejecutaba con frecuencia ciertos comandos que yo no esperaba. Algunos eran ineficientes. Uno de ellos era potencialmente problemático en un contexto de CI. Sin el log, nunca me habría enterado.

    Los hooks no solo protegen tu sistema. Te dan información real sobre cómo trabaja el agente — y esa información es la que necesitas para mejorar tus prompts, tu CLAUDE.md y tu arquitectura de agentes con el tiempo.

    Si estás construyendo algo serio con Claude Code — más de un agente, un workflow automatizado, código que toca producción —, los hooks no son opcionales. Son la diferencia entre un agente que funciona y uno en el que confías.

    Si quieres ver cómo encajan los hooks dentro de un sistema de agentes más completo — con sub-agentes, routines y MCP — en el curso Construye con IA cubrimos el stack completo desde la idea hasta el producto, incluyendo cómo estructurar los guardrails de seguridad para workflows que corren sin supervisión constante.

    Y si prefieres un entorno donde experimentar con otros developers que están construyendo lo mismo, en Dominicode Labs compartimos proyectos, configuraciones y workflows reales cada semana.


    Bezael Pérez — Developer senior, fundador de Dominicode. Lleva 15+ años construyendo software y los últimos años construyendo con IA. Escribe sobre arquitectura de agentes, Angular moderno y cómo pasar de idea a producto sin caos.

  • MCP Server en TypeScript: conecta Claude Code con cualquier API

    MCP Server en TypeScript: conecta Claude Code con cualquier API

    claude mcp add –transport stdio github-issues — node /ruta/absoluta/build/index.js

    Para todos los proyectos (ámbito global del usuario)

    claude mcp add –scope user –transport stdio github-issues — node /ruta/absoluta/build/index.js

    
    Verifica que Claude Code lo reconoce:
    
    ```bash
    claude mcp list
    

    Deberías ver github-issues en el listado con estado Pending approval. Una vez que lo apruebes desde Claude Code, pasará a connected.


    Cómo probarlo desde una sesión de Claude Code

    Abre Claude Code en cualquier directorio y escribe:

    Lista los issues abiertos del repo microsoft/vscode
    

    Claude detecta que tiene acceso al tool list_issues, lo llama con { owner: "microsoft", repo: "vscode", state: "open" }, y devuelve la lista formateada directamente en el chat.

    Sin salir. Sin copiar y pegar. Sin fricción.

    Para repos privados, añade tu token de GitHub como variable de entorno antes de registrar el server:

    # En el comando de registro pasa el env directamente
    claude mcp add --transport stdio github-issues --env GITHUB_TOKEN=ghp_xxx -- node /ruta/absoluta/build/index.js
    

    Y en el código, descomenta la línea Authorization: Bearer ${process.env.GITHUB_TOKEN}.


    Ir más allá: cuándo crear tu propio MCP server

    Esta es la pregunta real. El ecosistema de MCP servers públicos ya tiene integraciones para GitHub, Slack, Notion, bases de datos, filesystems, y decenas más. No construyas lo que ya existe.

    Crea tu propio server cuando:

    1. Tienes una API interna que nadie más va a integrar
    2. Necesitas transformar o filtrar datos antes de que lleguen al modelo — la lógica de negocio importa
    3. Quieres controlar exactamente qué puede hacer Claude y qué no en tu entorno
    4. Estás construyendo un producto y necesitas que Claude interactúe con él de forma programática

    El patrón que acabas de aprender escala sin cambios. Añadir un tool nuevo es copiar el bloque del handler y registrarlo en ListToolsRequestSchema. Añadir autenticación es una cabecera. Añadir caché es un Map en memoria.

    El scaffold es siempre el mismo. Lo que cambia es la lógica de negocio de cada tool.

    Si quieres profundizar en este modelo de trabajo — construir con IA de forma estructurada, con specs, con MCP servers propios, con agentes que hacen trabajo real — en el curso Construye con IA: De la Idea al Producto con Claude Code trabajamos exactamente este flujo. Desde la idea hasta tener algo en producción.


    FAQ

    ¿Necesito compilar TypeScript para usar el server? ¿No puedo usar tsx directamente?

    Puedes. Para desarrollo local, tsx src/index.ts funciona. Para registrar en Claude Code de forma estable, compilar a JS es más fiable porque no dependes de que tsx esté instalado globalmente. En el comando claude mcp add puedes usar npx tsx si prefieres:

    claude mcp add --transport stdio github-issues -- npx tsx /ruta/src/index.ts
    

    ¿Cuál es la diferencia entre stdio y HTTP como transporte?

    StdioServerTransport es el modo local: Claude Code lanza tu server como proceso hijo y se comunica por stdin/stdout. Es el modo más simple y suficiente para tools personales o de equipo. El transporte HTTP (Streamable HTTP) es para servers remotos que quieres exponer como servicio — por ejemplo, si construyes un MCP server para tu empresa y lo despliegas en un servidor.

    ¿Mis tools pueden leer archivos del sistema o ejecutar comandos?

    Sí, un MCP server tiene acceso completo al sistema donde se ejecuta. Puede leer archivos con fs, ejecutar procesos con child_process, hacer peticiones de red. Eso también es la responsabilidad: el server corre con los permisos del usuario que lo lanza, así que diseña los tools con cuidado y no expongas capacidades destructivas sin confirmación.

    ¿Funciona con Claude Desktop o solo con Claude Code?

    Funciona con cualquier cliente MCP compatible. Claude Desktop usa claude_desktop_config.json en lugar de claude mcp add, pero el server es exactamente el mismo. También es compatible con Cursor, Continue, y cualquier cliente que implemente el protocolo. Ese es el punto de MCP: escribes el server una vez, lo consumes desde donde quieras.

    ¿Puedo añadir varios tools al mismo server?

    Sí, y es lo recomendable cuando los tools comparten contexto. Un server de GitHub podría tener list_issues, create_issue, list_pull_requests y get_file_content en el mismo proceso. Cada tool se declara en el handler de ListToolsRequestSchema y se implementa en el bloque if correspondiente dentro de CallToolRequestSchema.


    Conclusión

    Ya sabes cómo funciona MCP, qué son los tres primitivos, y tienes un server real funcionando que conecta Claude Code con la API de GitHub. El siguiente paso es obvio: sustituye la llamada a GitHub por la API que necesites tú.

    Si estás construyendo flujos de trabajo con agentes IA y quieres ir más allá de los MCP servers públicos, en Dominicode Labs publicamos proyectos completos, code reviews y recursos exclusivos para developers que construyen con IA en serio.

    Para entender cómo Claude Code orquesta tools, sub-agentes y contexto dentro de una sesión, lee primero la introducción a Claude Code que publiqué aquí — es el punto de entrada que te va a dar el marco conceptual completo.


    Bezael Pérez — Developer senior, fundador de Dominicode. 15+ años construyendo software. Ahora construyendo con IA.

  • CLAUDE.md y memoria persistente: mi flujo real con Claude Code

    CLAUDE.md y memoria persistente: mi flujo real con Claude Code

    Nombre y propósito del proyecto

    [Una o dos líneas. Para qué sirve y quién lo opera.]

    Reglas globales

    [Idioma, tono, convenciones no negociables. Las cosas que si Claude Code
    ignora, el output es inutilizable.]

    Estructura del repositorio

    [Árbol de directorios con una línea explicando qué hay en cada carpeta.
    Claude Code necesita saber dónde está cada cosa sin tener que explorar.]

    Comandos disponibles

    [Los scripts, CLIs y comandos que puede ejecutar. Con ejemplo real de uso.]

    Convenciones de nomenclatura

    [Patrones de nombres de archivos. Crítico para proyectos con muchos docs.]

    Qué NO hacer

    [Igual de importante que lo que sí hacer. Archivos que no tocar,
    patrones que evitar, decisiones ya tomadas que no reabrir.]

    
    Lo que no incluyo: historia del proyecto, motivaciones, "por qué elegimos X tecnología". Eso es contenido para un ADR o el README. El CLAUDE.md tiene que ser operativo al 100%.
    
    **Longitud objetivo: menos de 200 líneas.** Si supera eso, estás incluyendo demasiado. Claude Code no necesita el contexto completo de cada decisión — necesita las reglas de operación.
    
    ### Lo que la mayoría mete en CLAUDE.md y no debería
    
    He revisado muchos CLAUDE.md de proyectos de developers en la comunidad. El error más común: meter todo lo que "podría ser útil".
    
    Eso mata el propósito del documento. Cuando el CLAUDE.md tiene 500 líneas, Claude Code lo lee entero pero no distingue qué es crítico y qué es relleno. El resultado es el mismo que no tener CLAUDE.md: ruido.
    
    Solo va al CLAUDE.md lo que, si Claude Code lo ignora, rompe el proyecto o produce output inutilizable.
    
    ---
    
    ## El sistema de memoria persistente
    
    El contexto de una sesión de Claude Code desaparece cuando la sesión termina. Eso es una limitación real y no va a cambiar pronto — la ventana de contexto no es memoria a largo plazo.
    
    El workaround que funciona: archivos Markdown.
    
    ### La estructura que uso
    
    En el directorio del proyecto tengo una carpeta `memory/` con dos tipos de archivos:
    
    1. **`MEMORY.md`** — el índice. Una lista de una línea por cada archivo de memoria con un enlace y una descripción de qué contiene. Claude Code lo lee al arrancar la sesión y sabe qué hay disponible.
    
    2. **Archivos individuales de memoria** — uno por tema. Nomenclatura descriptiva: `project_kursar.md`, `feedback_email_style.md`, `reference_tools.md`.
    
    Una entrada en `MEMORY.md` tiene esta forma:
    
    ```markdown
    # Memory Index — Dominicode Company Agents
    
    - [User Profile](user_profile.md) — Solo creator, YouTube + Udemy + books, comunidad en español
    - [Curso Angular 22](project_curso_angular22.md) — Regrabación en curso; ejemplos verificados en ejemplos/v22-features/
    - [Estilo emails Bezael](feedback_email_style.md) — Abrir con historia breve; no estilo telegráfico
    - [WordPress taxonomía](reference_wordpress_taxonomia.md) — IDs reales verificados (AI=37, TypeScript=42…)
    

    Hay tres prefijos que uso para distinguir el tipo de contenido:

    • project_ — estado de un proyecto activo con decisiones tomadas
    • feedback_ — algo que salió mal o que aprendí de una sesión anterior y no quiero volver a repetir
    • reference_ — datos estáticos que Claude Code necesita consultar (IDs, URLs, credenciales de formato)

    Por qué funciona mejor que repetirlo en cada sesión

    La alternativa es pegar el contexto en el primer prompt de cada sesión. Lo hice durante semanas. El problema: acumulas un primer prompt de 800 palabras que tarde o temprano omites porque es tedioso, y cuando lo omites, Claude Code trabaja sin ese contexto.

    Con archivos de memoria, el contexto está disponible siempre que Claude Code los lea. Y como están versionados en el repo, no se pierden entre sesiones ni entre máquinas.

    El inconveniente honesto: Claude Code no lee esos archivos automáticamente a menos que se lo indiques. Tienes que incluirlos en el arranque de sesión o referenciarlos con @archivo cuando son relevantes. Esto lo resuelvo con el ritual de inicio que cuento más adelante.


    Gestión del contexto en sesiones largas

    Esto es lo que menos se habla y lo que más impacta en la calidad del trabajo.

    Una sesión larga de Claude Code acumula contexto de forma lineal. Cada intercambio, cada archivo leído, cada respuesta generada ocupa espacio en la ventana. Cuando la ventana se llena, el modelo empieza a "comprimir" el historial — mantiene las instrucciones recientes y los bloques de código más relevantes, pero los matices de conversaciones anteriores se difuminan.

    El resultado es exactamente lo que me pasó esa tarde: Claude Code responde con coherencia local (el último intercambio está bien) pero pierde coherencia global (contradice decisiones tomadas hace cuarenta minutos).

    Cómo lo detecto

    Hay tres señales de que el contexto está degradado:

    • Claude Code propone algo que ya descartamos explícitamente en la misma sesión
    • Las respuestas se vuelven más genéricas y pierden el tono específico del proyecto
    • Me pide información que ya le di al inicio de la sesión

    Cuando aparece cualquiera de las tres, no sigo. Empiezo sesión nueva.

    Cuándo empezar sesión nueva (aunque duela)

    La respuesta rápida: cuando terminas un bloque de trabajo concreto.

    No esperes a que el contexto se degrade. Trata cada sesión de Claude Code como una unidad de trabajo enfocada. Si estoy escribiendo un post del blog, esa es la sesión. Si paso a revisar el curriculum de un curso, es una sesión nueva.

    Este cambio de mentalidad es lo que más impacta en la consistencia del output. Una sesión larga y dispersa produce resultados mediocres. Sesiones cortas y enfocadas producen resultados que puedes usar directamente.

    @files: cuándo y cómo los uso

    Claude Code tiene la sintaxis @archivo para incluir el contenido de un archivo específico en el contexto. Es la herramienta más infrautilizada que conozco entre developers que llevan meses con Claude Code.

    Uso @archivo para tres cosas:

    Dar contexto específico sin abrir un archivo manualmente. Si estoy trabajando en el agente de blog y necesito que Claude Code vea el estado actual del MEMORY.md, escribo @memory/MEMORY.md en el prompt. El contenido entra directamente en el contexto sin que yo tenga que copiarlo.

    Anclar decisiones pasadas. Si en una sesión nueva necesito que recuerde una decisión de arquitectura que está en specs/agentkit-pro/spec.md, la referencio con @. Entra en el contexto de esa sesión específicamente donde la necesito.

    Forzar coherencia entre archivos. Si estoy modificando un componente y quiero que Claude Code sea consciente de cómo lo usa otro módulo, incluyo ambos con @. Sin eso, trabaja con el archivo aislado y puede romper la integración.

    Lo que no hago: incluir diez archivos con @ en el mismo prompt. Cuantos más archivos incluyes, más contexto consumes antes de empezar el trabajo real. Selecciono solo los que son directamente relevantes para la tarea concreta de esa sesión.


    El ritual de inicio de sesión

    Después de meses ajustando esto, tengo un primer prompt que uso como plantilla base. No es magia — es contexto específico entregado de forma eficiente.

    Contexto de esta sesión:
    - Proyecto: [nombre]
    - Tarea: [qué voy a hacer hoy, en una línea]
    - Decisiones previas que aplican: @memory/MEMORY.md
    - Archivos relevantes: @[archivo-1] @[archivo-2]
    - Restricciones: [lo que NO quiero que haga en esta sesión]
    
    Empieza por [primera acción concreta].
    

    Los tres elementos críticos son:

    La tarea en una línea. No el proyecto entero, solo lo que hacemos hoy. Cuanto más específico, mejor el foco de Claude Code durante toda la sesión.

    Las restricciones. Es lo que más me ha ahorrado tiempo. "No toques el archivo X", "no propongas cambiar el stack", "si necesitas más información, pregunta antes de generar código". Sin restricciones explícitas, Claude Code optimiza para completar la tarea con las decisiones que considera mejores — que no siempre son las que tú ya tomaste.

    Una primera acción concreta. No "ayúdame con el proyecto". Sino "lee el archivo X y dime si la estructura de directorios es coherente con las reglas de CLAUDE.md". La primera acción específica establece el tono de toda la sesión.


    Lo que todavía falla y cómo lo mitigo

    Honestidad completa aquí, porque la mayoría de posts sobre Claude Code solo muestran los casos de éxito.

    Los archivos de memoria no se actualizan solos. Si en una sesión tomo una decisión importante — por ejemplo, cambio la arquitectura de un módulo o descubro que una librería no funciona para mi caso de uso — tengo que acordarme de actualizar el archivo de memoria correspondiente antes de cerrar la sesión. Si no lo hago, en la siguiente sesión Claude Code no tiene ese contexto. Todavía me olvido. La solución parcial: incluir "actualiza MEMORY.md con las decisiones de esta sesión" como último paso de cada sesión de trabajo.

    El CLAUDE.md global a veces entra en conflicto con el del proyecto. Tengo reglas globales que son sensatas para el 90% de mis proyectos pero que en algún proyecto específico quiero anular. Claude Code no siempre resuelve bien ese conflicto — a veces aplica la regla global aunque el CLAUDE.md del proyecto diga lo contrario. La solución: en el CLAUDE.md del proyecto, cuando necesito anular una regla global, lo digo explícitamente: "Aunque el CLAUDE.md global indica X, en este proyecto aplicamos Y."

    La compresión de contexto no es predecible. No hay un indicador que te diga "estás al 80% de la ventana de contexto, es hora de empezar sesión nueva". Lo detecto por los síntomas que describí antes. Estoy esperando que Claude Code añada algún tipo de indicador de uso de contexto — de momento no existe.

    Las sesiones cortas y enfocadas son más difíciles de mantener. Cuando estoy en el flow, la tentación de seguir en la misma sesión es real. Cada vez que cedo, la calidad del output en la segunda mitad de la sesión baja. Es un problema de disciplina, no de herramienta.


    FAQ

    ¿Cuántas secciones debe tener un CLAUDE.md?

    No hay un número correcto. Lo importante es que cada sección tenga una función operativa clara. Si no puedes responder "qué hace Claude Code diferente por tener esta sección", esa sección sobra. En mis proyectos suelo tener entre 5 y 8 secciones.

    ¿Puedo tener múltiples CLAUDE.md en subdirectorios?

    Sí. Claude Code lee el CLAUDE.md del directorio raíz y también los de subdirectorios cuando trabaja en ellos. Esto es útil en monorepos o cuando tienes un frontend y un backend con convenciones distintas. No lo abuses — si tienes CLAUDE.md en diez subdirectorios, el agente pasa más tiempo leyendo instrucciones que trabajando.

    ¿Qué diferencia hay entre poner algo en CLAUDE.md y decirlo en el primer prompt?

    El CLAUDE.md aplica a todas las sesiones del proyecto de forma permanente. El primer prompt aplica solo a esa sesión. Usa CLAUDE.md para convenciones estables que no cambian entre sesiones. Usa el primer prompt para el contexto específico de lo que haces hoy.

    ¿Cuándo tiene sentido usar memoria persistente vs. simplemente tener un CLAUDE.md más completo?

    CLAUDE.md es para reglas e instrucciones: cómo trabajar en este proyecto. Los archivos de memoria son para estado e historial: qué ha pasado ya, qué decisiones están tomadas, qué feedback recibí en sesiones anteriores. Si en tu CLAUDE.md estás escribiendo cosas como "el curso de Angular lleva dos semanas atrasado" o "el cliente pidió cambiar el color primario a azul", eso debería ir en un archivo de memoria, no en CLAUDE.md.

    ¿Funciona igual en proyectos de código que en proyectos de contenido?

    Igual de bien, o incluso mejor en proyectos de contenido. Todo lo que describí aquí lo uso tanto para el repositorio de código de Kursar como para el sistema de agentes de Dominicode — que no tiene una sola línea de código productivo, pero tiene 18 agentes, 118 documentos en la base de conocimiento, y decisiones editoriales acumuladas durante meses. El sistema de memoria persistente es especialmente valioso cuando el "código" son documentos, estrategias y decisiones.


    Conclusión

    El contexto no es un detalle técnico de Claude Code que puedas ignorar. Es el recurso central que determina si el agente trabaja contigo o contra ti.

    CLAUDE.md bien estructurado te da coherencia por defecto. La memoria persistente te da continuidad entre sesiones. El ritual de inicio te da foco en cada sesión. Y saber cuándo empezar sesión nueva te salva de la degradación silenciosa que destruye la calidad del output.

    No necesitas implementar todo esto de golpe. Empieza por el CLAUDE.md del proyecto — 100 líneas operativas, sin relleno. Eso solo ya cambia radicalmente cómo trabaja Claude Code en tu repositorio.

    Si quieres ver este sistema aplicado a un proyecto real de principio a fin, en el curso Construye con IA trabajamos exactamente con este flujo: CLAUDE.md, memoria, gestión del contexto y SDD como metodología para que el agente tenga siempre el contexto correcto en el momento correcto.

    Y si ya tienes Claude Code corriendo y quieres profundizar con otros developers que están en el mismo camino, en Dominicode Labs compartimos los patrones que van funcionando en producción — incluyendo los que fallan y cómo los arreglamos.


    Posts relacionados


    Bezael Pérez es developer senior con 15+ años de experiencia y fundador de Dominicode. Construye con Claude Code, Angular y TypeScript, y documenta lo que funciona — y lo que no — para developers que quieren ir más allá del vibe coding.