Custom Subagents: crear agentes especializados a medida

Descripción

Los built-in subagents de Claude Code cubren patrones genéricos: explorar, planificar, ejecutar, correr comandos. Pero cada proyecto tiene tareas específicas que se repiten y que se beneficiarían de un agente dedicado. ¿Necesitas un agente que revise código contra los estándares de tu equipo? ¿Uno que genere documentación con tu formato? ¿Uno que escriba tests siguiendo tus convenciones exactas?

Para eso existen los custom subagents: agentes que tú defines con instrucciones específicas, herramientas permitidas, y restricciones claras. Los custom subagents viven en .claude/agents/ como archivos markdown, y Claude Code los usa cuando son relevantes para la tarea. Son la evolución natural de los skills — misma filosofía de especialización, pero con la capacidad completa de un agente independiente.

Esta cápsula te enseña a crear custom subagents desde cero: estructura del archivo, configuración de herramientas, definición de restricciones, y patterns para subagents de equipo. Al final, sabrás cuándo usar un skill y cuándo usar un custom subagent — y cómo crearlos de forma que sean mantenibles y útiles.

Qué son los custom subagents

Un custom subagent es un archivo markdown con YAML frontmatter en .claude/agents/ (u otro scope) que define un agente especializado. Cuando Claude Code detecta que un custom subagent es relevante para la tarea, o cuando lo invocas directamente, crea una instancia de agente con las instrucciones y restricciones que definiste.

El comando /agents — la forma recomendada de crearlos

En lugar de crear el archivo a mano, Claude Code ofrece /agents: una interfaz interactiva para gestionar subagents.

> /agents

Esto abre una interfaz con tabs:

• Running: subagents activos en la sesión actual
• Library: todos los subagents disponibles (built-in, user, project, plugin)

Desde Library puedes:

• Create new agent (con guiado o generado por Claude)
• Editar subagents existentes
• Ver qué subagent gana cuando hay duplicados
• Eliminar subagents custom

Recomendación: Usa /agents para crear tus primeros subagents. Cuando quieras editar manualmente el archivo, sabes qué contiene.

Comando CLI para listar subagents

Desde la terminal, sin iniciar Claude Code interactivo:

claude agents

Muestra todos los subagents agrupados por source (built-in, user, project, plugin) e indica cuáles están overridden por definiciones de mayor prioridad.

Scopes de subagents (dónde viven)

Reglas de resolución:

• Mismo nombre en múltiples scopes → gana el de mayor prioridad
• .claude/agents/ se descubre caminando hacia arriba desde tu directorio actual (funciona en monorepos)
• --add-dir NO agrega subagents (solo grants file access)

Subagents inline via CLI (--agents flag)

Para testing rápido o automatización, puedes definir subagents inline como JSON al lanzar Claude Code:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

Útil para scripts de CI/CD donde no quieres committear un subagent pero sí usar uno específico.

YAML Frontmatter: el formato actual de subagents

Los custom subagents usan el mismo formato que los Skills: YAML frontmatter + contenido markdown.

---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes to catch issues.
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: sonnet
color: purple
memory: project
---

You are a senior code reviewer specialized in this codebase.

Your role: review changes and provide actionable feedback.

## Rules
- Focus on: correctness, performance, maintainability, security
- Don't make changes — only report findings
- Classify each finding: critical, warning, suggestion
- Reference exact file:line

## Project conventions
- TypeScript strict (no `any`)
- Pure functions when possible
- Explicit error handling

## Output format
For each finding:
- **[TYPE]** file:line — Problem description
- Suggestion

Campos principales del frontmatter

Memoria persistente de subagents

Un feature importante: los subagents pueden tener memoria persistente entre sesiones.

Con memory: project, el subagent acumula insights en .claude/agent-memory/<nombre>/ — cada vez que el subagent corre, agrega al directorio.

Con memory: user, la memoria vive en ~/.claude/agent-memory/ — persiste entre todos tus proyectos.

Caso de uso típico: Un code-reviewer que aprende patrones problemáticos recurrentes del equipo y los recuerda en próximas reviews. Un debugger que acumula errores comunes del proyecto.

---
name: code-reviewer
description: Code reviewer with memory of recurring patterns
memory: project
---

Después de varias reviews, el directorio .claude/agent-memory/code-reviewer/ tiene archivos con insights acumulados, que el subagent lee al empezar.

initialPrompt — auto-submit del primer turn (marzo 2026)

Feature reciente: en el frontmatter del subagent puedes declarar un initialPrompt que se auto-submita como el primer mensaje apenas el subagent arranca. Útil cuando el subagent siempre necesita hacer lo mismo al inicio.

Ejemplo: subagent security-scanner que siempre arranca escaneando:

---
name: security-scanner
description: Scans code for security vulnerabilities
tools: [Read, Grep, Glob]
model: sonnet
initialPrompt: |
  Escanea el codebase en busca de:
  1. Hardcoded secrets (API keys, tokens, passwords)
  2. SQL injection vulnerabilities
  3. XSS vectors en templates
  4. Dependencias con CVEs conocidos

  Para cada hallazgo: archivo, línea, severidad (critical/high/medium/low), y sugerencia de fix.
---

Eres un security scanner especializado en aplicaciones web.
Tu rol: encontrar problemas de seguridad, no crearlos.

Reglas:
- Nunca modifiques código, solo reporta
- Clasifica cada finding por severidad
- Incluye CVE IDs cuando apliquen
- Prioriza por impacto real, no solo teórico

Al invocar este subagent con /agents o via delegación, Claude Code ejecuta automáticamente el initialPrompt como primera instrucción — el subagent arranca ya trabajando, sin que tú tengas que darle la primera orden.

Útil cuando:

• El subagent siempre hace lo mismo al iniciar
• Quieres reducir fricción de delegation
• El "prompt inicial" es parte del contrato del subagent

Dónde viven

your-project/
├── .claude/
│   ├── agents/
│   │   ├── code-reviewer.md
│   │   ├── test-writer.md
│   │   ├── doc-generator.md
│   │   └── migration-agent.md
│   ├── skills/
│   │   ├── create-component.md
│   │   └── write-test.md
│   ├── settings.json
│   └── settings.local.json
├── CLAUDE.md
├── src/
└── ...

La estructura es similar a los skills: archivos markdown en un directorio específico. La diferencia clave es el directorio (.claude/agents/ vs .claude/skills/) y la naturaleza del contenido.

Cómo se invocan

Los custom subagents se pueden invocar de varias formas:

1. Directamente: Claude Code los detecta como agentes disponibles
2. Por nombre: Puedes referirte a ellos en tu prompt
3. Automáticamente: Si Claude Code detecta que la tarea coincide con el propósito del subagent

Tú: Usa el code-reviewer agent para revisar los cambios 
    que acabo de hacer.

Tú: Necesito documentar el módulo de pagos. Usa el 
    doc-generator.

Estructura de un custom subagent

Un custom subagent es un archivo markdown con secciones que definen su comportamiento. La estructura es flexible, pero estos son los elementos clave:

Estructura básica

# Code Reviewer

Eres un agente especializado en revisión de código para 
este proyecto.

## Tu rol
Revisas código contra los estándares del proyecto y 
proporcionas feedback actionable.

## Reglas
- Enfócate en: correctitud, performance, mantenibilidad
- NO hagas cambios al código — solo reporta hallazgos
- Clasifica cada hallazgo: critical, warning, suggestion
- Referencia la línea y archivo exactos

## Convenciones del proyecto
- TypeScript estricto (no usar any)
- Funciones puras cuando sea posible
- Error handling explícito (no swallow errors)
- Tests para toda lógica de negocio

## Formato de output
Para cada hallazgo, usa:
- **[TIPO]** archivo:línea — Descripción del problema
- Sugerencia de fix

Elementos de configuración

Nombre y propósito

El nombre del archivo define la identidad del subagent. Claude Code lo usa para decidir cuándo activarlo:

Best practice: Usa nombres descriptivos que reflejen el propósito. Claude Code usa el nombre para determinar relevancia.

Instrucciones (el core del subagent)

Las instrucciones definen qué hace el subagent y cómo. Escríbelas como si le explicaras a un developer nuevo exactamente cómo hacer la tarea:

## Instrucciones

Cuando te pidan escribir tests:

1. Lee el archivo que se va a testear
2. Identifica todas las funciones exportadas
3. Para cada función:
   a. Determina los inputs válidos e inválidos
   b. Identifica edge cases (null, undefined, empty, overflow)
   c. Escribe tests que cubran el happy path y al menos 2 edge cases
4. Usa el pattern describe/it con nombres descriptivos
5. Usa factories para datos de prueba (ver __tests__/factories/)
6. Nunca mockees la base de datos — usa el test database

Restricciones (lo que NO debe hacer)

Las restricciones son tan importantes como las instrucciones. Definen los límites del subagent:

## Restricciones

- NO modifiques archivos de producción (solo archivos de test)
- NO cambies la configuración de Vitest
- NO agregues dependencias nuevas sin listarlas en el reporte
- NO generes tests para funciones privadas (no exportadas)
- NO uses snapshots — preferimos assertions explícitas

Contexto del proyecto

Puedes incluir información relevante que el subagent necesita:

## Contexto del proyecto

- Framework de tests: Vitest
- Base de datos de test: SQLite in-memory
- Factories: en __tests__/factories/ usando factory pattern
- Fixtures: en __tests__/fixtures/ para datos estáticos
- Coverage mínimo: 80% branches
- CI ejecuta: vitest run --coverage

Ejemplos de custom subagents

Ejemplo 1: Code Reviewer Agent

# Code Reviewer

Eres un revisor de código especializado para este proyecto.

## Tu rol

Revisas pull requests y cambios de código contra los estándares 
del proyecto. Tu output es un reporte de revisión, no cambios 
al código.

## Qué revisar

### Correctitud
- ¿La lógica es correcta?
- ¿Se manejan todos los edge cases?
- ¿Hay race conditions o problemas de concurrencia?

### TypeScript
- ¿Se usa `any`? (prohibido en este proyecto)
- ¿Las interfaces están bien tipadas?
- ¿Se usan type guards donde aplica?

### Error handling
- ¿Se capturan los errores correctamente?
- ¿Se usan custom error classes del proyecto?
- ¿Los errores se logean antes de re-throw?

### Performance
- ¿Hay queries N+1?
- ¿Se usa paginación en queries que podrían retornar muchos resultados?
- ¿Hay computaciones costosas que deberían estar en caché?

### Tests
- ¿Los cambios tienen tests correspondientes?
- ¿Los tests cubren edge cases?

## Formato del reporte

Code Review Report

Critical (bloquea merge)

• [CRITICAL] archivo:línea — descripción Sugerencia: ...

Warnings (debería arreglarse)

• [WARNING] archivo:línea — descripción Sugerencia: ...

Suggestions (nice to have)

• [SUGGESTION] archivo:línea — descripción Sugerencia: ...

Veredicto

APPROVED / CHANGES_REQUESTED / NEEDS_DISCUSSION

## Restricciones

- NO modifiques ningún archivo
- NO ejecutes comandos
- Solo lee y analiza
- Si no entiendes algo, menciónalo en vez de asumirlo

Ejemplo 2: Test Writer Agent

# Test Writer

Eres un agente especializado en escribir tests para este proyecto.

## Tu rol

Generas tests unitarios y de integración siguiendo las 
convenciones exactas del proyecto. No implementas features — 
solo escribes tests.

## Convenciones de testing

### Estructura de archivos
- Tests unitarios: coubicados con el módulo en `__tests__/[name].test.ts`
- Tests de integración: en `__tests__/integration/[name].integration.test.ts`
- Factories: en `__tests__/factories/[entity].factory.ts`

### Naming
- `describe('ClassName')` o `describe('functionName')`
- `it('should [comportamiento esperado] when [condición]')`
- Ejemplo: `it('should return null when user is not found')`

### Patterns
- Usa Vitest: describe, it, expect, vi (para mocks)
- Arrange-Act-Assert en cada test
- Factories para crear datos de prueba (nunca hardcodear datos)
- Tests independientes: cada test debe poder correr solo
- No compartir estado mutable entre tests

### Base de datos
- Tests unitarios: mockear el repository layer
- Tests de integración: usar SQLite in-memory
- Siempre limpiar la BD entre tests (beforeEach → truncate)

## Proceso

1. Lee el archivo a testear
2. Identifica todas las funciones/métodos públicos
3. Para cada uno, genera:
   - Happy path test
   - Al menos 2 edge cases
   - Error cases (qué pasa cuando falla)
4. Si hay factory existente para la entidad, úsala
5. Si no hay factory, créala en __tests__/factories/
6. Ejecuta los tests para verificar que pasan

## Restricciones

- NO modifiques archivos de producción
- NO cambies tests existentes (solo agrega nuevos)
- NO uses snapshot testing
- NO importes desde paths absolutos (usa aliases @ del proyecto)
- Si un test falla, reporta el error — no lo fixes silenciosamente

Ejemplo 3: Documentation Agent

# Documentation Generator

Eres un agente especializado en generar documentación técnica 
para este proyecto.

## Tu rol

Generas y actualizas documentación técnica: README de módulos, 
JSDoc/TSDoc, y guías de uso. La documentación debe ser útil 
para developers que se unen al equipo.

## Tipos de documentación

### README de módulo
Para cada directorio principal en src/, genera un README.md con:
- Propósito del módulo (1-2 párrafos)
- Estructura de archivos
- Interfaces principales (con ejemplos de uso)
- Dependencias con otros módulos

### TSDoc para funciones exportadas
```typescript
/**
 * Brief description of what the function does.
 *
 * @param paramName - Description of the parameter
 * @returns Description of return value
 * @throws {ErrorType} When this error can occur
 *
 * @example
 * ```typescript
 * const result = functionName(input);
 * ```
 */

Guías de uso

Para features complejas, genera una guía con:

• Qué problema resuelve
• Cómo usarla (code examples)
• Configuración necesaria
• Troubleshooting común

Convenciones

• Español para README y guías
• Inglés para TSDoc (estándar de la industria)
• Ejemplos de código siempre ejecutables (no pseudocódigo)
• Máximo 200 líneas por documento
• Sin emojis en documentación técnica

Restricciones

• NO modifiques código de producción
• NO generes documentación para archivos de test
• NO documentes funciones internas (no exportadas)
• Verifica que los ejemplos de código compilan

### Ejemplo 4: Migration Agent

Un agente para migraciones de base de datos con Knex. Incluye: proceso de migración (analizar → generar archivo con `up`/`down` → verificar rollback → ejecutar en test DB → confirmar tests), convenciones de naming (`YYYYMMDD_HHMMSS_descripcion.ts`), y restricciones (no producción, no DROP sin confirmación, no modificar migraciones ejecutadas). El mismo pattern que los anteriores: rol + proceso + convenciones + restricciones.

---

## Skill vs Subagent: cuándo usar cada uno

Esta es la decisión más importante de este módulo. Skills y subagents se complementan pero no son intercambiables.

### Comparación directa

| Criterio | Skill | Custom Subagent |
|---|---|---|
| **Qué es** | Instrucciones en markdown | Agente completo con contexto propio |
| **Ubicación** | `.claude/skills/` | `.claude/agents/` |
| **Cómo se invoca** | `/nombre` (slash command) | Por nombre o automáticamente |
| **Context** | Comparte el context del parent | Context propio aislado |
| **Razonamiento** | Sigue instrucciones paso a paso | Razona, decide, ejecuta |
| **Complejidad ideal** | Tareas de 5-15 pasos | Tareas que requieren análisis + decisión |
| **Ejemplo** | "Crea un componente con estos 7 pasos" | "Revisa el código y dame un reporte" |

### Árbol de decisión

¿La tarea tiene pasos fijos y predecibles? ├── SÍ → ¿Necesita razonamiento para decidir qué hacer? │ ├── NO → SKILL (instrucciones directas) │ └── SÍ → CUSTOM SUBAGENT (agente que razona) └── NO → CUSTOM SUBAGENT (necesita flexibilidad)

Ejemplos:

• "Crea componente React con CSS Modules" → SKILL (pasos fijos: crear archivo, crear estilos, crear test, barrel export)

• "Revisa este PR contra nuestros estándares" → SUBAGENT (necesita analizar, razonar, clasificar hallazgos)

• "Genera documentación para este módulo" → SUBAGENT (necesita entender el código para documentarlo)

• "Agrega un nuevo comando CLI con boilerplate" → SKILL (pasos fijos: crear archivo, registrar comando, crear test)

### Cuándo migrar un skill a subagent

Señales de que un skill necesita ser un subagent:

1. **El skill requiere decisiones:** "Si el archivo ya existe, actualízalo. Si no, créalo." — esto requiere razonamiento, no solo pasos.
2. **El output es variable:** Un skill que siempre produce lo mismo puede ser skill. Si el output depende del análisis, necesita subagent.
3. **Necesita leer mucho contexto:** Si el skill necesita analizar 10+ archivos antes de actuar, un subagent con context aislado es más eficiente.
4. **Tiene lógica condicional compleja:** "Si es un modelo Sequelize, haz X. Si es TypeORM, haz Y. Si es Prisma, haz Z." — un subagent maneja mejor esta complejidad.

### Cuándo NO crear un subagent

- La tarea se resuelve con un hook (automatización simple)
- La tarea es una instrucción lineal sin decisiones
- No se va a reutilizar (es una tarea one-off)
- Ya existe un built-in subagent que hace lo mismo

---

## Best practices para custom subagents

### 1. Single responsibility

Cada subagent debe tener un propósito claro y acotado. No crees un subagent que "revisa código, genera documentación, y escribe tests" — crea tres subagents separados.

❌ all-in-one-agent.md (hace todo) ✅ code-reviewer.md (solo revisa código) ✅ test-writer.md (solo escribe tests) ✅ doc-generator.md (solo genera documentación)

### 2. Restricciones explícitas

Define siempre qué NO debe hacer el subagent. Las restricciones son más importantes que las instrucciones porque previenen daños:

```markdown
## Restricciones
- NO modifiques archivos de producción
- NO ejecutes comandos destructivos (rm, DROP)
- NO instales dependencias sin listarlas primero
- NO ignores errores silenciosamente

3. Contexto de proyecto incluido

No asumas que el subagent sabe cómo funciona tu proyecto. Incluye la información necesaria directamente en el archivo:

## Contexto del proyecto
- Framework: Next.js 14 con App Router
- ORM: Prisma con PostgreSQL
- Tests: Vitest + Testing Library
- Estilo: Tailwind CSS
- Linting: ESLint + Prettier

4. Formato de output definido

Define exactamente cómo quieres el output del subagent. Esto hace los resultados consistentes y predecibles:

## Formato de output

### Para cada issue encontrado:
**[SEVERITY]** `archivo:línea`
> Descripción del issue
> 
> Sugerencia: [cómo arreglarlo]

### Al final del reporte:
- Total de issues: N
- Critical: N | Warning: N | Suggestion: N
- Veredicto: PASS / FAIL

5. Testea con tareas simples primero

Antes de confiar en un custom subagent para tareas críticas, pruébalo con algo simple:

Tú: Usa el code-reviewer agent para revisar el archivo 
    src/utils/format.ts. Es un archivo pequeño — quiero 
    ver si el agente sigue las convenciones que definí.

Si el output no coincide con lo esperado, ajusta las instrucciones del subagent.

Patterns comunes

Pattern 1: Review antes de merge

Crea un code-reviewer.md y úsalo antes de cada PR:

Tú: Revisa los archivos que modifiqué en esta sesión 
    usando el code-reviewer agent. Dame el reporte 
    antes de hacer commit.

Pattern 2: Documentación post-implementación

Después de implementar una feature, genera documentación automáticamente:

Tú: Acabo de implementar el módulo de notificaciones.
    Usa el doc-generator agent para documentar las 
    interfaces públicas y crear el README del módulo.

Pattern 3: Tests en paralelo con implementación

Mientras implementas, un subagent puede escribir tests:

Tú: Implementa el servicio de pagos. En paralelo, que 
    el test-writer agent genere los tests basándose en 
    la interfaz que estoy definiendo.

Pattern 4: Chaining de subagents

El output de un subagent alimenta al siguiente:

Paso 1:
Tú: Usa el code-reviewer agent para analizar el módulo 
    de autenticación.

[Claude Code obtiene el reporte]

Paso 2:
Tú: Basándote en los issues critical del reporte, 
    arregla los problemas encontrados.

Paso 3:
Tú: Ahora usa el test-writer agent para agregar tests 
    que cubran los edge cases que el reviewer identificó.

Este chain — review → fix → test — es un pipeline de calidad completo operado por subagents.

Pattern 5: Subagent de onboarding

Para proyectos de equipo, crea un subagent que ayude a nuevos miembros a entender el codebase. Un onboarding-guide.md que cubre: arquitectura general, cómo agregar features, cómo ejecutar tests, convenciones, y dependencias principales. Respuestas concisas con referencias a archivos concretos.

Pitfalls y edge cases

Pitfall 1: Subagent demasiado genérico

Un subagent que dice "ayuda con todo" no es más útil que el agente principal. La especificidad es lo que hace valiosos a los subagents:

❌ general-helper.md → "Ayuda con cualquier tarea del proyecto"
✅ code-reviewer.md → "Revisa código contra estándares específicos"

Pitfall 2: Instrucciones contradictorias con CLAUDE.md

Si tu CLAUDE.md dice "usa CSS Modules" pero tu subagent dice "usa styled-components", hay un conflicto. Mantén la consistencia:

❌ CLAUDE.md: "CSS Modules" + subagent: "styled-components"
✅ CLAUDE.md: "CSS Modules" + subagent: "Al crear estilos, 
   sigue la convención de CSS Modules del proyecto"

Regla: Los subagents deben referenciar y respetar CLAUDE.md, no contradecirlo.

Pitfall 3: Subagents sin restricciones

Un subagent sin restricciones puede hacer cosas inesperadas. Siempre define qué NO debe hacer:

❌ Solo instrucciones de qué hacer
✅ Instrucciones + restricciones claras

Pitfall 4: Demasiados subagents

Más subagents no es mejor. Si tienes 15 subagents, Claude Code no sabrá cuándo usar cada uno:

❌ 15 subagents híper-específicos
✅ 3-5 subagents bien definidos y diferenciados

Regla: Empieza con 2-3 subagents que cubran tus tareas más repetitivas. Agrega más solo cuando tengas una necesidad clara.

Pitfall 5: No testear el subagent

Crear un subagent y asumir que funciona es un error común. Pruébalo con un caso simple donde conozcas el resultado esperado, un edge case para verificar restricciones, y un caso real para validar utilidad.

Edge case: Subagent que contradice al usuario

Si el usuario pide algo que viola las restricciones del subagent, el subagent debe reportar el conflicto — no violar sus restricciones silenciosamente.

Edge case: Múltiples subagents aplicables

Si tienes code-reviewer.md y security-auditor.md, y la tarea es "revisa la seguridad del código", Claude Code puede elegir uno o usar ambos. Haz que los nombres y propósitos sean claramente distintos para evitar ambigüedad.

Ejemplo completo integrado

Escenario: Configurar un pipeline de calidad con custom subagents

Vas a crear 3 custom subagents para un proyecto Node.js/TypeScript que, usados en secuencia, forman un pipeline de calidad.

Paso 1: Crear los 3 subagents

Crea los siguientes archivos en .claude/agents/:

code-reviewer.md — Revisa código TypeScript contra estándares del proyecto (TypeScript estricto, funciones < 30 líneas, archivos < 300 líneas, error handling explícito). Output con hallazgos clasificados como CRITICAL/WARNING/OK. Read-only.

test-writer.md — Escribe tests con Vitest. Convenciones: archivos coubicados, pattern describe/it/Arrange-Act-Assert, factories en __tests__/factories/. Para cada función: happy path + 2 edge cases + 1 error case. No modifica producción, no usa snapshots.

doc-generator.md — Genera documentación técnica en español. README de módulo (máx 150 líneas con diagrama y ejemplo real), TSDoc en inglés para funciones exportadas. No documenta funciones internas ni tests.

Paso 4: Usar el pipeline

Sesión 1 — Implementas una feature nueva:
Tú: Implementa el endpoint de búsqueda de productos.

Sesión 2 — Review:
Tú: Usa el code-reviewer agent para revisar los archivos 
    que creé para la búsqueda de productos.
[Reporte: 2 warnings, 1 suggestion]

Tú: Arregla los warnings del reporte.

Sesión 3 — Tests:
Tú: Usa el test-writer agent para generar tests del 
    módulo de búsqueda de productos.
[Tests generados: 12 tests, 100% passing]

Sesión 4 — Documentación:
Tú: Usa el doc-generator agent para documentar el 
    módulo de búsqueda de productos.
[README generado + TSDoc agregado]

Pipeline completo: implementar → revisar → testear → documentar. Cada paso con un agente especializado.

Ejercicios prácticos

Ejercicio 1: Crear tu primer custom subagent

Crea un subagent en .claude/agents/code-reviewer.md adaptado a tu proyecto. Incluye:

1. Nombre y rol
2. Al menos 5 estándares específicos de tu proyecto
3. Formato de output definido
4. Al menos 3 restricciones

Pruébalo con un archivo existente de tu proyecto.

Tú: Usa el code-reviewer agent para revisar src/services/user.ts

Resultado esperado: un reporte con hallazgos clasificados 
por severidad, siguiendo el formato que definiste.

Ejercicio 2: Skill vs Subagent — decide correctamente

Para cada tarea, decide si necesitas un skill o un custom subagent y justifica:

1. Crear un nuevo endpoint REST con boilerplate estándar
2. Revisar un PR contra las convenciones del equipo
3. Generar un componente React con tests y estilos
4. Analizar la deuda técnica de un módulo
5. Agregar logging a todas las funciones de un servicio
6. Generar el changelog para un release

Ejercicio 3: Crear un test-writer subagent

Crea .claude/agents/test-writer.md para tu proyecto. Asegúrate de incluir:

1. Tu framework de testing (Vitest, Jest, Mocha, etc.)
2. Tus convenciones de naming
3. Dónde viven los tests en tu proyecto
4. Cómo manejas datos de prueba (factories, fixtures, etc.)

Pruébalo: pídele que genere tests para un archivo existente.

Ejercicio 4: Pipeline de 3 subagents

Si completaste los ejercicios 1 y 3, ya tienes un code-reviewer y un test-writer. Crea un doc-generator y ejecuta el pipeline completo en una feature de tu proyecto:

1. Implementa un cambio pequeño
2. Usa code-reviewer → analiza el resultado
3. Usa test-writer → verifica los tests
4. Usa doc-generator → verifica la documentación

Ejercicio 5: Subagent de equipo

Piensa en tu equipo (real o hipotético). ¿Qué tarea repetitiva se beneficiaría de un subagent compartido? Créalo y documenta:

1. Qué problema resuelve
2. Por qué un subagent y no un skill
3. Cómo lo usaría un compañero que nunca lo ha visto

Resumen

Los custom subagents son tu herramienta para crear agentes especializados que entienden tu proyecto y tus convenciones. A diferencia de los skills (instrucciones paso a paso), los subagents razonan, analizan, y toman decisiones.

Lo que aprendiste en esta cápsula:

• Los custom subagents viven en .claude/agents/ como archivos markdown
• Cada subagent tiene: nombre, instrucciones, contexto, formato de output, y restricciones
• Skill = pasos fijos y predecibles. Subagent = razonamiento y análisis
• Los subagents deben ser: focused (single responsibility), restringidos (qué NO hacer), testeados (verificar output)
• Los subagents se pueden encadenar para crear pipelines de calidad
• Empieza con 2-3 subagents y agrega más solo cuando haya necesidad clara
• Las restricciones son tan importantes como las instrucciones

Siguiente cápsula: 04 - Plugin Marketplace — cómo instalar capacidades pre-construidas (skills, hooks, subagents, MCP) desde el marketplace oficial de Anthropic con el comando /plugin.

Recursos adicionales

Documentación oficial

• Sub-agents — Tipos, configuración y creación de subagents
• Plugins Reference — Skills, agents, hooks: referencia completa
• Best Practices — Cómo organizar skills y agents

Skills vs Subagents

• Memory — Cómo CLAUDE.md interactúa con subagents
• CLI Reference — Slash commands y modos

Patterns de agentes

• Claude Code Overview — Arquitectura y modelo de agentes
• Settings — Configuración de permisos para agents