Tag: Agentes IA

  • GPT-6.2 Astra vs Claude Fable 5.2: mismo precio, otro coste

    GPT-6.2 Astra vs Claude Fable 5.2: mismo precio, otro coste

    El 17 de noviembre OpenAI publicó el precio de GPT-6.2 Astra en la API: $8 por millón de tokens de entrada y $40 de salida.

    Ese número te suena: es exactamente lo que cobra Claude Fable 5.2 desde que Anthropic le bajó el precio. Mismo input, mismo output, al céntimo.

    Y aquí empieza el problema. Hasta el 17 de noviembre de 2026, cualquier comparativa tipo GPT-6.2 Astra vs Claude Fable 5.2 arrancaba por la tabla de precios. Ahora esa tabla dice "empate". Si sigues decidiendo por el precio por token, vas a elegir a ciegas.

    En corto: GPT-6.2 Astra y Claude Fable 5.2 cuestan lo mismo por token ($8/$40), pero no por tarea: en Artificial Analysis, Astra sale a $4,00 y Fable a $26,54, con 62 puntos de índice frente a 65. Con prompts por debajo de 272.000 tokens, Astra es el primer candidato a medir para agentes de volumen; por encima de ese umbral, o si necesitas el techo de calidad, Fable justifica su coste.

    ¿Qué es GPT-6.2 Astra?

    GPT-6.2 Astra es el modelo frontier de OpenAI para trabajo profesional y agéntico complejo, lanzado el 17 de noviembre de 2026 junto a GPT-6.2 Sol, su modelo eficiente para el día a día.

    Ambos están en ChatGPT Work, en Codex y en la API como gpt-6.2-astra y gpt-6.2-sol. Astra baja un 20 % respecto a GPT-6 Astra ($10/$50 entonces) y Sol se queda en $2/$10. Si quieres el contexto del lanzamiento anterior, lo conté en GPT-6 Astra: precio, API y el asterisco de los 272.000 tokens.

    GPT-6.2 precio API: lo que cambia y lo que no

    El precio base de GPT-6.2 Astra empata con Fable 5.2, pero la letra pequeña no: caché y contexto largo van en direcciones opuestas.

    La ficha oficial del modelo confirma $8 de input, $0,40 de input cacheado, $10 por escritura de caché y $40 de output. Y confirma que el asterisco sigue ahí: si una request supera los 272.000 tokens de input, el input pasa a $16 y el output a $60, para toda la request.

    Anthropic va por el otro lado. Según su página de precios, Fable 5.2 cobra lo mismo por token en todo su contexto de 1M. Una request de 900.000 tokens paga la misma tarifa que una de 9.000.

    GPT-6.2 Astra vs Claude Fable 5.2: la tabla de decisión

    Con el precio por token empatado, la comparación útil es el coste por tarea, el contexto y el riesgo de cada uno.

    El coste por tarea es lo que pagas, sumando todas las requests, para que un modelo termine una tarea completa: depende del precio por token y, sobre todo, de cuántos tokens de input y output consume hasta acabar.

    Criterio GPT-6.2 Astra Claude Fable 5.2
    Input / output (por 1M) $8 / $40 $8 / $40
    Lectura de caché (por 1M) $0,40 $0,20
    Más de 272.000 tokens de input $16 / $60, toda la request Sin recargo hasta 1M
    Precio mezclado (7:2:1 caché/input/output) $5,88 $5,74
    Intelligence Index (AA, variante Max) 62 65
    Coste medio por tarea (AA) $4,00 $26,54
    Tokens de output en el índice 65,8M 275M
    Tiempo medio por tarea (AA) 14,3 min 41,5 min
    Modelo pequeño del mismo proveedor a $2/$10 GPT-6.2 Sol: 57 puntos, $1,01 por tarea Sonnet 5.5: 55 puntos, $10,02 por tarea
    Limitación o riesgo Recargo ×2 de input y ×1,5 de output por encima de 272.000 tokens; usuarios que señalan sobreingeniería El más caro por tarea del índice (puesto 94 de 94 en coste); 4 breaking changes desde 5.1

    Fuentes: AA GPT-6.2 Astra, AA Fable 5.2, AA GPT-6.2 Sol, AA Sonnet 5.5, consultadas el 20 de noviembre de 2026.

    Fíjate en dos filas. El precio mezclado difiere en 14 céntimos: Fable es incluso un 2,4 % más barato por token gracias a su caché. Pero el coste por tarea es 6,6 veces mayor ($26,54 / $4,00).

    La diferencia no está en la tarifa. Está en cuántos tokens quema cada modelo para terminar. Fable generó 275M de tokens de output en el índice; Astra, 65,8M. Eso es 4,2 veces más salida, y salida a $40 el millón.

    El contexto largo da la vuelta a la cuenta

    Por encima de 272.000 tokens de input y con los mismos tokens, Fable 5.2 pasa a ser más barato por request que GPT-6.2 Astra, a veces casi la mitad.

    Haz la cuenta con una request sin caché de 10.000 tokens de output:

    Input de la request GPT-6.2 Astra Claude Fable 5.2
    270.000 tokens $2,16 + $0,40 = $2,56 $2,16 + $0,40 = $2,56
    300.000 tokens $4,80 + $0,60 = $5,40 $2,40 + $0,40 = $2,80

    Treinta mil tokens más y Astra cuesta casi el doble que Fable. Si tu agente arrastra el repositorio entero en cada turno, ese umbral importa más que cualquier benchmark.

    ¿Cuál es mejor para coding y agentes?

    En coding la ventaja de Fable 5.2 se estrecha, y el coste por tarea depende tanto del harness como del modelo.

    En la tabla de benchmarks que recopila DataCamp, con cifras reportadas por los fabricantes, Fable 5.2 saca 49,1 % en FrontierCode 2.0 frente al 44,2 % de Astra. Astra gana en Agents' Last Exam v1.1 (78,3 % frente a 72,8 %).

    Lo útil está en el hilo de Hacker News del lanzamiento, con más de 860 comentarios. El usuario ariwilson pasó su propio benchmark de 30 tareas de bugs y features, dos ejecuciones por modelo: Astra y Fable resolvieron 54 de 60 cada uno. Astra a $1,11 por arreglo, Fable a $1,78.

    Ojo a ese número. En su harness la diferencia es de 1,6 veces, no de 6,6. El coste por tarea de Artificial Analysis no es el tuyo. Por qué un benchmark público no sustituye a tus tareas lo detallé en los benchmarks de IA para programar que sí importan en 2026.

    Y el comportamiento tampoco es igual. Otro usuario, CSMastermind, lo resume en una línea: "I actually have the problem with Fable stopping too early on tasks but Astra way overengineers things".

    Routing: el empate real está en los modelos pequeños

    El modelo pequeño cambia más la cuenta que el flagship: GPT-6.2 Sol y Sonnet 5.5 cuestan los mismos $2/$10, pero Sol sale a $1,01 por tarea y Sonnet a $10,02.

    En el benchmark de ariwilson, GPT-6.2 Sol resolvió 50 de 60 a $0,31 por arreglo: cuatro tareas menos que Astra a menos de un tercio del coste.

    Si haces routing, lo que conté en GPT-6.1 Sol vs GPT-6 Astra sigue valiendo: el modelo pequeño se queda con el grueso del tráfico y el flagship entra solo cuando la tarea lo pide. Lo que no debes hacer es comparar proveedores por la tarifa. Mide tus tareas:

    type ModelId = 'gpt-6.2-astra' | 'gpt-6.2-sol' | 'claude-fable-5-2' | 'claude-sonnet-5-5';
    
    interface Price { input: number; cachedInput: number; output: number } // USD por 1M tokens
    
    const PRICES: Record<ModelId, Price> = {
      'gpt-6.2-astra':     { input: 8, cachedInput: 0.40, output: 40 },
      'gpt-6.2-sol':       { input: 2, cachedInput: 0.10, output: 10 },
      'claude-fable-5-2':  { input: 8, cachedInput: 0.20, output: 40 },
      'claude-sonnet-5-5': { input: 2, cachedInput: 0.10, output: 10 },
    };
    
    // Normaliza el usage de cada SDK a esto: en OpenAI los cacheados van dentro
    // de input_tokens; en Anthropic, cache_read_input_tokens va aparte.
    interface TurnUsage { uncachedInput: number; cachedInput: number; output: number }
    
    function turnCost(model: ModelId, u: TurnUsage): number {
      const p = PRICES[model];
      const prompt = u.uncachedInput + u.cachedInput;
      // OpenAI: por encima de 272k de input, input y caché x2 y output x1,5 en toda la request.
      // Asumo que el umbral cuenta también lo cacheado: compruébalo con tu factura.
      const longCtx = model.startsWith('gpt-') && prompt > 272_000;
      const inMul = longCtx ? 2 : 1;
      const outMul = longCtx ? 1.5 : 1;
      return (
        (u.uncachedInput * p.input * inMul +
          u.cachedInput * p.cachedInput * inMul +
          u.output * p.output * outMul) / 1_000_000
      );
    }
    
    // Coste de una tarea = suma de todos sus turnos (sin escrituras de caché).
    export const taskCost = (model: ModelId, turns: TurnUsage[]) =>
      turns.reduce((acc, t) => acc + turnCost(model, t), 0);
    

    Pasa 20 o 30 tareas reales por cada modelo, guarda el usage de cada turno y compara taskCost dividido entre tareas resueltas. Ese número, no la tarifa, es el que decide. Es la misma disciplina que aplicamos en Construye con IA: primero defines qué es "tarea resuelta" y después mides.

    Cuándo NO cambiar de modelo

    Cambiar de Fable 5.2 a GPT-6.2 Astra solo por el coste por tarea del índice es mala idea en al menos cuatro casos.

    Los rankings son de la primera semana. Las cifras de Artificial Analysis se consultaron el 20 de noviembre de 2026, tres días después del lanzamiento, y los benchmarks de la tabla de DataCamp los reportan los propios fabricantes.

    Wccftech informa de que en el Coding Agent Index de Artificial Analysis Astra 6.2 se queda en 53, como GPT-6 Astra; la web de AA no muestra ese dato en abierto, así que tómalo con pinzas. Según el mismo artículo, Tibo, de OpenAI, explicó en X que algunas personas tuvieron acceso anticipado a una versión que cambió en los últimos días antes del lanzamiento.

    Tu harness no es el de Artificial Analysis. El caso de ariwilson lo demuestra: 6,6 veces en el índice, 1,6 veces en su benchmark. Si tu agente ya está afinado para Claude Code (prompts, tools, hooks), migrar a Codex cuesta horas de ingeniería que no salen en ninguna tabla.

    Tus prompts pasan de 272.000 tokens. Ahí Astra paga doble input y 1,5 veces el output en toda la request. Un agente que trabaja con contexto enorme puede salir más caro en Astra aunque gaste menos tokens.

    Estás a mitad de migración a 5.2. Si acabas de pelearte con los cuatro breaking changes que describí en Claude Fable 5.2: precio, breaking changes y routing, cambiar de proveedor ahora es abrir otro frente.

    Cómo elegir entre GPT-6.2 Astra y Fable 5.2 hoy

    Si hoy pagas Fable 5.2 para todo, no migres el agente: monta la medición. Coge las 30 últimas tareas de tu backlog que el agente resolvió bien, pásalas por GPT-6.2 Astra y GPT-6.2 Sol con el snippet de arriba, y compara coste por tarea resuelta.

    Si Astra empata en calidad y tus prompts viven por debajo de 272.000 tokens, tienes un ahorro real. Si no, ya sabes por qué pagas Fable.

    La pieza que convierte esto en algo repetible es tener escrito qué cuenta como "resuelto": una spec con criterios de aceptación, que es lo que explico en el libro Spec-Driven Development. Si quieres el método completo para diseñar agentes con evals y tools, lo tienes gratis en el ebook El Developer Agéntico.

    Preguntas frecuentes

    ¿Cuánto cuesta GPT-6.2 Astra en la API?

    GPT-6.2 Astra cuesta $8 por millón de tokens de input, $0,40 por input cacheado, $10 por escritura de caché y $40 por millón de output. Si una request supera los 272.000 tokens de input, el input pasa a $16 y el output a $60 para toda la request, según la ficha oficial de OpenAI.

    ¿GPT-6.2 Astra es mejor que Claude Fable 5.2?

    No en la clasificación general: en el Intelligence Index de Artificial Analysis, Fable 5.2 saca 65 y Astra 62. Pero Astra cuesta $4,00 por tarea frente a $26,54 de Fable. En coding, benchmarks de usuarios como el de ariwilson en Hacker News los dejan empatados en tasa de acierto, con Astra más barato.

    ¿Por qué cuestan lo mismo por token y tan distinto por tarea?

    Porque el coste por tarea depende de cuántos tokens consume el modelo para terminar. En el índice de Artificial Analysis, Fable 5.2 generó 275M de tokens de output frente a 65,8M de Astra. A $40 el millón de output, esa diferencia pesa mucho más que el precio de la caché.

    ¿Qué modelo pequeño conviene para routing, GPT-6.2 Sol o Sonnet 5.5?

    Ambos cuestan $2/$10 por millón de tokens. En Artificial Analysis, GPT-6.2 Sol saca 57 puntos a $1,01 por tarea y Sonnet 5.5 saca 55 a $10,02. Si tu stack ya es Claude, mide antes de mezclar proveedores: el coste de mantener dos SDK y dos cachés también cuenta.

    ¿A partir de cuántos tokens GPT-6.2 Astra sale más caro que Fable 5.2?

    A partir de 272.000 tokens de input por request. Por encima de ese umbral, OpenAI cobra $16 de input y $60 de output en toda la request, mientras Fable 5.2 mantiene $8/$40 hasta 1M de contexto. Con 300.000 tokens de input y 10.000 de output, Astra cuesta $5,40 y Fable $2,80.


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

  • Orquestar agentes de IA con Herdr: que se hablen sin bucles

    Orquestar agentes de IA con Herdr: que se hablen sin bucles

    Imagina la escena. Claude Code termina un endpoint, abre un panel al lado, arranca a Codex y le pide que revise el diff. Codex contesta: "dos comentarios menores, el resto bien". Claude Code arregla los dos comentarios y vuelve a preguntar. Codex aprueba.

    Dos modelos de dos empresas distintas se han puesto de acuerdo. Todo verde. Nadie ha ejecutado los tests de integración, porque ninguno de los dos tenía esa instrucción.

    Herdr permite orquestar agentes de IA desde la terminal con una skill y una CLI. Lo espectacular es que los agentes se hablen entre sí. Lo peligroso es exactamente lo mismo.

    En corto: con la skill de Herdr, un agente como Claude Code puede abrir paneles, arrancar a Codex, Gemini o Grok en ellos, mandarles prompts, esperar a que terminen y leer su respuesta, incluso en otra máquina por SSH. Trátalo como un harness: roles fijos, un tope de rondas y una persona que aprueba, porque dos agentes que se responden entre sí pueden darse la razón o entrar en bucle.

    ¿Qué es orquestar agentes de IA con Herdr?

    Orquestar agentes de IA con Herdr es dejar que un agente, desde su propio panel, use la CLI de Herdr para crear paneles, lanzar otros agentes de código, darles trabajo y recoger su resultado, sin que tú hagas de mensajero.

    Herdr es un multiplexor de terminal para agentes que mantiene las sesiones vivas y sabe si cada agente trabaja, está bloqueado o ha terminado. Todo lo que sigue está comprobado contra la documentación de Herdr v0.9.5. La instalación y la comparativa con tmux están en qué es Herdr. Aquí voy a otra cosa: agentes que dirigen a otros agentes.

    La skill de Herdr: cómo un agente controla a los demás

    La skill de Herdr es un archivo SKILL.md que enseña a un agente a usar la CLI herdr cuando corre dentro de un panel de Herdr. Se instala así, según la página oficial de la skill:

    npx skills add herdrdev/herdr --skill herdr -g
    

    Con ella, el agente ve los paneles vecinos, divide paneles sin robarte el foco, lee su salida, espera a que otro agente termine y arranca agentes ayudantes. La CLI también tiene herdr pane rename y herdr pane close, y la skill solo le deja cerrar los paneles que haya creado él.

    Dos detalles del SKILL.md importan más que los comandos: sin HERDR_ENV=1 el agente debe pararse, y la skill solo se activa cuando el usuario menciona Herdr. El agente no delega por iniciativa propia. Se lo pides tú.

    En la demo de NetworkChuck se ve el caso extremo, un Claude Code repartiendo trabajo a varios agentes a la vez, pero el patrón útil es mucho más pequeño.

    Un agente implementa, otro revisa: el bucle mínimo

    El patrón más rentable de agentes que hablan entre sí es un implementador y un revisor de otro proveedor. Un modelo distinto tiene sesgos distintos, y eso es justo lo que quieres en una revisión.

    La receta base ya la viste en qué es Herdr. Aquí cambian dos cosas: el panel se abre junto al agente que orquesta (--current) y el prompt revisa contra un contrato. Los comandos salen de la guía de automatización de Herdr; el prompt es mío:

    # Abre un panel hermano, en el mismo directorio, sin quitarte el foco
    split=$(herdr pane split --current --direction right --cwd "$PWD" --no-focus)
    pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
    
    # Arranca a Codex como revisor, con un nombre estable
    herdr agent start reviewer --kind codex --pane "$pane"
    
    # Le da trabajo y espera a que termine (máximo 5 minutos)
    herdr agent prompt reviewer "Revisa git diff main contra docs/spec.md. Lista solo incumplimientos de la spec, con fichero y línea. Si no hay ninguno, responde NINGUNO." --wait --timeout 300000
    
    # Lee la respuesta del panel de al lado
    herdr agent read reviewer --source recent-unwrapped --lines 120
    

    Fíjate en el prompt. No dice "revisa el código": dice contra qué se revisa y qué formato tiene la respuesta. Eso evita la escena del principio, porque el revisor compara contra un contrato y no contra la opinión del que implementó. Es la idea de la Revisión por Contrato aplicada a un revisor que también es una IA.

    Para que el principal se entere de que el otro tiene una pregunta, Herdr ofrece herdr agent wait reviewer --until blocked, y la API por socket permite suscribirse al evento pane.agent_status_changed. Y aquí la skill vuelve a ser sensata: cuando el agente vecino está bloqueado en una aprobación, le dice al principal que lo inspeccione y pregunte al usuario antes de responder. Si tu agente principal aprueba permisos de otro agente sin preguntarte, lo has configurado tú así.

    Agentes en otra máquina con herdr --machine

    Herdr guarda máquinas remotas por SSH con herdr machine add y deja enrutar comandos a ellas con el prefijo --machine, según la guía de conexión entre máquinas. Eso significa que un agente en tu portátil puede dar trabajo a un agente que corre en tu servidor de build:

    herdr --machine "Build machine" agent list
    # usa el ID o el nombre que devuelva agent list
    herdr --machine "Build machine" agent prompt w1:p1 "Ejecuta la suite e2e y resume solo los fallos" --wait --timeout 1800000
    herdr --machine "Build machine" agent read w1:p1 --source recent-unwrapped --lines 120
    

    Dos letras pequeñas. Los IDs de paneles y los nombres de agentes son de cada servidor, así que --current no apunta a nada remoto y hay que usar IDs explícitos. Y el prefijo apunta a una máquina cada vez: no hay listados combinados. Yo lo usaría para lo que no cabe en el portátil, como la suite e2e o una build pesada, no para repartir una feature entre dos continentes.

    Herdr frente a subagentes y a un solo agente

    Herdr compensa cuando necesitas un revisor de otro proveedor o mover trabajo a otra máquina; si todo cabe en Claude Code, los subagentes salen más baratos. Esta es la comparativa con lo que tienes en Claude Code sin instalar nada:

    Criterio Un solo agente Subagentes de Claude Code Cross-session messaging Orquestador en paneles de Herdr
    Mezcla proveedores (Codex, Gemini, Grok…) No No No, solo sesiones de Claude Code Sí, 24 tipos de agente en --kind
    Ves el trabajo de cada agente Sí Solo el resultado Cada sesión en su terminal Sí, cada uno en su panel
    Estado de cada agente No aplica Dentro de tu sesión Solo un aviso cuando otra sesión queda libre working, blocked, done, idle, unknown
    Funciona entre máquinas No No Sí, con Remote Control y cuenta de claude.ai Sí, por SSH
    Coste en tokens El mínimo Sube con cada subagente Cada mensaje es un prompt Una sesión completa por agente
    Limitación o riesgo Un solo sesgo revisando su propio trabajo Contexto aislado, solo un proveedor Sin buzón durable Estado detectado leyendo la pantalla; bucles y acuerdos en falso si no pones reglas

    Si solo quieres que Codex revise un diff, el plugin oficial codex-plugin-cc lo hace sin paneles. Mi opinión: orquestar agentes de IA con Herdr compensa cuando además quieres ver qué hace cada uno en vivo.

    Lo que se rompe cuando los agentes se hablan entre sí

    Cuando dos agentes se hablan, fallan de cuatro formas: se dan la razón, entran en bucle, leen un estado falso o uno contesta por ti.

    El acuerdo en falso. Dos agentes que leen el mismo diff sin un criterio externo tienden a aprobarse. La solución no es un tercer agente, es una spec o unos tests que ninguno de los dos pueda reinterpretar.

    El bucle. El revisor pide un cambio, el implementador lo hace, el revisor pide otro. Sin un tope de rondas, eso no termina nunca, o termina cuando se acaba tu cuota. Pon el límite en el prompt del orquestador: dos rondas y, si sigue habiendo desacuerdo, me lo traes a mí.

    El estado que miente. Herdr deduce el estado leyendo lo que el agente pinta en pantalla, y la propia documentación avisa de que Antigravity y Grok cuentan como idle en cuanto vuelven a su prompt, aunque tengan subagentes trabajando. El issue más grave abierto: una aprobación de un subagente de Antigravity que se detecta como idle en vez de blocked, sin notificación, y que caduca sola a los 60 segundos (hay casos parecidos en #2354 y #5004, este con Claude Code).

    Si tu orquestador espera a idle para leer el resultado, puede leer un trabajo a medias.

    El orquestador que contesta por ti. En Hacker News, un usuario cuenta que, con Rex (una alternativa a Herdr), deja una sesión que mira cómo van las demás y le presenta las decisiones que necesitan de él. Ese es el rol correcto del agente principal: juntar las preguntas, no responderlas. Si la pregunta es "¿borro estos registros?", la respuesta es de una persona. En el mismo foro hay quien no ve la ventaja frente a los subagentes con comunicación de ida y vuelta de Claude Code desktop. Es una objeción razonable si solo usas Claude.

    Esto es diseño de harness, no de prompts: quién implementa, quién revisa, contra qué y cuándo para la máquina y entra una persona.

    Cuándo NO orquestar agentes de IA con Herdr

    Cuando la tarea es pequeña. Anthropic midió en su sistema de investigación multiagente (13 de junio de 2025) que un agente gasta unas 4 veces los tokens de un chat y un sistema multiagente unas 15 veces. Con cuatro agentes en cuatro paneles, cada uno con su sesión completa, pagas un multiplicador parecido por un cambio que uno solo resolvía. Lo comparé con más datos en harness multiagente vs un solo agente.

    Cuando todos necesitan el mismo contexto. Cada agente lee el repo por su cuenta. Si las subtareas dependen unas de otras, pagas varias veces la misma lectura y además tienes que sincronizarlos.

    Cuando no usas worktrees. La skill, por defecto, abre el panel ayudante en el mismo directorio y no crea worktrees salvo que lo pidas. Dos agentes escribiendo en la misma carpeta se pisan. Para que cada uno trabaje en su copia existe herdr worktree create; si no lo usas, deja que solo uno escriba y que el otro lea.

    Y si lo que necesitas es orquestar agentes de IA dentro de tu propio código, con un plan y workers en paralelo, el camino es otro: cómo se construye un orquestador de agentes IA en TypeScript.

    Lo que puedes hacer hoy

    Monta solo el bucle mínimo:

    1. Instala la skill y abre Claude Code dentro de un panel de Herdr.
    2. Escribe en tu AGENTS.md tres reglas: Codex revisa contra docs/spec.md, máximo dos rondas, la decisión final es tuya. Si tienes CLAUDE.md, Claude Code no lee AGENTS.md por su cuenta: impórtalo desde ahí con @AGENTS.md.
    3. Pide a Claude Code que lance el revisor con el bloque de comandos de arriba.
    4. Al cabo de una semana, cuenta cuántos hallazgos del revisor no habrías visto tú. Si son cero, no necesitas dos agentes.

    Si quieres entender qué pasa por debajo cuando un agente coordina a otros (el loop, las tools, cómo se reparte la memoria), está explicado en el ebook gratuito El Developer Agéntico. Diseñar ese harness completo (quién implementa, quién revisa y contra qué) es lo que trabajo en el workshop SDD + Agentic Engineering. Y si quieres llevarlo a un producto de verdad, de la idea al despliegue, es lo que hacemos en Construye con IA.

    Preguntas frecuentes

    ¿Puede Claude Code hablar con Codex directamente?

    No de forma nativa: el cross-session messaging de Claude Code solo conecta sesiones de Claude Code. Para una revisión puntual, OpenAI publica un plugin oficial, codex-plugin-cc, que añade /codex:review a Claude Code. Herdr va más allá: Claude Code usa la CLI para mandar un prompt al panel donde corre Codex, ver su trabajo en vivo y leer su respuesta, así que la conversación pasa por la terminal.

    ¿Qué agentes puede arrancar la skill de Herdr?

    Los que acepta herdr agent start --kind: la documentación de la v0.9.5 lista 24, entre ellos claude, codex, gemini, grok y agy (Antigravity). Gemini aparece como menos probado y solo con detección de estado.

    ¿Cómo evito que dos agentes se respondan en bucle?

    Pon el límite en el prompt del agente que coordina: un número máximo de rondas y una salida clara cuando se agota, por ejemplo "si tras dos rondas hay desacuerdo, para y resume las dos posturas". Usa también --timeout en agent prompt --wait, porque las esperas de Herdr no tienen timeout por defecto.

    ¿La skill de Herdr funciona fuera de Herdr?

    No. La skill comprueba que exista HERDR_ENV=1, que solo está en procesos lanzados dentro de un panel de Herdr. Si no está, el agente debe pararse y avisar. Así evita controlar una sesión que no es suya.


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

  • CLAUDE.md modular vs monolítico: cómo organizar el contexto

    CLAUDE.md modular vs monolítico: cómo organizar el contexto

    Imagina un CLAUDE.md de 400 líneas. La regla sobre migraciones está en la 312.

    "Nunca edites una migración ya aplicada; crea una nueva." Claude la edita igual. La reescribes en mayúsculas, le pones un "IMPORTANTE" y la subes al principio. Dos semanas después, otra regla deja de cumplirse.

    Decides pasar a un CLAUDE.md modular. Partes el archivo en seis piezas enlazadas con @imports. Más ordenado, sí. Pero el agente se comporta igual, porque Claude Code sigue cargando las 400 líneas al arrancar.

    Partir el archivo no es tener un CLAUDE.md modular. Lo que cambia las cosas es cuándo carga cada instrucción.

    En corto: un CLAUDE.md modular deja en la raíz solo lo que hace falta en cada sesión y mueve el resto a capas que Claude Code carga bajo demanda: reglas con paths, CLAUDE.md de subcarpeta, skills y subagentes. Los @imports ordenan pero no ahorran contexto, porque cargan al arrancar. Menos ruido y menos contradicciones reducen las alucinaciones, aunque no las eliminan.

    El porqué está en Context Engineering: cómo estructurar la memoria de tus agentes. Aquí va el mapa de Claude Code y la migración.

    ¿Qué es un CLAUDE.md modular?

    Un CLAUDE.md modular es una arquitectura de contexto en la que el archivo raíz contiene solo los hechos que Claude necesita en todas las sesiones, y cada instrucción restante vive en la capa que se carga cuando de verdad aplica.

    La documentación oficial recomienda menos de 200 líneas por CLAUDE.md, porque los archivos largos "consumen más contexto y reducen la adherencia".

    Qué meter en la raíz ya lo conté en CLAUDE.md: el system prompt de tu proyecto. Este post trata de lo que sacas de ella.

    Las capas de contexto de Claude Code y cuándo carga cada una

    El momento de carga de cada capa decide lo que pagas en la ventana. Datos de la documentación de memoria, skills y subagentes, consultada el 7 de noviembre de 2026:

    Capa Cuándo entra en contexto Qué ocupa
    CLAUDE.md raíz + CLAUDE.local.md Siempre, al arrancar. El CLAUDE.md raíz se relee tras /compact Entero (se omite si pasa de 4 MiB)
    @imports Al arrancar, con el archivo que importa. Máximo 4 saltos Entero: no ahorra nada
    .claude/rules/ sin paths Al arrancar, con la prioridad de .claude/CLAUDE.md Entero
    .claude/rules/ con paths Al leer, escribir o editar un archivo que encaja con el glob Hasta 40.000 caracteres por archivo con ventana de 200K
    CLAUDE.md de subcarpeta Al leer, escribir o editar un archivo de esa carpeta Mismo límite
    Skills Descripción siempre; cuerpo al invocarse Hasta 1.536 caracteres por descripción; el listado, ~1% de la ventana
    Subagentes Al delegar, en su propia ventana Su prompt más tu CLAUDE.md, salvo Explore, Plan u omitClaudeMd
    Auto memory MEMORY.md al arrancar; temas bajo demanda Primeras 200 líneas o 25 KB de MEMORY.md

    Dos detalles cambian decisiones.

    Los niveles managed policy, usuario, proyecto y local no se sobrescriben: se concatenan, del más amplio al más específico. Si dos se contradicen, Claude "puede elegir uno de forma arbitraria". La precedencia estricta es de settings.json, no de CLAUDE.md.

    Y un subagente no te libra del monolito. Arranca con ventana limpia, pero carga toda tu jerarquía de CLAUDE.md. Con 400 líneas en la raíz, cada subagente las paga también. Más sobre esto en arquitectura de subagentes frente al mega-prompt.

    CLAUDE.md monolítico vs modular: la comparativa

    El monolítico gana en simplicidad; el modular, en precisión. Ninguno es gratis:

    Criterio Monolítico Modular
    Coste fijo por sesión Todo el archivo Raíz, reglas sin paths y listado de skills
    Encontrar una regla Un sitio, Ctrl+F Tienes que saber qué capa la tiene
    Contradicciones Frecuentes, pero visibles en una lectura Menos por pieza, invisibles entre piezas
    Previsibilidad Lo que está, carga Depende de que el agente toque el archivo que dispara la regla
    Limitación o riesgo Pasadas 200 líneas baja la adherencia y la regla 312 compite con todo Una regla con paths que no se dispara no existe para Claude, y no te avisa

    Mi opinión: a partir de 200 líneas, el monolítico ya no es una opción neutral. Es deuda, y un CLAUDE.md modular es la forma de pagarla.

    El error más común: creer que @imports ahorra contexto

    @imports organiza, pero no difiere la carga. La documentación lo dice explícitamente: dividir en imports "ayuda a organizar, pero no reduce el contexto", porque lo importado carga junto al CLAUDE.md que lo referencia.

    Hay una trampa más fina. En el issue #16299 de anthropics/claude-code, abierto en enero de 2026 sobre reglas con paths que cargaban siempre, un usuario midió en octubre, con la versión 2.1.300, que un @import dentro de una regla con ruta carga al arrancar aunque la regla no se dispare: el cuerpo de la regla no sumaba nada, pero el import de 20.000 caracteres que llevaba dentro sí, unos 17.000 tokens.

    En el mismo hilo, otro equipo cuenta que 75 archivos de referencia en .claude/rules/ sin paths le subían el arranque a 139.500 tokens antes de abrir un archivo. Lo vieron con /context.

    Si quieres que algo cargue tarde, no lo importes.

    Qué va en cada capa: criterios para organizar CLAUDE.md

    A cada bloque de tu CLAUDE.md, una pregunta: ¿cuándo lo necesita Claude?

    Si la instrucción… Va en…
    Aplica en toda sesión (build, convenciones globales, prohibiciones) CLAUDE.md raíz
    Solo importa al tocar ciertos archivos .claude/rules/ con paths
    Es un procedimiento de varios pasos Skill
    Llena la ventana de logs o búsquedas Subagente
    Es una preferencia tuya o la URL de tu sandbox CLAUDE.local.md, en .gitignore
    Claude la deduce leyendo el código En ningún sitio: bórrala
    Debe cumplirse sin excepción Un hook o permissions.deny

    La última fila pesa más de lo que parece: CLAUDE.md es contexto, no configuración que se haga cumplir.

    En monorepos, el CLAUDE.md por carpeta tiene sus propias reglas: las detallé en Claude Code en monorepos.

    Migración de ejemplo: de 400 líneas a un CLAUDE.md modular

    Imagina un backend en TypeScript con API REST, migraciones y tests end-to-end. Su CLAUDE.md de 400 líneas se reparte así:

    Bloque Líneas Destino
    Comandos, convenciones, prohibiciones 60 CLAUDE.md raíz
    Convenciones de la API 90 .claude/rules/api.md
    Migraciones y base de datos 70 .claude/rules/migrations.md
    Procedimiento de release 80 Skill release
    Árbol de carpetas y dependencias 50 Borrado
    URLs de staging y datos de prueba 50 CLAUDE.local.md

    El coste fijo por sesión pasa de 400 líneas a 60 más la descripción de una skill. Las 160 de API y migraciones solo entran cuando el agente toca esos archivos. Cifras ilustrativas.

    proyecto/
    ├── CLAUDE.md                 # 60 líneas: lo de todas las sesiones
    ├── CLAUDE.local.md           # en .gitignore
    └── .claude/
        ├── rules/
        │   ├── api.md            # paths: src/api/**
        │   └── migrations.md     # paths: src/db/**/*.ts
        └── skills/
            └── release/
                └── SKILL.md      # el cuerpo carga solo al invocarse
    

    Y la regla que no se cumplía, ahora pegada al código al que aplica:

    ---
    paths:
      - "src/db/**/*.ts"
    ---
    
    # Migraciones
    
    - Nunca edites una migración que ya está en main. Crea una nueva.
    - Cada migración lleva su `down`.
    - Ejecuta `npm run db:check` antes de dar la tarea por terminada.
    

    Para comprobarlo, ejecuta /context all al empezar: la regla de migraciones no debe estar en Memory files. Para ver cuándo entra, registra la carga con el hook InstructionsLoaded y pide a Claude que lea un .ts de src/db/. Si tu repo usa AGENTS.md, revisa antes cómo convive con CLAUDE.md: por defecto, un CLAUDE.md en la raíz hace que Claude deje de leerlo, salvo que lo importe con @AGENTS.md.

    Auto memory en Claude Code: por qué no es tu CLAUDE.md

    La memoria persistente de Claude Code son dos sistemas: CLAUDE.md lo escribes tú y auto memory lo escribe Claude. Auto memory vive en ~/.claude/projects/<proyecto>/memory/, solo en tu máquina.

    Al arrancar carga el índice MEMORY.md, hasta 200 líneas o 25 KB; los archivos de tema, bajo demanda. Es el patrón modular aplicado a la memoria.

    No la uses para reglas de equipo: no viaja por git ni llega a los subagentes. Un subagente puede tener su propia memoria con el campo memory, pero es otro directorio, no la tuya. La revisas con /memory. Cómo la uso en el día a día está en mi flujo real con CLAUDE.md y memoria.

    Si quieres llevar esto a la memoria y las herramientas de un agente propio, el ebook gratuito El Developer Agéntico lo trata a fondo.

    Por qué el contexto modular reduce alucinaciones (sin eliminarlas)

    El context engineering en Claude Code no hace que el modelo deje de inventar. Le quita motivos, por tres vías.

    Menos ruido. Si la sesión no toca la base de datos, las reglas de migraciones no compiten por atención.

    La regla llega cuando importa. Una regla con paths entra cuando Claude abre el archivo afectado, justo antes de decidir, aunque tras un /compact tiene que volver a dispararse.

    Menos contradicciones. Ante instrucciones contradictorias, Claude puede elegir una de forma arbitraria. Archivos pequeños de un solo tema se revisan mejor, y /doctor prompt-audit (desde la versión 2.1.283) busca archivos que chocan entre sí.

    Lo que no resuelve: una regla ambigua sigue siéndolo aunque cargue a tiempo. Revisar lo que genera el agente contra una especificación sigue siendo necesario; es lo que practicamos en el workshop de SDD + Agentic Engineering.

    Cuándo NO modularizar tu CLAUDE.md

    Si tu CLAUDE.md cabe en 100 líneas. Un CLAUDE.md modular añade indirección sin ahorrar nada. Un archivo que lees en un minuto se audita mejor que cinco.

    Si tu agente escribe mucho por Bash. En el issue #93248, de septiembre de 2026, un usuario documentó con la versión 2.1.267 que su regla de TypeScript no cargó al crear un .ts desde cero. Otro midió en octubre, con la 2.1.296, que la herramienta Write ya la dispara, pero que las escrituras por Bash (sed -i, >, heredocs) y los comandos con pipes no cargan nada; las lecturas simples con cat o head sí. Una regla crítica con ruta puede no llegar nunca.

    Si la regla tiene que sobrevivir a /compact. Las reglas con paths entran en el historial y la compactación las resume con todo lo demás; no vuelven hasta que Claude toque otra vez un archivo que encaje. La documentación lo dice claro: si una regla debe persistir, quítale paths o súbela al CLAUDE.md raíz. Para la regla de migraciones del ejemplo, si es crítica, valora dejarla en la raíz o respaldarla con un hook.

    Si nadie va a mantener el mapa. Sin ese criterio, el modular acumula contradicciones igual que el monolítico, pero escondidas.

    Empieza por medir, no por partir

    Así empieza un CLAUDE.md modular: ejecuta /context all y mira qué carga al arrancar. Luego marca cada bloque de tu CLAUDE.md con su respuesta a "¿cuándo lo necesita Claude?". Lo que no sea "siempre" tiene otro sitio. Lo que Claude deduce del código, bórralo.

    Si quieres aplicarlo de principio a fin en un proyecto, de la spec al producto, es el flujo del curso Construye con IA: de la idea al producto con Claude Code.

    Preguntas frecuentes

    ¿Los @imports de CLAUDE.md reducen el consumo de contexto?

    No. Los archivos importados cargan al arrancar junto al CLAUDE.md que los referencia, con un máximo de cuatro saltos. Sirven para organizar o compartir un AGENTS.md, no para diferir la carga.

    ¿Cuándo se cargan los CLAUDE.md de las subcarpetas?

    Los del directorio donde arrancas y los superiores cargan al inicio. Los de subcarpetas, la primera vez que Claude lee, escribe o edita un archivo en ella. Por eso no salen en /context al empezar; cuando cargan, verás una línea Loaded con su ruta.

    ¿Sigue existiendo CLAUDE.local.md?

    Sí. Es el nivel local del proyecto: carga después de CLAUDE.md en el mismo directorio y debe ir en .gitignore. Si tu proyecto depende de AGENTS.md, crear un CLAUDE.local.md hace que Claude deje de leerlo, salvo que cambies la opción Project instructions en /config.

    ¿Cuánto contexto ocupa una skill que no he invocado?

    Su entrada en el listado: nombre y descripción, recortados a 1.536 caracteres. El listado completo tiene un presupuesto del 1% de la ventana. El cuerpo de SKILL.md entra al invocarla, y con disable-model-invocation: true ni siquiera la descripción está en contexto.


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

  • Usos de Herdr: 7 recetas reales para tus agentes de IA

    Usos de Herdr: 7 recetas reales para tus agentes de IA

    Imagina que llevas un mes con Herdr y solo conoces uno de sus usos: lo abres, lanzas un Claude Code en un panel y trabajas igual que antes, solo que con una barra lateral más bonita.

    Es lo que pasa con las navajas suizas: usas la hoja grande y nunca abres el resto. Y en Herdr las piezas que no usas son las que ahorran tiempo.

    Aquí van los usos de Herdr para agentes de IA que casi nadie abre: siete recetas con los comandos exactos y el aviso de cuándo no compensan.

    En corto: los usos de Herdr que más rinden están en su CLI y su configuración, no en la barra lateral: agentes en un servidor que revisas por SSH, un worktree con un agente por cada PR, avisos cuando acaba una suite y recuperar el layout tras un reinicio. Son siete recetas, cada una con su comando y el caso en el que no compensa. Todo está comprobado contra Herdr v0.9.5.

    ¿Qué hace posibles estos usos de Herdr?

    Herdr es un multiplexor de terminal open source para agentes de IA que mantiene vivas las sesiones en un servidor en segundo plano, detecta si cada agente está trabajando, bloqueado o ha terminado, y expone una CLI con salida JSON para controlarlo todo por código.

    La instalación y la comparativa con tmux están en qué es Herdr. Aquí van los usos, comprobados contra la documentación de la v0.9.5, del 14 de octubre de 2026. Varias recetas usan jq para leer la salida JSON.

    Los 7 usos de Herdr de un vistazo

    Estos son los siete usos de Herdr con el problema que resuelve cada uno, el comando clave y el caso en el que no compensa:

    # Problema Comando o ajuste clave Cuándo no merece la pena
    1 Los agentes mueren al cerrar el portátil ssh + herdr en el servidor, ctrl+b q Si todo corre en tu portátil
    2 Proyectos mezclados en la misma barra lateral herdr --session <nombre> Si solo tienes un proyecto activo
    3 Revisar varios PRs uno detrás de otro herdr worktree create + herdr agent start Con PRs de diez líneas
    4 Vigilar una suite larga herdr notification show Con tests que tardan segundos
    5 No ves que un agente te espera tab_bar_right + herdr agent list Con uno o dos agentes
    6 Salir del layout para ver el diff [[keys.command]] con type = "popup" Si ya revisas en el IDE
    7 Perder el layout tras un reinicio session-snapshots/ + pane_history Si nunca paras el servidor

    Receta 1: dejar agentes en un servidor y revisarlos desde el móvil

    Si los agentes corren en tu portátil y lo suspendes, se paran con él. La solución es que Herdr viva en la máquina donde está el código y tú solo te conectes, según la guía de trabajo de Herdr:

    ssh tu-usuario@servidor
    herdr
    # lanza tus agentes; para irte sin matar nada:
    # ctrl+b q
    

    Desde el móvil sirve cualquier cliente SSH: te conectas y ejecutas herdr. No hace falta app ni panel web, y la interfaz se adapta a pantallas estrechas.

    Cuándo no: si el código y las credenciales viven en tu portátil, mudarlo todo a un servidor cuesta más que dejar la tapa abierta. Y ojo con engancharte desde varios clientes: según el issue #4787, en macOS cada cliente reproduce su propio sonido por el mismo evento, y con ocho clientes el reportero vio coreaudiod por encima del 200 % de CPU.

    Receta 2: una sesión con nombre por proyecto

    Con dos proyectos en el mismo servidor, la barra lateral mezcla agentes que no tienen nada que ver. Una sesión con nombre es un servidor independiente, con sus propios paneles y workspaces (página de persistencia):

    herdr --session trabajo        # abre o se engancha a la sesión "trabajo"
    herdr --session personal
    herdr session list             # qué sesiones están vivas
    herdr session stop personal    # para esa sesión y sus paneles
    

    Para que un script hable con una sesión concreta, exporta HERDR_SESSION=trabajo antes de llamar a la CLI.

    Cuándo no: las sesiones comparten el mismo config.toml, y los plugins instalados son globales para tu usuario. Si buscas aislamiento real entre proyectos, una sesión con nombre no te lo da.

    Receta 3: revisar varios PRs en paralelo, un agente por worktree

    Para mí, este es el uso de Herdr que más tiempo ahorra: tres PRs, tres worktrees, tres agentes revisando a la vez.

    herdr worktree create, de la CLI de Herdr, hace checkout de una rama local si ya existe y devuelve en JSON el panel raíz del workspace nuevo. Con eso, el bucle sale solo (referencia de la CLI):

    repo=~/proyectos/api
    git -C "$repo" fetch origin main
    for pr in 412 415 418; do
      git -C "$repo" fetch origin "pull/$pr/head:pr-$pr"
      ws=$(herdr worktree create --cwd "$repo" --branch "pr-$pr" --label "pr-$pr" --no-focus)
      pane=$(printf '%s\n' "$ws" | jq -r '.result.root_pane.pane_id')
      herdr agent start "pr-$pr" --kind claude --pane "$pane" -- --permission-mode plan
      herdr agent prompt "pr-$pr" "Revisa git diff origin/main...HEAD. Lista bugs y riesgos con fichero y línea."
    done
    
    for pr in 412 415 418; do
      herdr agent wait "pr-$pr" --timeout 900000
      herdr agent read "pr-$pr" --source recent-unwrapped --lines 120
    done
    

    --permission-mode plan deja a Claude Code en solo lectura, y --kind codex pone a otro modelo a revisar (ese flag es de Claude Code: con Codex usa su propio modo de solo lectura). Al terminar, herdr worktree remove --workspace <id> borra el checkout, nunca la rama.

    Un aviso: Herdr crea cada worktree en una carpeta nueva (por defecto, bajo ~/.herdr/worktrees), y Claude Code puede preguntarte si confías en ella antes de aceptar nada. Si el agente aparece como blocked, el prompt no se ha enviado: acepta el diálogo en su panel y repite el agent prompt.

    Cómo repartir trabajo sin que los agentes se pisen está en dirigir agentes de IA en paralelo, y la parte de Git en worktrees con Claude Code.

    Cuándo no: con PRs pequeños, abrir tres sesiones completas cuesta más tokens que leer el diff tú. Y agent wait no tiene timeout por defecto: sin --timeout, puede esperar para siempre. Y si el servidor se reinicia, el agente vuelve sin --permission-mode plan (lo explica la receta 7): ya no es una revisión de solo lectura.

    Receta 4: que Herdr te avise cuando termina la suite

    Herdr avisa cuando un agente termina, pero tu suite e2e no es un agente. Para eso está herdr notification show, que funciona desde cualquier panel:

    npm run test:e2e; herdr notification show "Suite e2e terminada" --sound done
    

    Para disparar el aviso según la salida, combina pane run con pane wait-output:

    herdr pane run w1:p3 "npm run test:e2e"
    herdr pane wait-output w1:p3 --regex "[0-9]+ (passed|failed)" --timeout 1800000 \
      && herdr notification show "e2e" --body "Ya hay resultado" --sound request
    

    Lánzalo en un panel limpio: wait-output también mira lo que ya hay en pantalla, y un "failed" antiguo dispararía el aviso antes de tiempo.

    Cuándo no: notification show usa la entrega configurada en [ui.toast], y su valor por defecto es "off": sin cambiarlo, no verás ningún aviso emergente. Además, el issue #5238 documenta que con delivery = "terminal" en el terminal foot la CLI responde shown: true y no aparece nada.

    Receta 5: contar agentes bloqueados en la barra de estado

    Con seis agentes, el que te espera se pierde entre los que trabajan. La barra de pestañas admite entradas command que se ejecutan cada pocos segundos (configuración):

    [ui]
    tab_bar_right = [
      { type = "command", command = "~/.config/herdr/blocked.sh", interval_seconds = 5, timeout_seconds = 2 },
    ]
    

    Y el script, con los campos del esquema de la API (agents[].agent_status):

    #!/bin/sh
    n=$("$HERDR_BIN_PATH" agent list | jq '[.result.agents[] | select(.agent_status == "blocked")] | length')
    [ "$n" -gt 0 ] && echo "$n bloqueados"
    

    Dale permisos de ejecución con chmod +x ~/.config/herdr/blocked.sh. Si no hay ninguno bloqueado, el script no imprime nada y Herdr vacía la entrada. Para saltar al bloqueado, prefix+g abre el selector y la tecla b filtra los blocked.

    Cuándo no: con uno o dos agentes, la barra lateral ya te lo dice. Y en Windows estos comandos se ejecutan con cmd.exe /d /c, así que el script de arriba no te sirve tal cual.

    Receta 6: revisar el diff del agente en un popup

    Un agente termina y quieres ver qué ha tocado sin romper el layout. Un comando personalizado de tipo popup abre una ventana flotante y desaparece al salir. Es el ejemplo de lazygit de la documentación, con -p para abrir el repo del panel activo:

    [[keys.command]]
    key = "prefix+alt+g"
    type = "popup"
    command = "lazygit -p \"$HERDR_ACTIVE_PANE_CWD\""
    description = "diff del panel activo"
    width = "80%"
    height = "80%"
    

    Herdr pasa HERDR_ACTIVE_PANE_CWD a los comandos personalizados, así que en un worktree ves el diff de ese worktree.

    Cuándo no: si revisas los cambios en el IDE, esto es una ventana más. Y en Windows la sintaxis de variables cambia a %HERDR_ACTIVE_PANE_CWD%.

    Receta 7: recuperar el layout tras reiniciar el servidor

    Desengancharte con ctrl+b q no pierde nada. Parar el servidor sí: los procesos mueren y Herdr solo restaura la forma de la sesión. La página de estado de sesión da tres piezas para recuperar más:

    [experimental]
    pane_history = true   # vuelve el contenido reciente de cada panel tras reiniciar
    

    La reanudación de agentes viene activada (session.resume_agents_on_restore = true) y funciona si instalaste la integración del agente. Y si un reinicio te deja un layout roto, Herdr guarda hasta 48 copias en session-snapshots/, junto a session.json: localizas el directorio con herdr session list --json, paras el servidor, copias el snapshot elegido sobre session.json y arrancas.

    Cuándo no: pane_history viene apagado porque la salida de los paneles puede incluir tokens y secretos, y se guarda en disco en session-history.json.

    Además, la reanudación no conserva los flags con los que arrancaste el agente: en el PR #3302, un usuario con Herdr 0.9.4 cuenta que lanzó Claude Code con --name, --autocompact y --append-system-prompt-file, y tras el reinicio volvió como claude --resume <id>, sin ellos. El PR sigue abierto.

    Cuándo NO usar estas recetas de Herdr

    El estado es una deducción. Herdr lee la pantalla de cada panel para decidir si un agente está blocked. Si no reconoce un diálogo, cae a idle. La receta 5 cuenta lo que Herdr cree, no lo que pasa: un agente esperando en un selector raro no sumará.

    Es un proyecto 0.x. Los comandos son de la v0.9.5, y la propia documentación marca como experimentales piezas como pane_history o herdr update --handoff. Antes de actualizar un servidor donde automatizas, prueba tus scripts con la versión nueva.

    Windows tiene huecos. El attach directo a un solo terminal no existe en Windows nativo, los plugins están en preview y las recetas 5 y 6 necesitan otra sintaxis.

    Por dónde empezar con estos usos de Herdr

    Elige una receta, no siete. Si ya tienes un servidor, empieza por la 1: es la que más cambia con menos configuración. Si trabajas en local, prueba la 3 con dos PRs reales esta semana y compara lo que encontró cada agente con lo que habrías visto tú.

    Si quieres entender qué pasa dentro de cada agente mientras Herdr lo vigila (el loop, las tools, la memoria), está explicado en el ebook gratuito El Developer Agéntico.

    Y si quieres llevar ese flujo a un producto real con Claude Code, es lo que hacemos en Construye con IA. Decidir quién revisa qué, y contra qué contrato, es el núcleo del workshop SDD + Agentic Engineering.

    Preguntas frecuentes

    ¿Puedo usar Herdr desde el móvil?

    Sí, sin app. Te conectas por SSH al servidor donde corre Herdr con cualquier cliente SSH y ejecutas herdr. La interfaz se adapta a pantallas estrechas. Tus agentes tienen que estar en ese servidor, no en tu portátil.

    ¿Herdr puede revisar varios pull requests a la vez?

    Herdr no revisa nada: arranca agentes que revisan. Con herdr worktree create abres un checkout por rama y con herdr agent start lanzas un agente en cada uno. Antes tienes que traer cada PR como rama local, por ejemplo con git fetch origin pull/<n>/head:pr-<n>.

    ¿Puede Herdr avisarme cuando termina un proceso que no es un agente?

    Sí. herdr notification show lanza un aviso desde cualquier panel, así que puedes encadenarlo al final de un comando, como npm run test:e2e; herdr notification show "Suite terminada", o dispararlo con herdr pane wait-output cuando la salida coincide con una expresión regular. Antes tienes que cambiar ui.toast.delivery, que por defecto vale "off".

    ¿Se pierden los agentes si reinicio el servidor de Herdr?

    Los procesos sí se pierden. Herdr restaura el layout y, si instalaste la integración del agente, reanuda su conversación. No conserva los flags con los que lo arrancaste, y el contenido de los paneles solo vuelve si activas pane_history.


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

  • Verificación formal con IA: lo que AlphaProof Code enseña

    Verificación formal con IA: lo que AlphaProof Code enseña

    El 10 de noviembre de 2026 Google DeepMind publicó un paper con una frase que cualquiera que programe con agentes debería leer dos veces: "none of the authors wrote any proof code". Ninguno de los autores escribió una sola línea de prueba.

    Y, sin embargo, el repositorio contiene unos 6,5 millones de líneas de pruebas en Lean. Demuestran propiedades de seguridad de libsignal, la implementación de referencia del protocolo Signal. No del diseño en papel: del binario AArch64 que sale de compilar el código Rust sin tocarlo. Es verificación formal con IA sobre código que usa muchísima gente.

    Entonces, ¿a qué dedicaron cinco personas cuatro semanas? La respuesta es lo que importa si usas IA para programar, y no tiene nada que ver con matemáticas.

    En corto: En la verificación formal con IA de AlphaProof Code, los agentes generan las pruebas y el kernel de Lean, un comprobador determinista, decide cuáles valen. El trabajo humano se desplazó a escribir y revisar la especificación: qué hay que demostrar. Una prueba formal solo garantiza lo que dice la spec, y por eso la spec es ahora el cuello de botella.

    ¿Qué es la verificación formal con IA?

    La verificación formal con IA es el proceso en el que modelos de lenguaje generan demostraciones de que un programa cumple una especificación formal, y un verificador determinista, como el kernel de Lean, acepta o rechaza cada paso.

    La clave está en la segunda mitad. El modelo puede alucinar lo que quiera: si una prueba tiene un error lógico, Lean la rechaza. Por eso el paper trata las pruebas de los agentes como untrusted. En lo que hay que confiar es en la especificación, y esa no se puede comprobar automáticamente: si está mal, la garantía se debilita sin que nada falle.

    Qué verificó AlphaProof Code en el protocolo Signal

    AlphaProof Code demostró propiedades de seguridad de las sesiones uno a uno de libsignal, el handshake PQXDH y el Triple Ratchet, sobre el código máquina compilado.

    El objetivo fue libsignal-protocol v0.105.4 con spqr v1.6.0, envuelto en una pequeña herramienta de línea de comandos (libsignal-cli) y compilado con rustc estándar a un ejecutable Linux AArch64. Las propiedades demostradas son forward secrecy, seguridad post-compromiso, autenticación y secreto del handshake, y confidencialidad y autenticidad de los mensajes, en dos modelos: el simbólico y el computacional.

    Estas son las cifras, todas del paper técnico salvo donde se indica:

    Dato (paper del 10 nov 2026) Valor
    Código verificado ~560 KB, ~140.000 instrucciones AArch64
    Pruebas Lean generadas por agentes ~6,5 millones de líneas
    Lo que un humano debe leer y confiar ~26.000 líneas (~18.000 de specs + ~8.000 de semántica AArch64 y nombres de símbolos)
    Equipo y duración 5 personas, 4 semanas
    Agentes por campaña de pruebas 40 a 80, entre 24 y 72 horas en una sola máquina
    Código marcado para revisión humana ~1 %, según el post de DeepMind
    Modelos Specs: Gemini 4 Carbon y Claude Opus 5.5. Pruebas: solo Gemini 4 Carbon
    Referencia histórica seL4: 20 años-persona. CompCert: 6

    Divide la segunda fila entre la tercera: unas 250 líneas de prueba por cada línea que un humano tiene que revisar. Esa proporción resume el proyecto.

    Para comprobar que las specs no eran decorativas, el equipo reintrodujo dos bugs ya corregidos de libsignal, recompiló y demostró en Lean que esos binarios violaban el teorema de seguridad simbólico. Una spec que no detecta bugs conocidos no sirve de nada.

    Por qué en la verificación formal con IA el trabajo humano está en la spec

    El paper lo dice sin adornos en la sección 7: "once proofs become cheap, the hard question is what to prove. The majority of our effort went not into proofs but into specifications." Cuando las pruebas salen baratas, la pregunta difícil es qué demostrar.

    El proceso es más interesante que las cifras. Quien escribe la spec redacta unos pocos enunciados de alto nivel. Un agente de otra familia de modelos la revisa: si es fiel a la literatura y al código, y si es lo bastante fuerte para descartar bugs conocidos o plausibles. Tras muchas rondas de feedback humano, la spec se aprueba y se congela como objetivo de los agentes de prueba.

    Lo más revelador: escribir specs contra código real destapó errores en análisis publicados. El equipo documenta 15 huecos o bugs en el análisis computacional del Double Ratchet que usaron como referencia, y consultas ProVerif de otro paper que, tal como están impresas, hacen falsa la forward secrecy del receptor. Eran especificaciones revisadas por pares, y estaban mal.

    Este es el mismo patrón que defiendo para revisar código de agentes. El agente genera mucho, un comprobador determinista decide qué pasa y tú escribes y revisas el contrato. Lo explico paso a paso en Revisión por Contrato, y es la tesis del libro de Spec-Driven Development: la especificación es el artefacto que no puedes delegar.

    Qué se discute en Hacker News sobre AlphaProof Code

    El hilo de Hacker News del anuncio sumaba 679 puntos y 197 comentarios el 16 de noviembre de 2026. El subhilo que encabeza la discusión no debate si la IA sabe demostrar. Debate la spec.

    Lo abre hedora con una sospecha basada en su experiencia: "I've had Claude formally verify crypto and data storage formats. It wrote theorems that looked fine and the formal verification passed but the resulting code contained many, many bugs." Los teoremas parecían correctos, la verificación pasaba y el código tenía muchísimos bugs.

    El usuario fooker lo resumió así: "You'd just move from bugs in code to bugs in the spec." Y añadió: "AI will happily change the spec for you so the code verifies though, but that doesn't solve the trust issue." Es decir: pasas de bugs en el código a bugs en la spec, y la IA cambiará la spec encantada para que el código verifique.

    En el mismo subhilo, cortesoft recordó que eso vale para cualquier verificación formal: "You can only formally prove that code does what a spec says". Y pyrale dejó la pregunta que deberías hacer ante cualquier anuncio así: "the first question you should ask is what was proven."

    Estoy de acuerdo con los cuatro, y por eso el diseño de DeepMind es la lección correcta: la spec se congela antes de que trabajen los agentes de prueba. Si el agente que tiene que hacer pasar algo puede editar ese algo, no tienes verificación: tienes teatro.

    Límites: lo que la verificación formal con IA no garantiza

    La spec puede estar mal. Es el límite principal y el propio paper lo demuestra encontrando errores en specs publicadas. Una prueba en Lean garantiza que el binario cumple los teoremas, no que los teoremas digan lo que necesitas.

    Todo descansa en supuestos. El modelo simbólico idealiza las primitivas criptográficas: los hashes nunca colisionan y las firmas no se falsifican sin la clave. El computacional asume la seguridad de Gap-DH, XEdDSA, Kyber1024 (resistencia a colisiones), HKDF y HMAC (como PRF/PRG) y AES-CBC con HMAC. Además se confía en el kernel de Lean, en la semántica AArch64 y en los contratos de algunas rutinas de bajo nivel.

    El alcance es estrecho y explícito. Según el paper quedan fuera los grupos, el estado multidispositivo, la generación de claves (keygen no se verifica), los canales laterales y la recuperación post-cuántica que promete SPQR. El teorema computacional no da garantías contra un atacante cuántico, y su cota deja de decir nada en sesiones de unos 25.000 mensajes si casi cada mensaje abre una nueva época.

    No es la app. Lo verificado es una librería dentro de un ejecutable de prueba. Variantes del protocolo se usan en WhatsApp, Messenger y Google Messages, pero esas apps no son el objeto de la verificación.

    Verificación formal con IA a escala de un developer normal

    No necesitas Lean para aplicar la lección de la verificación formal con IA. Necesitas el mismo reparto de papeles: el agente genera, algo determinista decide y tú escribes lo que hay que cumplir. Esta escala va de lo más barato a lo más fuerte:

    Técnica Quién decide si vale Qué escribes tú Qué no cubre
    Tipos estrictos y branded types El compilador Los tipos del dominio Lógica y valores en runtime
    Property-based testing El runner, con 100 casos aleatorios por defecto Las propiedades Solo muestrea, no demuestra
    Mutation testing Stryker Nada nuevo: mide tus tests Lo que los tests no preguntan
    Contrato revisado + CI El pipeline Criterios de aceptación y tests congelados Lo que el contrato olvidó
    Prueba formal (Lean, Dafny) El verificador (kernel de Lean; Z3 en Dafny) Teoremas y supuestos Lo que la spec no dice

    Un ejemplo con fast-check. La propiedad es tu spec: la escribes tú y el agente no puede tocarla.

    import { test } from 'vitest';
    import fc from 'fast-check';
    import { applyDiscount } from './pricing'; // implementación generada por el agente
    
    // Spec escrita y revisada por un humano. Fuera del alcance de escritura del agente.
    test('un descuento nunca deja el precio negativo ni lo sube', () => {
      fc.assert(
        fc.property(
          fc.integer({ min: 0, max: 1_000_000 }), // precio en centavos
          fc.integer({ min: 0, max: 100 }),       // porcentaje
          (price, pct) => {
            const result = applyDiscount(price, pct);
            return result >= 0 && result <= price;
          }
        )
      );
    });
    

    Esto no es una prueba formal: prueba 100 entradas aleatorias por defecto (más si subes numRuns), no todas. Pero tiene la misma forma. Bloquea la escritura de ese directorio en los permisos del agente y el comentario de fooker se convierte en regla. En Claude Code basta con una regla de denegación en .claude/settings.json:

    { "permissions": { "deny": ["Edit(./tests/spec/**)"] } }
    

    Ojo: la regla bloquea las herramientas de edición del agente, no un script de Node o Python que abra el archivo por su cuenta. Para un bloqueo a nivel de sistema, la documentación de permisos remite al sandbox. Montar ese circuito con Claude Code de punta a punta es lo que hacemos en Construye con IA.

    Lo que te llevas de AlphaProof Code

    Elige una función que haya escrito un agente esta semana y escribe, antes de mirar el código, dos propiedades que siempre deban cumplirse. Ponlas en un archivo que el agente no pueda editar. Si las propiedades fallan, has encontrado un bug. Si no se te ocurre ninguna, has encontrado algo peor: no sabías qué tenía que hacer ese código.

    Esa es la habilidad que DeepMind acaba de señalar como cuello de botella. Si prefieres empezar por algo gratis, el ebook El Developer Agéntico explica cómo construir agentes de IA desde cero. Para practicarla con método, en el workshop SDD + Agentic Engineering trabajamos specs, contratos y revisión de lo que generan los agentes.

    Preguntas frecuentes

    ¿Qué es AlphaProof Code?

    Es un framework multiagente de Google DeepMind, presentado el 10 de noviembre de 2026, para especificar y verificar software en Lean. Los humanos deciden qué demostrar y aprueban la especificación; equipos de agentes generan las pruebas y el kernel de Lean las acepta solo si son correctas.

    ¿AlphaProof Code demuestra que Signal no tiene bugs?

    No. Demuestra que el binario de libsignal v0.105.4 cumple unos teoremas de seguridad concretos en sesiones uno a uno, bajo supuestos explícitos. Grupos, multidispositivo, generación de claves y canales laterales quedan fuera, y tampoco cubre las apps.

    ¿Qué modelos de IA usó DeepMind?

    Según el paper, las especificaciones se escribieron con agentes basados en Gemini 4 Carbon y Claude Opus 5.5, y las pruebas las generaron en exclusiva agentes basados en Gemini 4 Carbon. Ninguno de los autores escribió código de prueba.

    ¿Puedo usar AlphaProof Code en mi proyecto?

    No hay producto ni API anunciados. DeepMind ha publicado las especificaciones y las pruebas en GitHub para que cualquiera las revise, pero no el framework como herramienta.

    ¿Qué diferencia hay entre verificación formal y property-based testing?

    La verificación formal demuestra una propiedad para todas las entradas posibles; el property-based testing la comprueba en una muestra de entradas aleatorias (100 por defecto en fast-check). Las dos dependen de que la propiedad esté bien escrita.

    ¿La verificación formal con IA sustituye a los tests?

    No. Demuestra lo que dice la especificación y nada más: en el caso de Signal quedan fuera los grupos, el estado multidispositivo, la generación de claves y los canales laterales. Los tipos, los tests y el property-based testing siguen cubriendo lo que la spec no formaliza, y son mucho más baratos de escribir.


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

  • Claude Code VSCode, JetBrains o terminal: cuál elegir

    Claude Code VSCode, JetBrains o terminal: cuál elegir

    En enero de 2026, un developer contó en un issue de GitHub que había desinstalado el plugin de Claude Code de todos sus IDEs de JetBrains porque le resultaba inusable.

    El issue describía el problema: cada vez que Claude proponía un cambio, el IDE abría el diff en una pestaña nueva y le robaba el foco. Si estabas escribiendo, tus teclas acababan dentro del diff y podías aprobarlo sin querer.

    El modelo no era el problema: lo era la superficie. Claude Code en VSCode, en el plugin de JetBrains o en la terminal es el mismo agente, pero cada superficie te enseña sus cambios de una forma, te deja hacer cosas distintas y falla en sitios distintos.

    Elegir mal no rompe nada, pero trabajas con fricción y le echas la culpa al modelo.

    En corto: la extensión de Claude Code para VS Code es un panel gráfico con diffs en el editor y planes revisables, pero solo trae un subconjunto de comandos, sin el atajo ! ni autocompletado con Tab. El plugin de JetBrains (Beta) ejecuta el CLI en la terminal del IDE y le añade diffs y diagnósticos. Solo el CLI tiene todas las funciones.

    ¿Qué es la extensión de Claude Code para VS Code?

    La extensión de Claude Code para VS Code es una interfaz gráfica nativa que integra el agente de Claude Code en el editor, con diffs, planes y conversaciones dentro de VS Code en lugar de en la terminal. La documentación oficial de VS Code la presenta como "la forma recomendada de usar Claude Code en VS Code".

    Pide VS Code 1.94.0 o superior y cualquier plan de pago de Claude (Pro, Max, Team o Enterprise) o una cuenta de Claude Console, sin API key.

    Ojo: la extensión trae su propia copia privada del CLI para el panel de chat, pero no añade claude a tu PATH. Si escribes claude en la terminal integrada sin haber instalado el CLI por separado, no lo encuentra.

    Qué te da la extensión de Claude Code en VS Code

    Te da revisión sin salir del editor:

    • Diffs en el editor. En modo Manual, cada edición se abre comparada lado a lado. Aceptas o rechazas cambio a cambio (desde v2.1.275) o editas la propuesta antes de aceptarla.
    • Planes como documento. En modo Plan, VS Code abre el plan como un Markdown completo donde dejas comentarios en línea antes de que Claude empiece.
    • @-menciones con rango. Alt+K (Windows/Linux) u Option+K (Mac) inserta algo como @file.ts#5-10 a partir de tu selección.
    • Varias conversaciones. Abres conversaciones en pestañas o ventanas, cada una con su historial.
    • Uso del plan. /usage abre el diálogo Account & usage con las barras de límite de tu plan.
    • Checkpoints. Pasas el ratón por un mensaje y bifurcas la conversación desde ahí, rebobinas el código o las dos cosas.

    La extensión y el CLI comparten historial: empiezas en el panel y sigues en la terminal con claude --resume.

    Claude Code en JetBrains: el plugin es un puente al CLI

    El plugin "Claude Code [Beta]" no es una interfaz propia: ejecuta el comando claude en la terminal integrada del IDE y se conecta a él. Según la documentación de JetBrains, no incluye el CLI: hay que instalar las dos piezas.

    Funciona en la mayoría de IDEs de JetBrains, entre ellos IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm y GoLand. Lo que añade sobre la terminal es:

    • Ctrl+Esc (Windows/Linux) o Cmd+Esc (Mac) para abrir Claude Code desde el editor.
    • Los diffs se abren en el visor de diferencias del IDE. Se cambia con la opción Diff tool de /config.
    • La selección o la pestaña activa se comparte sola con Claude.
    • Alt+Ctrl+K (Windows/Linux) o Cmd+Option+K (Mac) inserta referencias como @src/auth.ts#L1-99.
    • Claude lee las inspecciones del IDE (lint, errores de sintaxis) con la herramienta getDiagnostics.

    Ojo: según la doc, Claude Code no pide los diagnósticos por su cuenta después de editar. Si quieres que mire los errores del IDE, pídeselo.

    Como lo que corre es el CLI, tienes sus comandos. Desde una terminal externa, /ide la conecta al IDE. Si tu día a día está en WebStorm o IntelliJ, este es tu camino.

    Claude Code VSCode vs JetBrains vs terminal: tabla de funciones

    La diferencia más grande está en los comandos: solo el CLI los tiene todos. La tabla parte de las dos páginas de la doc consultadas el 10 de octubre de 2026.

    Función CLI (terminal) VS Code (extensión) JetBrains (plugin Beta)
    Instalación CLI standalone Trae CLI privado; claude no queda en el PATH Plugin + CLI aparte
    Interfaz Terminal Panel gráfico CLI en la terminal del IDE
    Comandos y skills Todos Un subconjunto Los del CLI*
    Atajo ! de Bash Sí No Sí (es el CLI)*
    Autocompletado con Tab Sí No Sí (es el CLI)*
    Diffs Terminal, o IDE si está conectado Editor, cambio a cambio Visor de diffs del IDE
    Revisión del plan Modo plan Markdown con comentarios Modo plan del CLI*
    @-mención con rango A mano, o selección compartida si hay IDE conectado* Alt+K / Option+K Alt+Ctrl+K / Cmd+Option+K
    Diagnósticos del IDE Con IDE conectado Panel Problems (v2.1.285+) Inspecciones, si Claude las pide
    Varias conversaciones Varias terminales* Pestañas, ventanas y grupos Varias terminales*
    Checkpoints Sí Sí Sí (es el CLI)*
    Limitación principal Sin diffs gráficos sin IDE Subconjunto de comandos, sin ! ni Tab Beta; el diff roba el foco; en WSL2 hay que ajustar la red

    Las celdas marcadas con * son deducción mía, no salen de la doc. La de JetBrains dice que el plugin ejecuta claude, pero no publica tabla de paridad; la única tabla oficial es la de VS Code frente al CLI.

    El debate real: el diff que roba el foco en JetBrains

    El issue #9765 de anthropics/claude-code es la mejor lectura sobre los límites del plugin. Abierto el 17 de octubre de 2025, su autor lo marcó como severidad alta: en IntelliJ, cada diff abre una pestaña que roba el foco y tus teclas acaban dentro del diff.

    Anthropic lo cerró el 14 de enero de 2026 como not planned. Días después, el mantenedor explicó que la API de plugins de JetBrains no permite mostrar un diff sin coger el foco. Propuso dos salidas: el modo de aceptar ediciones automáticamente (y revertir con /rewind) o poner Diff tool en terminal desde /config, perdiendo el diff visual.

    Otro hilo, el issue #1232 (113 comentarios), trata de Claude Code en WSL que no detecta el IDE. En los comentarios funcionaron dos arreglos: pasar WSL2 a networkingMode=mirrored o abrir el firewall de Windows a la subred de WSL. Hoy la doc recoge los dos y recomienda el del firewall, porque no te obliga a cambiar el modo de red (mirrored, además, pide Windows 11 22H2). Anthropic lo cerró como resuelto en agosto de 2025, pero el problema de red sigue apareciendo.

    Cuándo usar la extensión de Claude Code y cuándo la terminal

    Elige según cómo revisas, no según dónde escribes el prompt.

    Usa Claude Code en VS Code si revisas cada cambio antes de aceptarlo, si trabajas a partir del plan o si llevas varias tareas en paralelo y quieres verlas en pestañas.

    Usa el plugin de JetBrains si tu día a día está en WebStorm, IntelliJ o PyCharm. Obtienes el CLI completo más el visor de diffs del IDE.

    Usa el CLI a pelo si necesitas un comando que el panel no trae, si tiras de ! o si trabajas en un servidor sin IDE.

    Mi regla: el panel de VS Code para revisar y la terminal integrada para todo lo que el panel no tiene.

    Si quieres el flujo completo de pasar de idea a producto con Claude Code, con revisión de cambios incluida, es lo que hacemos en el curso Construye con IA. Para la configuración inicial del agente tienes la guía de cómo configurar Claude Code para programar, y si dudas entre herramientas en vez de entre superficies, la comparativa de Claude Code y Cursor.

    Límites y riesgos de cada superficie

    JetBrains está en Beta. Lo dice el nombre y lo confirman los issues: robo de foco sin arreglo previsto, IDE no detectado en WSL2 si no ajustas la red (el bug de origen se cerró como resuelto en agosto de 2025) y, en Remote Development, el plugin va en el host remoto, no en tu máquina.

    acceptEdits en JetBrains tiene un riesgo concreto. La doc avisa de que en ese modo Claude puede modificar archivos de configuración que el IDE ejecuta solo, y eso puede saltarse los permisos de Bash. El modo auto tiene el mismo problema. Recomienda el modo Manual.

    Claude Code en VS Code no es el CLI completo. Solo trae un subconjunto de comandos, y la doc no publica la lista de lo que falta: tienes que escribir / y comprobarlo en tu versión.

    Las funciones van atadas a la versión. Muchas piezas de la extensión piden una versión mínima de Claude Code (v2.1.275 para revisar cambio a cambio, v2.1.280 para /plan). Si un tutorial muestra algo que no ves, mira tu versión.

    Lo que esto no resuelve: ninguna superficie revisa por ti. Un diff bonito no sustituye a una spec que diga qué debía hacer el cambio.

    Cómo comprobar qué le falta a tu extensión de Claude Code

    Escribe / en el panel de Claude Code y compara la lista con los comandos que usas en la terminal. Lo que falte es lo que te obliga a tener las dos superficies abiertas.

    Saber si lo que generó el agente es correcto se decide antes de abrir el diff. Es la tesis del libro de Spec-Driven Development: primero el contrato y después el código. Para el resto del setup: extensiones de VS Code y cómo usar Claude Code a diario.

    Preguntas frecuentes

    ¿La extensión de Claude Code para VS Code tiene las mismas funciones que el CLI?

    No. Según la doc oficial, la extensión trae un subconjunto de comandos y skills, y no tiene el atajo ! de Bash ni el autocompletado con Tab. Comparte con el CLI la configuración de MCP y el historial, y también tiene checkpoints.

    ¿Necesito instalar el CLI para usar Claude Code en JetBrains?

    Sí. El plugin no incluye el CLI: ejecuta el comando claude en la terminal del IDE. Si claude no está en tu PATH, verás el aviso "Cannot launch Claude Code" y tendrás que poner la ruta completa en los ajustes del plugin.

    ¿Qué versión de VS Code necesita Claude Code?

    VS Code 1.94.0 o superior. Además necesitas un plan de pago de Claude (Pro, Max, Team o Enterprise) o una cuenta de Claude Console. La extensión también se instala en Cursor.

    ¿Puedo pasar una conversación de Claude Code en VS Code a la terminal?

    Sí. La extensión y el CLI comparten historial. Ejecuta claude --resume en la terminal y elige la conversación en el selector.

    ¿Cómo evito que el diff de JetBrains me robe el foco?

    Desde /config, pon Diff tool en terminal. Los diffs vuelven a la terminal y pierdes el visor del IDE. Anthropic cerró el issue #9765 como not planned. Según el mantenedor, la API de plugins de JetBrains no permite abrir un diff sin coger el foco.


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

  • Multiplexor de terminal: qué es y cuál elegir en 2026

    Multiplexor de terminal: qué es y cuál elegir en 2026

    Lanzas un agente de código en un servidor por SSH. Le pides una migración que va a tardar cuarenta minutos. Cierras la tapa del portátil para ir a por un café.

    Cuando vuelves, el proceso ya no existe. El wifi se cortó dos minutos, la conexión SSH murió y el shell se llevó por delante todo lo que colgaba de él. Cuarenta minutos de trabajo del agente perdidos, y un repo a medio migrar.

    Ese problema tiene solución desde 1987 y se llama multiplexor de terminal. Durante años fue cosa de sysadmins. En 2026 vuelve a importar, porque ya no dejas corriendo un proceso largo: dejas corriendo tres o cuatro agentes a la vez.

    En corto: un multiplexor de terminal (tmux, GNU Screen, Zellij) mantiene tus sesiones vivas en un proceso servidor aunque cierres la ventana o se corte SSH, y te deja dividir una terminal en varias. Si trabajas en remoto o con agentes de IA en paralelo, usa tmux o Zellij; si todo es local y tu terminal ya tiene pestañas, probablemente no lo necesitas.

    ¿Qué es un multiplexor de terminal?

    Un multiplexor de terminal es un programa que ejecuta varias sesiones de terminal dentro de una sola ventana y las mantiene vivas en segundo plano, de forma que puedes desconectarte y volver sin que los procesos mueran.

    Una aclaración para quien llega buscando "qué es un multiplexer": en electrónica y redes, un multiplexor (MUX) es un circuito o técnica que combina varias señales en un solo canal. Este artículo no va de eso. Va de la herramienta de desarrollo, el terminal multiplexer.

    La idea clave es que separa dos cosas que normalmente van pegadas: la sesión (tus procesos) y la ventana (lo que ves). Cierras la ventana y la sesión sigue.

    Cómo funciona un multiplexor de terminal: servidor, sesiones y paneles

    Un multiplexor funciona con un modelo cliente-servidor: un proceso servidor guarda el estado y tú te conectas a él con un cliente. La guía oficial de tmux lo dice literal: "tmux keeps all its state in a single main process, called the tmux server". Tu terminal es solo un cliente que puede irse y volver.

    Concepto Qué es Ejemplo práctico
    Sesión Agrupa una o más ventanas Una sesión por proyecto: api, web
    Ventana Agrupa uno o más paneles Una ventana para el agente, otra para logs
    Panel Contiene una terminal y el programa que corre Claude Code a la izquierda, tests a la derecha
    Detach / attach Soltar el cliente / volver a engancharlo Cierras el portátil, vuelves y retomas
    Prefijo Combinación que avisa "lo siguiente es para el multiplexor", porque comparte el teclado con tus programas Ctrl-b en tmux, Ctrl-a en Screen

    Comandos básicos de tmux

    Estos son los comandos mínimos para sobrevivir, todos documentados en la wiki de tmux:

    # Crear una sesión con nombre
    tmux new -s agentes
    
    # Dentro de tmux: soltar la sesión sin matarla
    # Ctrl-b d
    
    # Ver qué sesiones siguen vivas
    tmux ls
    
    # Volver a engancharte a una sesión concreta
    tmux attach -t agentes
    
    # Dentro de tmux: dividir el panel
    # Ctrl-b %   -> izquierda y derecha
    # Ctrl-b "   -> arriba y abajo
    

    Con esos comandos, el multiplexor de terminal ya resuelve la escena del principio. Abres tmux new -s agentes en el servidor, lanzas el agente y, si se corta SSH, vuelves con tmux attach -t agentes. El proceso nunca se enteró.

    tmux vs Zellij vs GNU Screen: comparativa

    La respuesta corta: tmux es el estándar, Zellij es la opción más amable para empezar y GNU Screen solo tiene sentido si es lo único instalado en la máquina. Datos verificados el 9 de noviembre de 2026:

    Herramienta Primera versión Lenguaje Licencia Última versión estable Windows nativo Limitación principal
    GNU Screen 1987 C GPL-3.0-or-later 5.0.2 (11 jul 2026) No Paneles y configuración más torpes; poca evolución de UX
    tmux 2007 C ISC 3.8 (9 sep 2026) No (en Windows, vía WSL) Curva del prefijo; scroll y copiado pasan por el modo copia
    Zellij 2021 Rust MIT 0.45.1 (28 ago 2026) Sí, desde v0.44.0 (mar 2026) Sigue en 0.x; menos scripts y configuraciones heredadas que tmux
    Herdr 2026 Rust Apache-2.0 0.9.5 (14 oct 2026) Sí, con limitaciones Proyecto joven, API aún en 0.x; pensado para agentes, no general
    WezTerm 2018 Rust MIT 20240203 (feb 2024) Sí Multiplexa solo si usas WezTerm; sin release estable desde 2024

    Fuentes: releases de cada repo, tmux y GNU Screen en Wikipedia, y las notas de Zellij v0.44.0.

    tmux

    tmux es el estándar de facto en Linux y macOS: está en los repos de cualquier distro, viene preinstalado en muchos servidores, tiene la documentación más amplia y su comando send-keys permite que un script escriba en un panel. Su README lista OpenBSD, FreeBSD, NetBSD, Linux, macOS y Solaris. En Windows, la vía es WSL.

    Zellij

    Zellij es un multiplexor de terminal escrito en Rust que se describe como "a terminal workspace with batteries included". Trae layouts, plugins y una barra con los atajos visibles, así que no tienes que memorizar nada el primer día. Se maneja con zellij attach -c mi-sesion (crea la sesión si no existe) y zellij ls, según su documentación de comandos.

    GNU Screen

    GNU Screen es el multiplexor de terminal original, de 1987, y sigue mantenido. Su prefijo es Ctrl-a, se suelta con Ctrl-a d, se listan sesiones con screen -ls y se recupera con screen -r, según el manual oficial. Úsalo cuando entres en una máquina vieja donde no puedes instalar nada más.

    tmux vs Zellij: qué dice la gente que usa ambos

    El debate tmux vs Zellij rara vez tiene un ganador claro, y el hilo de Hacker News sobre Zellij de diciembre de 2025 lo refleja bien. Un usuario, stusmall, lo resume así: "I prefer zellij over tmux, but it is evolutionary not revolutionary". Su consejo: si no ves valor inmediato en cambiar, quédate con lo que tienes.

    Otro comentario del mismo hilo, de dr_kretyn, apunta al criterio real de elección. Usaba tmux porque "I could copy over my tmux config to remote hosts and work as if nothing changed", y al pasar a trabajar sobre todo en local ahora usa casi siempre su terminal, Kitty (comentario).

    Mi opinión: si ya sabes tmux, no cambies. Si empiezas hoy y trabajas en local o en Windows, empieza por Zellij. Si vas a entrar en servidores que no controlas, aprende tmux, porque es el que vas a encontrar instalado.

    Por qué un multiplexor de terminal importa con agentes de IA

    Con agentes de código, el multiplexor deja de ser un truco para SSH y pasa a ser tu panel de control. Claude Code y Codex en un panel cada uno, otro con los tests, otro con el servidor de desarrollo. Todo en una sesión que puedes soltar y recuperar.

    Resuelve tres cosas concretas. Primero, sobrevivir a la desconexión: el agente sigue aunque cierres la terminal o se corte la red. Segundo, paralelismo visible: ves de un vistazo qué agente está trabajando y cuál espera tu respuesta. Tercero, automatización: con tmux send-keys un script puede mandar instrucciones a un panel.

    Lo que no resuelve es el conflicto de archivos. Si dos agentes tocan el mismo repo a la vez, se pisan. Para eso necesitas aislar el código con git worktrees en Claude Code: un worktree por agente y un panel por worktree.

    Y si lo que te cuesta es saber qué agente está bloqueado esperando permiso, ahí entra un multiplexor especializado. Herdr mantiene las sesiones vivas igual que tmux, pero además detecta el estado de cada agente (trabajando, bloqueado, terminado).

    Para seguir una sola sesión de Claude Code desde el móvil no hace falta multiplexor: basta Remote Control.

    Este flujo de varios agentes con tareas separadas es el que trabajamos de principio a fin en el curso Construye con IA: de la idea al producto con Claude Code.

    Cuándo NO necesitas un multiplexor de terminal

    Si todo es local, sin SSH, y tu terminal o IDE ya divide la pantalla (Ghostty, Windows Terminal, VS Code), solo pierdes la persistencia. Además, conviene conocer estos límites:

    1. Windows nativo sin WSL. tmux y GNU Screen no corren en Windows nativo. Si no quieres WSL, las opciones de esta comparativa son Zellij (desde v0.44.0), Herdr o WezTerm.
    2. La curva del prefijo. Ctrl-b antes de cada acción cuesta una semana de memoria muscular, y choca con atajos de editores y de algunas TUIs.
    3. Scroll y copiar. En tmux la rueda del ratón y la selección no se comportan como en tu terminal: hay que entrar en modo copia (Ctrl-b [) o activar el ratón en la configuración.
    4. No sobrevive a un reinicio. El servidor vive en memoria. Si reinicias la máquina, los procesos mueren. En tmux recuperar el layout exige plugins como tmux-resurrect; Zellij y Herdr guardan el layout por defecto, pero el trabajo en curso se pierde igual.
    5. Espacio en pantalla. La barra de estado y los bordes de panel restan líneas, una queja que aparece en el hilo de HN de Zellij 0.45.0 (comentario: "I can't stand losing terminal real estate"); en el mismo hilo responden que Zellij puede configurarse para ocupar una sola línea, como tmux.

    Empieza por una sesión con nombre

    Si hoy trabajas con agentes en un servidor, haz una sola cosa: antes de lanzar el siguiente, escribe tmux new -s agentes. La próxima vez que se corte la conexión, tmux attach -t agentes te devolverá el trabajo intacto, y entenderás por qué esta categoría de herramientas lleva casi cuarenta años viva.

    Si quieres ir más allá y diseñar cómo se reparten el trabajo varios agentes (herramientas, memoria, orquestación), lo cuento en el ebook gratuito El Developer Agéntico.

    Preguntas frecuentes

    ¿Qué es un multiplexer en programación?

    En programación, un multiplexer suele referirse a un multiplexor de terminal: un programa como tmux, GNU Screen o Zellij que ejecuta varias terminales en una ventana y mantiene los procesos vivos al desconectarte. No tiene relación con el multiplexor de electrónica o redes.

    ¿Qué es mejor, tmux o Zellij?

    tmux es mejor si trabajas en servidores remotos o ya lo conoces, porque está disponible casi en todas partes y tiene más ecosistema. Zellij es mejor para empezar: muestra los atajos en pantalla, trae layouts y corre en Windows nativo desde la versión 0.44.0.

    ¿tmux funciona en Windows?

    tmux no tiene versión nativa para Windows (fuera de entornos tipo Unix como Cygwin o MSYS2); su README solo lista sistemas tipo Unix y macOS. En Windows se usa dentro de WSL. Si necesitas un multiplexor nativo en Windows, Zellij, Herdr y WezTerm sí lo ofrecen.

    ¿Un multiplexor mantiene los procesos si apago el ordenador?

    No. El multiplexor mantiene los procesos si cierras la ventana o se corta SSH, porque el servidor sigue corriendo en la máquina. Si la máquina se apaga o reinicia, el servidor muere con ella. Puedes recuperar la disposición de paneles (con plugins en tmux, de serie en Zellij), pero no los procesos.

    ¿Necesito un multiplexor para usar Claude Code?

    No es obligatorio: Claude Code funciona en cualquier terminal. El multiplexor aporta cuando lo ejecutas en un servidor por SSH, cuando quieres varias sesiones en paralelo a la vista o cuando necesitas que sigan corriendo tras cerrar la terminal.

    ¿Cómo recupero una sesión de tmux si se corta SSH?

    Vuelve a conectarte al servidor y ejecuta tmux attach -t nombre-de-sesion; si no recuerdas el nombre, tmux ls lista las sesiones que siguen vivas. La sesión está intacta porque el servidor de tmux nunca dependió de tu conexión SSH.


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

  • Claude Code git: commits, PRs y conflictos bajo control

    Claude Code git: commits, PRs y conflictos bajo control

    489 commits.

    Esa es la cifra que un developer dejó en el issue #29999 de anthropics/claude-code el 2 de marzo de 2026. Claude Code había firmado cada uno de sus commits con un Co-Authored-By: Claude, y él no se dio cuenta hasta tener casi quinientos. Su única salida, según contó: reescribir todo el historial y hacer force push.

    Para mí, el problema de fondo no era la línea de atribución. Era que, en su flujo de Claude Code git, nadie había decidido qué podía escribir el agente en el historial. Para arreglarlo, la salida pasaba por la operación más peligrosa de git.

    El riesgo real no es un mal commit del agente, sino perder el control de qué entra en el historial compartido.

    En corto: delega en Claude Code los commits locales, la separación de cambios en commits atómicos, la redacción de la PR y la primera propuesta de resolución de conflictos. Revisa tú cada PR y cada conflicto resuelto, con los tests en verde. Prohíbe con reglas deny en settings.json el force push, el push a main y el merge de PRs.

    ¿Qué hace Claude Code con git?

    Delegar git en Claude Code significa que el agente ejecuta git y gh desde su herramienta Bash (commits, ramas, PRs, resolución de conflictos), mientras las reglas de permisos y tu revisión deciden qué llega al historial compartido.

    Según la referencia de settings, consultada en octubre de 2026, le pasa a Claude dos cosas al empezar la sesión: unas instrucciones propias sobre cómo escribir commits y PRs, y una foto del repo con la rama actual, la rama principal, el git status y los commits recientes. Si usas tu propio flujo, puedes quitar ambas con "includeGitInstructions": false.

    También firma. Cada commit lleva por defecto un trailer Co-Authored-By: <modelo> <noreply@anthropic.com>, y cada PR una línea "Generated with Claude Code". Se controla con la clave attribution (commit, pr y sessionUrl). La antigua includeCoAuthoredBy está obsoleta desde la v2.0.62.

    {
      "attribution": {
        "commit": "",
        "pr": ""
      }
    }
    

    Con cadenas vacías desaparece la firma. En el mismo issue, Boris Cherny, de Anthropic, respondió el 17 de agosto de 2026 justo con esa configuración. Dos usuarios le contestaron en septiembre que la queja no era si se puede apagar, sino que venga encendido por defecto.

    Mi regla: decide la atribución el primer día y déjala en settings.json, no en una frase de CLAUDE.md. Una clave de configuración no depende de que el modelo la recuerde.

    Commits con Claude Code que expliquen el porqué

    Un commit que dice "update user service" no le sirve a nadie dentro de seis meses. El diff ya cuenta qué cambió; el mensaje tiene que contar por qué.

    El agente describe el qué porque solo ve el diff. El porqué hay que pedirlo y dejarlo escrito donde lo lea en cada sesión, el CLAUDE.md del proyecto:

    ## Git
    - Conventional Commits: `tipo(ámbito): resumen` en imperativo, máximo 72 caracteres.
    - El cuerpo explica POR QUÉ: qué problema había y qué alternativa descartamos.
      El qué ya está en el diff; no lo repitas.
    - Un commit = un cambio lógico. Si el diff mezcla refactor y feature, sepáralos.
    - Antes de commitear, `npm test` en verde. Nunca `--no-verify`.
    - Nunca push a main ni force push. El push lo decide el humano.
    

    Y en el momento del commit, dale el contexto que el diff no tiene:

    Haz commit de estos cambios. El motivo: el endpoint /orders devolvía 500
    cuando el cliente no tenía dirección, y preferimos un 422 con mensaje claro
    a crear una dirección vacía. Ponlo en el cuerpo del commit.
    

    Commits atómicos con Claude Code: separa antes de commitear

    Tras una sesión larga, el working tree mezcla el fix que pediste, un refactor "de paso" y cambios de formato.

    Pídele que lo ordene antes de tocar el historial:

    Revisa git diff y agrupa los cambios en commits atómicos.
    Antes de commitear, enséñame la propuesta: qué archivos van en cada commit
    y el mensaje de cada uno. No hagas nada hasta que te diga "ok".
    

    Ver la propuesta antes es la clave: un commit de 14 archivos con mensaje genérico se frena ahí, no en la PR.

    Mi regla: cuando un mismo archivo mezcla dos cambios lógicos, lo separo yo con git add -p. Es interactivo y prefiero no pedirle al agente que lo emule con parches.

    Pull request con Claude Code usando gh

    Crear la PR es una de las tareas que mejor delega Claude Code. La guía de flujos comunes lo recoge tal cual: basta con pedir "create a pr" y el agente usa gh pr create. Además, Claude Code vincula la sesión a la PR: claude --from-pr 1234 abre el selector de sesiones filtrado por las vinculadas a esa PR, y vuelves a la conversación días después.

    Lo que cambia la calidad de la PR es el prompt:

    Crea una PR en borrador contra develop con gh. La descripción lleva:
    1. Qué problema resuelve y por qué este enfoque.
    2. Qué NO cubre esta PR.
    3. Riesgos: qué puede romper en producción.
    4. Checklist: tests añadidos, migraciones, variables de entorno nuevas.
    Enséñame el cuerpo antes de ejecutar gh pr create.
    

    En borrador (--draft) y con el cuerpo revisado antes, corriges el texto sin notificar a nadie. Si quieres aplicar este enfoque a un proyecto completo con Claude Code, es lo que hacemos en el curso Construye con IA.

    Resolver conflictos de merge con Claude Code

    Aquí el agente es útil y peligroso a la vez: leer dos lados de un conflicto es tedioso, pero "resolver" puede significar quedarse con un lado y borrar el otro en silencio.

    Antes de nada, dale más contexto en los marcadores:

    git config merge.conflictStyle zdiff3
    

    Con zdiff3 cada conflicto muestra también la versión base, así el agente ve qué cambió cada rama en vez de adivinarlo.

    Después, el prompt que obliga a explicar antes de elegir:

    Hay conflictos en el merge. Para cada archivo en conflicto:
    1. Usa git log --merge -p para ver qué commits tocaron cada lado.
    2. Explícame la intención de cada lado en una frase.
    3. Propón la resolución que conserva AMBAS intenciones.
    4. Si no se pueden conservar las dos, para y pregúntame.
    No hagas el commit del merge hasta que pasen los tests.
    

    El paso 4 es el importante. Un conflicto donde las dos intenciones chocan no es un problema de texto: es una decisión de producto, y esa no la toma el agente.

    Con varios agentes en paralelo, los conflictos se multiplican; cómo evitarlos lo conté en dirigir agentes de IA en paralelo sin que se pisen.

    Qué delegar, qué revisar y qué prohibir

    Este es el reparto que propongo para un flujo de Claude Code git. La última columna es la que manda: cuanto más difícil es deshacer una operación, menos autonomía le doy al agente.

    Operación Decisión Regla de permisos Riesgo si sale mal
    git status, diff, log Delegar Ninguna: Claude Code las trata como solo lectura Nulo
    git add + git commit local Delegar allow Bajo: se deshace con git reset --soft HEAD~1
    Separar en commits atómicos Delegar con propuesta previa allow Bajo: historial local
    gh pr create Revisar el cuerpo antes ask Medio: notifica al equipo
    Resolver conflicto de merge o rebase Revisar + tests en verde ask en --continue; en el prompt, parar antes del commit Alto: puede borrar lógica sin que falle nada
    git push a tu rama Revisar ask Medio: ya es público
    git push --force, push a main Prohibir deny Crítico: reescribe trabajo ajeno
    gh pr merge Prohibir deny Crítico: salta la revisión humana

    Cómo bloquear el force push en Claude Code con reglas deny

    El sitio para esto son las reglas de permisos de .claude/settings.json, no las instrucciones en lenguaje natural. Según la documentación de permisos, las reglas se evalúan en orden deny, luego ask, luego allow, y un deny gana siempre, aunque otra regla más específica permita lo mismo.

    {
      "permissions": {
        "allow": [
          "Bash(git add *)",
          "Bash(git commit *)"
        ],
        "ask": [
          "Bash(git push *)",
          "Bash(gh pr create *)",
          "Bash(git rebase --continue*)",
          "Bash(git merge --continue*)",
          "Bash(git reset --hard*)",
          "Bash(git clean *)"
        ],
        "deny": [
          "Bash(git push *--force*)",
          "Bash(git push -f*)",
          "Bash(git push * -f*)",
          "Bash(git push * main)",
          "Bash(git push * HEAD:main)",
          "Bash(git commit *--no-verify*)",
          "Bash(gh pr merge *)"
        ]
      }
    }
    

    El * sustituye cualquier texto en su posición, así que git push *--force* cubre --force y --force-with-lease estén donde estén. Por qué esto va en permisos y no en un hook lo expliqué en hooks vs permissions en Claude Code: un hook que falla deja pasar el comando; una regla deny, no.

    Mi regla: el agente no hace push. Si prefieres lo mismo, mueve Bash(git push *) de ask a deny y olvídate de las variantes.

    Límites de delegar git a Claude Code

    Esto no te protege de todo. Hay cuatro huecos.

    Las reglas deny no son una frontera de seguridad. La propia documentación avisa: Bash(git push *) no bloquea git -C . push origin main ni git 'push' origin main. Tampoco paran git commit -n, que equivale a --no-verify, ni git push origin +rama, que fuerza sin --force. Y hay un hueco más común: un git push a secas desde main no menciona la rama, así que Bash(git push * main) no lo para. La barrera de verdad para main es la protección de ramas en GitHub o GitLab.

    Los conflictos semánticos no salen en los tests. Si una rama renombra un campo y otra añade código que usa el nombre viejo en un sitio sin cobertura, git no marca conflicto y los tests pasan. Que el agente lo explique ayuda; solo lo detecta quien conoce el dominio.

    Los commits grandes siguen colándose. Si no pides la propuesta antes, el agente puede agrupar una sesión entera en un solo commit.

    Los mensajes vuelven a describir el qué. Con CLAUDE.md mejoran, pero si no le das el motivo en el prompt, el agente lo deduce del diff. Y un porqué inventado es peor que no tenerlo.

    Claude Code git: cómo empezar hoy

    Copia el bloque deny de arriba en el .claude/settings.json de tu proyecto y haz commit para que lo tenga todo el equipo. Son cinco minutos que convierten "espero que el agente no haga force push" en "el agente no puede hacer force push de la forma habitual".

    Lo demás, los mensajes con porqué, los commits atómicos y las PRs con checklist, sale de la misma idea: escribir el contrato antes de que el agente ejecute. Si quieres aplicar eso a todo el ciclo y no solo a git, es la base del libro Spec-Driven Development.

    Preguntas frecuentes

    ¿Cómo quito el Co-Authored-By de los commits de Claude Code?

    Añade "attribution": { "commit": "", "pr": "" } a tu settings.json. Desde la v2.1.281 también puedes poner "attribution": false para quitar toda la atribución, incluido el enlace de sesión. Ojo: las versiones anteriores rechazan ese valor e ignoran el archivo entero, reglas deny incluidas. En un .claude/settings.json compartido por el equipo, usa cadenas vacías y "sessionUrl": false. La clave includeCoAuthoredBy está obsoleta desde la v2.0.62.

    ¿Puede Claude Code resolver conflictos de merge solo?

    Puede proponer la resolución y aplicarla, pero no debería cerrar el merge sin tu revisión. Pídele que explique la intención de cada lado, que pare si chocan y que no cierre el merge hasta que pasen los tests.

    ¿Cómo hago que Claude Code escriba commits que expliquen el porqué?

    Fija la convención en CLAUDE.md (cuerpo con el motivo, no con el qué) y dale el motivo en el prompt al pedir el commit. El agente solo ve el diff; el porqué tiene que venir de ti.

    ¿Cómo crea Claude Code una pull request?

    Usa la CLI gh con gh pr create. Necesitas gh instalado y autenticado. Pídele la PR en borrador y que te enseñe la descripción antes de crearla.

    ¿Una regla deny de Claude Code bloquea cualquier git push –force?

    No. Bloquea las formas habituales de escribir el comando, pero no variantes como git -C . push. Combínala con protección de ramas en el servidor para main.


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

  • GitHub Spec Kit con Claude Code: specs que el agente cumple

    GitHub Spec Kit con Claude Code: specs que el agente cumple

    La spec decía 200 caracteres. El código dice 500.

    En septiembre de 2026, un developer abrió el issue #4383 en el repo de Spec Kit. Había hecho todo bien: constitution, specify, plan, tasks, implement, usando GitHub Spec Kit con Claude Code. El PRD fijaba en 200 la longitud máxima de dos campos. spec.md lo decía. data-model.md también: SuspendReason nvarchar(200).

    Y Claude implementó SuspendReasonMaxLength = 500.

    Nadie le había dado mal la regla al agente. La regla se había perdido por el camino: tasks.md mencionaba el límite de un campo y no el del otro. Para el campo sin límite, el agente puso uno por su cuenta.

    En corto: GitHub Spec Kit no impide que Claude Code contradiga tu spec, pero hace visible dónde se rompe el hilo. Su plantilla te obliga a escribir historias priorizadas que se prueban por separado, escenarios Given/When/Then, requisitos numerados y criterios medibles. Sus comandos clarify, checklist, analyze y converge detectan las contradicciones antes de implementar y después.

    ¿Qué es GitHub Spec Kit?

    GitHub Spec Kit es un toolkit open source de GitHub que instala en tu agente de código (Claude Code, Copilot, Codex y otros) un proceso de Spec-Driven Development con plantillas y comandos que van de la especificación al plan, las tareas, el código y la verificación.

    No es un modelo ni un servicio. Es un CLI en Python (specify) que copia plantillas Markdown y skills a tu proyecto. Todo lo demás lo hace el agente siguiendo esas instrucciones.

    Va rápido. La última release cuando escribo esto es la v1.3.2, del 6 de noviembre de 2026, y el repo pasa de 148.000 estrellas (dato de la API de GitHub, 7 de noviembre de 2026).

    Los tres errores que hacen que el agente contradiga la spec

    Un agente contradice una spec por tres motivos que el formato de Spec Kit ataca de frente: la ambigüedad, la falta de slices verticales y los criterios de aceptación débiles.

    El resto de fallos lo tienes en los siete fallos de una spec que rompen a un agente de IA, y lo de los slices, en el post sobre spec global y slices verticales en un proyecto greenfield.

    La tesis es simple: un agente no contradice una spec por rebeldía. La contradice cuando la spec deja un hueco y él lo rellena. Spec Kit no hace al agente más obediente. Te deja menos huecos que rellenar.

    Cómo instalar GitHub Spec Kit en Claude Code

    Necesitas Python 3.11+, uv y Claude Code instalado. La página de la integración con Claude da la clave claude:

    uv tool install specify-cli
    specify init mi-proyecto --integration claude
    cd mi-proyecto
    

    En un proyecto que ya existe, la guía de proyectos existentes indica specify init --here --force --integration claude. Haz commit antes: --force puede sobrescribir archivos en las rutas que gestiona Spec Kit.

    Spec Kit instala sus comandos como skills en .claude/skills/speckit-<comando>/SKILL.md. En el chat de Claude Code se invocan con guion:

    /speckit-constitution Prioriza la exactitud fiscal y los tests de integración.
    /speckit-specify Exportación trimestral de facturas para la gestoría.
    /speckit-clarify
    /speckit-plan Next.js, Postgres y generación del CSV en el servidor.
    /speckit-checklist
    /speckit-tasks
    /speckit-analyze
    /speckit-implement
    /speckit-converge
    

    Si ves /speckit.specify con punto en la documentación, es la notación genérica: en Claude Code va con guion.

    El formato de spec de Spec Kit, sección a sección

    La plantilla spec-template.md tiene tres secciones obligatorias (User Scenarios & Testing, Requirements y Success Criteria), una condicional (Key Entities, si la feature maneja datos) y una sección final de Assumptions. Así se mapea cada error a un mecanismo concreto:

    Error en la spec Mecanismo de Spec Kit Qué lo detecta
    Ambigüedad Marcadores [NEEDS CLARIFICATION: …] (máximo 3 por spec) y sección Assumptions /speckit-clarify: hasta 5 preguntas y las respuestas se escriben en spec.md
    Sin slices verticales User stories con prioridad (P1, P2, P3) y un Independent Test cada una /speckit-tasks agrupa las tareas por historia
    Criterios débiles Escenarios Given/When/Then y Success Criteria medibles (SC-001…) /speckit-checklist, "unit tests for English"
    Spec, plan y tareas que no cuadran Requisitos numerados FR-001… para trazar cada uno /speckit-analyze, de solo lectura
    Código que no cumple la spec spec.md, plan.md y tasks.md como referencia /speckit-converge añade tareas por lo que falta
    Principios del proyecto ignorados .specify/memory/constitution.md /speckit-analyze marca cualquier conflicto con la constitución como CRITICAL

    Fuente: plantillas y comandos en templates/commands/, consultados el 7 de noviembre de 2026.

    La plantilla exige que cada historia sea "INDEPENDENTLY TESTABLE": si implementas solo una, sigues teniendo un MVP viable. Es un slice vertical con otro nombre.

    Ejemplo: de spec mala a spec en formato Spec Kit

    Caso: un SaaS de facturación para autónomos. Los usuarios quieren mandar sus facturas a la gestoría cada trimestre sin descargarlas una a una.

    La spec que suele llegar al agente:

    # Exportación para la gestoría
    
    Añadir exportación de facturas para la gestoría.
    Tiene que ser rápida y fácil de usar.
    Formato CSV o Excel.
    Opción de enviarlo por email automáticamente.
    Gestionar bien los errores.
    

    Cada línea es un hueco. "Rápida" no se puede medir. "CSV o Excel" deja la decisión al agente. "Gestionar bien los errores" no dice qué es un error. Y no hay orden: el agente puede empezar por el envío automático, la parte más difícil, sin que exista la exportación básica.

    La misma spec en el formato de Spec Kit:

    # Feature Specification: Exportación trimestral para la gestoría
    
    **Status**: Draft
    
    ## User Scenarios & Testing *(mandatory)*
    
    ### User Story 1 - Descargar el CSV del trimestre (Priority: P1)
    
    El autónomo elige un trimestre y descarga un CSV con todas sus
    facturas emitidas en ese periodo.
    
    **Why this priority**: sin esto no hay nada que enviar. Es el
    mínimo que ya ahorra el trabajo manual.
    
    **Independent Test**: con 3 facturas en el T2 y 1 en el T3,
    exportar el T2 devuelve un CSV con exactamente 3 filas.
    
    **Acceptance Scenarios**:
    
    1. **Given** un usuario con 3 facturas emitidas en el T2 de 2026,
       **When** exporta el T2 de 2026, **Then** descarga un CSV con
       3 filas y las columnas número, fecha, NIF del cliente, base
       imponible, tipo de IVA, cuota de IVA y total.
    2. **Given** una factura rectificativa en el T2, **When** exporta
       el T2, **Then** la rectificativa aparece con importes negativos.
    3. **Given** un trimestre sin facturas, **When** lo exporta,
       **Then** ve el mensaje "No hay facturas en este trimestre"
       y no se descarga ningún archivo.
    
    ---
    
    ### User Story 2 - Enviar el CSV al email de la gestoría (Priority: P2)
    
    El autónomo guarda el email de su gestoría y envía el CSV del
    trimestre con un botón.
    
    **Why this priority**: elimina el paso de adjuntar el archivo,
    pero depende de que la US1 funcione.
    
    **Independent Test**: con un email de gestoría guardado, pulsar
    "Enviar" genera un único email con el CSV del trimestre adjunto.
    
    **Acceptance Scenarios**:
    
    1. **Given** un email de gestoría guardado, **When** pulsa
       "Enviar T2", **Then** se envía un email con el CSV adjunto
       y el envío queda registrado con fecha y destinatario.
    2. **Given** que el T2 ya se envió, **When** pulsa "Enviar T2"
       otra vez, **Then** se le pide confirmación antes de reenviar.
    
    ---
    
    ### User Story 3 - Envío automático al cerrar el trimestre (Priority: P3)
    
    [...]
    
    ### Edge Cases
    
    - ¿Qué pasa con una factura con fecha del último día del trimestre
      a las 23:59 en otra zona horaria?
    - ¿Qué pasa si el email de la gestoría rebota?
    
    ## Requirements *(mandatory)*
    
    ### Functional Requirements
    
    - **FR-001**: System MUST incluir solo facturas emitidas, nunca
      borradores.
    - **FR-002**: System MUST asignar el trimestre por la fecha de
      emisión, no por la fecha de cobro.
    - **FR-003**: System MUST usar [NEEDS CLARIFICATION: ¿separador
      decimal coma o punto? Depende del programa de la gestoría].
    - **FR-004**: System MUST NOT modificar ninguna factura al exportar.
    
    ### Key Entities
    
    - **Factura**: número, fecha de emisión, cliente, base, IVA, total.
    - **Envío**: trimestre, destinatario, fecha y archivo enviado.
    
    ## Success Criteria *(mandatory)*
    
    ### Measurable Outcomes
    
    - **SC-001**: un usuario con 500 facturas en un trimestre obtiene
      el CSV en menos de 5 segundos.
    - **SC-002**: la suma de la columna total del CSV coincide al
      céntimo con el total facturado del trimestre en la app.
    
    ## Assumptions
    
    - La exportación a Excel queda fuera de esta versión.
    - Las facturas recibidas (gastos) no entran en esta feature.
    

    Fíjate en lo que cambió. El orden ya no es cosa del agente: P1 se puede terminar, probar y desplegar sin tocar P2. "Rápida" ahora es SC-001, con un número. "CSV o Excel" se convirtió en una decisión escrita en Assumptions. Y lo que de verdad no sabes, el separador decimal, queda marcado en vez de inventado.

    Ojo: una spec mejor no habría evitado por sí sola el bug del issue #4383. Allí la spec ya decía 200; el límite se perdió al pasar a tasks.md. Lo que lo atrapa es una restricción escrita como escenario (Given un motivo de 201 caracteres, When se guarda, Then se rechaza) más un comando que compare el código con ella. Un escenario se convierte en un test que falla, y un test que falla no deja pasar un 500 donde ponía 200.

    Cómo detecta Spec Kit las contradicciones antes de implementar

    Spec Kit detecta las contradicciones con cuatro comandos: clarify y checklist revisan la spec, analyze cruza spec, plan y tareas antes de implementar, y converge compara el código con los tres después. Es justo el punto donde falló el issue: algo se perdió entre spec.md y el código.

    /speckit-clarify revisa la spec por categorías y te hace como máximo cinco preguntas, de una en una, con opciones cerradas o respuestas de cinco palabras como mucho. Cada respuesta se escribe en spec.md. Pásalo antes de plan: es más barato resolver el separador decimal ahí que en un PR.

    /speckit-checklist genera lo que el propio comando llama "Unit Tests for English": comprueba si los requisitos están completos, son claros y no se contradicen. No prueba el código. Prueba la spec.

    /speckit-analyze cruza spec.md, plan.md y tasks.md y saca una tabla de hallazgos con severidad. Es estrictamente de solo lectura: no toca ningún archivo. Y la constitución manda: según el propio comando, un conflicto con ella es "automatically CRITICAL" y se arregla cambiando la spec, el plan o las tareas, no el principio.

    /speckit-converge va después de implementar. Compara el código con los tres artefactos y añade a tasks.md el trabajo que falta, sin tocar el código. Repites implement y converge hasta que el comando informa Converged.

    El issue #4383 acabó en un cambio a la plantilla de tasks. Desde el PR #4430, fusionado el 8 de septiembre de 2026, el comando pide citar literalmente en cada tarea las restricciones de campo de data-model.md: longitudes máximas, nullables, enums, reglas de validación. Aun así, el bot del repo, que clasificó el issue como "likely valid, needs reproduction", avisa de que el arreglo es solo de prompt y de que distintos agentes pueden seguir parafraseando las restricciones en vez de citarlas. Por eso no te fíes de un solo comando: analyze antes de implementar y converge después.

    La constitución: lo que ningún feature puede saltarse

    /speckit-constitution escribe .specify/memory/constitution.md, que se crea una vez por proyecto. La plantilla trae huecos para cinco principios, con ejemplos como "Test-First (NON-NEGOTIABLE)".

    Para el SaaS de facturas, uno de los principios sería este:

    ### I. Exactitud fiscal (NON-NEGOTIABLE)
    Los importes se calculan en céntimos enteros, nunca en coma flotante.
    Toda exportación tiene un test que compara su suma con el total del sistema.
    

    Ese principio no vive en ninguna spec concreta. Vive por encima de todas. Si mañana un plan propone calcular con number de JavaScript, analyze debería marcarlo como CRITICAL antes de que se escriba una línea.

    Spec Kit, un spec.md propio u OpenSpec

    No todo proyecto necesita Spec Kit:

    Criterio GitHub Spec Kit spec.md propio OpenSpec
    Instalación uv + Python 3.11+ Ninguna npm (Node 22.12+), Homebrew o script
    Formato de spec Plantilla fija: user stories P1-P3, Given/When/Then, FR, SC El que tú decidas Requisitos y escenarios en Markdown, por cambio
    Detección de contradicciones clarify, checklist, analyze, converge Depende de tu disciplina y tus prompts /opsx:verify en el perfil ampliado
    Specs a largo plazo Una carpeta por feature en specs/ Lo que mantengas a mano openspec/specs/ vivas; los cambios se archivan y las actualizan
    Limitación o riesgo Mucho Markdown y ceremonia; las specs por feature envejecen Nada te obliga a escribir criterios medibles Menos puertas de calidad; su README llama a Spec Kit "Thorough but heavyweight"

    Fuentes: README de Spec Kit, README de OpenSpec, consultados el 7 de noviembre de 2026. Si ya usas OpenSpec, tienes el paso a paso en cómo integrar OpenSpec con Claude Code.

    Mi opinión: el formato es lo mejor del paquete y te lo puedes llevar sin el CLI. Si copias la plantilla a tu spec.md propio, ya ganas la mitad; la otra mitad, analyze y converge, es lo que justifica instalarlo en proyectos medianos o grandes.

    Cuándo NO usar Spec Kit

    Para cambios pequeños. El proceso completo genera spec, plan, tareas, checklists y varios artefactos más. Para un bug de tres líneas es ceremonia pura. En este hilo de Hacker News, a raíz del análisis de Birgitta Böckeler sobre Kiro, Spec Kit y Tessl, un usuario contaba que lo dejó porque "Always made it too complex, and at some point it wasn't worth correcting it anymore". Para bugs, Spec Kit tiene ahora una extensión aparte (specify extension add bug); úsala en vez de pasar el bug por el flujo de features.

    Cuando esperas que la spec garantice el resultado. En el mismo hilo, otro usuario cuenta que usó Spec Kit con Claude Code durante dos semanas. Tras unos diez días de flujo, tenía tests fallando y un build que no salía. En el siguiente proyecto dejó de lado parte del flujo: montó sus propios comandos por sprint y revisaba cada sprint antes de seguir. Ese comentario es de octubre de 2025, antes de converge, pero la lección no caduca: la spec reduce los huecos, no sustituye la revisión.

    Cuando tus specs tienen que vivir años. Spec Kit crea una carpeta por feature. Si la feature 009 cambia lo que definió la 001, nada fusiona las dos automáticamente. Es lo que se preguntaba en el issue #620, "How to keep specs consistent and up-to-date with spec-kit?". Existe una guía para hacer evolucionar specs, pero el mantenimiento sigue siendo tuyo.

    Cuando no vas a leer lo que genera. Una spec sin revisar es un prompt vago convertido en Markdown largo; el README pide ejecutar los comandos de uno en uno y revisar cada resultado.

    Por dónde empezar a escribir specs para agentes de IA con Spec Kit

    Coge la última feature que le pediste a Claude Code y reescribe su spec con la plantilla: dos o tres historias con prioridad, un Independent Test por historia, escenarios Given/When/Then y al menos un criterio con número. Después pasa /speckit-clarify y mira qué te pregunta. Esas preguntas son los huecos que el agente iba a rellenar por ti.

    Si quieres el método completo detrás de este formato, está en el libro Spec-Driven Development. Y si prefieres verlo aplicado de la idea al producto con Claude Code, es lo que hacemos en el curso Construye con IA. Para la parte de revisar lo que genera el agente contra la spec, el workshop SDD + Agentic Engineering va justo de eso.

    Preguntas frecuentes

    ¿Cómo se instala GitHub Spec Kit en Claude Code?

    Con uv tool install specify-cli y specify init mi-proyecto --integration claude (en un repo existente, specify init --here --force --integration claude). Necesitas Python 3.11+, uv y Claude Code.

    ¿Los comandos de Spec Kit se escriben /speckit.specify o /speckit-specify?

    En Claude Code, /speckit-specify, con guion: Spec Kit los instala como skills en .claude/skills/. La documentación de referencia usa /speckit.specify como notación genérica, y cada agente tiene su propia forma de invocarlos.

    ¿Qué diferencia hay entre /speckit-clarify y /speckit-analyze?

    clarify resuelve dudas de la spec antes del plan y escribe las respuestas en spec.md. analyze cruza spec, plan y tareas después de tasks y no modifica ningún archivo.

    ¿Cómo se escriben criterios de aceptación para un agente de IA con Spec Kit?

    Con escenarios Given/When/Then en cada user story y Success Criteria numerados (SC-001…) con una cifra. Cada escenario fija un estado inicial, una acción y un resultado comprobable; cada criterio, un número que un test puede medir, como "menos de 5 segundos con 500 facturas". Si no se puede comprobar con un test, no es un criterio de aceptación: es un hueco que el agente rellenará por su cuenta.

    ¿Cuántos [NEEDS CLARIFICATION] puede tener una spec de Spec Kit?

    Como máximo tres. El comando specify está escrito para suponer con criterio y anotar esas suposiciones en Assumptions, y para marcar solo las decisiones críticas sin un valor razonable por defecto: alcance, seguridad o experiencia de usuario.

    ¿Spec Kit sirve para proyectos existentes o solo para empezar de cero?

    Sirve para los dos, pero en un proyecto existente no genera specs del comportamiento que ya tienes: empiezan con la siguiente feature que definas.

    ¿Puedo usar el formato de Spec Kit sin instalar el CLI?

    Sí. La plantilla templates/spec-template.md es Markdown público en el repo. Copiarla a tu propio spec.md te da las historias priorizadas, Given/When/Then, FR y SC. Lo que pierdes son los comandos que comprueban la coherencia entre spec, plan, tareas y código.


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

  • Claude Code sandbox: aísla el bash del agente sin Docker

    Claude Code sandbox: aísla el bash del agente sin Docker

    Le pides a Claude Code que arregle un test que falla. Lee el error, decide que falta una dependencia y lanza un npm install. El paquete trae un script postinstall. Ese script corre con tu usuario, en tu máquina, con acceso a tu ~/.ssh y a la red.

    Y aquí está la trampa: aprobaste el npm install porque tenía sentido. El permiso que diste era para el comando, no para todo lo que ese comando ejecuta por debajo. El Claude Code sandbox existe para cerrar ese hueco sin que tengas que montar Docker.

    En corto: el Claude Code sandbox (/sandbox) aísla a nivel de sistema operativo los comandos de shell del agente y sus procesos hijos: solo escriben en el proyecto y solo salen a la red por los dominios que permites. Viene desactivado y funciona en macOS, Linux y WSL2, no en Windows nativo. No cubre las herramientas de archivos, los servidores MCP ni los hooks.

    ¿Qué es el Claude Code sandbox?

    El Claude Code sandbox es un límite que impone el sistema operativo alrededor de los comandos de shell que ejecuta el agente, restringiendo qué archivos pueden escribir y a qué dominios de red pueden conectarse, incluidos los procesos que esos comandos lancen.

    Lo importante es quién lo impone. Una regla de permisos lee el texto del comando antes de ejecutarlo. El sandbox actúa sobre el proceso mientras corre. La documentación oficial de sandboxing (consultada el 10 de octubre de 2026) dice que el límite se mantiene "aunque un comando permitido haga más de lo que su nombre sugiere". Justo el postinstall del ejemplo.

    Por debajo usa Seatbelt en macOS y bubblewrap más socat en Linux y WSL2, sobre el paquete open source @anthropic-ai/sandbox-runtime.

    Qué aísla /sandbox en Claude Code por defecto

    Por defecto, un comando sandboxed escribe solo en el proyecto, el temp por usuario y los directorios añadidos, y sale a la red solo por un proxy local con una lista de dominios que empieza vacía. Pero dos valores por defecto conviene leerlos dos veces:

    Acceso Por defecto Con qué se cambia
    Escritura Directorio de trabajo, temp por usuario, directorios añadidos filesystem.allowWrite, filesystem.denyWrite
    Lectura Casi toda la máquina, incluidos ~/.ssh y ~/.aws/credentials filesystem.denyRead, credentials
    Red Sin ruta directa; proxy con lista de dominios vacía network.allowedDomains, network.deniedDomains
    Variables de entorno Heredadas de Claude Code, secretos incluidos credentials, CLAUDE_CODE_SUBPROCESS_ENV_SCRUB

    Fuente: tabla "What the sandbox restricts" de la doc oficial, octubre de 2026.

    El Claude Code sandbox impide que el agente escriba fuera del proyecto o salga a un host no aprobado. No impide que lea tus credenciales: no hay lista bloqueada de serie, solo se protege lo que declaras.

    Dentro del proyecto, eso sí, protege los archivos de configuración (.claude/settings*, .claude/hooks, .mcp.json, .bashrc, los hooks de .git), para que un comando no pueda darse permisos ni registrar un hook que corra fuera.

    Cómo activar el Claude Code sandbox

    Ejecuta /sandbox en una sesión o pon sandbox.enabled: true en tus settings:

    /sandbox
    

    En Mode eliges auto-allow (los comandos sandboxed no piden permiso; es el valor por defecto) o permisos regulares (apruebas cada comando). Se guarda en .claude/settings.local.json, solo para ese proyecto.

    Mi regla: configúralo en ~/.claude/settings.json, no en el panel, para que valga en todos los proyectos, y endurécelo:

    {
      "sandbox": {
        "enabled": true,
        "failIfUnavailable": true,
        "allowUnsandboxedCommands": false,
        "network": {
          "allowedDomains": ["registry.npmjs.org"]
        },
        "credentials": {
          "files": [
            { "path": "~/.ssh", "mode": "deny" },
            { "path": "~/.aws/credentials", "mode": "deny" }
          ],
          "envVars": [
            { "name": "GITHUB_TOKEN", "mode": "deny" }
          ]
        }
      }
    }
    

    Ojo: denegar ~/.ssh oculta tus claves, así que git push y git pull por SSH dejan de funcionar dentro del sandbox (en macOS ya fallan de serie). Usa remotos HTTPS o saca esos comandos con excludedCommands.

    failIfUnavailable importa: por defecto, si falta una dependencia o la plataforma no está soportada, Claude Code ejecuta los comandos sin sandbox y sigue. En true, se niega a arrancar.

    Para comprobarlo, pídele a Claude (no lo teclees con !, eso corre fuera) que ejecute touch ~/sandbox-probe. Debe fallar con Operation not permitted en macOS o Read-only file system en Linux y WSL2.

    En el curso Construye con IA montamos el flujo completo con Claude Code; el sandbox es la capa que conviene añadir antes de darle más autonomía.

    Claude Code sandbox en Windows: hazlo con WSL2

    En Windows nativo no hay sandbox: Claude Code ejecuta los comandos sin aislar. La única vía sin contenedores es correr Claude Code dentro de una distribución WSL2.

    Los pasos, según la doc:

    1. En PowerShell, wsl -l -v. Si tu distro sale con versión 1, conviértela a WSL2: con WSL1 el sandbox no arranca.
    2. Dentro de Ubuntu o Debian: sudo apt-get install bubblewrap socat.
    3. En Ubuntu 24.04 o superior, ejecuta sysctl kernel.apparmor_restrict_unprivileged_userns. Si devuelve 1, AppArmor impide a bubblewrap crear user namespaces y tienes que añadir el perfil de bwrap que da la doc.
    4. Instala Claude Code dentro de WSL2, reinícialo después de instalar los paquetes y ejecuta /sandbox. Si falta bubblewrap o socat, el panel solo muestra la pestaña Dependencies; si solo falta el filtro seccomp, que es opcional, Dependencies aparece junto a las demás.

    Ojo: desde WSL2, lanzar binarios de Windows (cmd.exe, /mnt/c/) pasa por un socket Unix al host; bloquearlo exige el filtro seccomp opcional (npm install -g @anthropic-ai/sandbox-runtime).

    Esto no siempre funcionó: en el issue #10567 (octubre de 2025, v2.0.28), /sandbox rechazaba WSL2. Hoy la doc lo lista como soportado, pero el issue sigue abierto y en agosto de 2026 aún había quien lo reportaba en la v2.1.175. Por eso conviene failIfUnavailable: si en tu WSL2 no arranca, te enteras al iniciar y no a mitad de sesión.

    ¿Sandbox nativo, Docker o nada? Cómo aislar un agente de IA

    Para aislar un agente de IA en tu máquina, /sandbox es la opción más barata, pero solo cubre la shell; Docker o una VM cubren el proceso entero:

    Opción Qué aísla Qué NO aísla Coste de montarlo Riesgo principal
    Nada (solo permisos) Nada a nivel de SO; depende de que apruebes bien Todo lo que haga el comando aprobado y sus hijos Cero Un comando legítimo ejecuta código no revisado con tu usuario
    /sandbox nativo Bash, PowerShell, Monitor y sus procesos hijos Herramientas de archivos, MCP, hooks, comandos que tecleas con ! Mínimo en macOS; bajo en Linux/WSL2 Lectura de credenciales si no las declaras; fallback silencioso sin failIfUnavailable
    Sandbox runtime (npx @anthropic-ai/sandbox-runtime claude) El proceso entero de Claude Code, MCP y hooks incluidos Lo que permitas en su config Bajo, pero es beta Formato de configuración que puede cambiar
    Dev container con firewall Entorno completo dentro de Docker Lo que montes con escritura y los tokens que metas dentro Medio: Docker + .devcontainer/ El proyecto montado sigue siendo modificable

    Fuente: Choose a sandbox environment, doc oficial, octubre de 2026.

    Mi regla: /sandbox para el trabajo diario, cuando tú sigues mirando lo que pasa. Para dejar al agente solo con --dangerously-skip-permissions, contenedor, VM o el sandbox runtime. La doc lo dice: el sandbox de Bash "no es suficiente" para ejecuciones desatendidas, porque archivos, MCP y hooks siguen en el host.

    El montaje con Docker está en entornos reproducibles con Docker y Dev Containers. Y por qué un límite del sistema operativo vale más que una lista de comandos prohibidos lo medimos en guardrails para agentes: con una blocklist típica pasaban 16 de 20 comandos destructivos. Si usas otro agente, compáralo con Pi, que no trae sistema de permisos.

    Límites del Claude Code sandbox: lo que no resuelve

    El Claude Code sandbox reduce el daño de un comando, pero la doc avisa: no es un límite de aislamiento completo.

    No cubre las herramientas de archivos, ni MCP, ni los hooks. Read, Edit y Write se rigen por las reglas de permisos, no por el sandbox: un denyRead no frena a la herramienta Read, y allowedDomains no limita WebFetch. Los servidores MCP locales y los hooks corren con tu acceso completo.

    El reintento fuera del sandbox existe. Si un comando falla dentro, Claude puede reintentarlo con dangerouslyDisableSandbox. En bypassPermissions pasa sin preguntar, y una regla de allow como Bash(curl *) también lo aprueba. En el issue #34315 (marzo de 2026), un usuario en modo acceptEdits vio el bypass ocurrir sin ningún prompt.

    Se cerró como corregido en la v2.1.113, aunque ese mismo día otro usuario dijo que seguía pasando en la 2.1.114 y el hilo se bloqueó sin reabrirse. La solución de fondo la dio otro usuario en el mismo hilo: "allowUnsandboxedCommands": false, con la que Claude Code ignora ese parámetro.

    No impide la exfiltración por la red. El proxy decide por el nombre de host que declara el cliente y, por defecto, no inspecciona TLS. Eso abre dos vías. Un dominio amplio como github.com ya es un canal de salida: si el agente lee un secreto (la lectura está abierta por defecto) y lo sube ahí, el sandbox no lo ve. Y con domain fronting, un comando puede llegar a hosts que ni siquiera están en tu lista. Si eso entra en tu modelo de amenaza, la doc recomienda un proxy propio que termine e inspeccione TLS. Es la cadena de la inyección indirecta de prompts.

    Rompe herramientas. docker es incompatible, jest necesita --no-watchman y en macOS fallan git por SSH y CLIs en Go como gh. Cada excludedCommands que añades es una puerta abierta.

    El ebook gratuito El Developer Agéntico dedica una parte a la seguridad de agentes: tools, MCP y por qué el aislamiento es una capa, no la solución.

    ¿Cómo empezar con /sandbox en Claude Code hoy?

    Abre ~/.claude/settings.json y pega el bloque de arriba: failIfUnavailable en true, allowUnsandboxedCommands en false y tus credenciales declaradas. Deja en allowedDomains solo el registro que uses de verdad y añade hosts cuando un comando falle por necesitarlos.

    El Claude Code sandbox te dice dónde puede actuar el agente. Qué debe hacer lo define la especificación que le das antes de empezar: es el método que explico en el libro Spec-Driven Development.

    Preguntas frecuentes

    ¿El Claude Code sandbox viene activado por defecto?

    No. Viene desactivado. Se activa con /sandbox dentro de una sesión o con "sandbox": { "enabled": true } en un archivo de settings como ~/.claude/settings.json.

    ¿Funciona /sandbox en Windows?

    En Windows nativo, no: Claude Code ejecuta los comandos sin aislar. Tienes que correr Claude Code dentro de una distribución WSL2 con bubblewrap y socat instalados, o usar un contenedor o una VM.

    ¿El sandbox protege mis claves SSH y mis tokens?

    No por defecto. Un comando sandboxed puede leer casi toda la máquina, incluidos ~/.ssh y ~/.aws/credentials, y hereda las variables de entorno. Tienes que declararlos en sandbox.credentials con "mode": "deny".

    ¿Es lo mismo /sandbox que el modo auto o --dangerously-skip-permissions?

    No. Los modos de permisos deciden si una acción se ejecuta. El sandbox limita a qué puede acceder un comando de shell mientras corre. Para ejecuciones desatendidas con --dangerously-skip-permissions, la doc recomienda contenedor, VM o el sandbox runtime, no solo /sandbox.


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