Módulo 1: Custom Subagents

1. Introducción al Módulo — Más Allá de Task() Básico

Descripción

Este módulo transforma tu relación con Claude Code. Hasta ahora has usado subagents como cajas negras — "haz esto y devuélveme el resultado." Eso funciona para tareas puntuales, pero no escala. Cuando necesitas un agente que solo revise código sin poder modificarlo, otro que implemente features siguiendo convenciones específicas, y un tercero que corra tests y reporte resultados en un formato concreto — necesitas subagents con identidad propia.

La diferencia entre delegar una tarea genérica y diseñar un subagent especializado es la misma que entre contratar a "alguien que programe" y contratar a un senior backend engineer con experiencia en FastAPI y PostgreSQL. La especificidad define la calidad del resultado. En este módulo vas a aprender a crear esa especificidad: roles claros, restricciones de herramientas, system prompts que definen comportamiento, y comunicación estructurada entre agentes.

Al terminar, tendrás 3 subagents especializados (reviewer, implementer, tester) trabajando en un flujo de desarrollo real. No como demo — como herramienta que puedes usar mañana en tu proyecto.

¿Dónde Estamos en la Guía?

Contexto en el Path

Esta es la Guía #9 del Claude Code Agentic Development Path. En las guías anteriores aprendiste a operar Claude Code: desde la instalación básica hasta prompt engineering avanzado, CLAUDE.md, hooks, MCP servers, y uso básico de subagents. Sabes cómo funciona todo. Ahora vas a aprender a orquestar sistemas donde múltiples agentes trabajan coordinados.

Guías #1-4: Fundamentos y Prompt Engineering    ← completadas
Guías #5-8: Claude Code intermedio               ← completadas
▶ Guía #9: Advanced Claude Code Workflows       ← ESTÁS AQUÍ
Guía #10: Claude Code in CI/CD Pipelines         ← siguiente
Guía #11: Security for AI-Generated Code         ← después

Hay una diferencia enorme entre saber usar una herramienta y saber orquestar un equipo de herramientas. Las guías anteriores te enseñaron Claude Code como herramienta individual. Esta guía te enseña a dirigir un equipo de agentes Claude Code.

Contexto en la Guía

Esta guía tiene 8 módulos organizados en 3 phases:

Phase 1: Subagents Avanzados (Módulos 1-3)
├── Módulo 1: Custom Subagents                    ← ESTÁS AQUÍ
├── Módulo 2: Agent Memory y Scopes
└── Módulo 3: Parallel Sub-Agent Delegation

Phase 2: Agent Teams y Plugins (Módulos 4-6)
├── Módulo 4: Agent Teams
├── Módulo 5: Plugins: Crear y Distribuir
└── Módulo 6: Hooks Avanzados y SDK Headless

Phase 3: Orquestación (Módulos 7-8)
├── Módulo 7: Remote Control y CLAUDE.md para Equipos
└── Módulo 8: Proyecto: Sistema Multi-Agente Completo

Duración total estimada: 8-10 horas (self-paced).

¿Hacia dónde vamos?

Este módulo abre Phase 1 porque todo lo que viene después depende de subagents bien definidos:

Primero aprendes a crear agentes con identidad propia (este módulo) — sin esto, Agent Teams son grupos de agentes genéricos
Luego configuras memoria persistente (módulo 2) — tus subagents recuerdan contexto entre sesiones
Después delegas en paralelo (módulo 3) — múltiples subagents trabajando simultáneamente
Formalizas la coordinación con Agent Teams (módulo 4) — team lead, task board, dependencias
Empaquetas funcionalidad en plugins (módulo 5) — distribuir configuraciones reutilizables
Automatizas con hooks y SDK (módulo 6) — control programático completo
Operas remotamente y estandarizas (módulo 7) — remote control y CLAUDE.md para equipos
Integras todo en un sistema multi-agente (módulo 8) — el proyecto culminante

El Problema: Subagents Genéricos No Escalan

Un escenario que has vivido

Tienes un proyecto con 20 archivos. Necesitas tres cosas: revisar el código reciente, implementar una feature nueva, y correr los tests. Con Claude Code básico, haces esto en una sola conversación — secuencial, manual, y con el contexto acumulándose.

Con subagents básicos, delegas cada tarea por separado:

"Revisa el código"       → Subagent genérico → resultado OK, pero revisó todo incluyendo tests
"Implementa login"       → Subagent genérico → implementó, pero cambió convenciones existentes
"Corre los tests"        → Subagent genérico → corrió tests, pero no reportó cobertura

Cada subagent hizo algo, pero ninguno hizo exactamente lo que necesitabas. ¿Por qué? Porque todos eran genéricos. Sin rol definido, sin restricciones, sin instrucciones específicas de qué buscar, qué ignorar, y cómo reportar.

Lo que cambia con subagents custom

Con subagents especializados, la misma tarea se ve así:

reviewer  → Solo lee código, busca 8 criterios específicos, reporta por prioridad
implementer → Solo edita archivos en src/, sigue convenciones de CLAUDE.md, sin tocar tests
tester    → Corre tests, reporta cobertura, lista los que fallan con causa raíz

Cada agente sabe exactamente qué hacer, qué puede tocar, y qué formato usar para reportar. La diferencia no es sutil — es la diferencia entre "alguien que programa" y un equipo con roles definidos.

El costo de no especializarse

Sin especialización, cada delegación requiere instrucciones repetitivas en el prompt. Escribes el mismo contexto una y otra vez. Y cuando olvidas un detalle, el subagent toma decisiones por ti — edita archivos que no debía, usa un estilo inconsistente, o ignora tests existentes.

Un subagent custom lo configuras una vez. Luego lo usas cien veces con la misma calidad.

Objetivo del Módulo

Al terminar este módulo serás capaz de:

✅ Crear un subagent personalizado como archivo Markdown con frontmatter YAML que define nombre, descripción, modelo, y herramientas
✅ Escribir system prompts efectivos que definen el rol, criterios de trabajo, y formato de output del subagent
✅ Restringir herramientas por subagent — un reviewer que solo puede leer, un implementer que puede editar, un tester que solo ejecuta
✅ Configurar subagents a nivel proyecto (.claude/agents/) y a nivel usuario (~/.claude/agents/)
✅ Orquestar un flujo de 3 subagents secuenciales: reviewer → implementer → tester

Objetivo profesional

Mañana, cuando abras un proyecto real, no delegarás tareas genéricas a Claude Code. Crearás un archivo .claude/agents/reviewer.md que define exactamente cómo quieres que se revise el código. Un implementer.md que sigue las convenciones de tu equipo. Un tester.md que reporta en el formato que tu CI espera. Estos agentes se comparten con tu equipo via git y producen resultados consistentes independientemente de quién los invoque.

Roadmap del Módulo

Mapa de cápsulas

#	Cápsula	Qué aprenderás	Tipo
01	Introducción (esta)	Contexto, objetivos, por qué los subagents custom importan	Intro
02	Roles con System Prompts	Crear subagents como archivos Markdown, definir roles con system prompts efectivos, scopes de subagent	Técnica
03	Restricción de Herramientas	Controlar qué puede hacer cada subagent: tools allowlist, disallowedTools, permission modes, hooks de validación	Técnica
04	Output Parsing y Comunicación	Encadenar subagents, parsear outputs, patrones de comunicación entre agentes	Técnica
05	Proyecto: 3 Subagents Especializados	Construir un flujo reviewer → implementer → tester funcional en un proyecto real	Proyecto

Flujo de aprendizaje

Primero entenderás cómo definir un subagent con identidad propia — el archivo Markdown, el frontmatter YAML, y el system prompt que define su comportamiento (cápsula 02). Con esa base, aprenderás a restringir lo que puede hacer — porque un reviewer que edita archivos no es un reviewer (cápsula 03). Luego verás cómo los subagents se comunican — el output de uno es el input del siguiente, y parsear esa comunicación es un skill (cápsula 04). Finalmente, construirás un sistema funcional de 3 agentes trabajando en secuencia sobre un proyecto real (cápsula 05).

La progresión es: definir identidad → restringir capacidades → conectar agentes → construir sistema.

Cada cápsula construye directamente sobre la anterior. No saltes a la 04 sin dominar la 02 y 03 — la comunicación entre agentes requiere que cada uno tenga un rol y restricciones claras primero.

Duración estimada del módulo: 1-1.25 horas.

Conexión con el Proyecto

Mini-proyecto de este módulo: 3 Subagents Especializados

En la cápsula 05 construirás un flujo de desarrollo con tres subagents:

Reviewer — Analiza el código reciente, busca problemas de calidad y seguridad, reporta por prioridad (crítico/warning/sugerencia). Solo puede leer — no modifica nada.
Implementer — Recibe el reporte del reviewer y hace las correcciones. Solo puede editar archivos en src/. Sigue las convenciones definidas en CLAUDE.md. No toca tests.
Tester — Ejecuta la suite de tests después de los cambios del implementer. Reporta tests que pasan, fallan, y cobertura. Solo puede ejecutar comandos — no edita código.

Tu prompt:
"Revisa los cambios recientes, corrige los problemas, y verifica que los tests pasen"

↓

reviewer (read-only)        → Reporte: 2 críticos, 3 warnings
    ↓
implementer (edit src/)     → Corrige los 2 críticos y 2 warnings
    ↓
tester (bash only)          → 18/18 tests pasan, 87% cobertura

Conexión con el proyecto final (Módulo 8)

Los subagents que creas aquí son los building blocks de todo lo que sigue. En el módulo 3, se delegarán en paralelo. En el módulo 4, se convertirán en teammates de un Agent Team. En el módulo 8 (proyecto integrador), serán los 4 agentes especializados del sistema multi-agente completo. Sin subagents bien definidos, el sistema entero falla.

Prerequisitos

Conocimientos necesarios

✅ Claude Code instalado y operativo — Guías anteriores del path completadas
✅ CLAUDE.md configurado — Al menos un proyecto con CLAUDE.md funcional
✅ Experiencia con subagents básicos — Has usado Task() o delegado tareas a subagents explore/general-purpose
✅ Git y terminal avanzado — Navegas repositorios, haces branching, resuelves conflictos
✅ Programación intermedia — Python o TypeScript a nivel de proyecto real

Verificación rápida

Si puedes responder "sí" a estas preguntas, estás listo:

¿Has delegado al menos una tarea a un subagent en Claude Code?
¿Sabes qué es un system prompt y por qué importa para un agente?
¿Tienes un proyecto con al menos 5 archivos donde puedas practicar?
¿Sabes qué hace git diff HEAD~3 y por qué un reviewer lo necesitaría?

No necesitas

❌ Experiencia con Agent Teams — se cubre en el módulo 4
❌ Conocimiento de hooks avanzados — se cubre en el módulo 6
❌ Experiencia con plugins o SDK — se cubren en módulos 5 y 6
❌ Un proyecto grande o complejo — funciona con cualquier codebase de 5+ archivos

Setup para el Módulo

Lo que necesitas tener listo

1. Un proyecto con Claude Code configurado:

Necesitas un proyecto real con múltiples archivos. Si no tienes uno a mano, puedes usar cualquier proyecto open source clonado. Lo importante es que tenga:

Al menos 5-10 archivos de código fuente
Un CLAUDE.md básico
Tests existentes (idealmente)
Historial de git con al menos 3 commits

2. Claude Code actualizado:

claude --version

Asegúrate de tener la versión 2.1.63 o posterior — las versiones más recientes usan el Agent tool (rename de Task tool) y soportan todas las features de subagents que cubriremos.

3. Directorio de agents:

Verifica que el directorio de agents existe:

# Para subagents a nivel proyecto
mkdir -p .claude/agents

# Para subagents a nivel usuario (disponible en todos los proyectos)
ls ~/.claude/agents/ 2>/dev/null || mkdir -p ~/.claude/agents

4. Familiarízate con el comando /agents:

Abre Claude Code y ejecuta:

/agents

Verás los subagents disponibles (built-in y custom). Este comando será tu herramienta principal para gestionar subagents.

Conceptos Clave que Usaremos

Antes de entrar a las cápsulas técnicas, asegúrate de tener claros estos conceptos:

Subagent: Una instancia separada de Claude que ejecuta una tarea específica con su propio contexto, system prompt, y herramientas. No comparte contexto con la conversación principal.
System prompt: El texto Markdown que define el comportamiento del subagent — qué hace, cómo lo hace, qué busca, y qué formato usa para reportar.
Frontmatter YAML: La sección de configuración al inicio del archivo del subagent que define nombre, descripción, tools, modelo, y permisos.
Tool restriction: Limitar qué herramientas puede usar un subagent. Un reviewer con solo Read/Grep/Glob no puede modificar tu código.
Scope: Dónde vive el subagent — proyecto (.claude/agents/) o usuario (~/.claude/agents/). Define su alcance de disponibilidad.

Límites: Qué NO Se Cubre en Este Módulo

❌ Agent Teams — Se cubre en el Módulo 4. Aquí trabajas con subagents individuales y secuenciales
❌ Memory y persistencia entre sesiones — Se cubre en el Módulo 2. Aquí los subagents empiezan de cero cada vez
❌ Delegación paralela — Se cubre en el Módulo 3. Aquí los subagents trabajan en secuencia
❌ Hooks avanzados — Se cubren en el Módulo 6. Aquí usamos hooks básicos de validación cuando sea necesario
❌ Plugins — Se cubren en el Módulo 5. Aquí los subagents son archivos locales, no paquetes distribuibles
❌ SDK headless — Se cubre en el Módulo 6. Aquí todo es interactivo en Claude Code

Evidencia de Éxito

Al terminar este módulo, sabrás que tuviste éxito si:

✅ Puedes crear un subagent como archivo Markdown con frontmatter YAML completo en menos de 5 minutos
✅ Tu reviewer subagent revisa código sin poder modificar ningún archivo
✅ Tu implementer subagent modifica solo los archivos que especificaste y sigue las convenciones de CLAUDE.md
✅ Tu tester subagent ejecuta tests y reporta resultados en un formato estructurado
✅ Los 3 subagents trabajan en secuencia produciendo un flujo funcional end-to-end
✅ Puedes explicar a un colega por qué un subagent custom supera a una delegación genérica

Test rápido de autoevaluación

Si puedes responder estas preguntas al terminar el módulo, vas por buen camino:

¿Cuál es la diferencia entre un subagent genérico y uno custom?
¿Dónde se almacenan los archivos de subagents y qué define su scope?
¿Qué campos son obligatorios en el frontmatter YAML de un subagent?
¿Por qué un reviewer no debe tener acceso a Write y Edit?
¿Cómo se comunica el resultado de un subagent a otro en un flujo secuencial?

Nota sobre Features Experimentales

Las features de subagents que cubrimos en este módulo son estables y GA (Generally Available). Los subagents como archivos Markdown, el frontmatter YAML, el tool restriction, y la delegación secuencial son funcionalidad core de Claude Code.

Features experimentales como Agent Teams (módulo 4) están marcadas explícitamente cuando las cubramos. Este módulo no usa ninguna feature experimental.

Última verificación de funcionalidad: Marzo 2026

Resumen

Este módulo establece la base para toda la guía — custom subagents son el building block de Agent Teams, plugins, y orquestación multi-agente
La diferencia clave: un subagent genérico hace "algo"; un subagent custom hace exactamente lo que necesitas con restricciones claras
Aprenderás a crear subagents como archivos Markdown con frontmatter YAML que definen rol, herramientas, modelo, y permisos
Los system prompts son el skill más importante — la calidad del subagent depende directamente de la calidad de las instrucciones que le das
El mini-proyecto construye un flujo de 3 agentes (reviewer → implementer → tester) que puedes usar en proyectos reales
Todo lo aprendido aquí se usa en los módulos 2-8 — sin subagents bien definidos, nada de lo que sigue funciona

Recursos Adicionales

Create Custom Subagents (Anthropic Docs) — Documentación oficial completa de subagents en Claude Code
CLI Reference — Claude Code — Referencia de flags como --agents para definir subagents via CLI
Claude Code Best Practices — Buenas prácticas generales que aplican a subagents
Hooks Reference — Referencia de hooks que se usan para validación en subagents
Claude Code Overview — Contexto general de Claude Code como agente de código
Skills Documentation — Skills que se pueden precargar en subagents

Siguiente cápsula: En la cápsula 02 crearás tu primer subagent custom — un archivo Markdown con frontmatter YAML y un system prompt que define exactamente qué hace, cómo lo hace, y qué herramientas puede usar. Verás la diferencia entre un subagent genérico y uno diseñado con propósito.

Siguiente →2. Definiendo Roles con Subagent Files y System Prompts