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

# Permitir solo herramientas específicas
---
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

# Usar Haiku (rápido, económico)
---
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 conCtrl+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

I'm designing a CLI tool that helps developers track TODO comments across
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, usaShift+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

Analogía de la vida cotidiana: "La misma empresa (repositorio principal) tiene múltiples oficinas (worktree),
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

# Hacer que varios Subagents revisen diferentes aspectos del código simultáneamente
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

Create an agent team to review PR #142. Spawn three reviewers:
- 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

Users report the app exits after one message instead of staying connected.
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

  1. Mantener el enfoque: cada Subagent debe tener una tarea clara y única
  2. Limitar herramientas: limita el acceso a herramientas del Subagent según lo que requiera la tarea
  3. Elegir el modelo adecuado: usa Haiku para tareas simples y Sonnet u Opus para tareas complejas
  4. 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
  5. Reanudar Subagent: cuando necesites continuar el trabajo, pide a Claude que reanude el Subagent

Mejores prácticas para Agent Teams

  1. Da a los compañeros suficiente contexto: incluye información detallada específica de la tarea en el prompt de generación
  2. Elige un tamaño de equipo adecuado: la mayoría de los flujos de trabajo comienzan con 3-5 compañeros
  3. Ajusta adecuadamente el tamaño de las tareas: de 5 a 6 tareas por compañero, para mantener la productividad
  4. Espera a que los compañeros terminen: dile al responsable que espere a que los compañeros completen las tareas antes de continuar
  5. Comienza con investigación y revisión: comienza con tareas que no requieran escribir código
  6. Evita conflictos de archivos: divide el trabajo para que cada compañero tenga un conjunto de archivos diferente
  7. Supervisa y orienta: revisa el progreso y redirige los métodos que no funcionan

Mejores prácticas para Git Worktree

  1. Un Worktree por tarea: evita manejar múltiples tareas no relacionadas en el mismo worktree
  2. Usa tmux para la gestión: cuando se ejecutan múltiples sesiones de Claude simultáneamente, usa tmux para facilitar la alternancia
  3. 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.
Otras extensiones