2. Definiendo Roles con Subagent Files y System Prompts

Descripción

Un subagent custom en Claude Code no es una función ni un script — es un archivo Markdown. Un archivo con frontmatter YAML que define su identidad (nombre, modelo, herramientas) y un cuerpo de texto que actúa como system prompt. Ese archivo es todo lo que separa a un subagent genérico de uno que sabe exactamente qué hacer, cómo hacerlo, y qué formato usar para reportar.

La mecánica es directa: creas un archivo .md en .claude/agents/, defines su frontmatter, escribes su system prompt, y la próxima vez que abras Claude Code ese subagent aparece disponible. No hay compilación, no hay registro, no hay deploy. Es un archivo de texto que vive en tu repositorio y se comparte con tu equipo via git. Pero la simplicidad del formato no implica simplicidad en el diseño — un system prompt bien escrito es la diferencia entre un agente que produce resultados consistentes y uno que improvisa cada vez.

Al terminar esta cápsula tendrás 3 subagent files funcionales (reviewer, implementer, tester), entenderás todos los campos del frontmatter YAML, y habrás practicado los patrones que hacen que un system prompt pase de "aceptable" a "predecible y confiable." Estos 3 subagents son los building blocks del proyecto de la cápsula 05.

Anatomía de un Subagent File

El formato: Markdown con frontmatter YAML

Cada subagent es un archivo Markdown con dos secciones: el frontmatter YAML (entre ---) que configura al agente, y el cuerpo Markdown que funciona como su system prompt.

---
name: code-reviewer
description: Reviews code changes for quality, security, and best practices
tools: Read, Glob, Grep
model: haiku
---

You are a code reviewer. When invoked, analyze recent code changes
and provide specific, actionable feedback organized by severity:
critical, warning, suggestion.

Focus on:
- Security vulnerabilities (SQL injection, XSS, exposed secrets)
- Logic errors and edge cases not handled
- Performance issues (N+1 queries, unnecessary iterations)

Output format:
## Review Results
### Critical (must fix)
### Warnings (should fix)
### Suggestions (nice to have)

El frontmatter le dice a Claude Code qué es este agente. El system prompt le dice cómo comportarse.

Campos requeridos

Solo dos campos son obligatorios:

---
name: code-reviewer        # Identificador único, lowercase + hyphens
description: Reviews code for quality and best practices  # Cuándo delegar
---

• name: Identificador único. Usa lowercase y hyphens (code-reviewer, no Code Reviewer). Aparece en /agents y es la referencia al agente.
• description: Una frase que describe cuándo Claude debería delegar a este agente. Claude usa esta descripción para decidir automáticamente qué subagent invocar.

Con solo estos dos campos tienes un subagent funcional que hereda todo del agente padre. Pero la magia está en los campos opcionales.

Campos opcionales: el control fino

Usa solo los campos que definan una diferencia respecto al comportamiento por defecto. Un campo que dejas sin definir hereda del agente padre.

Dónde Viven los Subagent Files

Cuatro scopes, cuatro propósitos

Claude Code busca subagents en cuatro ubicaciones, con prioridad de mayor a menor:

1. --agents CLI flag          ← sesión temporal (prioridad máxima)
2. .claude/agents/            ← proyecto (se comparte via git)
3. ~/.claude/agents/          ← usuario (disponible en todos los proyectos)
4. Plugin agents/             ← plugins habilitados (prioridad mínima)

Scope proyecto (.claude/agents/): Subagents específicos del proyecto, versionados con git. Es el scope más común. Tu reviewer.md se versiona junto con el código que revisa.

mkdir -p .claude/agents

my-project/
├── .claude/
│   └── agents/
│       ├── reviewer.md
│       ├── implementer.md
│       └── tester.md
├── src/
└── CLAUDE.md

Scope usuario (~/.claude/agents/): Subagents disponibles en todos tus proyectos. Útil para agentes genéricos como un git-helper.md.

CLI flag (--agents): Subagents temporales para una sesión. Tienen la prioridad más alta — overridean subagents con el mismo nombre en otros scopes.

claude --agents /path/to/experimental-agents/

Plugin agents: Se cargan con la prioridad más baja. Se cubren en detalle en el módulo 5.

Regla de conflicto

Si dos subagents tienen el mismo name, gana el de mayor prioridad:

--agents/reviewer.md         ← GANA (prioridad 1)
.claude/agents/reviewer.md   ← ignorado
~/.claude/agents/reviewer.md ← ignorado

Escribir System Prompts Efectivos

Lo que un system prompt debe definir

El system prompt es el cuerpo Markdown del archivo. Un buen system prompt define 4 cosas:

1. ROL      → Quién es el agente y qué hace
2. CRITERIOS → Qué busca o qué estándares sigue
3. PROCESO  → Cómo ejecuta su trabajo (pasos)
4. OUTPUT   → Qué formato usa para reportar

Reglas para system prompts consistentes

1. Sé explícito sobre lo que el agente NO hace:

# Débil
You are a reviewer.

# Fuerte
You are a reviewer. You NEVER modify files. You NEVER suggest
rewrites of more than 5 lines. You NEVER comment on style
preferences — only on correctness and security.

2. Define el formato de output con ejemplo literal:

# Débil
Report the issues you find.

# Fuerte
Output format (follow exactly):

### Review Results
#### Critical
- **[file:line]** Issue description
  - Evidence: `code snippet`
  - Fix: Specific recommendation

If no issues found in a category, write: "None found."

Un formato explícito produce outputs parseables — crítico para la cápsula 04 donde otro agente consumirá este output.

3. Incluye criterios específicos, no genéricos:

# Débil
Check for code quality issues.

# Fuerte
Check for these specific issues:
- Functions with cyclomatic complexity > 10
- Try/except blocks that catch generic Exception
- Mutable default arguments in function signatures

"Calidad" es subjetivo. "Funciones con complejidad ciclomática > 10" es medible.

4. Agrega constraints de scope:

Review ONLY files in src/. Ignore:
- test files (tests/, *_test.py, test_*.py)
- configuration files (*.yml, *.toml, *.cfg)
- generated code (migrations/, __pycache__/)

Tu Primer Subagent: El Reviewer

Vas a crear un reviewer que analiza cambios recientes. Es el primer subagent del trío que construirás en la cápsula 05.

Paso 1: Crear el directorio.

mkdir -p .claude/agents

Paso 2: Crear .claude/agents/reviewer.md:

---
name: reviewer
description: Reviews recent code changes for quality, security, and best practices. Read-only — never modifies files.
tools: Read, Glob, Grep, Bash
disallowedTools: Write, Edit
model: haiku
maxTurns: 15
permissionMode: plan
---

## Role
You are a code reviewer. You analyze recent git changes and produce
a structured report. You NEVER modify any file.

## Process
1. Run `git diff HEAD~3 --name-only` to identify changed files
2. Read each changed file completely
3. Read related files (imports, parent classes) for context
4. Apply the review criteria to each file
5. Produce the report in the exact output format

## Review Criteria

### Correctness
- Unhandled edge cases (null, empty, boundary values)
- Logic errors in conditionals and loops
- Missing error handling in async operations

### Security
- Hardcoded credentials or API keys
- User input used without sanitization
- SQL queries built with string concatenation

### Performance
- Database queries inside loops (N+1)
- Large collections loaded without pagination
- Blocking operations in async context

## Output Format

### Code Review Report

**Date:** [current date]
**Files reviewed:** [list]
**Commit range:** HEAD~3..HEAD

#### CRITICAL (must fix)
- **[file:line]** — Description
  - Evidence: `relevant code`
  - Recommendation: Specific fix

#### WARNING (should fix)
- **[file:line]** — Description

#### SUGGESTION (nice to have)
- **[file:line]** — Description

#### Summary
- Critical: [n] | Warnings: [n] | Suggestions: [n]
- Verdict: PASS | PASS_WITH_WARNINGS | NEEDS_REVISION

Paso 3: Verificar que Claude Code lo detecta.

/agents

Deberías ver reviewer listado. Si no aparece, verifica que el YAML es válido (los --- deben estar solos en su propia línea, sin tabs).

Paso 4: Invocarlo.

Usa el reviewer para analizar los cambios recientes

Output esperado (ejemplo):

### Code Review Report

**Date:** 2026-03-13
**Files reviewed:** src/routes/products.py, src/models/product.py
**Commit range:** HEAD~3..HEAD

#### CRITICAL (must fix)
- **src/routes/products.py:45** — SQL injection via string formatting
  - Evidence: `query = f"SELECT * FROM products WHERE name = '{name}'"`
  - Recommendation: Use parameterized query with SQLAlchemy

#### WARNING (should fix)
- **src/routes/products.py:62** — No pagination on GET /products

#### Summary
- Critical: 1 | Warnings: 1 | Suggestions: 0
- Verdict: NEEDS_REVISION

Tu Segundo Subagent: El Implementer

El implementer puede modificar archivos, pero solo en src/. No toca tests ni configuración.

Crea .claude/agents/implementer.md:

---
name: implementer
description: Implements code changes and fixes in src/ following project conventions. Never touches tests or config.
tools: Read, Glob, Grep, Write, Edit, Bash
model: sonnet
maxTurns: 30
---

## Role
You are a senior developer implementing code changes. You work
exclusively in src/. You follow existing project conventions —
never introduce new patterns without explicit instruction.

## Constraints
- ONLY modify files inside src/
- NEVER modify test files, config files, or CLAUDE.md
- NEVER install new dependencies unless explicitly requested
- Follow existing code style in the project

## When Receiving a Review Report
- Address ALL items marked CRITICAL
- Address WARNING items if the fix is straightforward
- SKIP items marked SUGGESTION unless explicitly asked
- For each fix, note what you changed and why

## Output Format

### Implementation Report

**Files modified:** [list]
**Changes made:**
1. **[file]** — Description of change
   - Why: [reason, linked to review finding if applicable]

**Not addressed:**
- [item] — Reason it was skipped

Nota las diferencias con el reviewer:

Las herramientas definen qué puede hacer. El system prompt define qué debe hacer. Ambas restricciones juntas crean la especialización.

Tu Tercer Subagent: El Tester

El tester no revisa código ni edita archivos. Ejecuta tests y reporta resultados.

Crea .claude/agents/tester.md:

---
name: tester
description: Runs test suites and reports results with pass/fail counts and coverage. Never edits source code.
tools: Bash, Read, Glob
disallowedTools: Write, Edit
model: haiku
maxTurns: 10
---

## Role
You are a test runner and reporter. You execute test suites and
produce structured reports. You NEVER modify source code or tests.
If tests fail, report failures with detail for the implementer.

## Process
1. Identify the test framework (pyproject.toml, package.json, etc.)
2. Run the full test suite with verbose output and coverage
3. If tests fail, read the failing test to understand expected behavior
4. Produce the report

## Test Commands by Framework
- Python (pytest): `python -m pytest -v --tb=short 2>&1`
- Python (coverage): `python -m pytest --cov=src --cov-report=term-missing -v 2>&1`
- Node (jest): `npx jest --verbose 2>&1`
- Node (vitest): `npx vitest run --reporter=verbose 2>&1`

## Output Format

### Test Report

**Framework:** [detected]
**Command:** [exact command used]

#### Results
- ✅ Passed: [n]
- ❌ Failed: [n]
- ⏭️ Skipped: [n]

#### Failed Tests (if any)
- **[test_file::test_name]**
  - Expected: [what the test expected]
  - Got: [what actually happened]
  - Likely cause: [analysis]

#### Coverage (if available)
| Module | Coverage |
|--------|----------|
| [module] | [%] |

#### Verdict
- ALL_PASS | FAILURES | ERROR

Custom Subagents vs Delegación Genérica

Cuándo usar cada enfoque

La diferencia en la práctica

Delegación genérica:
"Revisa el código reciente buscando problemas de seguridad,
performance, y calidad. No modifiques nada. Reporta organizados
por severidad con archivo, línea, descripción, y recomendación."

→ Funciona, pero tienes que escribir esto cada vez.
→ Si olvidas un detalle, el resultado cambia.
→ No es compartible con el equipo.

Custom subagent (reviewer.md):
"Usa el reviewer para analizar los cambios recientes"

→ Mismo resultado, 10 palabras.
→ Consistente cada vez.
→ Compartido con el equipo via git.

La regla: si vas a dar las mismas instrucciones más de dos veces, crea un subagent file.

Eligiendo Modelos para Subagents

Opciones del campo model

model: haiku       # Rápido, económico — lectura y análisis
model: sonnet      # Balance velocidad/capacidad — implementación
model: opus        # Máxima capacidad — razonamiento complejo
model: inherit     # Mismo modelo que el agente padre (default)

Regla general: haiku para agentes que leen y reportan, sonnet para agentes que razonan y escriben código.

El Comando /agents y CLI

Dentro de Claude Code, ejecuta /agents para ver todos los subagents organizados por scope (built-in, project, user). Desde la terminal: claude agents lista todos, y claude --agents /path/ carga agents adicionales con prioridad máxima.

Nota sobre Task() y Agent

En la versión 2.1.63, la herramienta Task fue renombrada a Agent. Ambos nombres funcionan:

Task("Revisa el código reciente")    ← sigue funcionando
Agent("Revisa el código reciente")   ← nombre oficial actual

La compatibilidad hacia atrás se mantiene. No necesitas migrar código existente.

Conexión con el Proyecto

Los tres subagents que creaste — reviewer.md, implementer.md, tester.md — son los building blocks del proyecto de la cápsula 05, donde los orquestarás en un flujo secuencial completo:

Tu prompt → reviewer → reporte → implementer → cambios → tester → verificación

Antes de orquestarlos, necesitas refinar sus restricciones de herramientas (cápsula 03) y aprender a parsear la comunicación entre ellos (cápsula 04). Los subagent files que creaste aquí son la versión inicial — se refinarán en las cápsulas siguientes.

Troubleshooting

"Mi subagent no aparece en /agents"

Causa: El archivo no está en la ubicación correcta o el frontmatter YAML tiene errores de sintaxis.

ls -la .claude/agents/
head -5 .claude/agents/reviewer.md

El YAML es sensible a la indentación. No uses tabs (solo espacios) y los --- deben estar en la primera columna, sin espacios antes.

"El subagent ignora las restricciones de tools"

tools define un allowlist (solo esas herramientas). disallowedTools define un denylist (todas excepto esas). Para un reviewer read-only, usa ambos:

tools: Read, Glob, Grep, Bash
disallowedTools: Write, Edit

"El subagent produce output en formato diferente cada vez"

Incluye un ejemplo literal del output en el system prompt. No solo describas el formato — muéstralo. La frase "follow this EXACT structure" más el ejemplo literal reducen la variación a casi cero.

"El subagent tarda demasiado"

Configura maxTurns y acota el scope en el system prompt. "Revisa todos los archivos del proyecto" en un proyecto de 500 archivos consume muchos turns. "Revisa solo los archivos cambiados en los últimos 3 commits" es acotado y rápido.

"Dos subagents con el mismo nombre causan conflicto"

El de mayor prioridad gana (ver sección de scopes). Renombra uno de los dos o usa --agents para override temporal.

Ejercicios

Ejercicio 1: Crear un subagent mínimo (Fácil)

Crea un subagent file con solo los campos requeridos (name y description) y un system prompt de 5 líneas. El subagent debe listar todos los TODO y FIXME en el codebase.

---
name: todo-finder
description: Finds all TODO and FIXME comments across the codebase
---

Search for comments containing TODO, FIXME, HACK, or XXX.
Report organized by type with file path and line number.

### TODO/FIXME Report
#### FIXME (urgent)
- **[file:line]** — Comment text
#### TODO (planned)
- **[file:line]** — Comment text
**Total:** [count] items found

Ejercicio 2: Diagnosticar un system prompt débil (Fácil)

Identifica los 5 problemas de este system prompt y reescríbelo:

---
name: api-checker
description: Checks API endpoints
tools: Read, Bash
---

Check the API endpoints and tell me if they work correctly.
Report any problems you find.

---
name: api-checker
description: Validates API endpoint contracts — response codes, schemas, error handling
tools: Read, Bash, Glob, Grep
disallowedTools: Write, Edit
model: haiku
maxTurns: 15
---

## Role
API endpoint validator. Read route definitions, verify contracts. NEVER modify code.

## Process
1. Find route files: search for *routes*, *router*, *endpoints*
2. Extract: method, path, expected responses
3. Check routes have response models, error handling (404, 422), auth

## Output Format
### API Validation Report
**Endpoints found:** [count]
#### PASS
- [METHOD /path] — All checks passed
#### FAIL
- [METHOD /path] — [issue] → Fix: [recommendation]
#### Summary: Passed [n] | Failed [n]

Ejercicio 3: Crear un subagent de scope usuario (Medio)

Crea un git-summarizer en ~/.claude/agents/ disponible en todos tus proyectos. Debe analizar historial reciente de git y producir un resumen para standup. Debe funcionar en cualquier proyecto sin asumir stack.

---
name: git-summarizer
description: Summarizes recent git activity for standup or reporting
tools: Bash, Read
disallowedTools: Write, Edit
model: haiku
maxTurns: 10
---

## Role
Git history summarizer. Works with any project. NEVER modifies files.

## Process
1. `git log --oneline -20`
2. `git log --since="3 days ago" --format="%h %an %s" --no-merges`
3. `git diff --stat HEAD~5`
4. `git shortlog -sn --since="1 week ago"`

## Output Format
### Git Activity Summary
**Period:** Last 3 days
#### Recent Commits — [hash, author, message]
#### Files Changed — [insertions/deletions summary]
#### Active Contributors — [commit count per contributor]
#### Highlights — [notable changes, new files, refactors]

Ejercicio 4: Diseñar un subagent para tu proyecto (Medio)

Piensa en una tarea repetitiva de tu proyecto actual. Diseña un subagent completo con las 4 secciones (Rol, Criterios, Proceso, Output) y al menos 3 restricciones específicas.

---
name: migration-reviewer
description: Reviews Django migrations for safety — destructive ops, missing reverses, data integrity
tools: Read, Glob, Grep
disallowedTools: Write, Edit, Bash
model: sonnet
maxTurns: 12
---

## Role
Migration safety reviewer. Identifies operations that could cause
downtime or data loss. NEVER modifies migration files.

## Criteria
### CRITICAL — RemoveField with data, DeleteModel with rows,
incompatible AlterField, RunSQL with DROP/TRUNCATE
### WARNING — AddField(null=False) without default, missing reverse,
AddIndex without CONCURRENTLY

## Process
1. Find `*/migrations/0*.py` files
2. Read each migration, check operations against criteria
3. Read related model for context

## Output Format
### Migration Safety Report
**Migrations reviewed:** [list]
#### CRITICAL — Block deployment
- **[file]** — Risk: [impact] → Mitigation: [action]
#### Verdict: SAFE_TO_DEPLOY | NEEDS_REVIEW | BLOCK_DEPLOYMENT

Ejercicio 5: Flujo multi-scope con override (Difícil)

Tienes un reviewer.md genérico en ~/.claude/agents/. Para un proyecto fintech, necesitas criterios adicionales de compliance (PCI-DSS, SOX). Diseña la estrategia de override: ¿dónde colocas cada archivo y por qué? Crea el frontmatter del reviewer fintech con los campos adicionales necesarios.

---
name: reviewer
description: Fintech reviewer with PCI-DSS and SOX compliance awareness
tools: Read, Glob, Grep, Bash
disallowedTools: Write, Edit
model: sonnet        # sonnet (no haiku) — compliance requiere más razonamiento
maxTurns: 20         # más turns por los checks adicionales
---

Ejercicio 6: Completar el frontmatter (Difícil)

Dado este system prompt, escribe el frontmatter YAML completo y justifica cada campo:

You are a performance profiler. You identify slow endpoints by
analyzing route handlers, database queries, and external API calls.
You run benchmarks with curl and report response times. You suggest
optimizations but NEVER implement them.

---
name: perf-profiler
description: Profiles API endpoint performance — analyzes handlers, DB queries, runs benchmarks
tools: Read, Glob, Grep, Bash
disallowedTools: Write, Edit
model: sonnet
maxTurns: 20
permissionMode: default
---

Resumen

• Un subagent custom es un archivo Markdown con frontmatter YAML y un system prompt — sin compilación ni deploy
• Solo dos campos son obligatorios: name y description
• Los campos opcionales (tools, disallowedTools, model, permissionMode, maxTurns) definen la especialización
• Subagent files viven en 4 scopes: --agents flag > .claude/agents/ > ~/.claude/agents/ > plugin agents/
• Un system prompt efectivo define: rol, criterios, proceso, y formato de output
• Las restricciones negativas ("NEVER modify files") son tan importantes como las positivas
• Usa haiku para agentes que leen y reportan, sonnet para agentes que razonan y escriben código
• Crea customs para tareas repetitivas con criterios específicos — si das las mismas instrucciones más de dos veces, crea un archivo
• Los 3 subagents creados aquí (reviewer, implementer, tester) son los building blocks del proyecto de la cápsula 05

Recursos Adicionales

1. Create Custom Subagents (Anthropic Docs) — Documentación oficial de subagents como archivos Markdown con frontmatter YAML
2. Claude Code CLI Reference — Referencia del CLI con flags --agents y claude agents
3. Claude Code Best Practices — Buenas prácticas de prompts y delegación aplicables a subagents
4. Prompt Engineering: System Prompts — Principios de system prompts transferibles a subagent prompts
5. Prompt Engineering: Be Clear and Direct — Técnicas de claridad para diseño de subagents
6. Claude Code Tips and Tricks — Tips sobre cómo estructurar trabajo con agentes
7. Claude Models Documentation — Referencia de modelos para elegir el correcto por subagent
8. Claude Code Overview — Contexto de Claude Code como agente para entender cómo encajan los subagents

Siguiente cápsula: En la cápsula 03 profundizarás en las restricciones de herramientas — cómo tools, disallowedTools, y permissionMode crean subagents que solo pueden hacer lo que les corresponde. Verás cómo un reviewer sin acceso a Write es fundamentalmente diferente a uno con instrucciones de "no escribas" — la restricción técnica es más confiable que la instrucción de texto.