A finales de noviembre del año pasado estaba tres semanas dentro de un build de WooCommerce para un cliente mayorista. Treinta y tantos tipos de post personalizados, un motor de precios a medida, y un flujo de checkout con más lógica condicional de la que me gustaría recordar. Yo era el único desarrollador en el proyecto. Y estaba perdiendo días solo por cambiar de contexto entre la capa de plugins, los overrides del tema, y los endpoints de la API REST.
Fue entonces cuando me comprometí de verdad con ejecutar Claude Code subagents en paralelo. No experimentando. De verdad reestructurando cómo divido el trabajo para que múltiples agentes puedan avanzar simultáneamente sin pisarse.
Aquí está lo que aprendí, incluyendo dónde me equivoqué al principio.
---
Qué Significa "Subagents" Realmente en Claude Code
La gente usa la palabra sin mucha precisión. En el framework agéntico de Claude, un subagent es simplemente una instancia de Claude que recibe una tarea acotada de un orquestador, la ejecuta y devuelve el resultado. El orquestador (que puede ser una sesión de Claude) decide cómo dividir el trabajo, qué subagents activar y cómo combinar los resultados.
En la práctica, para la mayoría de nosotros que construimos sitios y aplicaciones, esto significa ejecutar múltiples sesiones de terminal, cada una con un contexto Claude Code enfocado, contra el mismo repositorio. A veces la orquestación es automatizada mediante un script. A menudo, honestamente, es solo yo coordinando manualmente qué está haciendo cada agente desde un documento de planificación en Notion.
La diferencia entre trabajo secuencial y en paralelo
El trabajo agéntico secuencial es lo que la mayoría de desarrolladores hacemos por defecto: pedirle a Claude que haga la tarea A, esperar, luego pedirle que haga la tarea B. Está bien para cosas simples. Pero si A y B no dependen del output una de la otra, estás desperdiciando tiempo.
Los subagents en paralelo se ejecutan simultáneamente en flujos de trabajo independientes. El proyecto de WooCommerce que mencioné: tenía un agente refactorizando la lógica del motor de precios mientras otro estaba generando comentarios PHPDoc en los controladores de la API REST. Cero solapamiento. Ambos terminados en el tiempo que habría tomado hacer uno.
---
Cómo Estructuro Realmente la División del Trabajo
Esta es la parte que nadie explica con suficiente claridad. La configuración del agente es lo fácil. Lo difícil es averiguar qué dividir.
Uso una regla simple que inventé después de un incidente doloroso de conflicto de merge en 2022: ningún agente debe tocar el mismo archivo durante la misma sesión. Sin excepciones. Si no puedo garantizar eso, las tareas no se ejecutan en paralelo.
Mi paso de planificación antes de cualquier ejecución en paralelo
Antes de activar cualquier cosa, escribo un breve manifiesto de tareas. Nada complicado, solo un archivo de texto plano o una página en Notion con:
- Nombre de la tarea y una descripción de una línea
- Archivos en alcance (lista explícita)
- Archivos fuera de alcance (cualquier cosa adyacente que podría tentar a un agente a divagar)
- Formato de output esperado
- Cualquier contexto que el agente necesite que no esté en la base de código
Esto me toma quizás 15 minutos. Me ha salvado de un número genuinamente vergonzoso de conflictos.
---
Los Tres Tipos de Flujos de Trabajo que Divido con Más Frecuencia
Con más de 12,000+ construcciones de sitios en Seahawk, y mi propio trabajo con clientes en solitario al margen, he notado que las mismas categorías aparecen repetidamente como buenos candidatos para la paralelización.
1. Generación de documentación y código
Un agente escribe o refactoriza código. Otro escribe documentación, pruebas o comentarios para un módulo diferente. Estos casi nunca entran en conflicto y ambos son genuinamente tediosos de hacer manualmente. En el proyecto mayorista de WooCommerce, tenía un subagente generando stubs de pruebas PHPUnit para las funciones de precios mientras otro estaba construyendo las columnas de administrador personalizadas. Los stubs de prueba tomaron aproximadamente cuatro minutos. Las columnas de administrador tomaron doce. No perdí ninguno de esos cuatro minutos esperando.
2. Aislamiento de frontend y backend
Si tu frontend y backend viven en directorios claramente separados (que deberían, pero eso es otro artículo), esta es una división natural. He ejecutado un subagente construyendo componentes React en /resources/js mientras otro estaba conectando controladores Laravel en /app/Http . El único punto de coordinación fue acordar el contrato de API antes de que cualquiera de los agentes comenzara. Lo escribí en un archivo AGENTS.md en la raíz del proyecto. Ambos agentes lo consultaron.
3. Refactorización módulo por módulo
Las refactorizaciones grandes son miserables cuando se hacen secuencialmente. Si tienes, digamos, ocho módulos de funciones que cada uno necesita el mismo tipo de cambio (actualizar un método obsoleto, migrar a un nuevo helper, lo que sea), divídelos entre agentes. Una vez ejecuté cuatro agentes simultáneos migrando un plugin heredado de bucles WP_Query a un patrón de repositorio. Cada agente obtuvo dos módulos. Hecho en menos de una hora. Secuencialmente eso iba a ser medio día.
---
Configuración de Herramientas: Lo Que Realmente Uso
No voy a pretender que tengo una infraestructura elaborada. Mi configuración actual es:
- Claude Code ejecutándose en múltiples paneles
tmuxen una sola MacBook Pro M3 - Un archivo
AGENTS.mdcompartido en la raíz del proyecto que define convenciones, propiedad de archivos y el contrato de API entre flujos de trabajo - Ramas Git por agente. Siempre. Incluso si la rama solo existe durante veinte minutos
- Un rápido
git diff --statantes de cualquier fusión para detectar sorpresas
El archivo AGENTS.md es probablemente lo más útil que he añadido a mi flujo de trabajo en el último año. Es un archivo markdown simple que le dice a cualquier agente (o humano, en realidad) cuáles son las convenciones del proyecto, qué archivos pertenecen a qué flujo de trabajo y qué evitar tocar. Piénsalo como un CONTRIBUTING.md pero escrito para ventanas de contexto de IA.
Sobre la gestión de ventanas de contexto
Aquí es donde la gente se vuelve perezosa y luego confundida. Cada subagente tiene su propio contexto. Eso significa que si el Agente B necesita saber qué decidió el Agente A, tienes que decírselo explícitamente. No lo sabrá automáticamente.
Lo manejo manteniendo un SESSION_LOG.md que actualizo manualmente después de que cada agente completa un fragmento. Son tres a cinco puntos máximo: qué se hizo, qué cambió, qué el siguiente agente necesita saber. La sobrecarga es baja. La alternativa es que un agente haga suposiciones que rompan tu código, y esa sobrecarga es mucho mayor.
---
Dónde Sale Mal (Desde la Experiencia Dolorosa)
Seahawk tenía un proyecto de panel de control fintech la primavera pasada donde intentamos ejecutar subagentes en un monorepo sin propiedad de archivos adecuadamente definida. Dos agentes decidieron actualizar el archivo compartido utils/formatters.ts . Ninguno sabía del otro. La fusión resultante estuvo bien, técnicamente, pero pasamos 40 minutos reconciliando la intención. Completamente evitable.
Los modos de fallo que veo repetidamente:
- Archivos de utilidad compartidos. Estos son una trampa. Bloquéalos. Si un subagente necesita actualizar una utilidad compartida, esa tarea debe ejecutarse sola, no en paralelo.
- Descripciones de tareas vagas. Un agente que recibe "limpia el módulo de auth" lo interpretará de forma muy diferente dependiendo de lo que haya en su contexto. Sé específico. "Refactoriza
AuthController.phppara usar la interfazUserRepositoryya definida enapp/Repositories/UserRepository.php. No modifiques la interfaz en sí." Esa es una instrucción segura. - Sin aislamiento de ramas. Ejecutar todos los agentes en
maines cómo creas tardes viernes emocionantes. Las ramas no cuestan nada. - Sin el manifiesto. Lo sé, lo sé. Se siente como carga adicional. Hazlo de todas formas. Cada vez que lo he saltado, me he arrepentido en menos de una hora.
---
Una Ejecución Paralela Real, Paso a Paso
Así fue más o menos la sesión del martes pasado para un proyecto de migración de Shopify a WooCommerce (anonimizado, pero la estructura es exacta).
- Escribí el manifiesto de tareas en Notion. Cuatro tareas identificadas como paralelizables.
- Creé cuatro ramas git: agent/product-import, agent/tax-logic, agent/rest-endpoints,
agent/admin-ui. - Abrí cuatro paneles
tmux, una sesión de Claude Code en cada uno. - Pegué la sección relevante de
AGENTS.mdal inicio de cada sesión como contexto. - Gave each agent its task prompt, referencing specific files.
- Ejecuté los cuatro simultáneamente. Me hice un café. Realmente lo bebí mientras aún estaba caliente, lo que se sintió como un milagro.
- Revisé cada rama. Ejecuté
phpcsen el PHP,eslinten cualquier JS modificado. - Fusioné en secuencia: importación de productos primero (los otros tenían dependencias ligeras de su esquema), luego lógica fiscal, luego los endpoints REST, luego la UI de admin.
- Actualicé
SESSION_LOG.mdcon lo que cambió.
Tiempo total para las cuatro tareas combinadas: aproximadamente 35 minutos. Mi estimación para completarlas secuencialmente era 90 minutos a 2 horas. Me lo quedo.
---
Qué Esto Hace (y No Hace) Reemplazar
Los suagentes paralelos no son un sustituto para pensar. Ese paso de planificación de 15 minutos es genuinamente tú haciendo el trabajo de arquitectura. Los agentes ejecutan. Aún tienes que saber qué construir, cómo encajan las piezas, y si el resultado es realmente correcto.
Reviso la salida de cada agente antes de que toque main. Cada sola vez. He atrapado a un suagente escribir con confianza una capa de caché que habría causado problemas de datos obsoletos en una configuración multisitio. El código se veía bien. Era lógicamente incorrecto para el contexto específico. Solo lo capté porque lo leí.
La orientación de Anthropic sobre tareas de agentes específicamente marca la importancia de los puntos de control humanos antes de acciones irreversibles. Eso no es un lugar común corporativo. Es realmente un consejo importante, especialmente cuando los agentes tienen acceso de escritura a bases de datos o están ejecutando migraciones.
La otra cosa que esto no reemplaza: comunicación con clientes. Un agente puede construir una característica. No puede decirle a un cliente por qué un plazo se movió o gestionar expectativas alrededor de cambio de alcance. Esa parte sigue siendo tuya.
---
FAQ
¿Necesito acceso especial a API o herramientas para ejecutar suagentes de Claude Code?
No se requiere configuración exótica. Claude Code es la herramienta de codificación basada en terminal de Anthropic, y puedes ejecutar múltiples instancias en sesiones de terminal separadas (yo uso tmux). Necesitas una clave de API de Claude con límites de velocidad suficientes si estás accediendo a la API directamente. Para cargas de trabajo paralelas pesadas, verifica tu nivel de límite de velocidad antes de empezar para no quedarte sin conexión a mitad de sesión.
¿Cómo evito que los agentes entren en conflicto sobre archivos compartidos?
Define file ownership before you start. The AGENTS.md convention I described works well. If two tasks both need a shared utility file changed, don't parallelize those two tasks. Run the shared utility change first, commit it, then run the other tasks in parallel from that clean base.
¿Esto solo es útil en proyectos grandes?
Honestamente, no. Lo he usado en sitios de una sola página donde quería que la documentación se generara junto con código de nuevas funcionalidades. La sobrecarga de planificación es lo suficientemente baja que incluso ahorros de tiempo modestos la justifican. Dicho esto, si un proyecto tiene menos de quizás cinco tareas distintas paralelizables, el tiempo de configuración comienza a superar el beneficio. Usa tu criterio.
¿Qué pasa si un agente produce una salida deficiente?
Lo capturas en la revisión, descartas la rama e intentas de nuevo con un prompt más específico. Ese es todo el punto del aislamiento de ramas. Una salida deficiente del agente te cuesta el tiempo para revisarla y re-indicar. No debería costarte una base de código rota si estás siguiendo la regla de rama-por-agente.
¿Puedo automatizar la orquestación en lugar de hacerlo manualmente?
Sí, y para flujos de trabajo repetidos vale la pena. He escrito scripts simples en Bash que lanzan llamadas secuenciales a Claude Code con prompts y contexto predefinidos. Para orquestación paralela completamente automatizada, construirías una capa de orquestador que genere agentes programáticamente, recoja salidas y maneje dependencias. Esa es una inversión de ingeniería más grande. Para la mayoría de freelancers y agencias pequeñas, la coordinación manual con tmux y un manifiesto de tareas es suficiente.
---
La verdad honesta es que los subagentes paralelos no me convirtieron en un desarrollador dramáticamente mejor. Me convirtieron en uno más rápido, en la clase específica de tareas donde el cuello de botella era la ejecución en lugar del pensamiento. El pensamiento sigue siendo mío. Las decisiones de arquitectura, las llamadas con clientes, la revisión de código. Todo sigue siendo mío.
¿Pero las partes de ejecución tediosa? Me llevaré cada minuto que pueda recuperar.