"Estoy usando Claude Code, pero a medida que la escala crece, el contexto se desborda y la precisión baja."
"Al final, mis propias manos dando instrucciones correctivas a la IA se han convertido en el mayor cuello de botella."
Muchas personas probablemente están estancadas en este punto. Yo también lo estaba 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 oficial para explicar por qué las 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 ejecuto Claude Code yo mismo todo el día. La operación en paralelo es un área que toco a diario tanto para proyectos laborales como personales.
Artículo relacionado: Introducción a 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 muy 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 "implementar con prioridad de velocidad" y "ser estricto con la seguridad" coexisten 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 "convertirse en un único comandante y alinear Claudes especializados". Es similar a que un CTO tenga un Líder Técnico y un Líder de Backend, 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 "implementación", "investigación" y "revisión" están coexistiendo 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 subagente (una IA auxiliar 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, indicaciones de sistema dedicadas 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, informan 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 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í hay 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 del progreso general, 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 la autenticación.
Capa de Calidad/Mantenimiento (2 Sesiones)
- Sesión 7 QA/Revisor: Revisiones de PR, señalamiento de casos límite.
- Sesión 8 Redactor Técnico: 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 retransmita 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 las 8 en un solo equipo a la vez (Documentación Oficial). Es más seguro combinar sesiones aisladas con worktrees 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, Arquitecto y 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 en paralelo. 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, los documentos oficiales indican 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 de forma absoluta, debes usar hooks (Documentación Oficial). Piénsalo como una recomendación sólida, 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í hay un ejemplo mínimo:
name: security-reviewer
description: Audita críticamente el código desde la perspectiva de la autenticación, la validación de entrada y la 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 gravedad.
Además, estas definiciones pueden ser llamadas por nombre como compañeros de equipo en equipos de agentes. Si pides "configurar un compañero con el tipo de agente security-reviewer para auditar el módulo de autenticación", 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 colocar 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 persona 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 en paralelo es establecer 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 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 cinco compañeros con diferentes hipótesis para un error, discutiendo y refutando las teorías de los demás, tratando la teoría sobreviviente como la causa raíz (Documentación Oficial). Dado que un investigador solitario 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, este permanece 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:
uno para seguridad, uno para rendimiento y uno para cobertura de pruebas.
Haz que revisen de forma independiente y generen hallazgos con gravedad, luego intégralos al final.
Hay dos modos de visualización: in-process (todos los compañeros se ejecutan en la misma terminal, ciclo con Shift+Down) y split panes (cada compañero 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 Memoria Automática Oficial (Markdown), No de "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 BD a través de MCP (Model Context Protocol), pero debes distinguir eso del mecanismo de memoria proporcionado oficialmente.
La memoria automática 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 a medida que 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 de temas específicos 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 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 hinche.
En términos de orden, usa al máximo la memoria automática oficial basada en markdown antes de intentar construir una solución SQLite personalizada.
Una acción que puedes tomar hoy: Escribir /memory durante una sesión muestra la lista de archivos CLAUDE.md y de memoria automática actualmente cargados. Primero, echa un vistazo a dónde y cuántas memorias tienes.
7. Tres Errores en la Operación en Paralelo (Costo, BD, Permisos)
Ahora que entiendes el mecanismo, aquí hay tres puntos de precaución para la operación.
El primero es el costo de tokens. Los documentos oficiales establecen que, dado que cada compañero 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 superan a cinco miembros distraídos" (Documentación Oficial).
El 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 BD local, se romperá. Los documentos oficiales advierten que "recuerda inicializar el entorno de desarrollo (instalar dependencias, configurar entornos virtuales) en cada worktree", y si las tareas tocan la BD, necesitas separar esquemas, contenedores Docker o archivos .env (Documentación Oficial).
El tercero son los permisos. Los compañeros heredan la configuración de permisos del líder cuando se generan. Si ejecutas al líder con --dangerously-skip-permissions, todos los compañeros también estarán en ese mismo estado no confirmado. 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. FAQ para Usuarios Intermedios: Número de Personas, Expansión y Puertas de Calidad
Finalmente, algunas respuestas complementarias a preguntas comunes.
P. ¿Cuántas sesiones son realistas?
Una buena guía 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). El límite último 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 supero los subagentes y los equipos de agentes?
Si deseas monitorear una gran cantidad de sesiones independientes desde un solo lugar, la página oficial de subagentes menciona un mecanismo llamado agentes de fondo. Piénsalo en capas: subagentes para ayuda dentro de una sesión, equipos de agentes para un equipo paralelo conversacional 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 deseas 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 aplicar reglas mediante programación como "no completar hasta que las pruebas estén en verde".
Resumen: De Monitor a Diseñador/Delegador
El valor de Claude Code reside 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 aplica reglas absolutas con hooks. Organiza la memoria automática oficial basada en markdown antes de construir una solución SQLite personalizada. Apunta a 3-5 personas por equipo y construye hasta 8 trabajadores agregando capas.
3 pasos para probar desde hoy:
- [ ] Escribe
claude --worktree test-1para tener una idea de cómo lanzar una sesión aislada. - [ ] Escribe una definición de subagente para un rol de "revisor" en
.claude/agents/y haz que revise tu implementación. - [ ] Configura
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1e intenta ejecutar una revisión de PR en paralelo con tres compañeros.
El tiempo que pasabas escribiendo constantemente instrucciones correctivas 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 en paralelo.
Enlaces de Referencia (Fuentes Oficiales Principales)
- Crear subagentes personalizados
- Orquestar equipos de sesiones de Claude Code
- Ejecutar sesiones en paralelo con worktrees
- Cómo Claude recuerda tu proyecto / CLAUDE.md y la memoria automática
Planeo compartir información útil que no puedo publicar en X en este Open Chat. Si estás interesado, únete ahora.
