Módulo 1: Custom Subagents

5. Proyecto — Pipeline de 3 Subagents Especializados

Descripción del Proyecto

Has aprendido a crear subagents como archivos Markdown con frontmatter YAML, a definir system prompts que producen outputs predecibles, a restringir herramientas para que cada agente solo pueda hacer lo que le corresponde, y a parsear la comunicación entre agentes para encadenarlos. Ahora vas a integrar todo en un sistema funcional.

En este proyecto construyes un pipeline de desarrollo con 3 subagents especializados: un reviewer que analiza código reciente buscando problemas, un implementer que corrige los problemas encontrados, y un tester que ejecuta la suite de tests para verificar que las correcciones no rompieron nada. Cada subagent tiene un rol estricto definido por su frontmatter, restricciones de herramientas que garantizan que no se salga de su función, y un formato de output que el siguiente agente en la cadena puede consumir.

El flujo es lineal: tú escribes un prompt, Claude delega al reviewer, el reviewer devuelve un reporte, Claude procesa ese reporte y delega al implementer con los hallazgos, el implementer hace los cambios y devuelve un resumen, Claude delega al tester, y el tester ejecuta los tests y reporta resultados. Al final, Claude te presenta un resumen consolidado. No hay magia — cada paso es explícito, cada output es estructurado, y cada agente tiene exactamente las herramientas que necesita.

Este es el proyecto culminante del Módulo 1. Si los 3 subagents funcionan en secuencia y el reporte final integra resultados de los 3, has dominado custom subagents. Si además puedes explicar por qué el reviewer no tiene Write y el tester no tiene Edit, has internalizado la filosofía de restricción por diseño.

Objetivo del Proyecto

Construir un pipeline funcional de 3 subagents (reviewer → implementer → tester) donde cada agente tiene rol, herramientas, modelo, y formato de output definidos — y ejecutarlos en secuencia sobre un proyecto real.

Al completar este proyecto:

✅ Tendrás 3 archivos de subagent en .claude/agents/ listos para usar en cualquier proyecto
✅ Cada subagent estará restringido a las herramientas que necesita — sin excepciones
✅ El reviewer producirá reportes clasificados por prioridad (Critical / Warning / Suggestion)
✅ El implementer tomará el reporte del reviewer como input y corregirá los problemas
✅ El tester ejecutará la suite completa y reportará pass/fail, cobertura, y causas raíz
✅ Habrás ejecutado el pipeline completo al menos una vez con resultados verificables
✅ Podrás explicar por qué cada restricción de herramientas existe

Duración estimada: 1.5-2 horas (setup: 15 min + subagents: 45 min + testing individual: 20 min + pipeline: 20 min + iteración: 15 min).

Especificaciones Técnicas

Stack Tecnológico

Herramienta: Claude Code v2.1.63+
Subagent files: Markdown con frontmatter YAML
Ubicación: .claude/agents/ (scope proyecto)
Modelos: haiku (reviewer, tester), sonnet (implementer)
Proyecto base: Cualquier proyecto con código fuente en src/, tests, y al menos 3 commits en git

Requisitos del Proyecto Base

Para que el pipeline tenga sentido, necesitas un proyecto con:

Requisito	Mínimo	Ideal
Archivos de código en `src/`	3+	8-15
Tests existentes	3+	10+
Commits en git	3+	10+
CLAUDE.md	Básico	Con convenciones de estilo
Framework de tests	Cualquiera	pytest o jest

Si no tienes un proyecto a mano, clona cualquier proyecto open source con tests. Lo importante es que haya código que revisar, archivos que potencialmente corregir, y tests que ejecutar.

Setup Inicial

cd your-project

mkdir -p .claude/agents

ls .claude/agents/

claude --version

Verifica que Claude Code es v2.1.63 o posterior. Si no, actualiza:

claude update

Estructura Final del Proyecto

Al terminar, tu proyecto tendrá esta estructura adicional:

your-project/
├── .claude/
│   └── agents/
│       ├── code-reviewer.md      ← Subagent 1: solo lee
│       ├── code-implementer.md   ← Subagent 2: edita src/
│       └── code-tester.md        ← Subagent 3: solo ejecuta
├── src/                          ← Código que el pipeline analiza
├── tests/                        ← Tests que el tester ejecuta
├── CLAUDE.md                     ← Convenciones del proyecto
└── ...

Funcionalidades Obligatorias

Subagent 1: Code Reviewer (`code-reviewer.md`)

Rol: Analiza cambios recientes en el código y produce un reporte estructurado por prioridad. Solo lee — nunca modifica archivos.

Especificaciones:

Campo	Valor	Justificación
`tools`	`Read, Grep, Glob, Bash`	Lee archivos, busca patrones, ejecuta `git diff`
`disallowedTools`	`Write, Edit`	Garantiza que no modifique código
`model`	`haiku`	Lectura y análisis no requieren razonamiento profundo
`maxTurns`	`15`	Suficiente para leer archivos y producir el reporte

8 criterios de revisión:

Legibilidad — Nombres descriptivos, funciones cortas, flujo claro
Naming conventions — Consistencia con las convenciones del proyecto
Error handling — Try/except específicos, no genéricos. Errores no silenciados
Security — No hardcoded secrets, no SQL injection, no inputs sin sanitizar
Performance — No N+1 queries, no loops innecesarios, no blocking en async
Edge cases — Null checks, empty collections, boundary values
DRY — Sin duplicación significativa. Lógica compartida extraída
Type safety — Type hints presentes y correctos (Python), tipos explícitos (TypeScript)

Formato de output: Reporte con secciones Critical / Warning / Suggestion, cada hallazgo con archivo, línea, descripción, evidencia, y recomendación.

Subagent 2: Code Implementer (`code-implementer.md`)

Rol: Recibe el reporte del reviewer y corrige los problemas encontrados. Solo modifica archivos en src/. Sigue las convenciones de CLAUDE.md.

Especificaciones:

Campo	Valor	Justificación
`tools`	`Read, Edit, Write, Grep, Glob`	Lee código, busca contexto, edita y crea archivos
`disallowedTools`	`Bash`	No ejecuta comandos — solo modifica código
`model`	`sonnet`	Implementación requiere razonamiento sobre lógica
`maxTurns`	`25`	Puede necesitar múltiples ediciones en varios archivos

Reglas de implementación:

Corrige TODOS los hallazgos marcados como Critical
Corrige hallazgos Warning si el fix es directo (< 10 líneas)
Ignora Suggestion a menos que se indique explícitamente
Solo modifica archivos dentro de src/
Nunca modifica tests, configuración, ni CLAUDE.md
Sigue las convenciones existentes del proyecto
Reporta cada cambio realizado y cada hallazgo no abordado con justificación

Subagent 3: Code Tester (`code-tester.md`)

Rol: Ejecuta la suite de tests y reporta resultados. No modifica código fuente ni tests — solo ejecuta y reporta.

Especificaciones:

Campo	Valor	Justificación
`tools`	`Bash, Read, Grep, Glob`	Ejecuta tests, lee archivos de test para contexto
`disallowedTools`	`Write, Edit`	No puede modificar código ni tests
`model`	`haiku`	Ejecutar tests y reportar no requiere razonamiento profundo
`maxTurns`	`12`	Ejecutar suite + analizar fallos

Información que reporta:

Framework detectado y comando ejecutado
Conteo total: passed, failed, skipped
Para cada test fallido: nombre, qué esperaba, qué obtuvo, causa raíz probable
Cobertura por módulo (si está configurado)
Veredicto final: ALL_PASS, FAILURES, ERROR

Guía Paso a Paso

Paso 1: Crear el Code Reviewer

Crea el archivo .claude/agents/code-reviewer.md con el siguiente contenido completo:

---
name: code-reviewer
description: Analyzes recent code changes against 8 quality criteria. Read-only — never modifies files. Reports by priority: Critical, Warning, Suggestion.
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
model: haiku
maxTurns: 15
---

## Role

You are a senior code reviewer. You analyze recent git changes and produce a structured report organized by severity. You NEVER modify any file. Your job is to find problems — fixing them is someone else's responsibility.

## Process

1. Run `git diff HEAD~3 --name-only` to identify recently changed files
2. Filter: only review files in `src/` (skip tests, configs, docs)
3. For each changed file:
   a. Read the complete file
   b. Read related files (imports, parent classes, interfaces) for context
   c. Apply all 8 review criteria
4. Produce the report in the exact output format below

If `git diff HEAD~3` returns no files, try `git diff HEAD~1` or report that no recent changes were found.

## Review Criteria

### 1. Readability
- Functions longer than 30 lines
- Deeply nested logic (3+ levels)
- Unclear control flow

### 2. Naming Conventions
- Variables/functions not following project conventions
- Inconsistent naming style within a file
- Single-letter variables outside of loops/comprehensions

### 3. Error Handling
- Bare `except:` or `except Exception:`
- Silenced errors (empty except blocks)
- Missing error handling on I/O, network, or database operations

### 4. Security
- Hardcoded credentials, API keys, or secrets
- User input used without validation or sanitization
- SQL queries built with string concatenation or f-strings

### 5. Performance
- Database queries inside loops (N+1 pattern)
- Loading large collections without pagination or limits
- Blocking operations in async context

### 6. Edge Cases
- Missing null/None checks before attribute access
- No handling of empty collections (empty list, empty dict)
- Missing boundary value validation (negative numbers, zero, max int)

### 7. DRY (Don't Repeat Yourself)
- Duplicated logic blocks (3+ lines repeated)
- Copy-pasted code with minor variations
- Logic that should be extracted into a shared function

### 8. Type Safety
- Missing type hints on function signatures (Python)
- Using `Any` where a specific type is known
- Type mismatches between function signature and usage

## Output Format

Follow this EXACT structure:

Code Review Report

Date: [YYYY-MM-DD] Commit range: HEAD~3..HEAD Files reviewed: [list of files]

CRITICAL (must fix before merge)

[file:line] — [Short description]
- Criteria: [which of the 8 criteria]
- Evidence: [relevant code snippet]
- Recommendation: [specific fix]

WARNING (should fix)

[file:line] — [Short description]
- Criteria: [which of the 8 criteria]
- Evidence: [relevant code snippet]
- Recommendation: [specific fix]

SUGGESTION (nice to have)

[file:line] — [Short description]
- Criteria: [which of the 8 criteria]
- Recommendation: [specific improvement]

Summary

Priority	Count
Critical	[n]
Warning	[n]
Suggestion	[n]

Verdict: [PASS | PASS_WITH_WARNINGS | NEEDS_REVISION]

PASS: 0 critical, 0 warnings
PASS_WITH_WARNINGS: 0 critical, 1+ warnings
NEEDS_REVISION: 1+ critical


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

Paso 2: Verificar el Reviewer

Antes de crear los otros subagents, verifica que el reviewer funciona correctamente.

2a. Verificar que Claude Code lo detecta:

Abre Claude Code en tu proyecto y ejecuta:

/agents

Deberías ver code-reviewer en la lista de subagents del proyecto. Si no aparece:

Verifica que el archivo está en .claude/agents/code-reviewer.md
Verifica que los --- del frontmatter están solos en su propia línea
Verifica que no hay tabs en el YAML (solo espacios)

2b. Ejecutar el reviewer:

Usa el code-reviewer para analizar los cambios recientes del proyecto

Qué verificar en el output:

✅ Solo revisó archivos en src/ (no tests, no configs)
✅ Ejecutó git diff para encontrar archivos cambiados
✅ Cada hallazgo tiene archivo, línea, criterio, evidencia, y recomendación
✅ Los hallazgos están clasificados en Critical / Warning / Suggestion
✅ El resumen tiene conteo y veredicto
✅ NO modificó ningún archivo (verificar con git status)

git status

Si git status muestra archivos modificados que no estaban modificados antes, el reviewer violó su restricción. Revisa el frontmatter.

2c. Si el reviewer no produce output estructurado:

Es normal en la primera iteración. Ajusta el system prompt — agrega "Follow this EXACT structure. Do not deviate." al inicio de la sección Output Format. La palabra EXACT reduce significativamente la variación.

Paso 3: Crear el Code Implementer

Crea .claude/agents/code-implementer.md:

---
name: code-implementer
description: Fixes code issues from review reports. Only modifies files in src/. Follows project conventions from CLAUDE.md. Never touches tests or config.
tools: Read, Edit, Write, Grep, Glob
disallowedTools: Bash
model: sonnet
maxTurns: 25
---

## Role

You are a senior developer who fixes code issues identified in review reports. You work exclusively in `src/`. You follow existing project conventions — never introduce new patterns, libraries, or styles unless explicitly instructed.

## Constraints

- ONLY modify files inside `src/`
- NEVER modify files in `tests/`, `test/`, or any test file
- NEVER modify configuration files (*.yml, *.toml, *.cfg, *.json at root)
- NEVER modify CLAUDE.md, README.md, or documentation files
- NEVER install new dependencies
- NEVER delete files
- Follow the coding style already present in the project

## When Receiving a Review Report

Read the entire report first. Then:

1. **CRITICAL items:** Fix ALL of them. These are blockers.
2. **WARNING items:** Fix if the change is straightforward (< 10 lines changed). Skip if it requires architectural changes.
3. **SUGGESTION items:** SKIP unless explicitly asked to address them.

For each fix:
- Read the file and surrounding context before editing
- Make the minimal change that resolves the issue
- Preserve existing code style (indentation, quotes, naming)
- If a fix could affect other files, read those files first

## Process

1. Parse the review report to extract all items by priority
2. Read CLAUDE.md for project conventions
3. For each CRITICAL item:
   a. Read the file mentioned
   b. Understand the context around the problematic code
   c. Apply the fix
   d. Record what you changed
4. For each WARNING item (if straightforward):
   a. Same process as CRITICAL
5. Produce the implementation report

## Output Format

Follow this EXACT structure:

Implementation Report

Files modified: [list of files changed] Review items addressed: [n] of [total]

Changes Made

[file:line] — [What was changed]
- Review item: [CRITICAL|WARNING] — [original description]
- Fix applied: [description of the fix]
- Lines changed: [n]
[file:line] — [What was changed]
- ...

Items Not Addressed

[file:line] — [original description]
- Reason: [why it was skipped — "SUGGESTION: not requested" | "WARNING: requires architectural change" | etc.]

Summary

Category	Found	Fixed	Skipped
Critical	[n]	[n]	[n]
Warning	[n]	[n]	[n]
Suggestion	[n]	[n]	[n]

Paso 4: Verificar el Implementer

4a. Verificar detección:

/agents

Confirma que code-implementer aparece con las herramientas Read, Edit, Write, Grep, Glob. Sin Bash.

4b. Ejecutar el implementer con el reporte del reviewer:

No ejecutes el implementer de forma aislada la primera vez — necesita un reporte de review como input. Pero puedes hacer una prueba simple:

Usa el code-implementer para agregar type hints a las funciones en src/ que no los tengan

Qué verificar:

✅ Solo modificó archivos en src/
✅ No tocó tests ni configuración
✅ Cada cambio tiene descripción y justificación
✅ No ejecutó comandos (no tiene Bash)

git diff --stat

Verifica que los archivos modificados están todos en src/. Si modificó algo fuera de src/, revisa las instrucciones del system prompt.

Paso 5: Crear el Code Tester

Crea .claude/agents/code-tester.md:

---
name: code-tester
description: Runs the project test suite and reports results with pass/fail counts, coverage, and root cause analysis for failures. Never modifies code.
tools: Bash, Read, Grep, Glob
disallowedTools: Write, Edit
model: haiku
maxTurns: 12
---

## Role

You are a test runner and reporter. You execute the project's test suite and produce a detailed report. You NEVER modify source code, test files, or any other file. If tests fail, your job is to report WHY they fail — not to fix them.

## Process

1. **Detect the test framework:**
   - Check for `pyproject.toml`, `setup.cfg` → pytest
   - Check for `package.json` → jest, vitest, or mocha
   - Check for `Cargo.toml` → cargo test
   - Check for `go.mod` → go test
   - If unclear, look for test files and infer

2. **Run the full test suite:**
   - Python (pytest): `python -m pytest -v --tb=short 2>&1`
   - Python (with 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`
   - Always redirect stderr to stdout with `2>&1`

3. **If tests fail:**
   - Read the failing test file to understand what it expects
   - Read the source file the test is testing
   - Determine the likely root cause
   - Do NOT attempt to fix anything

4. **If the test command fails entirely (not installed, config error):**
   - Report the error clearly
   - Suggest what might be wrong
   - Try an alternative command if obvious (e.g., `pytest` instead of `python -m pytest`)

## Output Format

Follow this EXACT structure:

Test Report

Framework: [detected framework and versión] Command: [exact command executed] Execution time: [seconds]

Results

Status	Count
✅ Passed	[n]
❌ Failed	[n]
⏭️ Skipped	[n]
Total	[n]

Failed Tests

(If no failures, write "All tests passed.")

[test_file::TestClass::test_name]
- Expected: [what the test expected]
- Got: [what actually happened]
- Error: [error message]
- Root cause: [your analysis of why it fails]
...

Coverage

(If coverage data is available)

Module	Statements	Covered	Missing	Coverage
[module]	[n]	[n]	[lines]	[%]
Total	[n]	[n]	—	[%]

(If coverage is not configured, write "Coverage not configured. Run with --cov to enable.")

Verdict

[ALL_PASS | FAILURES | ERROR]

ALL_PASS: All tests passed successfully
FAILURES: One or more tests failed
ERROR: Test suite could not execute (missing dependency, config error)

Paso 6: Verificar el Tester

6a. Verificar detección:

/agents

Confirma que code-tester aparece con Bash, Read, Grep, Glob. Sin Write, sin Edit.

6b. Ejecutar el tester de forma aislada:

Usa el code-tester para ejecutar la suite de tests del proyecto

Qué verificar:

✅ Detectó el framework correcto
✅ Ejecutó el comando de tests
✅ Reportó pass/fail/skipped con conteos
✅ Si hubo fallos, incluyó análisis de causa raíz
✅ NO modificó ningún archivo

git status

Confirma que no hay cambios en archivos. Si el tester modificó algo, el frontmatter tiene un error.

Paso 7: Verificar los 3 Subagents en `/agents`

Antes de encadenarlos, verifica que los 3 están correctamente configurados:

/agents

Deberías ver una salida similar a:

Project agents (.claude/agents/):
  code-reviewer    — Analyzes recent code changes against 8 quality criteria...
  code-implementer — Fixes code issues from review reports...
  code-tester      — Runs the project test suite and reports results...

Verifica esta tabla de capacidades:

Herramienta	code-reviewer	code-implementer	code-tester
Read	✅	✅	✅
Grep	✅	✅	✅
Glob	✅	✅	✅
Bash	✅	❌	✅
Write	❌	✅	❌
Edit	❌	✅	❌

Cada agente tiene exactamente lo que necesita. Ni más, ni menos.

Paso 8: Ejecutar el Pipeline Completo

Ahora viene el momento de encadenar los 3 subagents. El encadenamiento sucede a través de la conversación principal de Claude Code — tú le pides que ejecute el flujo y Claude delega a cada subagent en secuencia.

El prompt para el pipeline completo:

Ejecuta el siguiente flujo de desarrollo en secuencia:

1. Usa el code-reviewer para analizar los cambios recientes (HEAD~3)
2. Toma el reporte del reviewer y pásalo al code-implementer para que corrija los problemas encontrados
3. Después de que el implementer termine, usa el code-tester para ejecutar los tests y verificar que todo funciona

Al final, dame un resumen consolidado con:
- Qué encontró el reviewer
- Qué corrigió el implementer
- Qué reportó el tester
- Veredicto final: ¿el código está listo?

Qué observar durante la ejecución:

Claude delega al reviewer → Debería ejecutar git diff, leer archivos, producir reporte
Claude procesa el reporte → Extrae los hallazgos Critical y Warning
Claude delega al implementer → Le pasa los hallazgos como contexto. El implementer lee archivos, hace cambios, reporta
Claude delega al tester → El tester ejecuta tests, reporta resultados
Claude presenta resumen → Consolida la información de los 3 subagents

El flujo visual:

Tu prompt
    │
    ▼
┌─────────────────────────────┐
│  Claude (conversación main) │
│                             │
│  1. Delega a code-reviewer  │──── git diff, lee archivos
│     ← recibe reporte        │     8 criterios evaluados
│                             │
│  2. Procesa reporte         │──── extrae Critical/Warning
│     Delega a code-implementer│    con hallazgos como contexto
│     ← recibe cambios        │     edita solo en src/
│                             │
│  3. Delega a code-tester    │──── ejecuta pytest/jest
│     ← recibe resultados     │     analiza fallos
│                             │
│  4. Presenta resumen final  │──── consolida los 3 reportes
└─────────────────────────────┘

Paso 9: Verificar el Pipeline

Después de la ejecución, verifica cada fase:

Verificación del reviewer:

# El reviewer no debe haber modificado nada durante su fase
# (el implementer sí — verificar que solo tocó src/)
git diff --name-only

Todos los archivos modificados deben estar en src/.

Verificación del implementer:

git diff --stat

Confirma que los cambios corresponden a los hallazgos del reviewer. Si el implementer cambió algo que no estaba en el reporte, el system prompt necesita ajuste.

Verificación del tester:

Si los tests pasan: el pipeline tuvo éxito
Si los tests fallan: lee el reporte del tester para entender por qué. Puedes re-ejecutar solo el implementer con más contexto, y luego el tester otra vez

Paso 10: Iterar si es Necesario

Si el pipeline no funcionó perfectamente en la primera ejecución, es normal. Los puntos comunes de iteración:

El reviewer produce output inconsistente: Refuerza el formato. Agrega al system prompt del reviewer:

IMPORTANT: Follow the Output Format section EXACTLY. Do not add extra sections,
do not change headers, do not omit the Summary table.

El implementer no recibe el reporte completo: El prompt de encadenamiento necesita ser más explícito. Cambia "pásalo al implementer" por:

Pasa el reporte COMPLETO del reviewer al code-implementer. Incluye
todos los hallazgos con su clasificación, archivo, línea y descripción.

El tester falla al ejecutar tests: Puede ser un problema de entorno (virtualenv no activado, node_modules no instalados). El tester reportará el error — léelo y corrige el entorno antes de re-ejecutar.

Checklist de Validación

Usa esta checklist para confirmar que tu pipeline está completo:

Archivos creados

.claude/agents/code-reviewer.md existe y tiene frontmatter válido
.claude/agents/code-implementer.md existe y tiene frontmatter válido
.claude/agents/code-tester.md existe y tiene frontmatter válido

Detección

/agents muestra los 3 subagents con sus descripciones
Cada subagent muestra las herramientas correctas

Restricciones de herramientas

El reviewer NO puede escribir ni editar archivos (verificado con git status después de ejecución)
El implementer NO puede ejecutar comandos Bash
El implementer SOLO modifica archivos en src/
El tester NO puede escribir ni editar archivos (verificado con git status)

Output estructurado

El reviewer produce reporte con secciones Critical / Warning / Suggestion
El reviewer incluye archivo, línea, criterio, evidencia, y recomendación
El implementer produce reporte con Changes Made y Items Not Addressed
El tester produce reporte con Results, Failed Tests, Coverage, Verdict

Pipeline completo

Los 3 subagents se ejecutan en secuencia: reviewer → implementer → tester
El implementer recibe los hallazgos del reviewer como input
El tester ejecuta después de los cambios del implementer
Claude presenta un resumen consolidado al final
El resumen incluye información de los 3 subagents

Modelos

El reviewer usa haiku (rápido, lectura)
El implementer usa sonnet (capaz, implementación)
El tester usa haiku (rápido, ejecución)

Referencia Rápida — Los 3 Archivos

Los 3 subagent files completos y listos para copy-paste están en los pasos 1, 3 y 5 de la guía anterior:

Archivo	Paso	Descripción
`.claude/agents/code-reviewer.md`	Paso 1	Read-only, haiku, 8 criterios, reporte por prioridad
`.claude/agents/code-implementer.md`	Paso 3	Edit src/, sonnet, corrige Critical y Warning
`.claude/agents/code-tester.md`	Paso 5	Execute-only, haiku, pass/fail + coverage + root cause

Cada archivo es self-contained. Copia el bloque de código del paso correspondiente directamente a .claude/agents/. No necesitan archivos adicionales ni dependencias extra.

Variaciones del Pipeline

Variación 1: Pipeline con scope reducido

Si tu proyecto es grande, acota el scope del reviewer:

Ejecuta el pipeline reviewer → implementer → tester, pero el reviewer
solo debe analizar los archivos cambiados en el último commit (HEAD~1).

Variación 2: Pipeline solo para Critical

Si quieres un pipeline rápido que solo atienda lo urgente:

Ejecuta el pipeline completo, pero el implementer solo debe corregir
hallazgos marcados como CRITICAL. Ignora WARNING y SUGGESTION.

Variación 3: Pipeline con re-ejecución

Si los tests fallan después de las correcciones:

El tester reportó 2 tests fallidos. Pasa el reporte del tester al
code-implementer para que corrija los problemas, y luego ejecuta
el code-tester otra vez para verificar.

Este patrón extiende el pipeline a: reviewer → implementer → tester → implementer → tester. Cada iteración reduce los fallos.

Variación 4: Ejecutar subagents individualmente

No siempre necesitas el pipeline completo. Cada subagent funciona de forma independiente:

Usa el code-reviewer para analizar los cambios de la última semana

Usa el code-tester para ejecutar solo los tests del módulo auth

Usa el code-implementer para agregar error handling a las funciones
en src/services/ que no tienen try/except

Errores Comunes y Soluciones

Error 1: "El subagent no aparece en /agents"

Síntoma: Ejecutas /agents y tu subagent no está en la lista.

Causas posibles:

El archivo no está en .claude/agents/ (verifica la ruta exacta)
El frontmatter YAML tiene errores de sintaxis
Hay tabs en lugar de espacios en el YAML
Los --- tienen espacios antes o después

Solución:

ls -la .claude/agents/
head -10 .claude/agents/code-reviewer.md

Verifica que los delimitadores --- están solos en su línea, sin espacios. El YAML solo usa espacios para indentación.

Error 2: "El reviewer modificó archivos"

Síntoma: Después de ejecutar el reviewer, git status muestra archivos modificados.

Causas posibles:

disallowedTools mal escrito (es camelCase: disallowedTools, no disallowed_tools)
Los nombres de herramientas son case-sensitive: Write, no write
Falta Edit en disallowedTools

Solución: Verifica el frontmatter:

disallowedTools: Write, Edit

Ambos nombres deben ser PascalCase. Después ejecuta /agents y confirma que las herramientas mostradas son correctas.

Error 3: "El implementer cambió archivos fuera de src/"

Síntoma: git diff --stat muestra cambivos en tests o configuración.

Causa: La restricción de directorio está en el system prompt (instrucción) pero no enforced por herramientas ni hooks. El system prompt dice "ONLY modify files inside src/" pero técnicamente puede editar cualquier archivo.

Solución: Para un enforcement más estricto, agrega un hook PreToolUse. Pero para la mayoría de casos, el system prompt con "ONLY" y "NEVER" es suficiente. Si el problema persiste, refuerza con:

CRITICAL CONSTRAINT: If the file path does not start with "src/",
do NOT edit it under any circumstances. This is a hard rule.

Error 4: "El tester no puede ejecutar los tests"

Síntoma: El tester reporta ERROR porque el comando de tests falla.

Causas posibles:

El virtual environment no está activado
Dependencias no instaladas (pytest no encontrado)
El tester intenta ejecutar desde el directorio incorrecto

Solución: Antes de ejecutar el pipeline, verifica que los tests funcionan manualmente:

python -m pytest -v --tb=short 2>&1

Si esto falla fuera del pipeline, el problema es del entorno, no del subagent.

Error 5: "El output del reviewer no es consistente"

Síntoma: El reviewer produce reportes con formatos diferentes cada ejecución.

Causa: El system prompt describe el formato pero no es suficientemente estricto.

Solución: Agrega estas líneas al inicio de la sección Output Format del reviewer:

IMPORTANT: Follow this EXACT structure. Do not add extra sections.
Do not change header names. Do not omit the Summary table.
If no issues in a category, write "None found." — do not omit the category.

Error 6: "El pipeline se detiene a mitad de camino"

Síntoma: Claude ejecuta el reviewer pero no continúa con el implementer.

Causa: El prompt de orquestación no es suficientemente explícito sobre la secuencia.

Solución: Usa un prompt más directo:

Ejecuta estos 3 pasos EN SECUENCIA, uno después del otro:

PASO 1: Delega al code-reviewer para analizar HEAD~3
PASO 2: Cuando el reviewer termine, toma su reporte completo y
        delégalo al code-implementer para que corrija los problemas
PASO 3: Cuando el implementer termine, delega al code-tester
        para ejecutar los tests

Al final, dame un resumen consolidado de los 3 reportes.

Error 7: "El implementer no recibe el contexto del reviewer"

Síntoma: El implementer no sabe qué problemas corregir porque no tiene el reporte del reviewer.

Causa: Cada subagent tiene su propio contexto — no comparten memoria. Claude debe explícitamente pasar la información de uno a otro.

Solución: En el prompt de orquestación, enfatiza que el reporte se pase completo:

PASO 2: Pasa al code-implementer el reporte COMPLETO del reviewer,
        incluyendo todos los hallazgos con su clasificación (CRITICAL,
        WARNING, SUGGESTION), archivo, línea, y descripción.

Claude actúa como intermediario — lee el output del reviewer y lo incluye como contexto al invocar al implementer.

Error 8: "El reviewer marca TODO como Critical"

Síntoma: El reviewer clasifica hallazgos triviales (naming, style) como Critical.

Causa: Los criterios de clasificación no están definidos en el system prompt.

Solución: Agrega criterios explícitos de clasificación:

## Classification Rules

CRITICAL: Security vulnerabilities, data loss risk, logic errors
that produce wrong results, unhandled exceptions that crash the app.

WARNING: Missing error handling that won't crash but degrades UX,
performance issues, missing validation on user input.

SUGGESTION: Naming improvements, style consistency, refactoring
for readability, adding type hints.

When in doubt, classify DOWN (Warning instead of Critical,
Suggestion instead of Warning).

Recursos del Proyecto

Create Custom Subagents (Anthropic Docs) — Documentación oficial de subagents: formato de archivo, frontmatter YAML, tool restriction, hooks, scopes
Claude Code Hooks Reference — Referencia de hooks PreToolUse para enforcement avanzado de restricciones
Claude Code CLI Reference — Flags de CLI como --agents para cargar subagents desde ubicaciones custom
Claude Code Best Practices — Buenas prácticas de prompting y delegación que aplican a system prompts de subagents
Prompt Engineering: Be Clear and Direct — Técnicas de claridad aplicables al diseño de system prompts para subagents
Claude Models Documentation — Referencia de modelos para elegir haiku vs sonnet vs opus por tipo de tarea

Conexión con el Siguiente Módulo

Has construido un pipeline funcional con 3 subagents especializados. Funciona. Pero tiene una limitación fundamental que probablemente ya notaste: cada vez que ejecutas el pipeline, los subagents empiezan de cero.

El reviewer no recuerda qué encontró en la ejecución anterior. Si corriste el pipeline ayer y el reviewer encontró 3 warnings que decidiste ignorar, hoy te los vuelve a reportar. No sabe que ya los viste. No sabe que son falsos positivos para tu contexto. No sabe que el implementer ya evaluó uno y decidió no cambiarlo porque requiere un refactor más grande.

El implementer no recuerda las convenciones que aprendió. Si en la primera ejecución descubrió que tu proyecto usa single quotes en Python y decoradores custom para logging, en la siguiente ejecución tiene que redescubrirlo leyendo CLAUDE.md y el código otra vez. Cada ejecución es una primera vez.

El tester no recuerda qué tests fallaban antes. No puede decirte "estos 2 tests ya fallaban antes de los cambios del implementer — son pre-existentes, no regresiones." Para él, cada ejecución es la primera suite que ve.

Esta falta de memoria entre sesiones es el problema más crítico de los subagents custom. Los 3 agentes que creaste aquí son competentes pero amnésicos. El Módulo 2: Agent Memory y Scopes resuelve exactamente esto — aprenderás a configurar memoria persistente con scopes (session, project, user) para que tus subagents acumulen contexto entre ejecuciones. Un reviewer con memoria se convierte en un reviewer que conoce tu proyecto.

Resumen

Construiste un pipeline funcional de 3 subagents: reviewer → implementer → tester
Cada subagent es un archivo Markdown con frontmatter YAML en .claude/agents/
El reviewer (haiku, read-only) analiza código contra 8 criterios y reporta por prioridad
El implementer (sonnet, edit src/) corrige los problemas encontrados por el reviewer
El tester (haiku, execute-only) ejecuta tests y reporta resultados con análisis de fallos
Las restricciones de herramientas garantizan que cada agente solo hace lo que le corresponde
El encadenamiento sucede a través de Claude como intermediario — cada output se pasa como contexto al siguiente agente
Los 3 archivos son copy-paste ready — puedes usarlos en cualquier proyecto con src/ y tests
La limitación principal es la falta de memoria entre sesiones — el Módulo 2 la resuelve

Siguiente módulo: El Módulo 2 (Agent Memory y Scopes) te enseña a resolver la amnesia de tus subagents. Configurarás memoria persistente para que el reviewer recuerde hallazgos anteriores, el implementer acumule conocimiento de convenciones, y el tester distinga regresiones de fallos pre-existentes. Los subagents que creaste aquí son la base — la memoria los convierte en agentes que evolucionan.

← Anterior4. Output Parsing y Comunicación Entre Agentes Siguiente →1. Introducción al Módulo — El Problema de la Memoria Efímera

5. Proyecto — Pipeline de 3 Subagents Especializados

5. Proyecto — Pipeline de 3 Subagents Especializados

Descripción del Proyecto

Objetivo del Proyecto

Especificaciones Técnicas

Stack Tecnológico

Requisitos del Proyecto Base

Setup Inicial

Estructura Final del Proyecto

Funcionalidades Obligatorias

Subagent 1: Code Reviewer (code-reviewer.md)

Subagent 2: Code Implementer (code-implementer.md)

Subagent 3: Code Tester (code-tester.md)

Guía Paso a Paso

Paso 1: Crear el Code Reviewer

Code Review Report

CRITICAL (must fix before merge)

WARNING (should fix)

SUGGESTION (nice to have)

Summary

Paso 2: Verificar el Reviewer

Paso 3: Crear el Code Implementer

Implementation Report

Changes Made

Items Not Addressed

Summary

Paso 4: Verificar el Implementer

Paso 5: Crear el Code Tester

Test Report

Results

Failed Tests

Coverage

Verdict

Paso 6: Verificar el Tester

Paso 7: Verificar los 3 Subagents en /agents

Paso 8: Ejecutar el Pipeline Completo

Paso 9: Verificar el Pipeline

Paso 10: Iterar si es Necesario

Checklist de Validación

Archivos creados

Detección

Restricciones de herramientas

Output estructurado

Pipeline completo

Modelos

Referencia Rápida — Los 3 Archivos

Variaciones del Pipeline

Variación 1: Pipeline con scope reducido

Variación 2: Pipeline solo para Critical

Variación 3: Pipeline con re-ejecución

Variación 4: Ejecutar subagents individualmente

Errores Comunes y Soluciones

Error 1: "El subagent no aparece en /agents"

Error 2: "El reviewer modificó archivos"

Error 3: "El implementer cambió archivos fuera de src/"

Error 4: "El tester no puede ejecutar los tests"

Error 5: "El output del reviewer no es consistente"

Error 6: "El pipeline se detiene a mitad de camino"

Error 7: "El implementer no recibe el contexto del reviewer"

Error 8: "El reviewer marca TODO como Critical"

Recursos del Proyecto

Conexión con el Siguiente Módulo

Resumen

Subagent 1: Code Reviewer (`code-reviewer.md`)

Subagent 2: Code Implementer (`code-implementer.md`)

Subagent 3: Code Tester (`code-tester.md`)

Paso 7: Verificar los 3 Subagents en `/agents`