Dominar Claude Code Parte 6: Subagentes

Estás trabajando en una feature y te das cuenta de que necesitas tres cosas: revisión de seguridad de tus cambios, análisis de cobertura de tests y actualizaciones de documentación. Secuencialmente, eso es mucha espera. ¿Qué tal si Claude pudiera trabajar en las tres simultáneamente?

Eso es lo que hacen los subagentes. Son trabajadores de IA especializados con sus propias ventanas de contexto que se ejecutan en paralelo, cada uno enfocado en una tarea específica, devolviendo solo los resultados relevantes a tu conversación principal.

¿Qué Son los Subagentes?

Los subagentes son instancias aisladas de Claude que el Claude principal crea para manejar tareas específicas. La idea clave: cada subagente tiene su propia ventana de contexto. Esto importa porque:

• Tu conversación principal se mantiene limpia—sin desorden de tangentes de investigación
• Los subagentes pueden trabajar en paralelo sin interferir entre sí
• Solo los resultados destilados regresan, no el historial completo de exploración
• Las tareas complejas se dividen en piezas manejables

Piensa en ello como delegar a miembros del equipo. No necesitas ver cada búsqueda en Google que hicieron—solo necesitas sus conclusiones.

La Herramienta Task: Cómo Funciona

Bajo el capó, Claude usa la herramienta Task para crear subagentes. Cuando le pides a Claude hacer algo complejo, puede delegar partes a trabajadores especializados:

Tú: "Revisa este PR por problemas de seguridad, verifica la cobertura de tests y actualiza la documentación de la API"

Claude internamente:
├─→ Task(Auditor de Seguridad) → Hallazgos de seguridad
├─→ Task(Analizador de Cobertura) → Reporte de cobertura
└─→ Task(Escritor de Docs) → Documentación actualizada

Claude: "Esto es lo que encontré en las tres áreas..."

Claude puede ejecutar hasta 7 subagentes simultáneamente. Los resultados se fusionan de vuelta en tu conversación principal como salida limpia y resumida.

Tipos de Subagentes Integrados

Claude Code viene con varios tipos de agentes integrados que puedes invocar:

Explore — Exploración rápida del código base. Úsalo para encontrar archivos, buscar patrones, entender la arquitectura. Solo lectura, optimizado para velocidad.

"Usa un agente Explore para encontrar todos los archivos que manejan autenticación de usuarios"

Plan — Modo arquitecto de software. Diseña estrategias de implementación, identifica archivos críticos, considera trade-offs. Devuelve planes paso a paso.

"Usa un agente Plan para diseñar cómo deberíamos implementar notificaciones en tiempo real"

Bash — Especialista en ejecución de comandos. Ejecuta comandos shell, maneja operaciones git, ejecuta scripts.

"Usa un agente Bash para ejecutar la suite de tests y resumir los fallos"

general-purpose — La navaja suiza. Investigación, tareas de múltiples pasos, cualquier cosa que no encaje en los tipos especializados.

"Usa un agente general-purpose para investigar mejores prácticas de rate limiting"

Cuándo Claude Usa Subagentes Automáticamente

Claude no siempre anuncia cuándo está usando subagentes—simplemente lo hace cuando es eficiente. Delegación automática común:

• Exploración en modo plan — Cuando entras en modo plan, Claude a menudo crea un agente Explore para entender tu código base antes de proponer cambios
• Análisis paralelo de archivos — Leer múltiples archivos no relacionados simultáneamente
• Tareas de investigación — Búsquedas web y consultas de documentación
• Búsqueda de patrones — Encontrar patrones de código en código bases grandes

Verás indicadores de actividad cuando los subagentes están trabajando. Los resultados aparecen como si Claude hubiera hecho todo él mismo—porque técnicamente, así fue.

Creando Subagentes Personalizados

Para tareas especializadas y repetibles, crea tus propios subagentes. Viven en .claude/agents/:

.claude/agents/
└── security-auditor/
    └── AGENT.md

Formato de AGENT.md

---
Name: security-auditor
Description: "Audit code for security vulnerabilities including OWASP Top 10, authentication issues, data exposure, and injection attacks"
Tools: Read, Grep, Glob
Model: sonnet
---

# Security Auditor

You are a security specialist focused on finding vulnerabilities in code.

## Process

1. Scan for hardcoded secrets (API keys, passwords, tokens)
2. Check input validation on all user-facing endpoints
3. Review authentication and authorization flows
4. Analyze data handling for exposure risks
5. Look for injection vulnerabilities (SQL, command, XSS)
6. Check error messages for information leakage

## Output Format

Organize findings by severity:

### Critical (Must Fix Before Merge)
- Issue description
- File and line number
- Why it's dangerous
- How to fix it

### Warning (Should Fix)
- Same format as critical

### Info (Consider Fixing)
- Same format

## Constraints

- Read-only: analyze and report, don't modify code
- Flag uncertainty: if unsure, mark for human review
- Be specific: vague warnings aren't actionable

Opciones de Frontmatter

name (obligatorio) — Identificador del agente. Minúsculas, guiones permitidos.

description (obligatorio) — Cuándo usar este agente. Claude compara tus solicitudes con esta descripción para decidir si invocarlo. Sé específico.

tools — Qué herramientas puede usar el agente. Separadas por comas: Read, Grep, Glob, Bash, Write, Edit. Principio de mínimo privilegio—solo otorga lo necesario.

model — Qué modelo de Claude usar:

• sonnet — Rápido, rentable (por defecto)
• opus — Máxima capacidad para razonamiento complejo
• haiku — El más rápido, para tareas simples
• inherit — Usar el mismo modelo que la conversación principal

color — Identificador visual en la UI (opcional)

Invocando Subagentes Personalizados

Una vez creados, invoca los subagentes de forma natural:

"Usa el agente security-auditor para revisar los cambios en este PR"

"Ejecuta security-auditor en src/auth/"

"Que el auditor de seguridad revise los nuevos endpoints de pago"

Claude reconoce tu agente y lo crea con el contexto apropiado.

Patrones de Ejecución Paralela

Fan-Out: Múltiples Perspectivas

Analiza el mismo código desde diferentes ángulos simultáneamente:

"Revisa este PR con security-auditor, performance-analyzer
y test-coverage en paralelo"

┌─→ Agente de Seguridad ──→ Reporte de Seguridad
              │
Tu Código ────┼─→ Agente de Rendimiento ─→ Reporte de Rendimiento
              │
              └─→ Agente de Cobertura ───→ Reporte de Cobertura

                        ↓
                Análisis Combinado

Cada agente se enfoca en su especialidad. Obtienes retroalimentación completa más rápido que con una revisión secuencial.

Pipeline: Entrega Secuencial

Encadena agentes donde cada uno construye sobre el anterior:

Código → Agente Analizador → Análisis
                                ↓
                  Agente Refactorizador → Código Mejorado
                                              ↓
                                    Agente de Tests → Tests

Úsalo cuando las etapas posteriores dependen de resultados anteriores.

Enrutamiento por Especialista

Dirige tareas a expertos del dominio:

"Implementa la feature del dashboard de usuario"

Claude dirige internamente:
├─→ Agente Frontend (componentes React)
├─→ Agente Backend (endpoints API)
└─→ Agente Base de Datos (cambios de schema)

Ejemplo: Construyendo un Equipo de Revisión

Vamos a crear un sistema de code review multi-agente.

Agente 1: Auditor de Seguridad

Mkdir -p .claude/agents/security-auditor
Cat > .claude/agents/security-auditor/AGENT.md << 'EOF'
---
Name: security-auditor
Description: "Review code for security vulnerabilities, OWASP issues, auth problems"
Tools: Read, Grep, Glob
Model: sonnet
---

# Security Auditor

Focus: Finding security vulnerabilities.

## Checklist
- [ ] Hardcoded secrets
- [ ] SQL/command injection
- [ ] XSS vulnerabilities
- [ ] Auth/authz issues
- [ ] Data exposure
- [ ] Insecure dependencies

## Output
Rate each finding: Critical / Warning / Info
Include: file, line, issue, fix
EOF

Agente 2: Analizador de Rendimiento

Mkdir -p .claude/agents/performance-analyzer
Cat > .claude/agents/performance-analyzer/AGENT.md << 'EOF'
---
Name: performance-analyzer
Description: "Analyze code for performance issues, N+1 queries, memory leaks, bottlenecks"
Tools: Read, Grep, Glob
Model: sonnet
---

# Performance Analyzer

Focus: Finding performance problems.

## Checklist
- [ ] N+1 database queries
- [ ] Missing indexes
- [ ] Unnecessary re-renders
- [ ] Memory leaks
- [ ] Blocking operations
- [ ] Large payload transfers

## Output
Rate each finding: Critical / Warning / Info
Include: file, line, issue, estimated impact, fix
EOF

Agente 3: Cobertura de Tests

Mkdir -p .claude/agents/test-coverage
Cat > .claude/agents/test-coverage/AGENT.md << 'EOF'
---
Name: test-coverage
Description: "Analyze test coverage, identify untested code paths, suggest missing tests"
Tools: Read, Grep, Glob, Bash
Model: sonnet
---

# Test Coverage Analyzer

Focus: Identifying gaps in test coverage.

## Process
1. Run existing tests to check current coverage
2. Identify untested functions and branches
3. Flag critical paths without tests
4. Suggest specific test cases to add

## Output
- Current coverage percentage
- List of untested critical paths
- Suggested test cases with priority
EOF

Usándolos Juntos

"Ejecuta una revisión completa del módulo de auth usando los agentes
security-auditor, performance-analyzer y test-coverage en paralelo"

Claude crea los tres, trabajan simultáneamente y obtienes un reporte completo.

Buenas Prácticas

1. Responsabilidad Única

Cada agente debería hacer una cosa bien. No crees un agente que "hace de todo"—eso es solo Claude con pasos extra.

2. Descripciones Específicas

El campo de descripción determina cuándo Claude auto-invoca tu agente. Sé específico:

# Mal - demasiado vago
Description: "Helps with code"

# Bien - disparadores específicos
Description: "Review code for SQL injection, XSS, CSRF, and authentication vulnerabilities using OWASP guidelines"

3. Permisos Mínimos

Solo otorga las herramientas que el agente necesita:

# Agentes analizadores: solo lectura
Tools: Read, Grep, Glob

# Agentes escritores: pueden modificar
Tools: Read, Write, Edit

# Agentes ejecutores: pueden ejecutar
Tools: Read, Bash

4. Formato de Salida Claro

Especifica exactamente cómo quieres los resultados. Los agentes que devuelven formatos consistentes son más fáciles de usar.

5. Sección de Restricciones

Dile al agente qué NO hacer. Previene la expansión del alcance y comportamientos inesperados.

Colecciones Populares de Subagentes

No construyas todo desde cero. Estas colecciones están probadas en batalla:

VoltAgent/awesome-claude-code-subagents — Más de 100 agentes para flujos de trabajo de desarrollo general.

wshobson/agents — 99 agentes y 15 orquestadores para flujos de trabajo de producción.

rshah515/claude-code-subagents — Más de 133 agentes cubriendo el SDLC completo.

Instálalos clonando en tu directorio .claude/agents/:

Git clone https://github.com/VoltAgent/awesome-claude-code-subagents.git .claude/agents/voltagent

Comandos vs Skills vs Subagentes

Comandos — Plantillas de prompts que invocas explícitamente con /comando. Comparten contexto con tu conversación principal y se ejecutan secuencialmente. Ideales para prompts repetidos donde quieres control explícito.

Skills — Módulos de conocimiento que Claude auto-compara con tus solicitudes. Se cargan en tu contexto principal cuando son relevantes. Ideales para estándares y patrones que deberían aplicarse automáticamente.

Subagentes — Trabajadores especializados con ventanas de contexto independientes. Pueden ejecutarse en paralelo y devuelven solo resultados destilados. Ideales para tareas paralelas complejas o cuando necesitas exploración aislada.

Limitaciones

• Sin anidamiento: Los subagentes no pueden crear otros subagentes
• Coste de tokens: Cada subagente usa su propio contexto, lo cual cuesta tokens
• Coordinación: Los flujos multi-agente complejos requieren orquestación clara
• Conflictos de escritura: Ten cuidado con múltiples agentes escribiendo en los mismos archivos

Qué Sigue

Los subagentes permiten que Claude delegue y paralelice trabajo. Pero ¿qué pasa si quieres que Claude se conecte a servicios externos—bases de datos, APIs o herramientas personalizadas que tu equipo ha construido?

Ahí es donde entra MCP (Model Context Protocol). En la Parte 7: Servidores MCP, exploraremos cómo extender las capacidades de Claude conectándolo a fuentes de datos y servicios externos.