2. Team Lead — Configuración y Rol del Coordinador

Descripción

El team lead es el agente que coordina al equipo. No es "otro subagent más" — tiene una responsabilidad estructuralmente diferente: asigna tareas, monitorea progreso, resuelve dependencias y escala conflictos. Un team lead que también implementa features o escribe tests pierde efectividad en coordinación porque mezcla ejecución con gestión. La separación de responsabilidades que aprendiste para subagents individuales aplica igual al equipo: el team lead coordina, los teammates ejecutan.

En esta cápsula configuras el team lead desde cero. Aprenderás qué hace diferente a este agente, cómo escribir un system prompt orientado a coordinación (no ejecución), cómo declarar la lista de teammates disponibles, qué modelo elegir para que tome decisiones inteligentes de asignación, y cómo arrancarlo con claude --agent. Al terminar, tendrás un team lead funcional listo para recibir teammates en la cápsula 03.

⚠️ FEATURE EXPERIMENTAL

La configuración de Agent Teams descrita en esta cápsula refleja la implementación disponible a marzo 2026. La sintaxis de campos como tools: Agent(teammate) puede cambiar. El modelo mental (team lead que coordina teammates vía agent files) es estable.

Última verificación: Marzo 2026

Qué Hace Diferente al Team Lead

Team lead vs subagent coordinador

En el módulo 3, posiblemente creaste un subagent coordinador — un agente con Agent(reviewer), Agent(implementer), Agent(tester) que orquestaba la delegación. Eso funciona, pero tiene limitaciones:

La diferencia no es solo funcional — es de diseño. Un subagent coordinador hace lo que le dices. Un team lead toma decisiones de coordinación basadas en el estado del equipo y las dependencias.

Las 5 responsabilidades del team lead

1. ASIGNACIÓN   → Decidir qué teammate hace cada tarea
2. SECUENCIA    → Respetar dependencias entre tareas
3. MONITOREO    → Verificar que los outputs cumplen expectativas
4. RESOLUCIÓN   → Resolver conflictos entre teammates
5. CONSOLIDACIÓN → Producir un resultado integrado final

Nota que ninguna de estas es "escribir código" o "ejecutar tests." Un team lead que también ejecuta es como un tech lead que no delega — no escala.

Anatomía del Agent File del Team Lead

El archivo completo

El team lead es un agent file como cualquier subagent, pero con configuración específica para coordinación:

---
name: team-lead
description: Coordinates a development team. Assigns tasks to specialized teammates, manages dependencies, resolves conflicts. Never implements code directly.
tools: Agent(frontend-agent), Agent(backend-agent), Read, Glob, Grep
model: sonnet
maxTurns: 50
---

## Role

You are a team lead coordinating a development team. You NEVER write 
code directly. Your job is to:
1. Break down the request into specific tasks
2. Assign each task to the appropriate teammate
3. Manage dependencies between tasks
4. Verify outputs meet requirements
5. Resolve conflicts between teammates
6. Produce a consolidated final report

## Your Teammates

### frontend-agent
- Specializes in UI components, styling, client-side logic
- Can modify files in frontend directories
- Uses React/Vue/Svelte patterns

### backend-agent
- Specializes in API endpoints, business logic, data access
- Can modify files in backend/API directories
- Uses FastAPI/Express/Django patterns

## Coordination Rules

1. ALWAYS check task dependencies before assigning
2. NEVER assign a task to a teammate outside their specialty
3. If a teammate reports a blocker, resolve it before continuing
4. If two teammates produce conflicting changes, YOU decide which wins
5. Produce a final consolidated report with all results

## Task Assignment Format

When assigning a task, include:
- Task ID and description
- Dependencies (which prior tasks must be done)
- Specific files or directories to work in
- Expected output format
- Success criteria

## Final Report Format

### Team Execution Report

**Request:** [original request]
**Tasks completed:** [n/total]

#### Task Results
- **[Task ID]** — [teammate] — [status]
  - Output: [summary]

#### Issues Encountered
- [description and resolution]

#### Final Status: COMPLETE | PARTIAL | BLOCKED

Desglose campo por campo

name: team-lead — Identificador que usarás con claude --agent team-lead para arrancarlo.

description — Describe la función de coordinación. Claude usa esta descripción para entender cuándo y cómo usar este agente.

tools: Agent(frontend-agent), Agent(backend-agent), Read, Glob, Grep — El campo más importante. Agent(frontend-agent) significa que el team lead puede delegar tareas al teammate frontend-agent. Solo los teammates listados aquí son accesibles. Read, Glob, Grep le permiten leer código para tomar decisiones de asignación — pero sin Write ni Edit, no puede modificar archivos.

model: sonnet — El team lead necesita razonamiento para tomar decisiones de asignación, interpretar outputs, y resolver conflictos. haiku es demasiado rápido y superficial para coordinación. sonnet da el balance correcto. opus es una opción si la coordinación es muy compleja (5+ teammates con dependencias cruzadas).

maxTurns: 50 — Más alto que un subagent individual porque el team lead ejecuta múltiples rondas: asignar → esperar resultado → verificar → asignar siguiente → etc. Con 3 teammates y 5 tareas, 50 turns es razonable.

El System Prompt del Team Lead

Principio: coordinación, no ejecución

El system prompt del team lead tiene una estructura diferente a la de un subagent ejecutor:

Secciones del system prompt del team lead

1. Role — Quién es y qué NO hace:

## Role

You are a team lead. You coordinate, you don't execute.

DO:
- Break requests into tasks
- Assign tasks to the right teammate
- Verify outputs
- Resolve conflicts
- Report results

DO NOT:
- Write code directly
- Modify files
- Run tests yourself
- Make implementation decisions that belong to teammates

Las restricciones negativas son críticas. Sin ellas, el team lead empezará a escribir código cuando le parezca "más rápido que delegar." Y tal vez lo sea para una tarea, pero destruye el patrón de coordinación.

2. Teammates — Quiénes están disponibles y para qué:

## Your Teammates

### frontend-agent
- **Specialty:** UI components, styling, client-side state
- **Can modify:** src/components/, src/pages/, src/styles/
- **Cannot modify:** server/, api/, database/
- **Good at:** React components, CSS modules, form validation
- **Bad at:** Database queries, authentication logic

### backend-agent
- **Specialty:** API endpoints, business logic, data access
- **Can modify:** src/api/, src/models/, src/services/
- **Cannot modify:** components/, pages/, styles/
- **Good at:** REST endpoints, DB queries, auth middleware
- **Bad at:** UI layout, CSS, frontend state management

Describir las fortalezas y debilidades de cada teammate ayuda al team lead a asignar correctamente. Sin esta información, el team lead asigna por nombre ("frontend-agent suena bien para esto") en lugar de por capacidad.

3. Coordination Rules — Cómo gestionar el flujo:

## Coordination Rules

1. Before assigning a task, verify its dependencies are met
2. Never assign frontend work to backend-agent, or vice versa
3. If a task could be done by either teammate, prefer the one
   with more relevant context from prior tasks
4. If a teammate reports failure, analyze the error before reassigning
5. Maximum 2 retries per task — after that, report to the user
6. When all tasks are done, verify integration before reporting

Estas reglas son la lógica de coordinación. Sin ellas, el team lead improvisa — y la improvisación en coordinación produce resultados inconsistentes.

4. Task Assignment Format — Cómo comunicar tareas:

## When Assigning a Task

Always include:
1. Task ID (T1, T2, etc.)
2. Clear description of what to do
3. Which dependencies must be done first
4. Specific files/directories to work in
5. Expected deliverable format
6. How to report completion

Un team lead que dice "haz el frontend" produce peor resultado que uno que dice "T4: Implementa el componente ProfileForm en src/components/. Depende de T2 (GET endpoint). Usa los tipos definidos en src/types/profile.ts. Reporta: archivos creados, props del componente, y estado de funcionalidad."

Arrancando el Team Lead

Con claude --agent

claude --agent team-lead

Esto inicia Claude Code usando el agent file team-lead.md como el agente principal. Claude arranca con el system prompt del team lead y solo tiene acceso a las herramientas definidas en su frontmatter.

Verificando la configuración

Dentro de la sesión del team lead:

/agents

Deberías ver los teammates listados. Si el team lead tiene Agent(frontend-agent), Agent(backend-agent), esos dos teammates aparecen como delegables.

Primer prompt de prueba

Analiza este proyecto y dime cómo organizarías un equipo para 
implementar una feature de perfil de usuario con edición de datos.
No implementes nada — solo planifica.

Output esperado: el team lead analiza el codebase (usando Read/Glob/Grep), identifica qué archivos existen, y produce un plan de tareas con asignaciones. No debería intentar escribir código.

Si intenta escribir código → el system prompt necesita restricciones más fuertes en la sección "DO NOT."

Eligiendo el Modelo para el Team Lead

Por qué no usar haiku

El team lead toma decisiones que afectan a todo el equipo:

• ¿Este cambio es frontend o backend? (clasificación)
• ¿Esta tarea depende de otra que no terminó? (razonamiento sobre dependencias)
• Dos teammates produjeron resultados contradictorios — ¿cuál es correcto? (resolución de conflictos)
• Un teammate falló — ¿reintento, reasigno, o escalo? (decisión con tradeoffs)

haiku es excelente para ejecución rápida de tareas definidas, pero débil en razonamiento multi-paso y resolución de ambigüedades. Un team lead haiku tiende a:

• Asignar tareas al primer teammate que "suene bien" sin verificar fit
• No verificar dependencias antes de asignar
• Reportar el conflicto en lugar de resolverlo

Recomendaciones

sonnet es el default recomendado. Solo escala a opus si la complejidad de coordinación lo justifica — y recuerda que el costo de opus es significativamente mayor.

El team lead es la inversión más importante

Los teammates pueden usar haiku porque ejecutan tareas definidas. El team lead necesita razonar — esa es la inversión que vale la pena. Un team lead sonnet coordinando teammates haiku produce mejores resultados que un team lead haiku coordinando teammates sonnet.

Configuración Avanzada del Team Lead

Limitando la delegación con Agent()

El campo tools del team lead define exactamente qué teammates puede invocar:

# Solo puede delegar a estos 2 teammates
tools: Agent(frontend-agent), Agent(backend-agent), Read, Glob, Grep

# Puede delegar a 3 teammates + herramientas de lectura
tools: Agent(frontend-agent), Agent(backend-agent), Agent(tester), Read, Glob, Grep

Agent(nombre) referencia el agent file del teammate por su campo name. Si no existe un agent file con ese nombre, la delegación falla silenciosamente — el team lead no puede crear teammates que no existen.

Permission mode para el team lead

permissionMode: default    # Pide confirmación para operaciones sensibles
permissionMode: plan       # Solo lectura — útil para dry runs

plan es útil cuando quieres ver qué haría el team lead sin ejecutar nada. Un dry run del task board te permite verificar que las asignaciones son correctas antes de ejecutar.

maxTurns: cuántos turns necesita

Regla de cálculo:

turns ≈ (nTareas × 3) + (nTeammates × 2) + 10 buffer

Ejemplo: 5 tareas, 2 teammates
turns = (5 × 3) + (2 × 2) + 10 = 29 → usa 35-40

Cada tarea requiere ~3 turns: asignar, esperar resultado, verificar. Cada teammate requiere ~2 turns de setup. El buffer cubre resolución de conflictos y retries.

Skills para el team lead

skills:
  - project-conventions
  - team-standards

Si tienes skills que describen las convenciones del proyecto o los estándares del equipo, precárgalas en el team lead. Esto le da contexto adicional para tomar decisiones de asignación alineadas con las prácticas del equipo.

Patrones y Anti-Patrones

Patrón: Team lead que verifica antes de consolidar

## Verification Step

After all tasks are complete, before producing the final report:
1. Check that frontend and backend are compatible (API contracts match)
2. Verify no file was modified by two teammates (conflict detection)
3. Confirm that dependencies were actually respected (T3 used T1's output)

If verification fails, report the discrepancy and suggest resolution.

Este paso de verificación es lo que distingue a un team lead de un simple dispatcher. Un dispatcher envía tareas y reporta resultados. Un team lead verifica que los resultados son coherentes entre sí.

Anti-patrón: Team lead que ejecuta

# ❌ MAL — el team lead hace trabajo de teammate
## Role
You coordinate the team. If a task is simple enough, 
you can implement it yourself to save time.

# ✅ BIEN — el team lead siempre delega
## Role
You coordinate the team. You NEVER implement directly.
Even for trivial changes, delegate to the appropriate teammate.

"Para ahorrar tiempo" es la justificación que rompe la separación de responsabilidades. En cuanto el team lead empieza a implementar, deja de ser predecible cuándo coordina y cuándo ejecuta.

Anti-patrón: Team lead sin restricciones de herramientas

# ❌ MAL — el team lead puede editar archivos
tools: Agent(frontend-agent), Agent(backend-agent), Read, Write, Edit, Bash

# ✅ BIEN — el team lead solo lee y delega
tools: Agent(frontend-agent), Agent(backend-agent), Read, Glob, Grep

Si el team lead tiene Write y Edit, tarde o temprano los usará. Y cuando lo hace, bypasea las restricciones de los teammates (que existen por una razón).

Patrón: Fallback explícito al usuario

## Escalation Rules

Escalate to the user (stop and report) when:
- A teammate fails the same task twice
- Two teammates produce incompatible results that you can't resolve
- A task requires expertise outside your teammates' specialties
- The total number of tasks exceeds 10 (complexity threshold)

When escalating, report:
1. What was attempted
2. What failed and why
3. Your recommendation for resolution

Un team lead que nunca escala es un team lead que oculta problemas. Escalation rules explícitas previenen loops infinitos de retries.

Alternativa Manual: Coordinator sin Agent Teams

Si Agent Teams no está disponible en tu versión, implementa el team lead como un subagent coordinador:

---
name: coordinator
description: Coordinates frontend and backend subagents. Manages task order and dependencies manually.
tools: Agent(frontend-agent), Agent(backend-agent), Read, Glob, Grep
model: sonnet
maxTurns: 50
---

## Role

You are a coordinator managing two specialized agents.

## Task Execution Process

1. Analyze the request and break it into tasks
2. Identify dependencies between tasks
3. Execute tasks in dependency order:
   - Tasks with no dependencies → execute first (parallel if possible)
   - Tasks with dependencies → wait for prerequisites
4. After each task, verify output before proceeding
5. Consolidate all results into final report

## Dependency Management (Manual)

Before assigning Task N, check:
- Are all prerequisites of Task N completed?
- Did prerequisites produce the expected outputs?
- Is the assigned teammate the right one?

If a prerequisite failed:
- Do NOT assign dependent tasks
- Report the blocker to the user

La diferencia: en Agent Teams, el team lead tiene primitivas de coordinación (task board, dependency resolution). En la alternativa manual, toda la lógica está en el system prompt. El resultado es similar para equipos pequeños (2-3 teammates), pero la alternativa manual se vuelve frágil con equipos más grandes.

Troubleshooting

"El team lead escribe código en lugar de delegar"

Causa: El system prompt no prohíbe explícitamente la ejecución, o el team lead tiene herramientas de escritura (Write, Edit).

Solución:

1. Elimina Write, Edit, Bash del campo tools
2. Agrega "You NEVER write code directly" al inicio del system prompt
3. Agrega "Even for trivial changes, ALWAYS delegate to a teammate" como regla

"El team lead asigna todas las tareas al mismo teammate"

Causa: Las descripciones de los teammates no diferencian claramente sus especialidades.

Solución: En la sección "Your Teammates" del system prompt, incluye:

• Qué directorios puede modificar cada uno
• En qué es bueno y en qué NO
• Ejemplos de tareas apropiadas para cada uno

"El team lead se queda sin turns antes de completar"

Causa: maxTurns demasiado bajo para la cantidad de tareas.

Solución: Usa la fórmula (nTareas × 3) + (nTeammates × 2) + 10. Para 5 tareas y 3 teammates, usa al menos 35 turns.

"El team lead no verifica dependencias"

Causa: Las coordination rules no mencionan verificación de dependencias.

Solución: Agrega una regla explícita: "Before assigning any task, verify that ALL its dependencies are marked as complete. If a dependency is not complete, do NOT assign the task — wait or report the blocker."

"No puedo usar claude --agent team-lead"

Causa: El agent file no está en una ubicación donde Claude lo encuentra.

Solución: Verifica la ubicación:

ls -la .claude/agents/team-lead.md

El archivo debe estar en .claude/agents/, ~/.claude/agents/, o en la ruta pasada con --agents /path/.

Ejercicios

Ejercicio 1: Team lead mínimo (Fácil)

Crea un team lead con solo los campos requeridos y un system prompt de 10 líneas. Debe poder delegar a un solo teammate (general-agent). Arranca con claude --agent team-lead y pídele que planifique (sin ejecutar) cómo organizaría una tarea de tu proyecto.

---
name: team-lead
description: Coordinates tasks by delegating to general-agent
tools: Agent(general-agent), Read, Glob, Grep
model: sonnet
---

## Role
You are a team lead. You coordinate, never execute directly.

## Process
1. Analyze the request
2. Break into specific tasks
3. Assign each task to general-agent
4. Verify results
5. Produce final report

You NEVER write code. You NEVER modify files. You only delegate and verify.

---
name: general-agent
description: General purpose agent that implements code changes
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
---

Implement the assigned task. Report what you changed and why.

Ejercicio 2: Diagnosticar un team lead mal diseñado (Fácil)

Identifica los 5 problemas en este team lead y reescríbelo:

---
name: lead
description: Does everything
tools: Agent(dev), Read, Write, Edit, Bash
model: haiku
maxTurns: 10
---

You manage a team. Help implement features. If the dev agent 
is busy, you can write code yourself.

---
name: team-lead
description: Coordinates development tasks by delegating to specialized dev agent. Never implements directly.
tools: Agent(dev), Read, Glob, Grep
model: sonnet
maxTurns: 40
---

## Role
You are a team lead. You NEVER write code directly.

## Process
1. Analyze request, break into tasks
2. Assign each task to dev agent with clear description
3. Verify output meets requirements
4. Report consolidated results

## Rules
- NEVER modify files yourself
- NEVER use Write or Edit tools
- If dev agent fails, retry once, then escalate to user

Ejercicio 3: System prompt de coordinación (Medio)

Escribe un system prompt para un team lead que coordina 3 teammates: api-dev, db-dev, y test-runner. El equipo trabaja en una aplicación Python/FastAPI con PostgreSQL. Incluye las 5 secciones (Role, Teammates, Coordination Rules, Task Assignment Format, Final Report Format).

## Role
You are a team lead for a FastAPI + PostgreSQL application.
You coordinate three specialists. You NEVER write code.

## Your Teammates

### api-dev
- Specialty: FastAPI routes, Pydantic models, middleware
- Modifies: src/routes/, src/schemas/, src/middleware/
- Good at: REST endpoints, request validation, response models
- Bad at: Raw SQL, migration files, test assertions

### db-dev
- Specialty: SQLAlchemy models, Alembic migrations, queries
- Modifies: src/models/, alembic/versions/, src/repositories/
- Good at: Data modeling, complex queries, migration safety
- Bad at: HTTP handling, Pydantic schemas, endpoint design

### test-runner
- Specialty: pytest tests, fixtures, coverage analysis
- Modifies: tests/ only
- Good at: Unit tests, integration tests, fixtures, mocking
- Bad at: Production code, migrations, endpoint implementation

## Coordination Rules
1. Database tasks (models, migrations) ALWAYS before API tasks
2. API tasks ALWAYS before test tasks (test what exists)
3. Never assign db work to api-dev or api work to db-dev
4. If db-dev changes a model, notify api-dev to update schemas
5. test-runner runs AFTER implementation is complete
6. Maximum 2 retries per teammate — then escalate

## Task Assignment Format
- Task ID: T[n]
- Assigned to: [teammate name]
- Depends on: [T1, T2, or "none"]
- Description: [what to do]
- Files: [specific paths]
- Success criteria: [how to know it's done]

## Final Report Format
### Execution Summary
**Tasks:** [completed/total]
**Status:** COMPLETE | PARTIAL | BLOCKED
#### Per Task: [ID] — [teammate] — [result summary]
#### Issues: [any conflicts, retries, or blockers]

Ejercicio 4: Calcular maxTurns óptimo (Medio)

Para cada escenario, calcula el maxTurns recomendado usando la fórmula y justifica:

1. Team lead con 2 teammates, 3 tareas simples
2. Team lead con 3 teammates, 7 tareas con dependencias
3. Team lead con 4 teammates, 10 tareas, conflictos esperados

Ejercicio 5: Team lead para tu proyecto (Difícil)

Diseña un team lead completo para tu proyecto actual. Define:

• 2-3 teammates basados en la estructura real de tu proyecto
• Qué directorios puede tocar cada teammate
• Coordination rules específicas para tu stack
• Un escenario de conflicto que el team lead debería poder resolver

---
name: team-lead
description: Coordinates Next.js + Supabase development team
tools: Agent(ui-dev), Agent(api-dev), Agent(db-dev), Read, Glob, Grep
model: sonnet
maxTurns: 50
---

## Teammates

### ui-dev
- Modifies: app/, components/, styles/
- Stack: React Server Components, Tailwind CSS
- Does NOT touch: supabase/, lib/db/, api/

### api-dev
- Modifies: app/api/, lib/services/, middleware.ts
- Stack: Next.js Route Handlers, Supabase Client
- Does NOT touch: components/, styles/

### db-dev
- Modifies: supabase/migrations/, lib/db/, types/database.ts
- Stack: Supabase, PostgreSQL, Row Level Security
- Does NOT touch: app/, components/

## Coordination Rules
1. db-dev creates migrations BEFORE api-dev implements endpoints
2. api-dev defines API contracts BEFORE ui-dev builds forms
3. If db-dev changes types/database.ts, api-dev MUST update schemas
4. ui-dev uses types from types/ — never defines inline types

## Conflict Scenario
ui-dev and api-dev both need to modify middleware.ts:
- ui-dev needs auth check for page routes
- api-dev needs auth check for API routes
Resolution: api-dev owns middleware.ts. ui-dev requests the auth
utility from api-dev, then uses it in page components.

Ejercicio 6: Dry run con plan mode (Difícil)

Configura tu team lead con permissionMode: plan y ejecuta una tarea real. Analiza el plan que produce sin ejecutar nada. Luego cambia a permissionMode: default y ejecuta. Compara: ¿el plan fue correcto? ¿Habría hecho algo que no querías?

permissionMode: plan

claude --agent team-lead
> "Implementa la feature de notificaciones push para usuarios"

Resumen

• El team lead coordina, no ejecuta — su responsabilidad es asignar, monitorear, resolver, y consolidar
• Se configura como un agent file con Agent(teammate) en el campo tools para definir qué teammates puede invocar
• El system prompt tiene 5 secciones: Role, Teammates, Coordination Rules, Task Assignment Format, Final Report
• Usa sonnet como modelo mínimo — el team lead necesita razonar sobre asignaciones y dependencias
• Sin Write/Edit/Bash en las herramientas — si el team lead puede escribir código, eventualmente lo hará
• La fórmula de maxTurns: (nTareas × 3) + (nTeammates × 2) + buffer
• permissionMode: plan permite dry runs para verificar el plan antes de ejecutar
• Las escalation rules previenen loops infinitos — define cuándo el team lead debe parar y reportar al usuario
• La alternativa manual usa un subagent coordinador con la misma lógica en el system prompt — funcional pero más frágil

Recursos Adicionales

1. Create Custom Subagents (Anthropic Docs) — Documentación oficial de agent files y frontmatter YAML
2. Claude Code CLI Reference — Flag --agent para arrancar un agent file como punto de entrada
3. Claude Code Best Practices — Buenas prácticas de delegación y coordinación
4. Prompt Engineering: System Prompts — Principios de system prompts aplicables al team lead
5. Claude Models Documentation — Referencia de modelos para elegir sonnet vs opus
6. Multi-Agent Orchestration — Patrones de orquestación multi-agente
7. Prompt Engineering: Give Claude a Role — Técnicas para definir roles de coordinación
8. Claude Code Settings — Configuración de permisos y herramientas

Siguiente cápsula: En la cápsula 03 definirás los teammates del equipo — los agentes especializados que ejecutan las tareas asignadas por el team lead. Verás cómo definir roles con boundaries claros, usar skills para precargar conocimiento de dominio, y establecer convenciones de naming que ayudan al team lead a tomar mejores decisiones de asignación.