Tareas en paralelo: haz que varios Claude trabajen al mismo tiempo en lugar de hacer cola

📚 Navegación de la serie: El artículo anterior 40 Chrome: de la mano con el navegador te enseñó cómo hacer que Claude interactúe con el navegador, haga clic en páginas y complete formularios automáticamente. Este artículo cambia de dimensión: en lugar de hacer que un solo Claude haga más tareas, haremos que varias tareas comiencen al mismo tiempo. Explicaremos tres métodos a la vez: aislamiento con git worktree, múltiples sesiones en segundo plano y ejecución por lotes headless, además de lo más importante: cuándo el paralelismo realmente facilita el trabajo y cuándo solo causa problemas.

Es un poco vergonzoso admitirlo, pero la primera vez que intenté "trabajar en paralelo", hice algo muy tonto: abrí dos terminales, hice cd en el mismo directorio del proyecto en ambas, y en una le pedí a Claude que modificara la página de inicio de sesión del frontend, mientras que en la otra le pedí que corrigiera un bug del backend.

En mi mente, pensaba felizmente: "Esto duplicará la eficiencia".

El resultado: ambas sesiones estaban modificando package.json, y las dependencias recién agregadas en una terminal fueron sobrescritas y revertidas directamente por los cambios de la otra. Al ejecutar git status, el área de trabajo era un desastre absoluto y era imposible distinguir quién había cambiado qué línea. Ese día pasé mucho más tiempo separando manualmente los cambios de ambos lados del que habría pasado si hubiera hecho las cosas una por una de manera ordenada, y me sentí cada vez más frustrado. Fue en ese momento cuando entendí: el paralelismo no es tan simple como "abrir varias ventanas", el núcleo es "no dejar que pisen el mismo terreno".

De hecho, Claude Code ya tiene preparadas herramientas de paralelismo adecuadas: --worktree le da a cada sesión una copia aislada del código, --bg envía las tareas al segundo plano para que se ejecuten en lotes, y claude agents te ofrece un panel de control centralizado para vigilarlas. En este artículo, eliminaremos ese problema de raíz y te guiaremos para que pruebes estos métodos tú mismo.

Al terminar este artículo, obtendrás:

• Una explicación sencilla de "por qué paralelizar" y los dos requisitos previos del paralelismo: tareas independientes y que no compitan por el mismo archivo.
• Una tabla comparativa con las cuatro formas oficiales de paralelismo (subagentes / vista de agentes / equipos de agentes / flujos de trabajo dinámicos) para saber cuál elegir.
• Cómo usar --worktree para dar a cada sesión una copia aislada y evitar sobrescrituras mutuas, incluyendo detalles sobre .worktreeinclude y la limpieza.
• Cómo usar claude agents y --bg para enviar tareas al segundo plano y vigilar el progreso en una sola pantalla, interviniendo solo cuando sea necesario.
• Cómo usar claude -p (modo sin cabecera o headless) para ejecutar tareas en scripts por lotes, optimizando la velocidad de inicio con --bare.
• La regla de decisión más importante: cuándo vale la pena paralelizar y cuándo solo terminarás confundiéndote.

---

01 Primero piensa: qué problema resuelve realmente el paralelismo y cuál es su requisito previo

Para empezar, la conclusión: el paralelismo resuelve la situación de "varias tareas independientes que no quieres esperar en fila una por una"; pero para que funcione, depende de un requisito previo: que estas tareas no compitan por el mismo archivo.

Si recuerdas los cuarenta artículos anteriores, básicamente hemos estado trabajando en "una sola sesión": abres un Claude, le das instrucciones y él trabaja paso a paso. Este modelo es suficiente para el 90% de las tareas. Pero hay dos situaciones en las que te parecerá lento.

Primero, cuando las tareas son naturalmente independientes y no tienen dependencias entre sí. Por ejemplo, "cambiar los estilos del frontend", "corregir un bug del backend" y "agregar un lote de pruebas unitarias" son tres cosas totalmente distintas, pero tienen que hacer cola: no se puede trabajar en el backend hasta terminar el frontend. Cosas que claramente se pueden hacer al mismo tiempo se ven obligadas a ejecutarse de forma secuencial.

Segundo, cuando la tarea es demasiado grande para una sola sesión. Por ejemplo, "reemplazar una API antigua por una nueva en todo el código base" involucra decenas o cientos de archivos. Si una sola sesión modifica todo de principio a fin, el contexto (es decir, su "memoria de trabajo", ver el artículo 19) se llenará por completo, y empezará a "olvidar cosas" a medida que avance.

Analogía: pagar en el supermercado. Si hay una sola caja y diez personas hacen una larga fila con sus carritos de compra, la décima persona tiene que esperar a que las nueve anteriores paguen; esto es la ejecución secuencial. Un supermercado inteligente abrirá varias cajas para que las diez personas se distribuyan en tres o cuatro filas y paguen al mismo tiempo, reduciendo de inmediato el tiempo total. Trabajar en paralelo es como "abrir más cajas": varias tareas independientes se asignan a diferentes Claude para que paguen al mismo tiempo, en lugar de amontonarse en una sola fila.

Pero que se puedan abrir más cajas tiene un requisito previo implícito: cada fila es independiente y no interfiere con las demás. Si tres cajeros usaran la misma caja registradora y pusieran dinero y cambio al mismo tiempo, todo se volvería un caos; ese es exactamente el problema del principio. Por lo tanto, la regla de oro del paralelismo es una sola:

¿Las tareas tocan los mismos archivos? Usa worktrees para aislar el trabajo.

En los escenarios reales a los que te enfrentarás, las tareas adecuadas para el paralelismo se ven así:

• "Corregir los bugs de estos tres módulos independientes": se dividen en tres sesiones para corregirlos al mismo tiempo sin interferencias.
• "Buscar código muerto sin usar en todo el directorio utils/": se envía a un subagente para que lo investigue, evitando llenar la conversación principal con una pila de archivos (ver artículo 23).
• "Ejecutar el mismo cambio con un script en 30 archivos": se escribe como una tarea por lotes headless para que la máquina la ejecute sola.

💡 Resumen rápido: el paralelismo sirve para que las tareas independientes no tengan que hacer fila (como abrir más cajas en el supermercado), pero la única regla de oro para que funcione es: no dejes que compitan por el mismo archivo, o de lo contrario el paralelismo solo causará caos.

---

02 Cuatro formas oficiales de paralelismo: conócelas primero para no abrumarte

El paralelismo en Claude Code no se limita a un solo método. La documentación oficial tiene una sección dedicada a comparar "Ejecución de agentes en paralelo", y la diferencia clave se reduce a una sola pregunta: ¿quién coordina estas tareas? ¿Es Claude quien asigna y recibe tareas en una sola conversación, eres tú quien las envía al segundo plano para revisarlas después, o es Claude quien actúa como supervisor dirigiendo a un equipo?

Conozcamos primero las cuatro formas con esta tabla. Esta sección es el mapa; las siguientes secciones profundizarán en cada una:

Método	Qué es	Quién coordina	Cuándo usarlo
Subagente (Subagent)	Un trabajador asignado dentro de una sesión que realiza la tarea en su propio contexto y devuelve un resumen	Claude asigna y recibe tareas en la conversación	Cuando las tareas secundarias llenan la conversación principal con resultados de búsqueda o logs que no volverás a revisar
Vista de agentes (Agent view)	Una pantalla para programar y monitorear múltiples sesiones en segundo plano usando claude agents (vista previa de investigación)	Tú envías las tareas y las revisas después	Cuando tienes varias tareas independientes, quieres delegarlas, ver su estado de un vistazo e intervenir solo si es necesario
Equipos de agentes (Agent teams)	Múltiples sesiones que trabajan de manera coordinada compartiendo una lista de tareas, enviándose mensajes y con un líder que supervisa (experimental, desactivado por defecto)	Claude actúa como supervisor y dirige al equipo	Cuando quieres que Claude divida el proyecto en varias partes, las asigne y mantenga a los trabajadores sincronizados (ver artículo 29)
Flujos de trabajo dinámicos (Workflows)	Un script que ejecuta una gran cantidad de subagentes y valida sus resultados (vista previa de investigación)	El script, no Claude, decide paso a paso	Cuando la tarea es demasiado grande para que la coordinen unos pocos subagentes, o cuando se necesita validación cruzada: auditoría de todo el código base, migración de 500 archivos

⚠️ Aviso de características experimentales: En la tabla anterior, la vista de agentes (agent view) y los flujos de trabajo dinámicos (workflows) están en fase de vista previa de investigación, y los equipos de agentes (agent teams) son experimentales y están desactivados por defecto. La interfaz, los atajos de teclado y el comportamiento pueden cambiar en el futuro. Verifica tu versión con claude --version antes de continuar. Los subagentes son una funcionalidad estable.

No necesitas memorizar esta tabla, solo recuerda una cosa: "quién coordina" es el factor decisivo: si Claude las asigna sobre la marcha en la conversación → subagentes; si tú las envías al segundo plano → vista de agentes; si Claude actúa como supervisor liderando un equipo → equipos de agentes; si se ejecutan de forma rígida por lotes en un script → flujos de trabajo dinámicos.

También hay dos herramientas que no son métodos de paralelismo en sí, sino complementos para apoyarlo. En este artículo nos enfocaremos principalmente en la primera:

• Worktrees: le da a cada sesión una copia independiente de git, asegurando que las sesiones paralelas nunca modifiquen el mismo archivo. Esta es la solución correcta para el problema del principio y se detalla en la sección 03.
• /batch: una skill que permite a Claude dividir un cambio grande en 5 a 30 subagentes aislados con worktrees, creando un PR para cada uno. Es una forma empaquetada de usar "subagentes + worktree", no un estilo de coordinación independiente.

Ya hemos analizado a fondo los subagentes (artículo 23) y los equipos de agentes (artículo 29) anteriormente, por lo que no los repetiremos en este artículo. Nos centraremos en los aspectos que aún no hemos cubierto: aislamiento con worktree, múltiples sesiones en segundo plano y ejecución por lotes headless.

💡 Resumen rápido: Hay cuatro formas oficiales de paralelismo, y "quién coordina" es la clave para distinguirlas; worktree y /batch son herramientas de soporte, no métodos independientes; este artículo se centra en worktree, sesiones en segundo plano y headless.

---

03 Aislamiento con worktree: dale a cada sesión "su propia copia"

Esta sección es la solución definitiva al problema del principio y la parte más importante que debes dominar en este artículo.

Primero, veamos por qué ocurre ese problema: cuando dos sesiones hacen cd en el mismo directorio, es equivalente a que dos personas dibujen sobre el mismo plano al mismo tiempo; lo que se escribe después sobrescribirá lo anterior, y naturalmente se volverá un caos. Git worktree (una característica nativa de git) está diseñado precisamente para solucionar esto de raíz.

Analogía: fotocopiar el plano original para que cada persona modifique su copia. Solo hay un diseño original. Si tres personas necesitan hacer anotaciones al mismo tiempo, trabajar en el mismo papel inevitablemente creará un desastre. La forma correcta es hacer tres fotocopias para que cada uno modifique su copia libremente y luego consolidar los cambios. Eso es exactamente lo que hace git worktree: a partir del mismo historial del repositorio, crea varios directorios de trabajo independientes, cada uno con sus propios archivos y ramas, pero compartiendo el mismo historial de commits y repositorios remotos. Los cambios que realice una sesión en su copia nunca afectarán a la copia de otra sesión.

La documentación oficial explica claramente este valioso punto:

Ejecutar cada sesión de Claude Code en su propio worktree significa que las ediciones en una sesión nunca tocarán los archivos de otra sesión, por lo que puedes hacer que Claude construya una característica en una terminal mientras corrige un error en una segunda terminal.

Iniciar una sesión aislada con una sola línea de comandos

La forma más sencilla de usarlo: agrega --worktree (o la abreviatura -w) seguida de un nombre al iniciar. Claude creará automáticamente un worktree aislado y comenzará a trabajar allí. Por defecto, este worktree se ubica en .claude/worktrees/<nombre>/ dentro de la raíz de tu repositorio, y la rama se llamará worktree-<nombre>:

claude --worktree feature-auth

¿Quieres abrir una segunda sesión independiente? Abre otra terminal, usa un nombre diferente y ejecuta el mismo comando:

claude --worktree bugfix-123

Ahora ambas sesiones están en sus respectivas copias independientes, una desarrollando características y la otra corrigiendo bugs, y ninguna tocará los archivos de la otra. El problema de la "sobrescritura mutua" se ha eliminado por completo. ¿No quieres pensar en un nombre? Omitelo y Claude generará uno automáticamente como bright-running-fox:

claude --worktree

También puedes pedirle temporalmente que entre en un worktree durante una conversación diciendo "trabaja en un worktree", y usará la herramienta EnterWorktree para crearlo.

Antes de usar --worktree por primera vez en un directorio, debes ejecutar claude de forma normal en ese directorio una vez para aceptar el diálogo de confianza del espacio de trabajo. Si no has aceptado la confianza, --worktree fallará directamente y te pedirá que ejecutes primero claude, incluso en el modo -p.

Tres trampas comunes para principiantes

Trampa 1: Agregar .claude/worktrees/ a .gitignore. De lo contrario, el contenido de estos worktree se mostrará en tu directorio principal como una pila de "archivos no rastreados", lo cual resulta molesto. La documentación oficial lo advierte explícitamente.

Trampa 2: Los worktree son copias limpias y nuevas; tu .env no estará allí. Un worktree es una copia recién obtenida. Por defecto, los archivos no rastreados por git en el repositorio principal (como .env, .env.local) no se copiarán, lo que provocará que la nueva sesión falle al iniciar por falta de variables de entorno. La solución es colocar un archivo .worktreeinclude en la raíz del proyecto para listar los archivos locales que deben copiarse automáticamente en cada worktree, usando la misma sintaxis que .gitignore:

.env
.env.local
config/secrets.json

Yo mismo caí en esta trampa: abrí con entusiasmo una sesión con -w para modificar el backend, pero Claude siguió reportando que no podía conectarse a la base de datos al ejecutarse. Pasé mucho tiempo analizando el error e incluso sospeché que la base de datos se había caído; finalmente me di cuenta de que .env no se había copiado al worktree, por lo que no podía leer la cadena de conexión. Desde entonces, coloco un archivo .worktreeinclude en la raíz de cada proyecto y nunca he vuelto a tener ese problema.

Trampa 3: Recuerda elegir "conservar o eliminar" al salir. Las reglas de limpieza oficiales son muy prácticas:

• Si no se cambió nada (sin cambios sin commit, sin archivos no rastreados, sin nuevos commits): el worktree y su rama se eliminarán automáticamente; pero si la sesión fue nombrada previamente (--name), Claude mostrará un mensaje para que decidas si conservarlo o eliminarlo.
• Si se cambiaron cosas: Claude te preguntará si quieres "conservar o eliminar". Si eliges conservar, mantendrá el directorio y la rama para que puedas regresar y continuar después; si eliges eliminar, se descartará el directorio junto con los cambios no guardados.
• Los worktree creados de forma no interactiva (-p) no se limpian automáticamente porque no hay un mensaje de salida; debes eliminarlos manualmente con git worktree remove.

Si no quieres que Claude lo cree automáticamente, también puedes hacerlo manualmente

Si quieres tener un control total sobre dónde se coloca el worktree y qué rama utiliza, puedes crearlo directamente con git (lo explicaremos en detalle en el artículo 43 sobre flujo de trabajo de git):

# Crear un worktree en una rama nueva
git worktree add ../proyecto-feature-a -b feature-a

# Entrar al directorio e iniciar Claude
cd ../proyecto-feature-a && claude

# Listar todos los worktrees
git worktree list

# Eliminarlo al terminar
git worktree remove ../proyecto-feature-a

La documentación oficial nos recuerda un detalle que es fácil de olvidar: cada nuevo worktree es una copia independiente, así que recuerda reinstalar las dependencias y configurar los entornos virtuales dentro de él. No esperes que herede el directorio node_modules instalado en el directorio principal.

💡 Resumen rápido: worktree le da a cada sesión una copia independiente del código (como fotocopiar planos para modificarlos por separado). Ejecutar claude --worktree <nombre> abre una sesión aislada con una sola línea; recuerda las tres trampas: agregar .claude/worktrees/ a .gitignore, copiar .env con .worktreeinclude y elegir "conservar / eliminar" al salir.

---

04 Paralelismo multisesión: enviar tareas al segundo plano y vigilarlas desde un panel de control

El aislamiento con worktree resuelve el problema de que los "archivos no interfieran entre sí", pero queda otra duda: si abres tres o cinco sesiones, ¿tienes que abrir tres o cinco terminales para alternar y vigilar cada una? Es demasiado agotador. Aquí es donde entra en juego la "vista de agentes (agent view)".

Analogía: el panel de estado de vuelos en la torre de control de un aeropuerto. El controlador de la torre no vigila un solo avión a la vez. En una gran pantalla se muestra el estado de todos los vuelos de un vistazo: cuál está rodando, cuál espera instrucciones y cuál ha aterrizado. El despachador normalmente echa un vistazo al resumen general e interviene para tomar el control por radio solo cuando un vuelo específico requiere su decisión. claude agents te ofrece precisamente esa pantalla de control: todas las sesiones en segundo plano se listan en filas, sus estados se muestran de un vistazo y tú intervienes solo cuando alguna lo necesita.

⚠️ Vista previa de investigación: agent view es una función marcada por el equipo oficial como vista previa de investigación. Requiere una versión reciente de Claude Code; la interfaz y los atajos de teclado pueden cambiar en el futuro. Verifica tu versión con claude --version antes de comenzar.

Enviar tareas al segundo plano

La esencia de las sesiones en segundo plano es: no están vinculadas a tu terminal. Aunque cierres esta pantalla, cierres la shell o abras otra sesión interactiva, seguirán ejecutándose. Hay un par de formas de enviarlas.

La primera es enviarla directamente desde la shell agregando --bg:

claude --bg "Investiga por qué la prueba inestable de SettingsChangeDetector siempre falla"

Una vez enviada, Claude imprimirá el ID corto de la sesión y los comandos para administrarla, que se verán parecidos a esto:

backgrounded · 7c5dcf5d
  claude agents             list sessions
  claude attach 7c5dcf5d    open in this terminal
  claude logs 7c5dcf5d      show recent output
  claude stop 7c5dcf5d      stop this session

La segunda es enviarla desde una sesión activa: escribe /bg (abreviatura de /background) para mover la conversación actual al segundo plano.

Administrarlas con la pantalla de control claude agents

Abre el panel de control central:

claude agents

Ocupará toda la terminal y listará todas las sesiones en segundo plano agrupadas por su estado: "Necesita entrada", "Trabajando" y "Completado". Cada fila comienza con un ícono cuyo color y animación indican el estado de la sesión:

Estado	Ícono	Significado
Trabajando	Animación parpadeante	Ejecutando herramientas o generando una respuesta
Necesita entrada	Amarillo	Esperando tu respuesta o aprobación de permisos
Completado	Verde	La tarea se completó con éxito
Fallido	Rojo	Terminó con un error

Las operaciones principales en la pantalla de control son tres; para los principiantes, recordar estas tres es suficiente:

• Space (Ver detalles): selecciona una fila y presiona la barra espaciadora para mostrar un panel flotante con la salida reciente o ver en qué pregunta está atascada. La mayoría de las veces no necesitas entrar a la conversación completa, basta con echar un vistazo.
• Responder: escribe tu respuesta directamente en el panel de detalles y presiona Enter para enviarla, sin salir del panel de control central.
• Enter / → (Acoplar): si quieres entrar a una sesión específica para conversar a fondo, presiona Enter para "acoplarte" a ella y se convertirá en una sesión interactiva completa. Presiona ← en un cuadro de entrada vacío para regresar al panel de control central.

Aquí hay un detalle oculto pero extremadamente crítico que conecta con el worktree de la sección anterior: antes de modificar archivos en cada sesión en segundo plano, Claude la moverá automáticamente a un worktree aislado bajo .claude/worktrees/. Es decir, cuando utilizas la vista de agentes para paralelizar tareas en segundo plano, el aislamiento de archivos se realiza automáticamente, sin necesidad de usar -w manualmente como en la sección 03. La documentación oficial confirma que la vista de agentes crea automáticamente un worktree independiente para cada sesión al asignarla.

Considera una combinación común de paralelismo: enviar tres sesiones al segundo plano al mismo tiempo; una para corregir una prueba inestable, otra para revisar un PR y otra para completar la documentación. Tú sigues haciendo tu trabajo y de vez en cuando ejecutas claude agents para revisar: cuando una cambie a verde vas a validarla, y cuando una se marque en amarillo vas a decidir. Es mucho más sencillo que abrir tres terminales y alternar entre ellas.

⚠️ Un detalle sobre el consumo de tu cuota: Las sesiones en segundo plano consumen tu cuota de suscripción de la misma manera que las sesiones interactivas. Ejecutar diez en paralelo consumirá tu saldo aproximadamente diez veces más rápido que ejecutar una sola. No las abras de forma desmedida solo porque se ejecutan en segundo plano.

💡 Resumen rápido: --bg envía tareas al segundo plano, /bg mueve la sesión actual al segundo plano y claude agents te da una pantalla de control (como el panel de vuelos del aeropuerto). Usa Space para ver detalles, responde directamente y presiona Enter para acoplarte. Las sesiones en segundo plano se aíslan automáticamente con worktrees, pero recuerda que usar más sesiones consumirá más cuota rápidamente.

---

05 Headless por lotes: escríbelo en scripts para que se ejecute sin supervisión

Los dos métodos anteriores se realizan "mientras tú estás frente a la terminal". Pero hay un tipo de tarea que no quieres vigilar: aplicar el mismo patrón a una serie de elementos o integrar Claude en CI o scripts para que sea invocado automáticamente como una herramienta de línea de comandos. Esto es el modo sin cabecera (headless: una forma de ejecución que no abre una interfaz interactiva y sale al terminar).

Analogía: poner instrucciones en un papel e introducirlas en una máquina de autoservicio para obtener resultados. No te quedarás frente a la máquina expendedora viendo cómo procesa; introduces el dinero, presionas el botón, el producto sale y todo ocurre sin que tengas que vigilarlo. Headless es esta forma "sin supervisión": escribes las instrucciones y los parámetros de una vez, se los entregas a claude -p y este se sale tras arrojar los resultados para que los uses directamente.

El núcleo es una sola opción: -p (o --print). Al agregarla, claude se ejecuta de forma no interactiva una vez y luego sale:

claude -p "Encuentra el bug en auth.py y corrígelo" --allowedTools "Read,Edit,Bash"

Aquí --allowedTools sirve para aprobar previamente qué herramientas puede usar. Como no hay nadie al lado para hacer clic en "Aceptar", debes indicarle con anticipación: "Usa estas herramientas libremente, no te detengas a preguntar" (ver detalles sobre modos de permisos en los artículos 20 y 35).

Tres complementos para hacerlo realmente útil

Complemento 1: Enviar datos mediante tuberías (pipes). El modo headless lee la entrada estándar (stdin), por lo que puedes enviarle datos mediante tuberías como con cualquier herramienta de línea de comandos. Por ejemplo, pasarle un error de compilación para que lo explique y guardar el resultado en un archivo:

cat build-error.txt | claude -p "Explica de forma concisa la causa raíz de este error de compilación" > output.txt

Cuando investigues por qué falló la compilación, envía una línea como esta; es mucho más rápido que copiar el error y pegarlo en una conversación.

Complemento 2: --bare para un inicio más rápido. Por defecto, claude -p carga el mismo contexto completo que una sesión interactiva (lee hooks, skills, plugins, MCP y CLAUDE.md). Al ejecutarlo en un script, esto resulta lento y puede verse afectado por configuraciones en ~/.claude de otros compañeros. Agregar --bare omite estas detecciones automáticas, lo que acelera el inicio y garantiza que los resultados sean consistentes en diferentes máquinas:

claude --bare -p "Resume este archivo" --allowedTools "Read"

El equipo oficial explica claramente:

--bare es el modo recomendado para scripts y llamadas de SDK, y se convertirá en el valor por defecto para -p en futuras versiones.

Complemento 3: --output-format json para obtener resultados estructurados. Los scripts necesitan analizar la salida de Claude, y el texto plano es difícil de procesar. Al agregar --output-format json, devolverá un JSON estructurado con metadatos (el resultado, el ID de sesión y total_cost_usd indicando cuánto costó la ejecución), lo que facilita su extracción con jq:

claude -p "Resume este proyecto" --output-format json | jq -r '.result'

Unir headless para procesamiento "por lotes"

Un solo -p no es procesamiento por lotes. El verdadero procesamiento por lotes consiste en envolverlo en un ciclo de shell para ejecutar la misma tarea en un conjunto de archivos. Por ejemplo, generar una descripción de una sola línea para cada archivo .py en un directorio:

for f in src/*.py; do
  claude --bare -p "Explica en una sola frase qué hace $f" --allowedTools "Read"
done

Este es el inicio de la "ejecución por lotes sin supervisión": ciclo, -p y --bare (las tres piezas clave). Por supuesto, si la escala es de decenas o cientos de archivos y necesitas validación cruzada de resultados, entonces deberías recurrir a flujos de trabajo dinámicos o /batch explicados en la sección 02, que están diseñados para estructurar este tipo de procesamiento por lotes de manera formal.

⚠️ Un cambio en la facturación a tener en cuenta: La documentación oficial indica que a partir del 15 de junio de 2026, el uso de Agent SDK y claude -p bajo planes de suscripción se deducirá de una cuota mensual independiente de Agent SDK, separada de tu consumo interactivo. Ten esto en cuenta antes de ejecutar scripts por lotes (los detalles de facturación se encuentran en el artículo 06).

💡 Resumen rápido: headless usa claude -p para ejecutarse de forma no interactiva una vez y luego salir (como usar una máquina de autoservicio sin vigilarla). Usa --allowedTools para aprobar herramientas de antemano, --bare para acelerar y --output-format json para obtener resultados estructurados. Envolverlo en un ciclo for de la shell crea un procesamiento por lotes básico.

---

06 La sección más crítica: cuándo NO paralelizar

Hemos explicado tres métodos de paralelismo, pero esta sección es más importante que todas las anteriores, porque muchas personas se entusiasman al aprender sobre paralelismo y quieren dividirlo todo, lo que resulta en mayor caos y mayores costos.

Establezcamos primero la línea de decisión. Para que valga la pena paralelizar, deben cumplirse dos condiciones simultáneamente: que las tareas sean mutuamente independientes (el resultado de A no dependa de B) y que no compitan por el mismo archivo (o que se aíslen mediante worktrees). Si falta alguna, el paralelismo solo te causará problemas.

Comparemos qué se debe paralelizar y qué se debe ejecutar secuencialmente:

Escenario	¿Paralelizar?	Por qué
Corregir bugs en tres módulos independientes	✅ Sí	Independientes, no compiten por archivos. Caso típico.
Ejecutar el mismo cambio por lotes en 30 archivos	✅ Sí (headless / /batch)	No hay dependencias mutuas, la máquina lo hace por ti.
"Refactorizar A primero, luego modificar B basándose en el nuevo A"	❌ No (secuencial)	B depende de los resultados de A. Paralelizar solo causará que use el A viejo.
Dos sesiones necesitan modificar package.json	❌ No (secuencial, o usar worktree)	Compiten por el mismo archivo. El problema exacto del principio.
Un cambio pequeño que toma cinco minutos	❌ No (secuencial)	El costo de coordinación para dividirlo supera el tiempo ahorrado.
Las tareas deben comunicarse resultados intermedios con frecuencia	⚠️ Depende	Alto costo de comunicación; es mejor usar una sola sesión secuencialmente.

Aquí tienes tres reglas prácticas basadas en la experiencia que te serán de ayuda:

Primero, si las tareas tienen dependencias de orden, nunca las paralelices. En tareas como "refactorizar primero el módulo central y luego adaptar los demás módulos a la nueva interfaz", el segundo paso debe esperar al primero. Si las paralelizas a la fuerza, la segunda se modificará según la versión antigua, y al terminar descubrirás que debes rehacer todo. Hacer esto solo desperdiciará la cuota de ambas sesiones en vano.

Segundo, no dividas tareas pequeñas. Para algo que se puede modificar en cinco minutos, el tiempo que pasas pensando cómo dividirlo, abriendo las sesiones y consolidando los cambios después superará los cinco minutos. Dividir el trabajo tiene un costo, y dividir tareas pequeñas es una pérdida neta.

Tercero, a mayor paralelismo, más rápido se consume tu cuota. Debemos enfatizar nuevamente la regla de la sección 04: paralelizar diez sesiones consumirá tu saldo aproximadamente diez veces más rápido. Un buen hábito es limitar el paralelismo manual a tres o cinco sesiones; si necesitas procesar grandes lotes (decenas o cientos), delega la tarea a /batch o flujos de trabajo dinámicos para gestionarla formalmente en lugar de abrir una pantalla llena de sesiones manualmente.

En pocas palabras, el paralelismo es una espada de doble filo: en el escenario adecuado multiplica la eficiencia, pero en el escenario incorrecto es más lento, costoso y caótico que la ejecución secuencial. Saber "cuándo paralelizar" siempre es más valioso que saber "cómo paralelizar".

💡 Resumen rápido: la regla de oro para que valga la pena paralelizar es "independencia + no competir por archivos"; si falta alguna, no dividas. No paralelices tareas con dependencias de orden o tareas pequeñas de cinco minutos. Controla el paralelismo dentro de tres o cinco sesiones para no agotar tu cuota, y delega los lotes grandes a /batch.

---

07 Práctica: experimenta el aislamiento con worktree y tareas en segundo plano tú mismo

La práctica hace al maestro. Este ejercicio se basa en un repositorio git. Si no tienes uno, crea uno simple para practicar. Los comandos son reales, se proporcionan los resultados esperados para cada paso y seguirlos te dará memoria muscular sobre estos métodos.

Requiere un proyecto git. Para las sesiones en segundo plano, necesitas una versión reciente de Claude Code (agent view está en vista previa de investigación); verifica primero con claude --version. Los comandos siguientes no dependen de herramientas especiales de red.

Paso 1: Entra a un proyecto git y acepta el diálogo de confianza primero

cd tu-proyecto-git
claude

Una vez dentro, haz una pregunta simple (como "¿de qué trata este proyecto?") y luego sal. Este paso es necesario para aceptar la confianza del espacio de trabajo; si no lo haces, el comando --worktree del siguiente paso fallará directamente.

Paso 2: Abre una sesión aislada con --worktree

claude --worktree test-parallel

Resultado esperado: Claude crea un worktree aislado bajo .claude/worktrees/test-parallel/ e inicia allí. Cualquier archivo que modifiques en esta sesión afectará solo a esa copia, dejando el directorio principal intacto. Al salir, si modificaste algo, te preguntará si quieres "conservar o eliminar"; para esta práctica, elige eliminar.

Paso 3: Confirma que el worktree realmente se ha creado (abre otra terminal y regresa al directorio principal del proyecto)

git worktree list

Resultado esperado: En la lista de worktrees, además de la copia principal, aparecerá una nueva línea apuntando a .../.claude/worktrees/test-parallel con su propia rama. Ver esta línea confirma que la copia aislada se creó correctamente.

Paso 4: Envía una tarea al segundo plano

claude --bg "Lista los títulos de todos los archivos markdown en este proyecto"

Resultado esperado: La terminal imprime una línea con backgrounded · <ID_corto>, seguida de los comandos de administración como claude attach / claude logs / claude stop. Ver esto confirma que la tarea se envió al segundo plano y tu terminal queda libre para otras cosas.

Paso 5: Abre la pantalla de control para vigilarla

claude agents

Resultado esperado: La terminal completa es ocupada por la vista de agentes, y la sesión que acabas de enviar aparece como una fila indicando su estado (trabajando o completado). Selecciónala y presiona Space para ver detalles de su salida, presiona Esc para cerrar el panel y presiona Esc nuevamente para salir de la vista de agentes. Ver esta lista agrupada confirma que puedes administrar múltiples sesiones en segundo plano en una sola pantalla.

Paso 6: Limpieza

# Detén la sesión en segundo plano (reemplaza <ID_corto> por el impreso en el paso 4)
claude stop <ID_corto>

# Elimina el worktree de práctica (en el directorio principal del proyecto)
git worktree remove .claude/worktrees/test-parallel

Resultado esperado: claude stop imprime una confirmación de detención; después de git worktree remove, al ejecutar git worktree list nuevamente, la línea de test-parallel habrá desaparecido. Ver que todo está limpio confirma que has completado el ciclo.

Al completar estos seis pasos, habrás experimentado todo el flujo: "abrir sesión aislada → verificar copia → enviar al segundo plano → vigilar en la pantalla → limpiar". En el futuro, cualquier paralelización que realices usará este mismo flujo, solo que con tareas y sesiones reales.

💡 Resumen rápido: El flujo de práctica consta de seis pasos: claude (aceptar confianza) → --worktree para abrir una sesión aislada → git worktree list para verificar → --bg para enviar al segundo plano → claude agents para vigilar → stop + git worktree remove para limpiar. Experimentarlo una vez es mejor que memorizar diez comandos.

---

08 Resumen

Este artículo abarca todo lo relacionado con "hacer que varios Claude tengan tareas al mismo tiempo", desde "por qué paralelizar" hasta "cuándo no hacerlo", detallando tres métodos prácticos.

Repasemos los puntos clave:

Qué quieres hacer	Qué usar	Detalle clave
Entender qué resuelve el paralelismo	Las dos condiciones de "independencia + no competir por archivos"	Como abrir más cajas en el supermercado, pero cada fila debe ser independiente
Conocer los tipos de paralelismo	Tabla de las cuatro formas oficiales	"Quién coordina" es el factor decisivo; agent view y workflows son de vista previa, teams es experimental
Evitar que las sesiones sobrescriban archivos	--worktree / git worktree	Da a cada sesión una copia aislada; recuerda agregar a .gitignore, configurar .worktreeinclude y limpiar
Enviar tareas al segundo plano e interactuar en una pantalla	--bg + claude agents	Las sesiones en segundo plano no se atan a la terminal y se aíslan automáticamente con worktree; usa Space para detalles y Enter para acoplarte
Ejecutar tareas mediante scripts por lotes	claude -p (headless)	Usa --allowedTools para aprobar herramientas de antemano, --bare para acelerar y --output-format json para resultados estructurados
Decidir cuándo no paralelizar	La regla de oro "independencia + no competir por archivos"	No dividas tareas con dependencias de orden o tareas pequeñas; controla el paralelismo dentro de tres o cinco sesiones

Ahora deberías ser capaz de: entender qué resuelve el paralelismo y que su regla de oro es "independencia y no competir por archivos"; distinguir cuál de las cuatro formas oficiales elegir; usar --worktree para dar a cada sesión una copia aislada evitando sobrescrituras; usar --bg y claude agents para enviar tareas al segundo plano e interactuar en una sola pantalla; usar claude -p para ejecutar tareas con scripts por lotes; y lo más important: ante cualquier tarea, decidir con calma si vale la pena paralelizar antes de dividirla.

Recordando el desastre de "modificar el mismo directorio en dos terminales", la causa raíz era no entender el aislamiento ni las dependencias. Ahora tienes la llave del aislamiento con worktrees y la regla de decisión para evitar dar rodeos innecesarios.

---

El siguiente artículo es 42 "Variables de entorno". En este artículo ya has visto algunas de ellas: CLAUDE_CODE_SIMPLE detrás de --bare, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS para desactivar tareas en segundo plano, CLAUDE_CONFIG_DIR para cambiar el directorio de configuración... Funcionan como interruptores ocultos que modifican silenciosamente el comportamiento de Claude Code. En el próximo artículo los analizaremos uno por uno para explicarte qué hace cada uno y cuáles vale la pena ajustar. Piensa en esto: la misma línea de comandos puede comportarse de manera diferente en tu máquina y en el entorno de CI; esa diferencia a menudo se esconde en las variables de entorno.

---

Lecturas recomendadas

• Cómo preguntar y dar instrucciones: comunicándote de forma efectiva con Claude
• Glosario (apto para principiantes): traduciendo la jerga técnica al lenguaje cotidiano
• GitHub Actions: menciona a Claude en un PR para que trabaje de forma autónoma