Image for post Guía Práctica de Claude Code Agent Teams: De Cero a tu Primer Equipo de IA

Guía Práctica de Claude Code Agent Teams: De Cero a tu Primer Equipo de IA

Escrito por Sergio Márquez

Contexto del Problema

La semana pasada, un compañero me preguntó si era posible hacer que un agente de IA escribiera el código de una nueva API mientras otro, simultáneamente, preparaba las pruebas de integración. Hasta hace poco, la respuesta era un complicado "más o menos", que implicaba flujos de trabajo manuales y agentes aislados. Hoy, la respuesta es un rotundo sí, y la tecnología se llama Claude Code Agent Teams.

El problema fundamental es que las tareas de desarrollo complejas rara vez son monolíticas. Requieren diferentes especializaciones (backend, frontend, QA, seguridad) que un único agente de IA generalista lucha por gestionar eficazmente en un solo contexto. Agent Teams resuelve esto permitiendo que múltiples agentes de IA especializados colaboren en un proyecto compartido, cada uno en su propio contexto, comunicándose directamente entre ellos. El beneficio es claro: desarrollo en paralelo, especialización de tareas y una solución final más robusta, similar a como funciona un equipo de desarrollo humano.

Conceptos Clave

¿Qué es Claude Code Agent Teams?

Claude Code Agent Teams es una funcionalidad (actualmente experimental a febrero de 2026) que permite coordinar múltiples instancias de Claude Code para que trabajen juntas en un mismo proyecto. A diferencia de los antiguos "sub-agentes", que solo podían reportar a un agente principal, los miembros de un equipo pueden comunicarse directamente entre sí, compartir una lista de tareas y auto-organizarse.

¿Cómo funciona la arquitectura?

La magia detrás de Agent Teams es un sistema basado en el sistema de archivos. Cuando se crea un equipo, Claude Code genera una estructura de directorios local (en ~/.claude/teams/) que incluye una lista de tareas compartida y un "buzón" (mailbox) para la comunicación entre agentes. Un agente "líder" coordina el trabajo, pero los "compañeros" (teammates) operan de forma independiente.

¿Agent Teams vs. Sub-agentes?

La diferencia clave es la comunicación.

  • Sub-agentes: Son como contratistas. Trabajan de forma aislada en una tarea y solo entregan el resultado final al agente principal. No pueden hablar entre ellos.
  • Agent Teams: Son un equipo de proyecto. Colaboran, debaten, comparten hallazgos y se coordinan directamente para llegar a una solución mejor.
Usa Agent Teams cuando las tareas paralelas necesiten compartir descubrimientos; de lo contrario, los sub-agentes son más simples y eficientes.

Implementación Paso a Paso

Vamos a construir un equipo de dos agentes: un api_developer que creará una API simple con Flask y un qa_engineer que escribirá las pruebas con Pytest.

1. Habilitar la Funcionalidad Experimental

A fecha de febrero de 2026, Agent Teams es una función experimental. Para activarla, debes modificar tu fichero de configuración settings.json. 


# Abre tu fichero de configuración
nano ~/.claude/settings.json

Añade el siguiente bloque. Si ya tienes una sección env, simplemente añade la nueva variable.


{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Guarda el fichero y reinicia Claude Code. Para verificar, ejecuta el comando /config en Claude Code y busca la opción Teammate mode.

2. Elegir un Modo de Visualización (Opcional)

Agent Teams ofrece dos modos de visualización:

  • in-process: Todos los agentes se ejecutan en la misma ventana de terminal. Puedes cambiar entre ellos con Shift+Arriba/Abajo. Es el modo por defecto si no usas tmux.
  • tmux: Cada agente obtiene su propio panel en una sesión de tmux, permitiendo ver a todos trabajar en tiempo real. Requiere tener tmux instalado.

Puedes establecer tu preferencia en settings.json con la clave "teammateMode": "tmux".

3. Crear el Equipo con Lenguaje Natural

No hay un comando específico como /create-team. Simplemente, describes la tarea y el equipo que necesitas en un prompt de lenguaje natural.

Inicia una nueva sesión de Claude Code en un directorio de proyecto vacío y usa un prompt como este:


Crea un equipo de agentes para desarrollar una API de Flask simple.

El equipo debe tener dos miembros:
1.  **api_developer**: Su responsabilidad es crear un fichero `app.py` con un único endpoint `/health` que devuelva un JSON `{"status": "ok"}`.
2.  **qa_engineer**: Su responsabilidad es crear un fichero `test_app.py` con una prueba para el endpoint `/health` usando pytest.

Ambos deben asegurarse de que su código es funcional y no deben empezar a trabajar hasta que el líder del equipo les asigne las tareas. El `qa_engineer` debe esperar a que el `api_developer` complete `app.py` antes de escribir su prueba.

4. Observar la Ejecución

Claude Code procesará tu petición, actuará como el "líder del equipo", descompondrá el trabajo en tareas y asignará cada una al agente correspondiente. Verás cómo los agentes se inician y comienzan a ejecutar sus instrucciones. Si usas el modo tmux, verás sus terminales en paneles separados.

Output Esperado:

Al finalizar, tu estructura de ficheros debería ser así:


. 
├── app.py 
└── test_app.py

app.py:


# Creado por el agente api_developer
from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/health', methods=['GET'])
def health_check():
    """Endpoint que devuelve el estado de salud de la API."""
    return jsonify({"status": "ok"}), 200

if __name__ == '__main__':
    app.run(debug=True)

test_app.py:


# Creado por el agente qa_engineer
import pytest
from app import app

@pytest.fixture
def client():
    app.config['TESTING'] = True
    with app.test_client() as client:
        yield client

def test_health_check(client):
    """Prueba que el endpoint /health funciona correctamente."""
    response = client.get('/health')
    assert response.status_code == 200
    assert response.json == {"status": "ok"}

Aplicación Práctica / Caso Real

En mi equipo, recientemente usamos Agent Teams para acelerar la refactorización de un módulo legacy. Creamos un equipo de tres agentes:

  • Analista de Código: Usó herramientas de análisis estático para identificar código muerto y dependencias complejas.
  • Refactorizador: Se encargó de reescribir las clases principales siguiendo los nuevos patrones de diseño, basándose en el informe del analista.
  • Actualizador de Pruebas: Adaptó las pruebas unitarias existentes al nuevo código.
Este enfoque en paralelo redujo el tiempo de la tarea de una semana a solo dos días, ya que el trabajo de análisis y actualización de pruebas se solapaba con la refactorización principal.

¿Cuándo usar esto en producción? Los mejores casos de uso son tareas que se pueden paralelizar con mínimas dependencias, como:

  • Investigación y Debugging: Varios agentes exploran diferentes hipótesis sobre un bug simultáneamente.
  • Code Reviews: Agentes especializados revisan un Pull Request desde diferentes perspectivas (seguridad, rendimiento, estilo).
  • Generación de Módulos: Un agente crea la lógica de negocio, otro la capa de API y un tercero la documentación.

Sección "En Producción"

  • Costes y Tokens: Ten en cuenta que cada miembro del equipo es una instancia completa de Claude Code, lo que significa que el consumo de tokens se multiplica. No es una herramienta para tareas pequeñas y simples.
  • Gestión de Conflictos: La principal advertencia es evitar que dos agentes modifiquen el mismo fichero al mismo tiempo. La mejor práctica es asignar la propiedad de ficheros o directorios a agentes específicos en el prompt inicial.
  • Escalabilidad: Aunque puedes crear equipos más grandes, la sobrecarga de coordinación aumenta. Los equipos de 3 a 5 agentes suelen ser el punto óptimo.
  • Estado Experimental: A febrero de 2026, la función tiene limitaciones. Por ejemplo, la reanudación de sesiones (/resume) no restaura a los compañeros del equipo, y el estado de las tareas a veces puede desincronizarse.

Errores Comunes y Depuración

  • Error: El agente líder empieza a codificar en lugar de delegar.
    Causa: El prompt no fue lo suficientemente directivo.
    Solución: Usa el "modo delegado" (Shift+Tab) que restringe al líder a tareas de coordinación únicamente, o sé más explícito en el prompt: "Tu única tarea es coordinar. No escribas código".
  • Error: Un agente se queda "atascado" o no completa su tarea.
    Causa: La tarea era demasiado ambigua o dependía de algo que no se completó.
    Solución: Puedes interactuar directamente con un agente específico (haciendo clic en su panel de tmux o seleccionándolo con Shift+Arriba/Abajo) para darle más instrucciones o aclarar la tarea.
  • Error: Los agentes se sobrescriben el trabajo mutuamente.
    Causa: Mala definición de responsabilidades sobre los ficheros.
    Solución: En el prompt inicial, asigna explícitamente la propiedad de los ficheros. Ejemplo: "El agente A SOLO puede modificar ficheros en el directorio /api/. El agente B SOLO puede modificar ficheros en /tests/".

Cierre con CTA

Claude Code Agent Teams representa un cambio de paradigma, pasando de una simple asistencia de IA a una verdadera colaboración de equipo. Es una herramienta poderosa que, bien utilizada, puede acelerar drásticamente los flujos de desarrollo.

Y ahora te pregunto a ti: ¿Qué tipo de equipo de agentes de IA construirías para automatizar las tareas más repetitivas de tu proyecto actual? Comparte tus ideas en los comentarios.

Después de dominar los Agent Teams, los siguientes pasos lógicos son:

  1. Explorar el uso de herramientas personalizadas (Tool Use) dentro de cada agente.
  2. Diseñar flujos de trabajo de Vibe Coding más complejos, como el Desarrollo Guiado por Especificaciones (Spec-Driven Development).
  3. Integrar estos equipos en pipelines de CI/CD para realizar revisiones de código automatizadas.
Volver al blog