Crear un subagente en Claude Code te permite delegar tareas específicas a un agente especializado que reutiliza el contexto de tu proyecto. Si trabajas con agentes de codificación y quieres planificar la implementación de un feature sin perder hilo, esta guía te muestra cómo configurar uno paso a paso.

El flujo se centra en un caso real: construir un agente Architect que diseñe el plan técnico del feature de ratings para Platzi Flix, apoyándose en el contexto previo de la conversación.

Qué es un subagente en Claude Code y para qué sirve

Un subagente es una instancia especializada que opera dentro de Claude Code con su propia personalidad, herramientas y modelo. Su valor está en que puede ejecutar una tarea puntual con foco, sin contaminar el contexto principal.

¿Qué es un subagente en Claude Code? Es un agente especializado que se invoca desde la conversación principal con un system prompt, herramientas y modelo propios para resolver una tarea específica como diseñar arquitectura o analizar bugs.

Claude Code es un agente de codificación que se apoya en modelos grandes de lenguaje y herramientas, y una de sus capacidades principales es justamente crear estos subagentes [0:00].

Cómo retomar una conversación previa con el comando resume

Antes de crear el subagente, necesitas el contexto. Si cerraste Claude Code, el comando /resume te muestra una lista de conversaciones anteriores con su antigüedad y la rama en la que ocurrieron [0:46].

Esto es clave porque el subagente Architect va a trabajar sobre el contexto que ya extrajimos en una clase anterior usando Ultra Think, Think Deeply y Think para analizar el feature de rating.

Cómo crear un subagente paso a paso con el comando agent

El comando /agent abre el flujo de creación. Vamos por las decisiones importantes.

Qué decisiones de configuración tomar al crear el agente

El asistente te pregunta varias cosas en orden:

• Alcance: personal (todos los proyectos de tu computadora) o solo este proyecto.
• Modo de generación: dejar que Claude lo genere o configuración manual.
• Nombre único: en este caso Architect, porque actuará como arquitecto de software especializado en definir las fases de implementación.
• System prompt inicial: puedes poner uno básico si planeas reemplazarlo después.
• Casos de uso: cuándo Claude debería invocarlo automáticamente.
• Herramientas permitidas: lectura, edición, ejecución de comandos, grep, edición múltiple, etc.
• Modelo: Sonnet para tareas generales, Opus para razonamiento complejo, Haiku para tareas simples, o el mismo de la conversación.
• Color: solo identificación visual; en este ejemplo, amarillo [2:00].

Por defecto el agente recibe todas las herramientas, pero puedes restringirlo a read-only si quieres que solo analice sin modificar nada.

Dónde se guarda la configuración del subagente

La definición queda en la carpeta .claude/agents/ del proyecto, en un archivo Markdown con un YAML front matter que contiene nombre, descripción, modelo y color, más el system prompt debajo [4:25].

¿Dónde vive un subagente de Claude Code? En un archivo Markdown dentro de la carpeta .claude/agents/ del proyecto, con configuración en YAML front matter y el system prompt en el cuerpo.

Cómo escribir un system prompt útil para un subagente Architect

El system prompt genérico que crea el asistente no alcanza. Un buen prompt para un agente arquitecto debe incluir:

• Especialización: arquitectura de software, diseño de sistemas y análisis técnico profundo.
• Responsabilidades concretas del rol.
• Contexto del proyecto sobre el que trabaja.
• Metodología de análisis a seguir.
• Instrucciones de trabajo paso a paso.
• Formato de salida esperado, en este caso Markdown con secciones de análisis técnico, problema identificado, impacto, propuesta de solución y plan de implementación [5:30].

La descripción tampoco es decorativa: define cuándo Claude debe invocar a este agente automáticamente, así que conviene ser específico sobre el caso de uso.

Cómo invocar un subagente dentro de una conversación activa

Después de modificar el archivo del agente, hay que reiniciar Claude Code para que tome los cambios. Luego usas /resume para volver a la conversación con el contexto cargado.

Para llamar al agente escribes @Architect y presionas tabulador. El nombre se resalta en amarillo, indicando que la siguiente instrucción se ejecutará dentro del contexto del subagente [7:10]. La instrucción puede ser tan directa como pedirle que use el contexto descubierto y construya el plan de implementación.

Cómo guardar el plan de implementación en el proyecto

Un detalle clave: los resultados del subagente deben quedar documentados en el repositorio. La forma de lograrlo es indicarle a Claude Code que guarde la salida con el formato del agente Architect dentro de una carpeta Spec en la raíz, con la nomenclatura 00_nombre_del_spec.markdown, donde 00 es un número que incrementa con cada nueva spec [9:00].

El resultado en Platzi Flix incluyó:

• Patrones identificados en el código existente.
• Arquitectura de datos actual documentada.
• Plan de implementación por fases, empezando por la capa de base de datos.
• Consideraciones de performance, como crear índices para que las queries no se vuelvan lentas.
• Notas de testing y escalabilidad.

La ventaja de hacerlo por fases secuenciales e incrementales es que no construyes el feature de un solo golpe, sino con puntos de control claros.

Para qué más sirve un subagente Architect

Este mismo subagente puede analizar features existentes, no solo crear nuevos. Si reportas un bug, el Architect puede investigar el código, identificar la causa y proponer un plan de mejora con la misma estructura de spec.

Los subagentes son herramientas potentes porque puedes crear muchos con personalidades distintas según el caso de uso: uno para arquitectura, otro para testing, otro para revisión de seguridad. El plan generado por Architect será la base para implementar el feature de ratings en las siguientes clases.

¿Qué subagente crearías tú primero para tu flujo de trabajo? Cuéntame en los comentarios.