Tienes un feature que necesita tres cosas al mismo tiempo. Puedes lanzar subagentes dentro de una sola sesion de Claude Code y dejarlos trabajar en paralelo. O puedes dividir el trabajo en tres tareas independientes, entregar cada una a un agente separado en su propio panel tmux, y dejarlos correr sin saber nada uno del otro.

Ambos enfoques paralelizan trabajo. Resuelven problemas distintos. Elige el incorrecto y terminaras quemando ventana de contexto en overhead de coordinacion o creando conflictos de merge que toman mas tiempo en resolver que la tarea original.

Este es el framework de decision que uso cada dia mientras corro 13 agentes Claude Code en la misma codebase. No es teorico. Es el resultado de haberme equivocado suficientes veces como para saber donde esta el limite.

Dos tipos de paralelismo

Claude Code soporta dos formas distintas de ejecutar trabajo concurrentemente.

Los subagentes son procesos hijos que se lanzan dentro de una sola sesion de Claude Code. El agente padre inicia multiples subagentes, cada uno aborda una parte del problema, y luego recolecta los resultados. Comparten el mismo directorio de trabajo y el contexto del padre. Piensa en ellos como threads en un solo proceso.

Parent agent
  ├── Subagent A: "Search lib/ for all usages of parseConfig"
  ├── Subagent B: "Search server/ for all usages of parseConfig"
  └── Subagent C: "Search components/ for all usages of parseConfig"

Los agentes separados corren en sesiones independientes de Claude Code, tipicamente en paneles tmux separados. Cada uno tiene su propia ventana de contexto, su propio archivo de identidad CLAUDE.md y su propia vista de la codebase. No comparten memoria. Se comunican a traves de artefactos: comentarios en tareas, actualizaciones de estado, codigo commiteado. Piensa en ellos como procesos separados sin estado compartido.

tmux pane 1: eng1 agent → "Build the REST endpoint"
tmux pane 2: eng2 agent → "Build the React component"
tmux pane 3: qa1 agent  → "Write integration tests for both"

El modelo mental importa porque determina como fluye el trabajo entre unidades. Los subagentes pueden pasar datos al padre de forma economica. Los agentes separados pasan datos a traves del sistema de archivos, git o un task tracker externo.

Cuando ganan los subagentes

Usa subagentes cuando el trabajo comparte estado y los resultados necesitan converger.

Investigacion en paralelo. Necesitas buscar un patron en cinco directorios, leer tres archivos de documentacion y sintetizar los hallazgos en una recomendacion. Los subagentes pueden tomar cada uno una ruta de busqueda, devolver resultados, y el padre puede combinarlos sin overhead de serializacion.

Transformaciones independientes sobre los mismos datos. Estas refactorizando un modulo y necesitas actualizar las definiciones de tipos, los tests y la documentacion en un cambio coherente. Cada subagente se encarga de un archivo, pero el padre asegura que los cambios sean consistentes porque ve los tres resultados antes de commitear.

Exploracion rapida. Estas debuggeando y necesitas revisar el git log, la salida de tests y la configuracion de runtime simultaneamente. Los subagentes pueden recopilar los tres en paralelo y el padre sintetiza un diagnostico.

El patron: distribuir, recopilar, actuar sobre el resultado combinado. Si tu paralelismo termina con el padre necesitando razonar sobre todos los outputs juntos, los subagentes son la herramienta correcta.

En que fallan los subagentes: cualquier cosa que tome mas de unos minutos por rama, cualquier cosa que modifique archivos en rutas superpuestas, o cualquier cosa que necesite verificacion independiente. Los subagentes comparten un directorio de trabajo, asi que dos subagentes escribiendo en el mismo archivo corromperan el trabajo del otro. Y como comparten contexto, un subagente de larga duracion consume la ventana disponible del padre.

Cuando ganan los agentes separados

Usa agentes separados cuando el trabajo puede verificarse de forma independiente y no necesita un contexto compartido para tener sentido.

Diferentes componentes del mismo feature. "Construye el endpoint de API" y "Construye el frontend que lo llama" son independientes hasta la integracion. El ingeniero de API no necesita el componente React en su contexto. El ingeniero de frontend no necesita el esquema de base de datos. Darle a cada uno su propio agente con un CLAUDE.md acotado mantiene el contexto limpio y evita que la complejidad de un agente contamine el trabajo del otro.

Diferentes criterios de aceptacion. Si la tarea A esta terminada cuando el endpoint devuelve 200 con la forma JSON correcta, y la tarea B esta terminada cuando el componente renderiza los datos con estados de error adecuados, esos son objetivos de verificacion separados. Un agente QA puede validar cada uno independientemente. Los subagentes no pueden verificarse independientemente porque producen un output combinado.

Trabajo que toca diferentes partes de la codebase. File ownership es la forma mas simple de prevenir conflictos de merge. El agente A es dueno de server/, el agente B es dueno de components/. Ninguno entra en territorio del otro. Si intentas esto con subagentes, el padre tendria que gestionar file locking, lo cual anula el proposito del paralelismo.

Tareas con diferentes horizontes de tiempo. Una tarea toma 10 minutos, la otra 2 horas. Con subagentes, el padre espera al hijo mas lento. Con agentes separados, la tarea corta se completa, se verifica y se shipea mientras la tarea larga sigue corriendo.

El patron: lanzar, olvidar, verificar por separado. Si cada pieza de trabajo se sostiene sola y puede verificarse sola, los agentes separados con tareas estructuradas son mas limpios.

El problema del handoff

El verdadero punto de decision se reduce a los handoffs.

Los handoffs de subagentes son economicos. El hijo devuelve datos al padre en el mismo contexto. Sin serializacion, sin escrituras a archivos, sin esperar actualizaciones de estado. El padre lanza tres subagentes, devuelven tres resultados, el padre tiene todo lo que necesita.

Los handoffs entre agentes separados son costosos pero durables. El agente A completa trabajo, commitea codigo, actualiza un estado de tarea y comenta lo que hizo. El agente B recoge esa senal (ya sea a traves de un coordinador o haciendo polling del task tracker) y comienza su trabajo dependiente. El overhead es real: necesitas un sistema de tareas, un protocolo de estados y alguna forma para que los agentes descubran lo que otros agentes han hecho.

La regla general: si el trabajo requiere mas de un handoff entre las unidades paralelas, usa subagentes. Si es un solo fan-out-and-gather, los subagentes son mas simples. Si el output del agente A es el input del agente B, que se convierte en el input del agente C, el costo de coordinacion de agentes separados esta justificado porque cada handoff produce un artefacto verificado y commiteado que no se perdera si un agente crashea o alcanza un limite de contexto.

Un ejemplo concreto. Necesitas:

Encontrar todos los endpoints de API que devuelven datos de usuario
Agregar rate limiting a cada uno
Escribir tests para los nuevos rate limits
Actualizar la documentacion de la API

Los pasos 1 y 2 estan fuertemente acoplados. Los resultados de busqueda (paso 1) alimentan directamente la modificacion (paso 2). Un subagente maneja la busqueda; el padre aplica los cambios. Eso es un patron de subagente.

Los pasos 3 y 4 son independientes entre si pero dependen del paso 2. Los tests necesitan el codigo real del endpoint. Los docs necesitan la forma final de la API. Estas son tareas separadas para agentes separados, cada una con sus propios criterios de aceptacion, cada una verificable por si misma.

Desglose estructurado de tareas en la practica

Cuando la respuesta es "agentes separados," necesitas una forma de descomponer el feature en tareas que puedan correr en paralelo sin pisarse entre si.

El proceso de descomposicion:

1. Identificar el grafo de dependencias. Antes de dividir nada, mapea que depende de que:

Feature: User profile page with activity feed

- API endpoint: GET /users/:id/profile     (no deps)
- API endpoint: GET /users/:id/activity     (no deps)
- React component: ProfileHeader            (depends on profile API)
- React component: ActivityFeed             (depends on activity API)
- Integration test: profile page end-to-end (depends on all above)

Los dos endpoints de API no tienen dependencias. Pueden correr en paralelo. Los dos componentes React dependen cada uno de una API. El test de integracion depende de todo.

2. Trazar los limites de ownership. Cada tarea obtiene un scope de archivos. El agente del profile API es dueno de server/routes/profile.ts y server/services/profile.ts. El agente del activity API es dueno de server/routes/activity.ts y server/services/activity.ts. Ninguno toca los archivos del otro. Si una utilidad compartida necesita modificacion, un agente crea el cambio y el otro espera.

3. Definir criterios de aceptacion por tarea. Cada tarea necesita una condicion clara de "listo" que pueda verificarse sin mirar las otras tareas. "Profile API devuelve 200 con la forma correcta" es verificable. "La pagina de perfil funciona" no, porque depende de la integracion.

4. Especificar los artefactos de handoff. Que necesita un agente downstream de uno upstream? Normalmente: codigo commiteado en un branch conocido, una actualizacion de estado y un comentario describiendo el contrato de interfaz (forma de API, props de componentes, firmas de funciones).

Esta descomposicion transforma un vago "construye la pagina de perfil" en cinco tareas discretas con dependencias explicitas y criterios de verificacion. Cada tarea puede asignarse a un agente que tiene exactamente el contexto que necesita y nada mas.

Beads para desglose estructurado

Aqui es donde tener un sistema real de tareas importa. No puedes rastrear cinco tareas paralelas con notas adhesivas y output de terminal.

beads es un issue tracker local-first que modela esta descomposicion de forma nativa. Un epic representa el feature. Los children representan los subtasks. Las dependencias evitan que los agentes comiencen trabajo antes de que los prerrequisitos esten listos.

Asi se ve el desglose en la practica:

# Create the epic
bd create --title "User profile page with activity feed" \
  --type epic --priority p2

# Create subtasks as children
bd create --title "GET /users/:id/profile endpoint" \
  --parent bb-epic1 --type task --priority p2

bd create --title "GET /users/:id/activity endpoint" \
  --parent bb-epic1 --type task --priority p2

bd create --title "ProfileHeader React component" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-profile-api

bd create --title "ActivityFeed React component" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-activity-api

bd create --title "Profile page integration test" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-profile-header,bb-activity-feed

Ahora la estructura es explicita. Un agente ejecutando bd show bb-profile-header ve que depende de la tarea del profile API. Si esa tarea no esta lista, el agente sabe que no debe empezar. Cuando el agente de API termina y marca su tarea como completa, la dependencia del agente frontend se resuelve.

El workflow del agente sigue un ciclo predecible:

# Agent claims the task
bd update bb-profile-api --claim --actor eng1

# Agent comments its plan before writing code
bd comments add bb-profile-api --author eng1 "PLAN:
1. Create route handler at server/routes/profile.ts
2. Add service layer at server/services/profile.ts
3. Return shape: { id, name, avatar, bio, joinedAt }
4. Test: curl localhost:3000/users/1/profile returns 200"

# Agent implements, tests, commits
# ...

# Agent marks done with verification steps
bd comments add bb-profile-api --author eng1 "DONE: Profile endpoint implemented.
Returns { id, name, avatar, bio, joinedAt }.
Verified: curl returns 200 with correct shape.
Commit: abc1234"

bd update bb-profile-api --status ready_for_qa

Cada paso queda registrado. El agente QA lee el comentario DONE y sabe exactamente como verificar. El agente downstream lee el comentario PLAN y conoce el contrato de API antes de que el codigo este terminado.

Esto no es overhead por el gusto del proceso. Es la estructura minima que evita que cinco agentes paralelos produzcan cinco piezas de codigo incompatibles.

Elegir por defecto

Despues de meses corriendo agentes en paralelo sobre trabajo de produccion, este es el arbol de decision que sigo:

Comienza con subagentes cuando:

La tarea es investigacion o exploracion (buscar, leer, comparar)
Los resultados necesitan converger en una sola accion
Todo el trabajo cabe en una ventana de contexto
No hay necesidad de verificacion independiente de cada unidad paralela

Cambia a tareas separadas cuando:

Diferentes partes del trabajo tocan diferentes archivos
Cada pieza tiene sus propios criterios de aceptacion
Quieres que QA verifique piezas independientemente
El trabajo durara lo suficiente como para que una pieza termine horas antes que otra
Los agentes necesitan diferente contexto (un agente de frontend no necesita internals de base de datos)

El enfoque hibrido para features complejos: Usa subagentes para la fase de investigacion y planificacion (distribuir, recopilar informacion, sintetizar un plan), luego descompone la implementacion en tareas separadas para agentes independientes. El workflow de spec-driven development encaja naturalmente aqui: un solo agente con subagentes escribe la spec, luego la spec se descompone en tareas para la flota multi-agente.

Visualizando el desglose

Una vez que tienes cinco o diez tareas estructuradas con dependencias entre ellas, rastrear el progreso en la terminal se vuelve dificil. bd list te muestra una lista plana. No muestra cuales tareas estan bloqueadas, cuales estan listas para empezar o cuanto ha progresado el epic.

Este es el problema que Beadbox resuelve. Lee la misma base de datos de beads y renderiza arboles de epics con indicadores de progreso, relaciones de dependencia y asignaciones de agentes. Ves cuales subtasks estan terminados, cuales estan bloqueados por prerrequisitos y cuales estan listos para que un agente los tome. El grafo de dependencias que especificaste con --deps se convierte en un mapa visual de tu trabajo paralelo.

Cuando un agente termina una tarea y actualiza el estado, Beadbox refleja el cambio en tiempo real. Sin refresh, sin volver a ejecutar bd list. El arbol se actualiza, la barra de progreso avanza y las tareas bloqueadas se desbloquean cuando sus dependencias se resuelven.

Son los mismos datos. Solo que visibles.

Si estas construyendo workflows como estos, dale una estrella a Beadbox en GitHub.

Subagentes de Claude Code vs. desglose estructurado de tareas: cuando usar cada uno