"Estoy usando Claude Code, pero a medida que crece la escala, el contexto se desborda y la precisión baja."
"Al final, mis propias manos dando instrucciones de corrección a la IA se han convertido en el cuello de botella más grande."
Muchas personas probablemente están estancadas en este punto. Yo también estaba igual al principio, metiendo código, pruebas y discusiones de diseño todo en una misma sesión, viendo cómo la precisión de Claude disminuía a medida que el historial se expandía.
Lo que me he dado cuenta recientemente es que el propio Claude Code ofrece oficialmente tres mecanismos para ejecutar múltiples sesiones en paralelo.
Además, estos tres son similares pero distintos; confundirlos puede provocar accidentes. Por el contrario, si los divides por rol, puedes pasar al "lado del mando" sin escribir ni una sola línea de código tú mismo.
Hoy voy a organizar estos tres mecanismos y la forma correcta de fijar los límites de los roles mientras reviso la información principal de la documentación oficial.
Específicamente, lo desglosaré en una configuración donde se colocan 8 sesiones en tres capas: Comando, Implementación y Calidad.
Como bonus, también usaré información principal para explicar por qué explicaciones comunes como "escribir IDs de roles en CLAUDE.md para cambiar" o "compartir memoria con SQLite" se desvían un poco del mecanismo oficial.
Mi nombre es tatsuki (@nobel_824).
Apoyo la utilización de IA para pequeñas y medianas empresas, ayudando con la implementación empresarial de Claude/Codex mientras yo mismo ejecuto Claude Code todo el día todos los días la operación paralela es un área que toco todos los días tanto para trabajo como para proyectos personales. La operación paralela es un área que trabajo todos los días tanto por trabajo como en proyectos personales.
Artículo relacionado: Introducción al Vibe Coding: 6 Pasos para que no programadores creen apps con Claude La era de la producción interna en un fin de semana
https://note.com/nobel/n/n8192ec07d689
1. Por qué "meter todo en una sola sesión" falla
La primera trampa es sobrecargar una sola sesión con demasiada información. Por más inteligente que sea el modelo Claude, se topa con límites estructurales.
Específicamente, te encuentras con estos tres problemas:
- Contaminación del contexto: Cuando el código de implementación, las pruebas, el historial de depuración y las discusiones de diseño se mezclan en el mismo contexto, la base del razonamiento se vuelve turbia y la precisión baja.
- Conflicto de instrucciones: Si "implementa con prioridad de velocidad" y "sé estricto con la seguridad" existen en el mismo lugar, los juicios se vuelven a medias.
- Inflado de tokens: Cargar un historial masivo cada vez es una pérdida tanto de tiempo como de costo.
La solución es la idea de "convertirte en un solo comandante y alinear Claudes especializados". Es similar a que un CTO tenga un Tech Lead y un Backend Lead, pero lo importante no es la vibra, sino utilizar correctamente los mecanismos oficiales de Claude Code.
Una acción que puedes tomar hoy: Piensa en tu sesión actual y verifica si la "implementación", la "investigación" y la "revisión" coexisten en un mismo contexto. Si es así, ese es tu punto de partida para dividirlas.
2. Corrigiendo los "tres mecanismos paralelos" proporcionados oficialmente
Este es el núcleo del artículo. Claude Code tiene tres mecanismos para el paralelismo, cada uno con un alcance diferente.
El primero es subagent (un AI ayudante que se ejecuta en un contexto separado de la conversación principal). Ejecuta tareas secundarias como investigación o revisiones usando su propia ventana de contexto, un prompt de sistema dedicado y permisos de herramientas limitados, devolviendo solo un resumen de los resultados a la sesión principal. El punto clave es que los subagentes se ejecutan dentro de la misma sesión, reportan solo al principal, y los subagentes no se comunican entre sí (Documentación oficial).
El segundo son los equipos de agentes (un mecanismo donde múltiples sesiones de Claude Code colaboran como un equipo). Una sesión se convierte en el líder del equipo y genera compañeros de equipo, colaborando a través de una lista de tareas compartida y un buzón de correo. A diferencia de los subagentes, los compañeros de equipo pueden enviarse mensajes directamente entre sí. Esta es una función experimental y está deshabilitada por defecto. Necesitas configurar CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 y usar Claude Code v2.1.32 o posterior (Documentación oficial).
El tercero es git worktree (una función de Git que permite múltiples directorios de trabajo desde el mismo repositorio). Al iniciar con claude --worktree feature-auth, Claude se lanza en un entorno aislado en una rama/directorio diferente. Si ejecutas otro en una terminal diferente, pueden ejecutarse en paralelo sin pisar los archivos del otro (Documentación oficial). Al usar la aplicación de escritorio, se crea automáticamente un worktree para cada nueva sesión.
Aquí tienes una tabla comparando los tres:
No te confundirás si recuerdas que worktree maneja el aislamiento de archivos, mientras que los subagentes y los equipos de agentes manejan la coordinación del trabajo en sí.
Una acción que puedes tomar hoy: Primero, intenta escribir claude --worktree bugfix-test para tener una idea de cómo lanzar una sesión aislada. Cuando termines después de hacer cambios, te preguntará si deseas conservar o eliminar el worktree.
3. Práctica: Desplegando 8 sesiones en una "estructura de 3 capas"
¿Cómo se traducen estos tres mecanismos en 8 sesiones? Yo uso un diseño dividido en capas de Comando, Ejecución y Calidad.
Capa de Comando/Diseño (2 sesiones)
- Sesión 1 PM (Project Manager): Gestión general del progreso, desglose de tareas, informes a humanos.
- Sesión 2 Arquitecto: Decide la coherencia técnica y la estructura de directorios. Requiere aprobación del plan para producir diseños sin escribir código.
Capa de Ejecución/Implementación (4 sesiones)
- Sesión 3 Frontend: Creación de componentes, ajustes de UI.
- Sesión 4 Backend: Implementación de endpoints, optimización de consultas.
- Sesión 5 Infra/DevOps: Mantenimiento de Docker, CI/CD.
- Sesión 6 Seguridad: Verificaciones de vulnerabilidades, endurecimiento de autenticación.
Capa de Calidad/Mantenimiento (2 sesiones)
- Sesión 7 QA/Revisor: Revisiones de PR, señalización de casos extremos.
- Sesión 8 Technical Writer: Mantenimiento de README, documentación de API.
Hay tres consejos para este diseño: Aísla las cuatro sesiones de la capa de implementación con worktrees para que no se pisen los archivos entre sí. Fija los roles para la capa de calidad como definiciones de subagentes o compañeros de equipo de agentes. Y haz que cada sesión transmita información a través de archivos Markdown compartidos (notas de diseño o resultados de revisión). El Arquitecto actualiza el diseño, la capa de implementación se mueve basándose en eso, y el Revisor escribe los resultados. Los humanos solo necesitan dar instrucciones a cada sesión activadas por estas actualizaciones de archivos.
Una nota: La guía oficial para un equipo de agentes es de 3 a 5 personas, así que no metas a los 8 en un solo equipo de una vez (Documentación oficial). Es más seguro combinar sesiones aisladas por worktree con un equipo de agentes de 3 a 5 personas y subagentes según sea necesario para alcanzar un total de 8 trabajadores.
Una acción que puedes tomar hoy: Elige dos roles de los 8 anteriores que parezcan fáciles de dividir en tu proyecto actual. En muchos casos, el Arquitecto y el Revisor son los primeros puntos de división.
4. Fija los límites de los roles con "definiciones de subagentes", no con "CLAUDE.md"
Déjame corregir un malentendido común sobre la operación paralela. Puede que veas explicaciones como "Escribe roles (ID: arch, ID: dev-main...) en CLAUDE.md y cambia de persona al inicio", pero este mecanismo en realidad no existe.
CLAUDE.md es un archivo de instrucciones compartido que Claude Code lee al inicio. Sin embargo, la documentación oficial establece claramente que CLAUDE.md es "contexto, no una configuración forzada". Dado que se pasa como un mensaje de usuario después del prompt del sistema, no se garantiza un cumplimiento estricto. Si quieres detener algo absolutamente, deberías usar hooks (Documentación oficial). Piénsalo como una recomendación fuerte, no como una "constitución" absoluta.
Entonces, ¿dónde fijas los roles? La respuesta son las definiciones de subagentes. Al colocar un archivo dentro de .claude/agents/ con un nombre, descripción, herramientas disponibles y modelo en el frontmatter, completas un experto reutilizable. Aquí tienes un ejemplo mínimo:
name: security-reviewer
description: Audita críticamente el código desde la perspectiva de la autenticación, validación de entrada y gestión de sesiones.
tools: Read, Grep, Bash
model: sonnet
Eres un revisor de seguridad senior. Concéntrate en el manejo de tokens,
la gestión de sesiones y la validación de entrada, e informa los hallazgos con niveles de severidad.
Además, estas definiciones pueden ser invocadas por nombre como compañeros de equipo en equipos de agentes. Si pides "configurar un compañero de equipo con el tipo de agente security-reviewer para auditar el módulo auth", se convierte en un miembro que hereda las herramientas y el modelo de esa definición (Documentación oficial). El diseño te permite escribir un rol una vez como definición de subagente y reutilizarlo tanto como subagente como miembro del equipo.
Ejemplo de prompt para probar (dejando que Claude cree una definición de rol):
Crea una definición de subagente para colocarla en .claude/agents/.
El rol es "un revisor que señala problemas de rendimiento y consultas N+1 en el código de implementación."
Incluye name / description / tools / model en el frontmatter,
y escribe el cuerpo en la personalidad de un ingeniero senior.
5. Construyendo un equipo "Arquitecto-Revisor" con equipos de agentes para aumentar la precisión
Una configuración que es muy efectiva en la operación paralela es configurar un "creador" y un "dudador" por separado. Esto no es solo teoría; la documentación oficial proporciona ejemplos del mundo real.
En el ejemplo oficial de "Revisión de código en paralelo", para un PR, se configuran tres compañeros de equipo para seguridad, rendimiento y cobertura de pruebas, cada uno mirando desde una perspectiva diferente mientras el líder integra los resultados. Además, en el ejemplo de "Hipótesis en competencia", se asignan a cinco compañeros de equipo diferentes hipótesis para un error con el fin de argumentar y refutar las teorías de los demás, tratando la teoría sobreviviente como la causa raíz (Documentación oficial). Dado que un único investigador tiende a dejarse llevar por la primera teoría, este enfoque crea conflicto intencionalmente para mejorar la precisión.
También puedes implementar una operación donde al Arquitecto "no se le da permiso para escribir código" usando funciones oficiales. Al requerir la aprobación del plan para un compañero de equipo, este se mantiene en un modo de plan de solo lectura, produciendo solo diseños hasta que el líder lo apruebe. Los criterios de aprobación se pueden escribir en el prompt del líder, como "solo aprobar planes que incluyan cobertura de pruebas."
Ejemplo de prompt para probar (configurando una estructura de conflicto de una sola vez):
Crea un equipo de agentes para revisar el PR #142. Configura tres compañeros de equipo:
uno para seguridad, uno para rendimiento y uno para cobertura de pruebas.
Haz que revisen de forma independiente y generen hallazgos con severidad, luego intégralos al final.
Hay dos modos de visualización: in-process (todos los compañeros de equipo se ejecutan en la misma terminal, ciclan con Shift+Down) y split panes (cada compañero de equipo en un panel separado; requiere tmux o iTerm2). Es más fácil empezar con in-process ya que no requiere configuración adicional.
6. Comparte memoria a través de la auto memoria oficial (Markdown), no con "SQLite"
Al ejecutar múltiples sesiones, el siguiente obstáculo es "compartir la memoria entre sesiones". Aunque a veces se introducen técnicas avanzadas como "almacenar memoria etiquetada en SQLite e inyectarla dinámicamente", eso no es una función estándar de Claude Code. Es posible si construyes una base de datos a través de MCP (Model Context Protocol), pero debes distinguir eso del mecanismo de memoria proporcionado oficialmente.
La auto memoria oficial funciona con archivos markdown. Dentro de ~/.claude/projects/<project>/memory/, se colocan archivos como MEMORY.md (índice) y archivos específicos de temas como debugging.md, y Claude escribe en ellos mientras trabaja. Las reglas de carga son claras: cada sesión lee hasta las primeras 200 líneas o 25KB de MEMORY.md, y Claude solo va a leer archivos específicos de temas cuando es necesario. Esto está disponible desde Claude Code v2.1.59, se guarda por repositorio (por lo tanto, se comparte entre worktrees) y se almacena localmente (Documentación oficial).
La belleza de este diseño es que, al "cargar siempre el índice y obtener los detalles solo cuando sea necesario", puedes mantener limpia la ventana de contexto. Incluso con miles de reglas pequeñas, el contexto no se contaminará cada vez, siempre que el índice no se infla.
En términos de orden, utiliza al máximo la auto memoria oficial basada en markdown antes de intentar construir una solución personalizada con SQLite.
Una acción que puedes tomar hoy: Escribir /memory durante una sesión muestra la lista de archivos CLAUDE.md y de auto memoria actualmente cargados. Primero, échale un vistazo a dónde y cuántas memorias tienes.
7. Tres dificultades en la operación paralela (Costo, BD, Permisos)
Ahora que entiendes el mecanismo, aquí tienes tres puntos de precaución para la operación.
Primero está el costo de tokens. La documentación oficial establece que, dado que cada compañero de equipo en un equipo de agentes tiene un contexto independiente, el uso de tokens aumenta proporcionalmente al número de personas. Usar 5 personas para tareas rutinarias resultará en una pérdida de costo. Por eso la recomendación oficial es de 3 a 5 personas, señalando que "tres miembros enfocados a menudo vencen a cinco miembros distraídos" (Documentación oficial).
Segundo es el alcance de aislamiento de los worktrees. Un worktree es solo un mecanismo de Git para la separación de archivos; las bases de datos, las variables de entorno y los servicios en ejecución aún se comparten. Si dos sesiones ejecutan migraciones en la misma base de datos local, se romperá. La documentación oficial advierte que "recuerdes inicializar el entorno de desarrollo (instalar dependencias, configurar entornos virtuales) en cada worktree", y si las tareas tocan la base de datos, necesitas separar esquemas, contenedores Docker o archivos .env (Documentación oficial).
Tercero son los permisos. Los compañeros de equipo heredan la configuración de permisos del líder cuando se generan. Si ejecutas el líder con --dangerously-skip-permissions, todos los compañeros de equipo también estarán en ese mismo estado sin confirmación. Dado que el impacto de un accidente se propaga en paralelo, es más seguro restringir los permisos en el lado del líder.
8. Preguntas Frecuentes para usuarios intermedios: Número de personas, Expansión y Controles de calidad
Finalmente, algunas respuestas complementarias a preguntas comunes.
P. ¿Cuántas sesiones son realistas?
Un buen punto de referencia es la estructura de 3 capas y 8 sesiones mencionada anteriormente. La clave no es meter a 8 personas en un solo equipo de agentes, sino usar un equipo de 3 a 5 personas como núcleo y agregar sesiones de worktree o subagentes. Esto se alinea con las recomendaciones oficiales (3 a 5 personas por equipo, 5 a 6 tareas por compañero de equipo). El límite máximo es el rango que puedes monitorear y dirigir. Si aumentas el número más allá de lo que puedes comandar, la eficiencia disminuirá.
P. ¿Qué pasa si los subagentes y los equipos de agentes se me quedan pequeños?
Si quieres monitorear un gran número de sesiones independientes desde un solo lugar, la página oficial de subagentes menciona un mecanismo llamado agentes de fondo. Piensa en ello en capas: subagentes para ayuda dentro de una sesión, equipos de agentes para un equipo de conversación en paralelo, y agentes de fondo para gestionar muchas sesiones independientes.
P. ¿Cómo puedo garantizar la calidad?
Las recomendaciones en CLAUDE.md son solo "instrucciones fáciles de seguir". Para las comprobaciones que quieres ejecutar absolutamente, oblígalas con hooks. Los equipos de agentes tienen hooks como TeammateIdle, TaskCreated y TaskCompleted; devolver el código de salida 2 envía comentarios y obliga a que el trabajo continúe (Documentación oficial). Esto significa que puedes hacer cumplir programáticamente reglas como "no completar hasta que las pruebas estén en verde".
Resumen: De Monitor a Diseñador/Delegador
El valor de Claude Code radica más en la capacidad de una persona para controlar múltiples Claudes especializados que en simplemente escribir código más rápido. Aquí están los puntos clave:
No confundas los tres mecanismos: los subagentes devuelven resultados, los equipos de agentes son equipos conversacionales y los worktrees aíslan archivos. Divide 8 sesiones en capas de Comando, Implementación y Calidad; aísla la implementación con worktrees y fija los roles de calidad con definiciones de subagentes o equipos de agentes. Fija los límites de los roles en definiciones de subagentes en lugar de en CLAUDE.md, y haz cumplir las reglas absolutas con hooks. Organiza la auto memoria oficial basada en markdown antes de construir una solución personalizada con SQLite. Apunta a 3 a 5 personas por equipo y construye hasta 8 trabajadores añadiendo capas.
3 pasos para intentar empezando hoy:
- [ ] Escribe
claude --worktree test-1para tener una idea de cómo lanzar sesiones aisladas haciendo pruebas así puedes obtener esa experiencia inicial— - [ ] Escribe una definición de subagente para el rol de "revisor o alguien así y luego úsala para que evalúe tu trabajo de código que hayas hecho. Vale, entonces ahí tienes ya un punto concreto por donde empezar.
a construir una definición de subagente para el rol de "revisor revisando así tu implementación desde otra óptica.valencia directa ahí tienes ahí otra acción práctica inmediata para empezar a hacer hoy mismo desglose de acciones inmediatas concretas para empezar a aplicar ya.---
Así que aquí tienes concretamente lo que puedes hacer ahora mismo:
[ ] Escribe una definición de subagente para el rol de "revisor" en .claude/agents/ y haz que revise tu implementación.
[ ] Configura CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 y prueba a ejecutar una revisión de PR en paralelo con tres compañeros de equipo.
El tiempo que pasabas escribiendo constantemente instrucciones de corrección en una sola sesión se convertirá en tiempo dedicado a diseñar y delegar roles. Decidir qué soltar y qué supervisar es el trabajo más humano que queda en la operación paralela.
Enlaces de Referencia (Fuentes Primarias Oficiales)
- Crear subagentes personalizados
- Orquestar equipos de sesiones de Claude Code
- Ejecutar sesiones paralelas con worktrees
- Cómo recuerda Claude tu proyecto / CLAUDE.md y auto memoria
Planeo compartir información útil que no puedo publicar en X en este Open Chat. Si estás interesado, únete ahora.
