💡 TL;DR: Aprende a definir subagentes con roles específicos en Claude Code usando archivos CLAUDE.md para dividir tareas complejas entre agentes especializados que trabajan en paralelo.

🎯 ¿Qué vas a lograr?

Vas a configurar un flujo con dos subagentes con roles distintos — uno que analiza y otro que implementa — para que Claude Code deje de ser un asistente genérico y se convierta en un equipo coordinado. Al final, entenderás cómo el contexto por archivo CLAUDE.md cambia completamente la calidad de las respuestas.

🧰 Requisitos

• Claude Code instalado (npm install -g @anthropic-ai/claude-code)
• Cuenta con acceso a la API de Anthropic (o suscripción Max)
• Un proyecto existente en cualquier lenguaje (sirve hasta un "hola mundo")
• Terminal con Node.js 18+

🚀 Paso a paso

Paso 1: Entiende qué es un subagente en Claude Code

Claude Code puede lanzar instancias paralelas de sí mismo para resolver subtareas. Pero sin instrucciones explícitas, todos los subagentes se comportan igual — sin rol, sin restricciones, sin especialización.

La clave está en el archivo CLAUDE.md: Claude lo lee automáticamente al iniciar en cualquier directorio. Si tienes uno en la raíz y otro en /backend, el agente que trabaje en /backend recibirá instrucciones distintas. Eso es contexto localizado.

Paso 2: Crea tu CLAUDE.md raíz como orquestador

En la raíz de tu proyecto, crea un CLAUDE.md que defina el rol del agente principal:

markdown

# Rol: Orquestador de proyecto

Eres el agente principal. Tu responsabilidad es:
1. Analizar el requerimiento del usuario
2. Dividirlo en tareas concretas
3. Delegar tareas de análisis al subagente en /docs
4. Delegar tareas de implementación al subagente en /src

**Nunca escribas código directamente.** Solo coordina y valida.
Cuando termines de delegar, resume qué hizo cada subagente.

Paso 3: Crea subagentes especializados por directorio

En /docs/CLAUDE.md, define el agente analista:

markdown

# Rol: Analista técnico

Eres responsable únicamente de documentar y analizar.
Cuando recibas una tarea:
- Escribe un análisis de impacto en `/docs/impact-analysis.md`
- Identifica dependencias y riesgos
- **No toques archivos fuera de /docs**
Sé conciso. Máximo 200 palabras por análisis.

En /src/CLAUDE.md, define el agente implementador:

markdown

# Rol: Desarrollador implementador

Eres responsable de escribir código limpio y con tests.
- Lee siempre el análisis en `/docs/impact-analysis.md` antes de implementar
- Escribe tests unitarios junto con cada función
- Usa los patrones que ya existen en el proyecto, no inventes nuevos
- **No modificas documentación ni archivos fuera de /src**

Paso 4: Lanza Claude Code y observa la orquestación

bash

cd tu-proyecto
claude

Luego escribe un prompt como:

Agrega una función que calcule el promedio de una lista de números.
Sigue el flujo de subagentes definido.

Claude Code leerá el CLAUDE.md raíz, entenderá su rol de orquestador, y delegará automáticamente: el analista documenta el impacto, el implementador lee ese análisis y escribe el código con tests.

⚠️ Errores comunes (y cómo evitarlos)

❌ Poner todo en un solo CLAUDE.md global Si metes todas las instrucciones en un archivo raíz, todos los subagentes heredan el mismo contexto y se pisan entre sí. Usa archivos CLAUDE.md por directorio para aislar responsabilidades.

❌ No delimitar qué archivos puede tocar cada agente Sin restricciones de scope, el agente implementador reescribirá tu documentación y viceversa. Siempre incluye una línea explícita como "No modifiques archivos fuera de /src". Claude respeta estas instrucciones de forma sorprendentemente consistente.

🔥 Tip extra: más allá del curso

El curso muestra subagentes para planificación de features, pero el patrón escala a algo más potente: pipelines de revisión de código automáticos.

Puedes tener un subagente revisor en /review/CLAUDE.md que solo lee PRs y genera comentarios en un archivo review-output.md, sin tocar nada más. Combinado con la integración de GitHub Actions que cubre el módulo 3 del curso, puedes hacer que ese revisor corra automáticamente en cada pull request — sin costo de tokens extra por contexto innecesario, porque cada agente solo carga lo que necesita.

bash

# Integración básica con GitHub Actions
claude --print "Revisa el diff adjunto según tu rol en CLAUDE.md" < diff.patch

Esto es lo que separa usar Claude Code como juguete de usarlo como infraestructura real de desarrollo.

📚 Recursos recomendados

• Documentación oficial de CLAUDE.md — cómo Claude lee y prioriza archivos de memoria
• Guía de prompt engineering para agentes — cómo escribir mejores instrucciones de rol
• Curso de Claude Code en Platzi — módulos 1 y 3 son los más relevantes para este flujo