Sub Agents en Claude Code: La Funcionalidad que Cambia tu Flujo de Desarrollo
Tiempo de lectura: 6 minutos
Si usas Claude Code regularmente, probablemente ya conoces su flujo básico: planificar, codificar, testear. Funciona bien. Pero hay una funcionalidad que Anthropic lanzó silenciosamente y que pocos desarrolladores están aprovechando: Sub Agents.
¿El resultado? Un flujo de trabajo donde cada tarea tiene un especialista dedicado, con su propio contexto y herramientas específicas.
El Problema que Resuelven los Sub Agents
Cuando desarrollamos, cambiamos constantemente entre diferentes “modos mentales”:
- Modo Arquitectura: Diseñando la estructura del código
- Modo Testing: Buscando edge cases y gaps de cobertura
- Modo Debugging: Rastreando la causa raíz de un bug
- Modo Documentación: Actualizando READMEs y comentarios
- Modo Refactoring: Mejorando código existente sin romper funcionalidad
El problema surge cuando le pides a Claude Code algo específico y decide hacer algo diferente:
- Le pides que corrija un test → refactoriza toda la suite de tests
- Le pides que encuentre un bug → implementa una feature nueva
- Le pides sugerencias → empieza a codificar cambios
Esto sucede porque Claude Code, por defecto, tiene acceso a todas las herramientas y opera en un solo contexto. Los Sub Agents resuelven exactamente esto.
¿Qué Son los Sub Agents?
Los Sub Agents son asistentes de IA especializados dentro de Claude Code. Cada uno tiene:
| Característica | Descripción |
|---|---|
| System Prompt propio | Instrucciones específicas para su rol |
| Herramientas restringidas | Solo acceso a lo que necesita |
| Contexto aislado | No se mezcla con otras tareas |
| Invocación explícita | Tú decides cuándo usarlo |
Piensa en ellos como un equipo de especialistas que puedes invocar según la tarea.
Configurando tus Primeros Sub Agents
Paso 1: Actualiza Claude Code
Primero, asegúrate de tener la última versión:
claude update
Paso 2: Accede al Menú de Agents
Dentro de Claude Code, ejecuta:
/agents
Verás opciones para crear, editar y gestionar tus agents.
Paso 3: Crea un Agent
Selecciona “Create new agent” y luego “Generate with Claude” (recomendado).
Claude te pedirá describir qué quieres que haga el agent. Por ejemplo:
Experto en análisis de cobertura de tests. Solo analiza y sugiere,
nunca modifica código. Identifica gaps en testing y edge cases no cubiertos.
Paso 4: Configura las Herramientas
Esta es la parte clave. Restringe las herramientas según el rol:
| Tipo de Agent | Herramientas Recomendadas |
|---|---|
| Arquitecto | Read, List, Glob (solo lectura) |
| Analista de Tests | Read, List, Glob (solo lectura) |
| Implementador | Read, Write, Edit, Bash |
| Debugger | Read, Bash, Edit (limitado) |
| Documentador | Read, Write (solo .md y comments) |
Un agent de arquitectura no debería poder editar código. Solo analiza y recomienda.
Paso 5: Elige el Alcance
Tienes dos opciones:
- Project Agents: Guardados en
.claude/agents/del proyecto. Versionados con git. - Global Agents: Disponibles en todos tus proyectos.
Para equipos, los Project Agents son ideales porque todos comparten los mismos especialistas.
Caso Práctico: Desarrollando una Feature con Sub Agents
Veamos un flujo real. Supongamos que necesitas implementar autenticación JWT en una API.
Agent 1: Arquitecto (Solo Lectura)
Nombre: arquitecto
Prompt: Experto en arquitectura de software. Analiza estructura de proyectos,
sugiere patrones y evalúa decisiones técnicas. NUNCA implementa código,
solo proporciona recomendaciones detalladas.
Herramientas: Read, List, Glob
Invocación:
@arquitecto Necesito implementar autenticación JWT.
¿Cómo debería estructurar los módulos?
Resultado esperado: Un análisis de tu estructura actual y recomendaciones de dónde colocar middleware, servicios, y utilidades. Sin tocar ningún archivo.
Agent 2: Implementador
Nombre: implementador
Prompt: Desarrollador enfocado en implementación. Sigue especificaciones
exactas sin agregar funcionalidad no solicitada. Escribe código limpio
y bien documentado.
Herramientas: Read, Write, Edit, Bash
Invocación:
@implementador Implementa el middleware de autenticación JWT
según las recomendaciones del arquitecto en /src/middleware/auth.ts
Resultado esperado: Implementación precisa de lo solicitado, sin refactors sorpresa.
Agent 3: Analista de Tests
Nombre: test-analyst
Prompt: Especialista en testing. Analiza cobertura existente, identifica
edge cases no cubiertos y sugiere tests necesarios. NO escribe tests,
solo proporciona especificaciones detalladas.
Herramientas: Read, List, Glob
Invocación:
@test-analyst Analiza el middleware de auth que acabamos de crear.
¿Qué casos de test necesitamos?
Resultado esperado: Lista detallada de casos de test: token válido, token expirado, token malformado, header faltante, etc.
Agent 4: Test Writer
Nombre: test-writer
Prompt: Escribe tests basándose en especificaciones proporcionadas.
Sigue las convenciones del proyecto. Un test a la vez cuando se solicite.
Herramientas: Read, Write, Edit
Invocación:
@test-writer Implementa los tests para el caso de token expirado
según el análisis anterior
Resultado esperado: Solo el test solicitado, no toda la suite.
Configuraciones de Agents Recomendadas
Aquí hay un set de agents que funciona bien para la mayoría de proyectos:
┌─────────────────┬──────────────────────────────────────┬─────────────────┐
│ Agent │ Propósito │ Herramientas │
├─────────────────┼──────────────────────────────────────┼─────────────────┤
│ arquitecto │ Análisis y diseño de estructura │ Read, List │
│ implementador │ Codificación de features │ Read, Write, │
│ │ │ Edit, Bash │
│ test-analyst │ Análisis de cobertura y gaps │ Read, List │
│ test-writer │ Escritura de tests específicos │ Read, Write │
│ debugger │ Investigación de bugs │ Read, Bash │
│ refactor │ Mejoras de código existente │ Read, Write, │
│ │ │ Edit │
│ docs │ Documentación y comentarios │ Read, Write │
│ reviewer │ Code review y sugerencias │ Read, List │
└─────────────────┴──────────────────────────────────────┴─────────────────┘
Tips para Aprovechar los Sub Agents
1. Empieza con 3-4 Agents
No necesitas crear 10 agents el primer día. Comienza con los esenciales: arquitecto, implementador, y test-analyst.
2. Restricción de Herramientas es Clave
La magia está en limitar lo que cada agent puede hacer. Un arquitecto que puede editar código eventualmente lo hará.
3. Usa Project Agents para Equipos
Guárdalos en .claude/agents/ y súbelos al repositorio. Todo el equipo trabaja con los mismos especialistas.
4. Delega Explícitamente
En lugar de esperar que Claude Code elija el agent correcto, invócalos directamente con @nombre-agent.
5. Itera en los Prompts
Si un agent no se comporta como esperas, ajusta su system prompt. Sé específico sobre lo que debe y no debe hacer.
Cómo Funciona la Delegación
Claude Code puede delegar automáticamente tareas a sub agents cuando detecta que otro especialista sería más apropiado. Pero también puedes ser explícito:
# Delegación explícita
@arquitecto revisa la estructura del módulo de pagos
# Claude Code decide
Necesito analizar la arquitectura de pagos
# (Claude puede invocar al arquitecto automáticamente)
Conclusión
Los Sub Agents transforman Claude Code de un asistente generalista a un equipo de especialistas. El beneficio principal no es velocidad de código—es control sobre el flujo de trabajo y eliminación de cambios de contexto no deseados.
Si llevas tiempo usando Claude Code y sientes que a veces “se va por las ramas”, los Sub Agents son la solución que estabas buscando.
¿Ya probaste los Sub Agents? Comparte tu configuración en los comentarios. ¿Qué agents has creado para tu flujo de trabajo?
Para más información, consulta la documentación oficial de Claude Code.