Volver

Claude Code Subagents: La Guía Definitiva que No Encontrarás en YouTube

Todo lo que necesitas saber sobre subagentes en Claude Code para cualquier lenguaje. Sin la confusión de tutoriales mal documentados, basado en documentación oficial y proyectos reales.

15 min

Estuve 3 días intentando entender los subagentes de Claude Code. La documentación oficial existe pero es escueta. Los tutoriales en YouTube confunden conceptos. Aquí está todo lo que necesitas saber, basado en documentación real y pruebas en proyectos de producción.

¿Qué Son Realmente los Subagentes?

Los subagentes son asistentes AI especializados que Claude Code puede delegar tareas. Cada subagente tiene su propio contexto de 200k tokens, system prompt personalizado y herramientas específicas.

No son:

  • Instalaciones npm complejas
  • Configuraciones JSON místicas
  • Servidores que corres en paralelo

Sí son:

  • Archivos Markdown con frontmatter YAML
  • Personalidades AI pre-configuradas
  • Contextos independientes de 200k tokens cada uno

Instalación Real (5 minutos)

Paso 1: Crear la estructura de directorios

# Para subagentes de proyecto (solo este proyecto)
mkdir -p .claude/agents

# Para subagentes globales (todos tus proyectos)
mkdir -p ~/.claude/agents

Paso 2: Crear tu primer subagente

Cada subagente se define en un archivo Markdown con esta estructura:

---
name: react-native-developer
description: Expert React Native developer. Use PROACTIVELY for mobile UI implementation
tools: Read, Write, Grep, Bash, MCP
---

You are a senior React Native developer specializing in:
- React Native 0.73+ with TypeScript
- Performance optimization with FlatList and React.memo
- Platform-specific code (iOS/Android)
- React Navigation 6 patterns
- Expo SDK when beneficial

When implementing:
1. Always use functional components with hooks
2. Implement proper TypeScript types
3. Handle both iOS and Android edge cases
4. Use React Native's built-in components over custom solutions
5. Follow React Native best practices from official docs

Performance guidelines:
- Use getItemLayout for FlatList when possible
- Implement proper keyExtractor functions
- Avoid anonymous functions in render
- Use InteractionManager for heavy operations

Guarda esto como .claude/agents/react-native-developer.md

Paso 3: Usar el subagente

Opción 1 - Comando directo:

> Use the react-native-developer subagent to create a task list component

Opción 2 - Claude lo invoca automáticamente:

> Create a React Native component for managing tasks with swipe actions

El Comando /agents (La Forma Fácil)

El comando /agents proporciona una interfaz interactiva donde puedes ver todos los subagentes disponibles, crear nuevos con configuración guiada, editar los existentes, y gestionar permisos de herramientas.

/agents

Te muestra:

Available Subagents:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 Built-in Agents
  - code-reviewer (Reviews code for quality)
  - test-writer (Writes comprehensive tests)

👤 User Agents (~/.claude/agents/)
  - data-analyst (SQL and data analysis expert)

📁 Project Agents (.claude/agents/)
  - react-native-developer ✓ (Active)
  - ui-designer

Actions:
[C]reate new  [E]dit  [D]elete  [R]efresh

Ejecución en Paralelo: La Verdad

Cuando un subagente está corriendo, puedes ver que el output dice “Task(Performing task X)”. Puedes correr múltiples subagentes en paralelo.

Sintaxis para paralelo:

# Explora el codebase con 4 agentes en paralelo
> Explore the codebase using 4 tasks in parallel

# Crea variaciones de UI con múltiples agentes
> Use 2 UI designers to create light and dark theme variations

El nivel de paralelismo está limitado a 10, pero puedes pedir más tareas y Claude las pondrá en cola.

Subagentes Especializados (Ejemplos que Uso)

1. Mobile UX Engineer

---
name: mobile-ux-engineer
description: Mobile UX specialist. MUST BE USED for user flow design
tools: Read, Write
---

You are a mobile UX expert focused on:
- Touch-friendly interfaces (min 44x44 points)
- Platform-specific patterns (iOS HIG, Material Design)
- Gesture areas and swipe zones
- Accessibility standards

Output semantic HTML structure without styling.

2. React Native Developer

---
name: react-native-developer
description: Expert React Native developer. Use PROACTIVELY for mobile UI implementation
tools: Read, Write, Grep, Bash, MCP
---

You are a senior React Native developer specializing in:
- React Native 0.73+ with TypeScript
- Performance optimization with FlatList and React.memo
- Platform-specific code (iOS/Android)
- React Navigation 6 patterns
- Expo SDK when beneficial

3. Backend Architect

---
name: backend-architect
description: Backend architecture expert. Use for API design and database modeling
tools: Read, Write, Bash, MCP
---

You design scalable backend systems:
- RESTful and GraphQL APIs
- Database schema optimization
- Microservices patterns
- Authentication and authorization
- Performance and caching strategies

4. Performance Optimizer (Universal)

---
name: performance-optimizer
description: Performance expert for any language/framework. Use after implementation
tools: Read, Write, Grep, Bash
---

You optimize applications by:
- Analyzing bottlenecks in any language
- Implementing language-specific optimizations
- Memory management improvements
- Database query optimization
- Caching strategies
- Bundle size reduction

MCP (Model Context Protocol) con Subagentes

Los subagentes pueden acceder a herramientas MCP de servidores MCP configurados. Cuando el campo tools se omite, los subagentes heredan todas las herramientas MCP disponibles.

Configurar Context7 para documentación de cualquier framework:

# Instalar Context7 MCP
npm install -g @context7/mcp-server

# Configurar para diferentes frameworks
context7 add react-native https://reactnative.dev/docs
context7 add nextjs https://nextjs.org/docs
context7 add vue https://vuejs.org/guide
context7 add django https://docs.djangoproject.com
context7 add rails https://guides.rubyonrails.org

Configurar en Claude Code:

// .mcp.json en la raíz de tu proyecto
{
  "mcpServers": {
    "context7": {
      "command": "context7",
      "args": ["serve"],
      "env": {}
    }
  }
}

Ahora tus subagentes pueden hacer:

> @mcp-query react-native "FlatList performance optimization"
> @mcp-query django "QuerySet optimization techniques"
> @mcp-query rails "Active Record N+1 queries"

Ejemplos Reales en Diferentes Stacks

React Native: App de Tareas

  1. Diseño UX inicial
> Use mobile-ux-engineer to design a task management app with:
- Quick add with FAB button
- Swipe to delete/complete
- Categories as chips
Focus on one-handed usage
  1. Implementación paralela
> Deploy 2 subagents in parallel:
1. react-native-developer: implement the task list
2. ui-designer: create Material You color scheme

Full Stack: E-commerce Platform

  1. Arquitectura paralela
> Run 3 parallel tasks:
1. backend-architect: design API for product catalog
2. frontend-developer: create Next.js product pages
3. database-expert: optimize PostgreSQL schema
  1. Optimización
> Use performance-optimizer to analyze the entire stack
Focus on API response times and frontend bundle size

Django + Vue: SaaS Dashboard

> Deploy 4 subagents for SaaS dashboard:
1. backend-architect: Django REST API design
2. vue-developer: create responsive dashboard
3. database-expert: design multi-tenant schema
4. security-expert: implement auth and permissions

Trucos Pro que Funcionan

1. Contexto compartido via archivos

# Los subagentes pueden compartir información
> All subagents should read REQUIREMENTS.md before starting
> Write findings to shared/analysis.md for other agents

2. Forzar uso de subagentes

Para fomentar uso más proactivo de subagentes, incluye frases como “use PROACTIVELY” o “MUST BE USED” en tu campo description.

3. Comando think para mejores resultados

Usa “think” para activar modo de pensamiento extendido, que da a Claude tiempo computacional adicional. Las frases específicas están mapeadas a niveles crecientes: “think” < “think hard” < “think harder” < “ultrathink”.

> Use react-native-developer and think hard about performance implications

4. Verificación con subagentes independientes

> Use code-reviewer subagent to verify the implementation
> Run security-auditor to check for vulnerabilities

Vibe coding responsable: Los subagentes aceleran el desarrollo, pero siempre revisa el output. Es la diferencia entre vibe coding productivo y código legacy del mañana.

Limitaciones Reales

1. Contexto no compartido

Los subagentes operan como entidades AI autónomas dentro del ecosistema de Claude Code, cada uno manteniendo contexto independiente. No comparten memoria directamente.

2. Consumo de tokens

Sesiones con tres subagentes activos típicamente consumen aproximadamente 3-4x más tokens que asistencia single-threaded equivalente.

3. Límite de paralelismo

Parece que el nivel de paralelismo está limitado a 10. Más tareas se encolan.

Setup Completo para Cualquier Proyecto

# 1. Crear estructura
mkdir -p .claude/agents

# 2. Crear CLAUDE.md para contexto del proyecto
cat > CLAUDE.md << 'EOF'
# Project Stack

Frontend: [Next.js/Vue/React Native/etc]
Backend: [Node.js/Django/Rails/etc]
Database: [PostgreSQL/MongoDB/etc]
Infrastructure: [AWS/Vercel/etc]

Conventions:
- [Tus convenciones específicas]
- [Estructura de archivos]
- [Patrones de diseño]

Commands:
- npm run dev: Start development
- npm test: Run tests
- [Otros comandos específicos]
EOF

# 3. Crear subagentes especializados según tu stack
# (adapta los ejemplos a tu tecnología)

# 4. Configurar MCP para tus docs
cat > .mcp.json << 'EOF'
{
  "mcpServers": {
    "context7": {
      "command": "context7",
      "args": ["serve"]
    }
  }
}
EOF

# 5. Usar!
claude-code

Flujo de Trabajo Universal

  1. Planning con think:

    > think hard about the architecture for [tu proyecto]

  2. Diseño con subagentes especializados:

    > Use [arquitecto/ux-engineer] to design the core structure

  3. Implementación paralela:

    > Run [N] parallel tasks:
1. backend-developer: implement API endpoints
2. frontend-developer: create UI components
3. database-expert: optimize queries

  4. Review y optimización:

    > Use code-reviewer to check the implementation
> Use performance-optimizer to find bottlenecks

Para Ti

Los subagentes no son magia negra. Son archivos Markdown con personalidades AI. El poder está en:

  1. Contextos separados = menos alucinaciones
  2. Especialización real = mejor código
  3. Paralelización = desarrollo más rápido
  4. MCP integration = documentación actualizada

Vibe coding con cerebro: Usa los subagentes para explorar ideas rápido, prototipar soluciones y acelerar el desarrollo. Pero el código que va a producción siempre pasa por tu criterio, tests y code review.

Setup básico: 5 minutos. Mejora en productividad: 3-4x. Vibe responsable: 100%.

¿Problemas o preguntas? jlopezlira@gmail.com

Si esto te ahorró horas de investigación, compártelo. La documentación oficial es buena pero escueta, y hay mucha desinformación dando vueltas.

PD: Este artículo usa citas de documentación oficial de Anthropic y experiencias verificadas de la comunidad. No es especulación, es lo que realmente funciona.