Ejecución en paralelo y background

Ejecución en paralelo

Cuando Claude Code recibe una tarea que puede descomponerse en subtareas independientes, lanza varios subagentes simultáneamente en lugar de ejecutarlos de forma secuencial. Cada subagente trabaja en su propia ventana de contexto, y el agente principal espera a que todos terminen antes de sintetizar los resultados.

investiga los modulos de autenticacion, base de datos y API
en paralelo usando subagentes separados

En este ejemplo, Claude lanzaría tres subagentes (probablemente de tipo Explore) que explorarían cada módulo de forma concurrente. Cada uno leería los archivos relevantes de su área, analizaría la estructura y devolvería un resumen. El agente principal combinaría los tres resúmenes en una respuesta unificada.

flowchart TD
    A["Agente principal"] --> B["Subagente: autenticación"]
    A --> C["Subagente: base de datos"]
    A --> D["Subagente: API"]
    B --> E["Resumen auth"]
    C --> F["Resumen DB"]
    D --> G["Resumen API"]
    E --> H["Síntesis de resultados"]
    F --> H
    G --> H

La ejecución en paralelo ofrece dos ventajas principales:

• Velocidad: tres investigaciones paralelas tardan lo que tarda la más lenta, no la suma de las tres.
• Aislamiento de contexto: cada subagente consume su propio contexto sin afectar al de los demás ni al principal.

La ejecución en paralelo funciona mejor cuando las tareas son verdaderamente independientes. Si la subtarea B depende del resultado de la subtarea A, Claude las ejecutará en secuencia, no en paralelo.

Cuándo se activa el paralelismo

Claude decide automáticamente si ejecutar subagentes en paralelo o en secuencia según la naturaleza de la tarea. No es necesario indicar explícitamente que se quiere paralelismo, Claude lo infiere cuando detecta que las subtareas no tienen dependencias entre sí.

Algunos indicadores que favorecen la ejecución en paralelo:

• La instrucción menciona módulos o archivos distintos que no se solapan
• Las subtareas son de lectura (no modifican los mismos archivos)
• Se puede expresar la tarea como una lista de investigaciones independientes

Foreground y background

Los subagentes pueden ejecutarse en dos modos: foreground (primer plano) y background (segundo plano). La diferencia afecta a cómo el usuario interactúa con Claude mientras el subagente trabaja.

Subagentes en foreground

En modo foreground, el subagente bloquea la conversación principal hasta que termina. Durante su ejecución, las solicitudes de permisos y las preguntas de clarificación se reenvían al usuario. Este es el comportamiento por defecto para la mayoría de las tareas.

El foreground es adecuado cuando:

• El resultado del subagente es necesario para continuar la conversación
• Se espera que el subagente necesite aprobación de permisos durante su ejecución
• La tarea es relativamente corta

Subagentes en background

En modo background, el subagente trabaja de forma concurrente mientras el usuario continúa interactuando con Claude en la conversación principal. Antes de lanzar el subagente, Claude solicita por adelantado todos los permisos que el subagente podría necesitar, de forma que pueda operar de forma autónoma.

Hay tres formas de ejecutar un subagente en background:

• 1. Pedir a Claude que ejecute la tarea en segundo plano:

ejecuta los tests del proyecto en background y avisame
cuando terminen

• 2. Pulsar Ctrl+B durante la ejecución de un subagente en foreground para enviarlo a segundo plano.

• 3. Configurar el campo background: true en el frontmatter del agente custom para que siempre se ejecute en segundo plano:

---
name: test-runner
description: Run test suites in the background
background: true
tools: Bash, Read, Grep
---

Cuando un subagente en background necesita hacer una pregunta de clarificación al usuario, esa llamada falla pero el subagente continúa su ejecución. Si falla por falta de permisos, se puede reanudar en foreground para resolver las aprobaciones pendientes.

Gestión de permisos en background

La diferencia clave entre foreground y background está en la gestión de permisos. En foreground, cada solicitud de permiso se reenvía al usuario en tiempo real. En background, Claude preaprueba los permisos necesarios antes del lanzamiento, y cualquier solicitud no preaprobada se deniega automáticamente.

| Aspecto | Foreground | Background | |---|---|---| | Bloquea la conversación | Sí | No | | Permisos en tiempo real | Sí | No (preaprobados) | | Preguntas al usuario | Se reenvían | Fallan silenciosamente | | Ctrl+B | Envía a background | N/A |

Para desactivar completamente la funcionalidad de tareas en background, se puede establecer la variable de entorno CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1.

Reanudación de subagentes

Cada invocación de un subagente crea una instancia nueva con contexto fresco. Sin embargo, existe la posibilidad de reanudar un subagente para continuar su trabajo desde donde lo dejó, conservando todo el historial de la conversación anterior (llamadas a herramientas, resultados y razonamiento).

usa el subagente code-reviewer para revisar el modulo de autenticacion
[El subagente completa y devuelve resultados]

continua esa revision y analiza tambien la logica de autorizacion
[Claude reanuda el subagente con todo el contexto previo]

Al reanudar, el subagente retoma exactamente donde paró, sin necesidad de repetir la exploración o el análisis previo. Esto es especialmente útil cuando una tarea se ha completado parcialmente y se quiere ampliar sin perder el trabajo realizado.

Transcripciones de subagentes

Las transcripciones de los subagentes se almacenan de forma independiente de la conversación principal en archivos con formato agent-{agentId}.jsonl dentro del directorio de transcripciones de la sesión (~/.claude/projects/{proyecto}/{sessionId}/subagents/).

Esta separación tiene implicaciones prácticas:

• Compactación independiente: cuando la conversación principal se compacta, las transcripciones de subagentes no se ven afectadas.
• Persistencia: las transcripciones persisten dentro de la sesión, lo que permite reanudar un subagente incluso después de reiniciar Claude Code si se reanuda la misma sesión.
• Limpieza automática: las transcripciones se eliminan según la configuración cleanupPeriodDays (30 días por defecto).

Autocompactación en subagentes

Los subagentes también soportan autocompactación con la misma lógica que la conversación principal. Cuando un subagente acumula suficiente contexto (por defecto al 95% de capacidad), compacta automáticamente su historial para liberar espacio y continuar operando.

La variable de entorno CLAUDE_AUTOCOMPACT_PCT_OVERRIDE permite ajustar este umbral. Un valor de 50 activaría la compactación a la mitad de la capacidad, útil para subagentes que procesan grandes volúmenes de datos.

Encadenamiento de subagentes

El encadenamiento consiste en ejecutar subagentes en secuencia, donde cada uno utiliza los resultados del anterior. A diferencia de la ejecución en paralelo, aquí existe una dependencia entre las tareas.

usa el subagente code-reviewer para encontrar problemas de rendimiento,
despues usa el subagente optimizer para corregirlos

Claude ejecuta primero el revisor de código, recibe sus hallazgos, y pasa el contexto relevante al optimizador. Cada subagente trabaja en su propia ventana de contexto, pero la información fluye del primero al segundo a través del agente principal.

flowchart LR
    A["Agente principal"] --> B["code-reviewer<br>Detecta problemas"]
    B --> C["Resultados"]
    C --> A
    A --> D["optimizer<br>Corrige problemas"]
    D --> E["Correcciones"]
    E --> A

Una restricción importante del encadenamiento es que los subagentes no pueden lanzar otros subagentes. Toda la orquestación pasa por el agente principal, que actúa como coordinador.

Si un flujo de trabajo requiere delegación anidada (un subagente que lance otro subagente), se deben usar Skills en lugar de subagentes, o diseñar el flujo como una cadena coordinada desde el agente principal.

Aislamiento con worktrees

Para subagentes que modifican archivos en paralelo, existe el riesgo de que dos subagentes editen el mismo archivo simultáneamente, provocando conflictos. La opción isolation: worktree resuelve este problema creando un worktree de Git temporal para el subagente.

---
name: feature-implementer
description: Implement features in isolated branches
isolation: worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

Implement the requested feature in this isolated worktree.
Create a branch, make changes, and commit.

Un worktree es una copia del repositorio que comparte el mismo historial de Git pero tiene su propio directorio de trabajo. El subagente opera en esta copia aislada, lo que permite:

• Modificar archivos sin afectar al directorio de trabajo principal
• Ejecutar tests en un estado limpio del código
• Crear commits y branches sin interferir con otros subagentes

Si el subagente no realiza ningún cambio, el worktree se limpia automáticamente.

Patrones de uso efectivo

Aislar operaciones con salida voluminosa

Una de las aplicaciones más efectivas de los subagentes es contener salidas extensas. Ejecutar una suite de tests completa, procesar logs o analizar documentación genera grandes cantidades de texto que consumirían rápidamente la ventana de contexto principal.

usa un subagente para ejecutar toda la suite de tests
y reporta solo los tests que fallan con sus mensajes de error

El subagente ejecuta los tests, procesa toda la salida (que puede ser de miles de líneas) y devuelve al agente principal solo la información relevante: qué tests fallaron y por qué.

Investigación en paralelo

Para tareas de exploración que abarcan múltiples áreas del proyecto, lanzar subagentes en paralelo reduce drásticamente el tiempo de investigación:

investiga en paralelo: 1) como funciona el sistema de cache,
2) que endpoints tiene la API, 3) como se gestionan las migraciones

Cada subagente explora su área de forma independiente y devuelve un resumen. El agente principal sintetiza los tres resúmenes en una visión completa del proyecto.

Verificación post-implementación

Tras implementar un cambio en la conversación principal, se puede delegar la verificación a un subagente para que revise el código sin consumir el contexto principal:

usa un subagente para revisar los cambios que acabamos de hacer
y buscar posibles edge cases o problemas de seguridad

Restricción de subagentes disponibles

Cuando se ejecuta un agente como proceso principal con claude --agent, se puede controlar qué subagentes puede lanzar mediante la sintaxis Agent(nombre) en el campo tools:

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

Esta configuración actúa como lista blanca: el coordinador solo puede lanzar los subagentes worker y researcher. Si intenta lanzar cualquier otro, la solicitud falla.

Para permitir el lanzamiento de cualquier subagente sin restricciones, se usa Agent sin paréntesis:

tools: Agent, Read, Bash

Si Agent se omite completamente de la lista de herramientas, el agente no puede lanzar ningún subagente. Esta restricción solo aplica a agentes que se ejecutan como proceso principal con claude --agent, los subagentes nunca pueden lanzar otros subagentes.

La combinación de ejecución en paralelo, background, reanudación y aislamiento con worktrees permite diseñar flujos de trabajo complejos donde múltiples agentes colaboran de forma coordinada, cada uno con su propio contexto, permisos y herramientas.