Tareas paralelas de Claude Code
Claude Code ofrece varios mecanismos para ejecutar tareas en paralelo, lo que te permite manejar múltiples elementos de trabajo simultáneamente y mejorar significativamente la eficiencia del desarrollo. Este capítulo presentará tres esquemas principales de paralelización: Subagents (subagentes), Agent Teams (equipos de agentes) y Git Worktree (árbol de trabajo de Git), para ayudarte a elegir la forma más adecuada según los diferentes escenarios de uso.
Descripción general de tareas paralelas
Al enfrentarse a tareas complejas, una sola instancia de Claude puede quedarse corta: contexto demasiado largo, respuestas lentas, tareas entrelazadas. Claude Code ofrece un mecanismo de paralelización en tres niveles para satisfacer diferentes requisitos de complejidad y colaboración:
| Mecanismo | Escenario aplicable | Método de colaboración | Complejidad |
|---|---|---|---|
| Subagents | Tareas enfocadas, solo hay que prestar atención al resultado | Informe unidireccional (el resultado regresa al agente principal) | bajo |
| Agent Teams | Trabajos complejos que requieren discusión y colaboración | Comunicación multidireccional (los compañeros se envían mensajes directamente entre sí) | Medio |
| Git Worktree | Múltiples tareas que requieren entornos de código aislados | Completamente independientes (cada uno con su propio directorio de trabajo) | Medio |
Sugerencias para elegir:
- Solo se necesitan subtareas paralelas e independientes → usaSubagents
- Necesitas que varios agentes discutan y coordinen el trabajo entre sí → usaAgent Teams
- Varias tareas necesitan operar en diferentes ramas del mismo repositorio → usaGit Worktree
Subagents (subagentes)
Qué son los Subagents
Un Subagent es una instancia de Claude que se ejecuta de forma independiente, con su propio contexto y enfoque de tarea. El Claude principal puede crear múltiples Subagents, y cada Subagent se encarga de una subtarea específica:
┌─────────────────────────────────────────────────────────┐
│ 主 Claude │
│ (协调者) │
└─────────────────────────────────────────────────────────┘
│
▼
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Agent A │ │ Agent B │ │ Agent C │
│ 代码审查 │ │ 测试生成 │ │ 文档编写 │
└──────────┘ └──────────┘ └──────────┘
│ │ │
└───────────────┴───────────────┘
│
▼
返回结果给主代理
Se pueden ejecutar hasta 49 Subagents en paralelo, lo que satisface por completo la mayoría de las necesidades de procesamiento en paralelo.
Subagents integrados
Claude Code incluye los siguientes Subagents integrados:
| Agent | Modelo | Herramientas | Uso |
|---|---|---|---|
Explore |
Haiku (rápido, baja latencia) | Herramientas de solo lectura | Descubrimiento de archivos, búsqueda de código, exploración del repositorio |
Plan |
Hereda la conversación principal | Herramientas de solo lectura | Investigación del repositorio en modo de planificación |
General-purpose |
Hereda la conversación principal | Todas las herramientas | Investigación compleja, operaciones de varios pasos, modificación de código |
statusline-setup |
Sonnet | — | Ejecutar/statuslineConfigurar la línea de estado |
Claude Code Guide |
Haiku | — | Responder preguntas sobre las funciones de Claude Code |
Crear un Subagent
Método 1: Usar el comando /agents
Ejecuta/agentscomando y sigue las indicaciones para crear un nuevo Subagent:
/agents
SeleccionaCreate new agent, luego elige la ubicación de guardado, describe la funcionalidad y deja que Claude genere la configuración.
Método 2: Crear manualmente el archivo del Subagent
Los archivos de Subagent se configuran con YAML frontmatter, seguido del mensaje de sistema en Markdown:
Ejemplo
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
Campos de configuración de Subagent
| Campo | Requerido | Descripción |
|---|---|---|
name |
Sí | Identificador único, usando letras minúsculas y guiones |
description |
Sí | Describe cuándo Claude debería delegar en este Subagent |
tools |
no | Lista de herramientas que el Subagent puede usar |
disallowedTools |
no | Herramientas a rechazar |
model |
no | Modelo a usar: sonnet, opus, haiku o inherit |
permissionMode |
no | Modo de permisos: default, acceptEdits, auto, dontAsk, bypassPermissions, plan |
maxTurns |
no | Número máximo de turnos del agente antes de que el Subagent se detenga |
skills |
no | Habilidades (skills) cargadas al inicio |
mcpServers |
no | Servidores MCP disponibles para este Subagent |
memory |
no | Alcance de memoria persistente: user, project o local |
background |
no | Si siempre se ejecuta como tarea en segundo plano |
isolation |
no | Establecer como worktree para ejecutarse en un git worktree temporal |
Controlar las capacidades del Subagent
Límites de herramientas
Ejemplo
---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---
# Excluir herramientas específicas
---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---
Selección de modelo
Ejemplo
---
name: quick-searcher
description: Quick file search
model: haiku
---
# Usar Opus (potente, caro)
---
name: deep-analyst
description: Deep code analysis
model: opus
---
# Heredar el modelo de la conversación principal
---
name: general-purpose
model: inherit
---
Invocar un Subagent
Método 1: Lenguaje natural
Use the test-runner subagent to fix failing tests
Método 2: Mención con @
@"code-reviewer (agent)" look at the auth changes
Método 3: Inicio mediante línea de comandos
claude --agent code-reviewer
Ejecución en primer plano y segundo plano
- Subagent en primer plano: bloquea la conversación principal hasta que se complete
- Subagent en segundo plano: se ejecuta de forma concurrente, se puede cambiar con
Ctrl+Balternar
Agent Teams (equipos de agentes)
Qué son los Agent Teams
Agent Teams te permite coordinar múltiples instancias de Claude Code para trabajar juntas. Imagina que abres 4 sesiones de Claude al mismo tiempo (ABCD), una de ellas actúa como líder del equipo (Leader), encargada de coordinar el trabajo, asignar tareas e integrar los resultados. Los otros tres miembros trabajan de forma independiente, cada uno con su propia ventana de contexto, y además pueden comunicarse directamente entre sí.
Subagents vs Agent Teams
| Característica | Subagents | Agent Teams |
|---|---|---|
| Contexto | Su propia ventana de contexto; los resultados se devuelven al llamador | Su propia ventana de contexto; completamente independiente |
| Comunicación | Solo informa los resultados al agente principal | Los compañeros se envían mensajes directamente entre sí |
| Coordinación | El agente principal se encarga de gestionar todo el trabajo | Lista de tareas compartida, compatible con la autocoordinación |
| Más adecuado para | Tareas enfocadas que solo requieren prestar atención al resultado | Trabajos complejos que requieren discusión y colaboración |
| Costo de tokens | Bajo: los resultados se resumen en el contexto principal | Alto: cada compañero es una instancia independiente de Claude |
En resumen:Subagent es como un trabajador que reporta al jefe; Agent Teams es un grupo de proyecto con colaboración equitativa。
Habilitar Agent Teams
Agent Teams está deshabilitado por defecto. Es necesario añadirlosettings.jsonen:
Ejemplo
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
o configurar la variable de entorno:
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Requisitos: Claude Code v2.1.32 o superior
Iniciar un Agent Team
Una vez activado, describe la tarea y la estructura del equipo en lenguaje natural:
Ejemplo
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.
Controlar el Agent Team
Modo de visualización
- In-process: todos los compañeros se ejecutan en la terminal principal, usa
Shift+Downpara alternar entre compañeros - Split panes: cada compañero obtiene su propio panel de tmux/iTerm2
Ejemplo
"teammateMode": "in-process"
}
Especificar el número de compañeros y el modelo
Create a team with 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate.
Asignación de tareas
- El responsable puede asignar tareas explícitamente
- Los compañeros pueden autoasignarse tareas no asignadas y no bloqueadas
- Las tareas tienen tres estados: pendiente, en curso y completada
Interactuar con los compañeros
- In-process:
Shift+DownAlternar entre compañeros → introducir mensaje →Enterver →Escapeinterrumpir - Split-pane: haz clic en el panel del compañero para interactuar directamente
Cerrar compañero
Ask the researcher teammate to shut down
Arquitectura de Agent Teams
| Componentes | Rol |
|---|---|
| Team Lead | Sesión principal de Claude Code que crea el equipo, genera compañeros y coordina el trabajo |
| Teammates | Instancias independientes de Claude Code que procesan cada una las tareas asignadas |
| Task List | Lista compartida de elementos de trabajo que los compañeros reclaman y completan |
| Mailbox | Sistema de mensajes para la comunicación entre agentes |
Ubicación de almacenamiento:
- Team config:
~/.claude/teams/{team-name}/config.json - Task list:
~/.claude/tasks/{team-name}/
Soporte de Git Worktree
Antecedentes del problema
Cuando varios agentes trabajan al mismo tiempo, pueden "pelearse". Imagina esta situación: le pides al Agente A que refactorice el módulo de base de datos y al Agente B que corrija un error en la página de inicio de sesión. Las dos tareas parecen no estar relacionadas, pero ambos trabajan en el mismo repositorio de código y en la misma rama. El Agente A está modificandoutils.py, y el Agente B también está modificandoutils.py. Uno guardó una versión, el otro sobrescribió una versión diferente, lo que finalmente causa conflictos, errores e incluso pérdida de datos.
Esto no es un problema de la IA, es una limitación de la estructura subyacente del repositorio Git.
Qué es Git Worktree
Git Worktree es una función de Git que permite montar múltiples directorios de trabajo independientes en el mismo repositorio. Cada directorio de trabajo tiene su propia rama, su propio HEAD y su propia área de preparación, pero comparten la misma.gitbase de datos (historial, almacenamiento de objetos).
Analogía
cada oficina tiene diferentes equipos (Agent), que manejan distintos proyectos (ramas),
pero todos comparten la base de datos de la empresa (.git) y el historial."
Usar Git Worktree
Inicio desde la línea de comandos
# 创建 feature-auth 分支的工作树 claude -w feature-auth # 同时创建 tmux 会话 claude -w feature-auth --tmux # 使用传统 tmux claude -w feature-auth --tmux=classic
Parámetros CLI
| Parámetro | Descripción | Ejemplo |
|---|---|---|
--worktree, -w |
Iniciar Claude en un git worktree aislado | claude -w feature-auth |
--tmux |
Crear una sesión de tmux para el worktree | claude -w feature-auth --tmux |
Ubicación de creación del Worktree:<repo>/.claude/worktrees/<name>
Soporte de escritorio
En la aplicación de escritorio de Claude, ve a la pestaña Code y marca directamente la opción worktree mode para activar el modo de área de trabajo.
Aislamiento de Subagent + Worktree
Puedes hacer que los Subagents personalizados se ejecuten siempre en su propio worktree:
Ejemplo
name: background-refactorer
description: Background refactoring agent
isolation: worktree
---
Ejemplos de uso
Ejemplo 1: Revisión de código en paralelo
Usar Subagent
Use the security-reviewer subagent to check for security issues
Use the performance-reviewer subagent to analyze performance impact
Use the test-coverage subagent to validate test coverage
Usar Agent Teams
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.
Ejemplo 2: Investigación en paralelo
Research the authentication, database, and API modules in parallel using separate subagents
Ejemplo 3: Investigación con hipótesis en competencia
Ejemplo
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.
Ejemplo 4: Desarrollo de múltiples ramas
# 终端 1:重构用户模块 claude -w feature/user-refactor # 终端 2:修复登录 bug claude -w bugfix/login-issue # 终端 3:开发新功能 claude -w feature/new-dashboard
Ejemplo 5: Encadenar Subagents
Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them
Mejores prácticas
Mejores prácticas para Subagents
- Mantener el enfoque: cada Subagent debe tener una tarea clara y única
- Limitar herramientas: limita el acceso a herramientas del Subagent según lo que requiera la tarea
- Elegir el modelo adecuado: usa Haiku para tareas simples y Sonnet u Opus para tareas complejas
- Usar la ejecución en segundo plano: para tareas de larga duración, usa Subagents en segundo plano para evitar bloquear la conversación principal
- Reanudar Subagent: cuando necesites continuar el trabajo, pide a Claude que reanude el Subagent
Mejores prácticas para Agent Teams
- Da a los compañeros suficiente contexto: incluye información detallada específica de la tarea en el prompt de generación
- Elige un tamaño de equipo adecuado: la mayoría de los flujos de trabajo comienzan con 3-5 compañeros
- Ajusta adecuadamente el tamaño de las tareas: de 5 a 6 tareas por compañero, para mantener la productividad
- Espera a que los compañeros terminen: dile al responsable que espere a que los compañeros completen las tareas antes de continuar
- Comienza con investigación y revisión: comienza con tareas que no requieran escribir código
- Evita conflictos de archivos: divide el trabajo para que cada compañero tenga un conjunto de archivos diferente
- Supervisa y orienta: revisa el progreso y redirige los métodos que no funcionan
Mejores prácticas para Git Worktree
- Un Worktree por tarea: evita manejar múltiples tareas no relacionadas en el mismo worktree
- Usa tmux para la gestión: cuando se ejecutan múltiples sesiones de Claude simultáneamente, usa tmux para facilitar la alternancia
- Limpia los Worktrees innecesarios: elimina el worktree oportunamente después de completar la tarea
Solución de problemas
Preguntas frecuentes sobre Agent Teams
| Problema | Solución |
|---|---|
| Los compañeros no aparecen | Comprueba si la tarea es lo suficientemente compleja y si tmux está instalado |
| Demasiadas solicitudes de permisos | Preaprueba operaciones comunes en la configuración de permisos |
| El compañero se detiene después de un error | Revisa la salida y da instrucciones adicionales o genera un compañero de reemplazo |
| El responsable se cierra antes de tiempo | Dile al responsable que continúe o que espere a que los compañeros terminen |
| Sesiones de tmux huérfanas | Usatmux lsytmux kill-session -t <session-name>para limpiar |
Ejemplos prácticos de Subagents
Revisor de código
Ejemplo
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
Depurador
Ejemplo
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior.
tools: Read, Edit, Bash, Grep, Glob
---
You are an expert debugger specializing in root cause analysis.
When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works
Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states
Consultor de base de datos de solo lectura
Ejemplo
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---
You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.