Capítulo 3: Agentes: Delegación Inteligente

1. ¿Qué son los Agentes en Claude Code?

Un agente en Claude Code es un subagente especializado que se ejecuta de forma aislada dentro del Task tool. Cada agente tiene un contexto propio, herramientas limitadas y un modelo asignado. No comparte la ventana de contexto del agente principal.

La diferencia fundamental

Cuando Claude Code trabaja directamente sobre una tarea compleja, todo el razonamiento, la exploración del código, los errores de build, los intentos fallidos y los resultados intermedios se acumulan en el contexto principal. A medida que la tarea crece, el contexto se llena de ruido. Los tokens se gastan en información que ya no es útil.

Los agentes resuelven esto mediante delegación con aislamiento de contexto: el agente principal describe la tarea con precisión, el subagente la ejecuta en su propio espacio, y devuelve únicamente el resultado útil. El contexto principal recibe una respuesta concisa en lugar de cientos de líneas de exploración.

Cómo funciona el Task tool

Internamente, cuando Claude Code invoca un agente, utiliza el Task tool que:

1. Crea un nuevo hilo de ejecución con contexto vacío
2. Proporciona al subagente las herramientas autorizadas en su frontmatter
3. Ejecuta el modelo asignado (opus, sonnet o haiku)
4. Captura el output final del subagente
5. Devuelve ese output al agente orquestador

El subagente nunca ve la conversación completa del usuario. Solo recibe la instrucción específica que el orquestador le envía. Esto es por diseño: mantiene al subagente enfocado y al orquestador en control del contexto global.

Por qué los agentes son superiores al contexto monolítico

Enfoque	Costo de tokens	Calidad de resultado	Mantenibilidad
Todo en contexto principal	Alto (acumulación lineal)	Degradada al crecer	Difícil de debuggear
Agentes especializados	Bajo (aislamiento)	Alta (foco especializado)	Clara separación de responsabilidades
Agentes encadenados	Moderado (sumatorio)	Muy alta (especialización por fase)	Excelente (outputs como inputs)

Los agentes también permiten paralelismo: múltiples subagentes pueden ejecutarse en simultáneo para tareas independientes (por ejemplo, revisar seguridad y revisar código en paralelo), reduciendo el tiempo total de un workflow.

El modelo mental correcto

Piensa en los agentes de ECC como un equipo de especialistas senior en una empresa de software:

• El planner es el tech lead que diseña el roadmap antes de escribir una línea
• El architect es el arquitecto que asegura que las decisiones de diseño sean sólidas
• El tdd-guide es el QA senior que insiste en tests antes de código
• El code-reviewer es el senior developer que audita cada pull request
• El security-reviewer es el especialista en seguridad que busca vulnerabilidades
• El chief-of-staff es el CTO que orquesta a todo el equipo
• Los language reviewers son los expertos en cada stack tecnológico

Este equipo no trabaja en la misma reunión: cada uno recibe una tarea específica, la ejecuta con sus herramientas, y entrega un resultado concreto.

---

2. Anatomía Completa de un Agente

Un agente de ECC es un archivo Markdown con frontmatter YAML y un prompt de sistema en el cuerpo. La estructura es:

---
name: nombre-del-agente
description: Descripción que Claude usa para selección automática
tools: ["Tool1", "Tool2"]
model: opus | sonnet | haiku
---

Prompt de sistema del agente (instrucciones de comportamiento)

Cada campo tiene un rol preciso en cómo funciona el agente.

Campo: name

El name es el identificador único del agente en el sistema. Se usa para:

• Invocación directa: cuando el orquestador envía una tarea al agente por nombre
• Referencia en comandos slash: /plan activa al agente planner
• Logging y trazabilidad: los outputs de los agentes se identifican por nombre

Convenciones de naming en ECC:

• Nombres en minúsculas con guión: code-reviewer, build-error-resolver
• Nombres descriptivos del rol, no de la tecnología cuando son genéricos: planner, architect
• Nombres que incluyen el lenguaje cuando son específicos: go-reviewer, rust-build-resolver
• Nombres que describen la acción cuando son operacionales: loop-operator, doc-updater

El nombre nunca debe ser ambiguo. Un agente llamado reviewer es menos claro que code-reviewer porque no especifica qué tipo de review hace.

Campo: description

La descripción es el campo más importante para la selección automática de agentes. Claude lee la descripción de todos los agentes disponibles y decide cuál invocar basándose en la coincidencia semántica con la tarea del usuario.

Una buena descripción incluye:

1. Qué hace el agente (rol primario)
2. Cuándo usarlo (trigger conditions)
3. Palabras clave de activación (las que aparecerán en los mensajes del usuario)
4. Indicación de uso proactivo (si el agente debe activarse sin pedirlo explícitamente)

Ejemplo de descripción efectiva (del planner real):

Expert planning specialist for complex features and refactoring.
Use PROACTIVELY when users request feature implementation,
architectural changes, or complex refactoring.
Automatically activated for planning tasks.

Esta descripción activa el agente cuando el usuario dice frases como “quiero implementar”, “necesito hacer refactoring”, “voy a agregar una feature”, o “cómo estructuro esto”. Las palabras clave están distribuidas a lo largo de la descripción para maximizar la cobertura semántica.

Descripción ineficaz (anti-patrón):

Plans things.

Esta descripción es demasiado vaga. Claude no tiene suficiente contexto para saber cuándo activar el agente ni qué tipo de planning hace.

Campo: tools

El campo tools es una lista de herramientas a las que el agente tiene acceso. Esto define el scope de acción del agente: qué puede leer, escribir, ejecutar y buscar.

Lista completa de tools disponibles en Claude Code:

Tool	Descripción	Uso típico
Read	Lee archivos del filesystem	Leer código, configuración, documentación
Write	Escribe archivos nuevos	Crear nuevos archivos de código
Edit	Modifica archivos existentes	Aplicar cambios puntuales
Bash	Ejecuta comandos shell	Build, tests, instalación de dependencias
Grep	Búsqueda por patrones en código	Encontrar referencias, imports, usos
Glob	Búsqueda de archivos por patrón	Listar archivos de un tipo
Task	Invoca subagentes (solo orquestadores)	Delegar subtareas

Principio de mínimo privilegio: un agente debe tener solo las herramientas que necesita para su tarea. Un agente de planning (planner) solo necesita leer el código existente, no modificarlo. Por eso sus tools son ["Read", "Grep", "Glob"]. Si le das acceso a Write y Edit, el agente podría empezar a implementar en lugar de solo planificar, violando la separación de responsabilidades.

Tabla de tools por tipo de agente:

Tipo de agente	Tools apropiadas	Tools que NO debe tener
Planificación/Análisis	Read, Grep, Glob	Write, Edit, Bash
Review	Read, Grep, Glob, Bash (solo para lint)	Write, Edit
Implementación	Read, Write, Edit, Bash, Grep, Glob	(todas necesarias)
Build resolver	Read, Write, Edit, Bash, Grep	Glob (generalmente innecesario)
Orquestador	Task + todas las anteriores	(ninguna limitación)

Campo: model

El modelo determina la calidad del razonamiento y el costo por token. ECC usa tres opciones:

opus: El modelo más capaz de Anthropic. Razonamiento profundo, análisis de sistemas complejos, decisiones de arquitectura. Costo alto.

sonnet: Balance óptimo entre capacidad y costo. Suficiente para la mayoría de tareas de código. Revisiones, implementación, testing.

haiku: El modelo más rápido y económico. Para tareas mecánicas, búsquedas simples, formateo.

Guía de selección de modelo:

Tarea	Modelo recomendado	Justificación
Diseño de arquitectura	opus	Requiere razonamiento sistémico complejo
Planificación detallada	opus	Necesita anticipar dependencias y riesgos
Revisión de código	sonnet	Análisis local, patrones conocidos
Implementación TDD	sonnet	Mecánica conocida, foco en correctitud
Resolución de build errors	sonnet	Diagnóstico lineal, soluciones conocidas
Búsqueda de documentación	haiku	Recuperación, no razonamiento
Actualización de docs	sonnet	Escritura de calidad necesaria
E2E testing	sonnet	Scripts de automatización medianos
Security review	sonnet	Patrones de vulnerabilidad conocidos
Revisiones de lenguaje específico	sonnet	Reglas de estilo y patrones del lenguaje

Impacto en costo de un workflow completo:

Si un workflow tiene 5 agentes y todos usan opus, el costo es significativamente mayor que si solo los agentes de análisis estratégico usan opus y el resto usa sonnet. ECC asigna opus únicamente donde el razonamiento profundo justifica el costo adicional.

---

3. Los 28 Agentes de ECC: Guía Completa

ECC incluye 28 agentes especializados organizados en categorías funcionales. A continuación, la documentación completa de cada uno.

---

3.1 Agentes de Planificación y Arquitectura

planner

---
name: planner
description: Expert planning specialist for complex features and refactoring. Use PROACTIVELY when users request feature implementation, architectural changes, or complex refactoring. Automatically activated for planning tasks.
tools: ["Read", "Grep", "Glob"]
model: opus
---

Propósito: Generar planes de implementación detallados antes de escribir código. El planner analiza el codebase existente, entiende las dependencias, identifica los riesgos y produce un blueprint paso a paso que otros agentes pueden seguir.

Cuándo usarlo:

• Antes de implementar cualquier feature nueva de más de 2 horas de trabajo
• Cuando una tarea implica cambios en múltiples archivos
• Antes de un refactoring que afecta interfaces públicas
• Cuando hay incertidumbre sobre el impacto de un cambio

Cuándo NO usarlo:

• Para cambios de una sola línea o bugfixes triviales
• Cuando el path de implementación ya está completamente claro
• Para tareas de documentación pura

Output típico que produce:

# Implementation Plan: User Authentication with OAuth

## Overview
Integrar OAuth 2.0 con Google y GitHub usando NextAuth.js sobre
la infraestructura existente de Express + PostgreSQL.

## Requirements
- Usuarios pueden autenticarse con Google o GitHub
- Sesión persistente con JWT de 7 días
- Perfil de usuario se crea automáticamente en primer login

## Architecture Changes
- Nuevo módulo: src/auth/ (AuthService, OAuthProvider, SessionManager)
- Modificar: src/middleware/auth.ts para soporte JWT
- Nueva tabla: users con columns oauth_provider, oauth_id

## Implementation Steps

### Phase 1: Database Schema (1h)
1. **Crear migración users table** (File: db/migrations/001_users.sql)
   - Action: Agregar tabla con oauth_provider y oauth_id
   - Why: Persistir identidad OAuth
   - Dependencies: Ninguna
   - Risk: Bajo

### Phase 2: Auth Service (3h)
2. **Implementar OAuthProvider** (File: src/auth/OAuthProvider.ts)
   - Action: Wrapper para NextAuth providers
   - Why: Abstracción para múltiples providers
   - Dependencies: Phase 1 completada
   - Risk: Medio (OAuth flow puede tener edge cases)

## Testing Strategy
- Unit tests para AuthService con mocks de providers
- Integration tests para el flujo completo de login
- E2E test para login con Google (requiere credenciales de test)

## Risks & Mitigations
- Token refresh: implementar refresh automático antes de expiración
- CSRF: usar state parameter en OAuth flow

## Success Criteria
- Login con Google y GitHub funciona end-to-end
- Tests pasan con 80%+ cobertura
- No hay secretos hardcodeados

Ejemplo de invocación:

/plan "Agregar sistema de notificaciones push con Firebase"

Claude lee la descripción del planner, ve que contiene “planning tasks” y “feature implementation”, y automáticamente invoca el agente con el contexto de la tarea.

---

architect

---
name: architect
description: Software architecture specialist for system design, scalability, and technical decision-making. Use PROACTIVELY when planning new features, refactoring large systems, or making architectural decisions.
tools: ["Read", "Grep", "Glob"]
model: opus
---

Propósito: Tomar decisiones de diseño de sistemas con perspectiva de largo plazo. Mientras el planner se enfoca en los pasos de implementación, el architect se enfoca en la estructura del sistema: qué capas existen, cómo se comunican, dónde viven las responsabilidades, y qué trade-offs implica cada decisión.

Cuándo usarlo:

• Al diseñar un nuevo módulo o servicio desde cero
• Al evaluar opciones de diseño (monolito vs microservicios, REST vs GraphQL, etc.)
• Al refactorizar la estructura de capas de una aplicación
• Cuando el sistema tiene problemas de escalabilidad o mantenibilidad estructurales

Cuándo NO usarlo:

• Para decisiones de implementación específicas (esas van al planner)
• Para bugfixes o cambios puntuales
• Para code reviews (esas van al code-reviewer)

Output típico que produce: Un documento de decisión de arquitectura (ADR) con contexto, opciones consideradas, decisión tomada y consecuencias. Incluye diagramas Mermaid del sistema propuesto y análisis de trade-offs.

Diferencia con el planner: El architect decide la estructura, el planner decide los pasos. El architect responde “¿cómo debe estar organizado el sistema?”, el planner responde “¿cuáles son los pasos para implementar X en este sistema?”.

Ejemplo de invocación:

Necesito diseñar el sistema de pagos. ¿Cómo debería estructurarlo?

El architect analiza el codebase existente, evalúa opciones de diseño (abstracción sobre Stripe + PayPal vs integración directa, dominio de pagos separado vs integrado, etc.) y produce una recomendación argumentada.

---

3.2 Agentes de Desarrollo

tdd-guide

---
name: tdd-guide
description: Test-Driven Development specialist enforcing write-tests-first methodology. Use PROACTIVELY when writing new features, fixing bugs, or refactoring code. Ensures 80%+ test coverage.
tools: ["Read", "Write", "Edit", "Bash", "Grep"]
model: sonnet
---

Propósito: Asegurar que todo el código nuevo sigue la metodología TDD: primero se escribe el test que falla, luego el código mínimo que lo pasa, luego se refactoriza. El agente enforce este ciclo y no avanza a la implementación hasta que el test está escrito y falla por las razones correctas.

Cuándo usarlo:

• Al implementar cualquier feature nueva
• Al corregir un bug (el test documenta el bug antes del fix)
• Al refactorizar (los tests existentes protegen contra regresiones)
• Cuando la cobertura de tests está por debajo del 80%

Cuándo NO usarlo:

• Para tareas de análisis o planning puro
• Para configuración de infraestructura donde los tests son impracticables
• Para scripts one-off de migración de datos

El ciclo TDD que enforce:

graph LR
    A[Escribir test que falla] --> B[Verificar que falla por la razón correcta]
    B --> C[Escribir código mínimo que lo pasa]
    C --> D[Ejecutar tests]
    D --> E{¿Todos pasan?}
    E -->|No| C
    E -->|Sí| F[Refactorizar]
    F --> D

Output típico: Archivos de test creados, implementación que los pasa, reporte de cobertura final.

Ejemplo de invocación:

/tdd "Implementar la función calculateDiscount que aplica descuentos por volumen"

El agente primero escribe el test con casos de borde (descuento 0%, 10%, 20%, precio negativo), luego implementa la función, luego verifica que los tests pasan.

---

refactor-cleaner

---
name: refactor-cleaner
description: Code refactoring specialist for removing dead code, improving structure, and reducing technical debt. Use when codebase has accumulated technical debt or after completing features.
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: sonnet
---

Propósito: Limpiar el código sin cambiar su comportamiento observable. Elimina código muerto, consolida duplicados, mejora nombres de variables y funciones, extrae funciones largas en funciones más pequeñas, y aplica principios SOLID.

Cuándo usarlo:

• Después de completar una feature (cleanup de la implementación)
• Antes de empezar una nueva feature en un módulo con deuda técnica
• Cuando hay dead code evidente (funciones nunca llamadas, imports sin usar)
• Cuando las funciones superan las 50 líneas o los archivos superan las 150 líneas

Cuándo NO usarlo:

• Para cambios que alteran el comportamiento (eso requiere TDD)
• Para rediseño arquitectural (eso requiere architect)
• Cuando no hay tests que protejan el refactoring

Output típico: Lista de cambios aplicados con justificación, diff de los archivos modificados, confirmación de que los tests siguen pasando.

---

doc-updater

---
name: doc-updater
description: Documentation synchronization specialist. Updates README, API docs, and inline comments to match code changes. Use after implementing features or modifying APIs.
tools: ["Read", "Write", "Edit", "Grep", "Glob"]
model: sonnet
---

Propósito: Mantener la documentación sincronizada con el código. Analiza qué cambió en el código y actualiza los archivos de documentación correspondientes: README, docstrings, comentarios inline, documentación de API.

Cuándo usarlo:

• Después de implementar una feature que cambia la API pública
• Cuando el README no refleja el estado actual del proyecto
• Cuando hay funciones públicas sin docstrings
• Al final de un sprint de desarrollo

Cuándo NO usarlo:

• Para documentación de arquitectura (eso requiere el architect)
• Para generar documentación desde cero de un proyecto legacy sin contexto

Output típico: Archivos de documentación actualizados, lista de cambios aplicados.

---

3.3 Agentes de Review y Calidad

code-reviewer

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code. MUST BE USED for all code changes.
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

Propósito: Realizar una revisión exhaustiva del código modificado antes de hacer commit. Analiza calidad del código, adherencia a principios SOLID, posibles bugs, violaciones de estilo, y problemas de mantenibilidad.

Cuándo usarlo:

• Inmediatamente después de escribir o modificar código (según la descripción: MUST BE USED)
• Antes de hacer commit de cualquier cambio de código
• Al revisar PRs de otros desarrolladores
• Cuando hay dudas sobre la calidad de una implementación

Cuándo NO usarlo:

• Para reviews de seguridad específicas (esas van al security-reviewer)
• Para reviews de arquitectura (esas van al architect)
• Para reviews específicas de un lenguaje (esas van al reviewer del lenguaje)

Lo que revisa:

• Correctitud: ¿el código hace lo que dice que hace?
• Principios SOLID: ¿las responsabilidades están bien separadas?
• DRY: ¿hay duplicación que debería extraerse?
• Nombres: ¿variables, funciones y clases tienen nombres descriptivos?
• Complejidad: ¿hay funciones demasiado largas o complejas?
• Error handling: ¿los errores se manejan apropiadamente?
• Tests: ¿el código tiene tests adecuados?

Output típico:

## Code Review: src/auth/AuthService.ts

### Problemas críticos (bloquean merge)
- [Línea 45] Token almacenado en localStorage — XSS vulnerable. Usar HttpOnly cookie.

### Problemas importantes (deben resolverse)
- [Línea 23] Función `validateUser` tiene 3 responsabilidades: validar, hashear y guardar.
  Separar en `validateCredentials`, `hashPassword`, `persistUser`.

### Sugerencias (nice to have)
- [Línea 67] Nombre `u` poco descriptivo. Renombrar a `authenticatedUser`.

### Lo que está bien
- Manejo de errores consistente con custom exceptions
- Tests cubren casos de borde (email inválido, contraseña vacía)

---

security-reviewer

---
name: security-reviewer
description: Security vulnerability detection and remediation specialist. Use PROACTIVELY after writing code that handles user input, authentication, API endpoints, or sensitive data.
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: sonnet
---

Propósito: Detectar y remediar vulnerabilidades de seguridad. Se enfoca en el OWASP Top 10 y patrones de vulnerabilidad específicos del stack tecnológico en uso.

Cuándo usarlo:

• Después de escribir código que maneja input del usuario
• Al implementar autenticación o autorización
• Al crear o modificar endpoints de API
• Al manipular datos sensibles (contraseñas, tokens, PII)
• Antes de un release a producción

Cuándo NO usarlo:

• Para revisiones de calidad general (eso va al code-reviewer)
• Para análisis de arquitectura de seguridad de alto nivel (eso va al architect)

Vulnerabilidades que busca:

Categoría	Ejemplos específicos
Injection	SQL injection, NoSQL injection, Command injection
Broken Authentication	Tokens débiles, sesiones sin expiración, credenciales hardcodeadas
Sensitive Data Exposure	Datos en logs, HTTP en lugar de HTTPS, encryption débil
XXE	XML External Entity attacks
Broken Access Control	Falta de autorización, IDOR, path traversal
Security Misconfiguration	CORS permisivo, headers faltantes, error messages verbosos
XSS	Reflected, Stored, DOM-based
Insecure Deserialization	Deserialización de input no confiable
Known Vulnerabilities	Dependencias con CVEs conocidos
Insufficient Logging	Falta de audit trail para acciones críticas

Output típico: Lista de vulnerabilidades con severidad (Critical/High/Medium/Low), descripción del vector de ataque, y código de remediación concreto.

---

3.4 Agentes de Build y Testing

build-error-resolver

---
name: build-error-resolver
description: Generic build error resolver for any language. Diagnoses and fixes compilation errors, dependency conflicts, and configuration issues. Use when build fails.
tools: ["Read", "Write", "Edit", "Bash", "Grep"]
model: sonnet
---

Propósito: Diagnosticar y resolver errores de build de forma sistemática. Analiza el output del error, busca la causa raíz en el código y la configuración, y aplica la corrección.

Cuándo usarlo:

• Cuando npm run build, cargo build, go build, o cualquier build command falla
• Cuando hay errores de TypeScript que bloquean el desarrollo
• Cuando hay conflictos de dependencias
• Cuando la CI/CD pipeline falla en el paso de build

Proceso de diagnóstico:

graph TD
    A[Build falla] --> B[Capturar error completo]
    B --> C{¿Es error de tipo?}
    C -->|Sí| D[Buscar definición del tipo]
    C -->|No| E{¿Es error de dependencia?}
    E -->|Sí| F[Verificar package.json / lock file]
    E -->|No| G{¿Es error de configuración?}
    G -->|Sí| H[Revisar config files]
    G -->|No| I[Analizar stack trace]
    D --> J[Aplicar fix]
    F --> J
    H --> J
    I --> J
    J --> K[Ejecutar build de nuevo]
    K --> L{¿Pasó?}
    L -->|No| B
    L -->|Sí| M[Done]

Output típico: Descripción del problema encontrado, fix aplicado, confirmación de que el build pasa.

---

e2e-runner

---
name: e2e-runner
description: End-to-end testing specialist using Playwright. Writes and runs E2E tests for critical user flows. Use to verify that features work correctly from the user perspective.
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: sonnet
---

Propósito: Escribir y ejecutar tests end-to-end con Playwright que verifican los flujos críticos del usuario. Se enfoca en los happy paths y los failure modes más probables desde la perspectiva del usuario final.

Cuándo usarlo:

• Al completar una feature con interacción de UI significativa
• Antes de releases a producción
• Para documentar flujos críticos que no deben romperse
• Cuando hay regresiones reportadas en flujos de usuario

Cuándo NO usarlo:

• Para tests unitarios o de integración (esos van al tdd-guide)
• Para features sin UI (APIs puras, workers, etc.)

Output típico: Archivos de test Playwright escritos y ejecutados, reporte de qué tests pasan y cuáles fallan.

---

3.5 Agentes de Lenguaje Específico

ECC incluye reviewers y build resolvers para los lenguajes más usados. La filosofía es la misma en todos: el reviewer analiza calidad y estilo idiomático del lenguaje, el build resolver diagnostica errores de compilación.

---

go-reviewer

---
name: go-reviewer
description: Go code review specialist. Enforces Go idioms, error handling patterns, goroutine safety, and performance best practices. Use after writing Go code.
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

Propósito: Revisar código Go con foco en los idiomas específicos del lenguaje: error handling explícito, interface composition, goroutine safety, context propagation, y performance de allocations.

Lo que revisa específicamente:

• Error handling: ¿se verifican todos los errores? ¿se usan errors.Is y errors.As correctamente?
• Goroutines: ¿hay goroutine leaks? ¿se usa context para cancelación?
• Interfaces: ¿las interfaces son pequeñas (principio de mínima superficie)?
• Naming: ¿los nombres siguen las convenciones Go (MixedCaps, no snake_case)?
• Concurrency: ¿se usa sync.Mutex o channels apropiadamente?
• Memory: ¿hay allocations innecesarias en hot paths?

Cuándo usarlo: Después de escribir o modificar código Go.

Ejemplo de invocación:

Acabo de implementar el handler de autenticación en Go. Revísalo.

---

go-build-resolver

---
name: go-build-resolver
description: Go build error resolver. Fixes compilation errors, module issues, and dependency conflicts in Go projects. Use when go build or go test fails.
tools: ["Read", "Write", "Edit", "Bash", "Grep"]
model: sonnet
---

Propósito: Resolver errores específicos de go build, go test, y el sistema de módulos de Go (go.mod, go.sum). Maneja casos como conflictos de versiones en el módulo, imports faltantes, y errores de tipos específicos de Go.

Errores comunes que resuelve:

• undefined: nombre — import faltante o typo en identificador
• cannot use X as type Y — type mismatch en assignments o function calls
• imported and not used — imports no usados que Go no permite
• go.sum: missing module — problemas con el lock file de módulos

---

python-reviewer

---
name: python-reviewer
description: Python code review specialist. Enforces PEP 8, type hints, Pythonic patterns, and security best practices. Use after writing Python code.
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

Propósito: Revisar código Python con foco en PEP 8, type hints, patrones Pythonic, y seguridad. Verifica que el código sea legible, mantenible y eficiente.

Lo que revisa específicamente:

• PEP 8: naming conventions, line length, imports organizados
• Type hints: ¿las funciones tienen annotations de tipos?
• Patrones Pythonic: list comprehensions vs loops explícitos, context managers, generators
• Seguridad: eval/exec con input no confiable, pickle de datos externos, f-strings vs format
• Performance: operaciones en DataFrames, uso de generators vs lists

---

rust-reviewer

---
name: rust-reviewer
description: Rust code review specialist. Reviews ownership, lifetimes, error handling with Result/Option, and unsafe code blocks. Use after writing Rust code.
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

Propósito: Revisar código Rust con foco en ownership, lifetimes, error handling y uso correcto de unsafe. Garantiza que el código es idiomático, eficiente y seguro.

Lo que revisa específicamente:

• Ownership: ¿hay clones innecesarios que podrían ser references?
• Error handling: ¿se usa ? operator correctamente? ¿tipos de error apropiados?
• Lifetimes: ¿las lifetime annotations son correctas y mínimas?
• Unsafe: ¿los bloques unsafe tienen justificación y comentario?
• Traits: ¿se implementan los traits estándar apropiados (Debug, Clone, Display)?
• Performance: ¿se evitan allocations innecesarias?

---

rust-build-resolver

---
name: rust-build-resolver
description: Rust build error resolver. Diagnoses and fixes Rust compilation errors, borrow checker violations, and Cargo dependency issues. Use when cargo build fails.
tools: ["Read", "Write", "Edit", "Bash", "Grep"]
model: sonnet
---

Propósito: Resolver los errores específicos del compilador Rust y del borrow checker. Los errores de Rust son famosos por ser verbosos pero informativos; este agente los interpreta y aplica las correcciones necesarias.

Errores comunes que resuelve:

• Borrow checker violations: uso de referencia inválida, movimiento después de borrow
• Lifetime errors: lifetimes que no coinciden en function signatures
• Trait bound errors: tipo que no implementa un trait requerido
• Cargo errors: conflictos de features, versiones incompatibles de crates

---

typescript-reviewer

---
name: typescript-reviewer
description: TypeScript code review specialist. Enforces strict typing, reviews generics usage, and ensures type safety. Use after writing TypeScript code.
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

Propósito: Revisar código TypeScript con foco en type safety, uso correcto de generics, y patrones avanzados del sistema de tipos. Asegura que el código no tenga any innecesarios ni type assertions incorrectas.

Lo que revisa específicamente:

• any types: detectar y reemplazar con tipos específicos
• Type assertions: as Type peligrosos sin type guards
• Generics: uso correcto de constraints (T extends ...)
• Utility types: Partial, Required, Pick, Omit usados apropiadamente
• Strict null checks: manejo correcto de undefined y null
• Return types: funciones con return types explícitos

---

java-reviewer

---
name: java-reviewer
description: Java code review specialist. Reviews for SOLID principles, Spring patterns, proper exception handling, and Java idioms. Use after writing Java code.
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

Propósito: Revisar código Java con foco en principios SOLID, patrones de Spring Framework, manejo de excepciones, y código idiomático moderno (Java 11+).

Lo que revisa:

• SOLID: separación de responsabilidades, inversión de dependencias con Spring
• Exception handling: checked vs unchecked exceptions, no swallow de excepciones
• Java moderno: Stream API, Optional, records, pattern matching
• Spring: uso correcto de @Transactional, lazy loading, circular dependencies
• Concurrency: uso seguro de shared state

---

java-build-resolver

---
name: java-build-resolver
description: Java build error resolver for Maven and Gradle projects. Fixes compilation errors, dependency conflicts, and Spring context issues. Use when Maven or Gradle build fails.
tools: ["Read", "Write", "Edit", "Bash", "Grep"]
model: sonnet
---

Propósito: Resolver errores de build de proyectos Java con Maven o Gradle, incluyendo conflictos de dependencias, errores del Spring Application Context, y problemas de configuración.

---

kotlin-reviewer

---
name: kotlin-reviewer
description: Kotlin code review specialist. Reviews coroutines usage, null safety, extension functions, and Android/JVM best practices. Use after writing Kotlin code.
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

Propósito: Revisar código Kotlin con foco en null safety, coroutines, extension functions, y patrones idiomáticos del lenguaje.

Lo que revisa:

• Null safety: uso de ?., !!, y manejo de nullables
• Coroutines: scope correcto, structured concurrency, manejo de errores en coroutines
• Extension functions: uso apropiado vs herencia o composition
• Data classes: uso correcto para POJOs/Value Objects
• Sealed classes: modelado correcto de estados con sealed

---

kotlin-build-resolver

---
name: kotlin-build-resolver
description: Kotlin build error resolver for Gradle projects. Fixes Kotlin compilation errors, Gradle DSL issues, and Android build problems. Use when Kotlin/Android build fails.
tools: ["Read", "Write", "Edit", "Bash", "Grep"]
model: sonnet
---

Propósito: Resolver errores de compilación de Kotlin y problemas del build system Gradle, incluyendo errores específicos de Android (manifest merges, resource conflicts, ProGuard).

---

cpp-reviewer

---
name: cpp-reviewer
description: C++ code review specialist. Reviews for memory management, RAII patterns, modern C++ idioms (C++17/20), and undefined behavior. Use after writing C++ code.
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

Propósito: Revisar código C++ con foco en memory safety, RAII, C++ moderno (C++17/20) y evitar comportamiento indefinido.

Lo que revisa:

• Memory management: raw pointers vs smart pointers, leaks potenciales
• RAII: recursos manejados correctamente con constructores/destructores
• C++ moderno: auto, range-for, structured bindings, std::variant, std::optional
• Undefined behavior: signed overflow, out-of-bounds, null dereference
• Move semantics: uso correcto de std::move y rvalue references

---

cpp-build-resolver

---
name: cpp-build-resolver
description: C++ build error resolver for CMake projects. Fixes compilation errors, linker errors, and CMakeLists.txt issues. Use when CMake or g++/clang++ build fails.
tools: ["Read", "Write", "Edit", "Bash", "Grep"]
model: sonnet
---

Propósito: Resolver errores de compilación de C++ y problemas de configuración de CMake, incluyendo errores de linker (undefined symbols, multiple definitions) y conflictos de ABI.

---

flutter-reviewer

---
name: flutter-reviewer
description: Flutter/Dart code review specialist. Reviews widget tree efficiency, state management patterns, and Dart idioms. Use after writing Flutter code.
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

Propósito: Revisar código Flutter y Dart con foco en eficiencia del widget tree, patrones de state management (Riverpod, Bloc, Provider) y performance de renderizado.

Lo que revisa:

• Widget tree: widgets innecesariamente stateful, rebuilds excesivos
• State management: uso correcto del patrón elegido (Riverpod/Bloc/Provider)
• Performance: const constructors, RepaintBoundary, lazy loading en listas
• Dart idioms: null safety, async/await, extension methods
• Accesibilidad: Semantics widgets donde corresponde

---

pytorch-build-resolver

---
name: pytorch-build-resolver
description: PyTorch and Python ML build error resolver. Fixes CUDA errors, dependency conflicts between torch/numpy/scipy, and environment issues. Use when PyTorch training or inference fails.
tools: ["Read", "Write", "Edit", "Bash", "Grep"]
model: sonnet
---

Propósito: Resolver problemas específicos de entornos de Machine Learning con PyTorch, incluyendo errores de CUDA, incompatibilidades entre versiones de torch/numpy/scipy, y problemas de entorno virtual.

---

3.6 Agentes de Documentación y Búsqueda

docs-lookup

---
name: docs-lookup
description: Documentation lookup specialist. Searches and retrieves information from project documentation, README files, and inline comments. Use when needing context about the project.
tools: ["Read", "Grep", "Glob"]
model: haiku
---

Propósito: Buscar y recuperar información de la documentación del proyecto. A diferencia de otros agentes que razonan, este agente es principalmente de recuperación: encuentra la información relevante y la devuelve.

Por qué usa haiku: La recuperación de documentación no requiere razonamiento complejo. Haiku es suficientemente capaz para buscar, leer y resumir documentación, y es significativamente más económico que sonnet u opus.

Cuándo usarlo:

• Al empezar a trabajar en un proyecto nuevo para obtener contexto
• Para verificar convenciones de código antes de implementar
• Para encontrar la documentación de una API interna

---

3.7 Agentes de Operaciones

chief-of-staff

---
name: chief-of-staff
description: High-level orchestrator for complex multi-agent workflows. Coordinates other agents sequentially or in parallel to complete large tasks. Use for tasks that require multiple specialized agents.
tools: ["Task", "Read", "Write", "Bash", "Grep", "Glob"]
model: opus
---

Propósito: Orquestar workflows complejos que requieren múltiples agentes especializados. El chief-of-staff es el único agente que tiene acceso al Task tool y puede invocar otros agentes.

Por qué usa opus: La orquestación requiere razonamiento sobre dependencias entre tareas, decisiones sobre paralelismo vs secuencial, y evaluación de los outputs de cada agente para decidir si son suficientes o si necesitan refinamiento.

Cuándo usarlo:

• Para workflows que involucran 3 o más agentes especializados
• Cuando las fases tienen dependencias complejas entre sí
• Para tareas de largo alcance que duran múltiples sesiones
• Para procesos que necesitan coordinación de múltiples especialistas

Cuándo NO usarlo:

• Para tareas que puede manejar un solo agente especializado
• Para workflows simples de 2 pasos (mejor hacerlos manualmente)

El chief-of-staff conoce el orden correcto de los agentes:

graph LR
    A[chief-of-staff] --> B[architect]
    A --> C[planner]
    A --> D[tdd-guide]
    A --> E[code-reviewer]
    A --> F[security-reviewer]
    A --> G[doc-updater]
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G

Output típico: Reporte final consolidado con los outputs de todos los agentes invocados, estado de cada fase, y resumen de lo que se completó.

Diferencia con el modo Agent de Claude Code: El chief-of-staff es el orquestador dentro de ECC. El modo Agent de Claude Code es el contexto en el que todo esto se ejecuta. El chief-of-staff vive dentro del modo Agent.

---

loop-operator

---
name: loop-operator
description: Autonomous loop operator for repetitive tasks. Iterates over collections (files, test cases, items) applying a consistent operation to each. Use for batch operations.
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: sonnet
---

Propósito: Ejecutar operaciones repetitivas de forma autónoma sobre una colección de items. En lugar de que el usuario supervise cada iteración, el loop-operator procesa todos los items y reporta los resultados.

Casos de uso típicos:

• Aplicar el mismo fix a todos los archivos de un tipo
• Agregar docstrings a todas las funciones públicas sin documentar
• Correr el code-reviewer sobre todos los archivos modificados en un PR
• Actualizar la versión de una dependencia en todos los package.json de un monorepo
• Aplicar una transformación de código a todos los archivos de un directorio

Cuándo NO usarlo:

• Para tareas donde cada item requiere decisiones diferentes
• Cuando las iteraciones tienen dependencias entre sí
• Para colecciones pequeñas (menos de 3 items, mejor hacerlo directo)

Output típico: Lista de items procesados, resultado de cada uno (éxito/fallo/skip), y resumen final.

---

harness-optimizer

---
name: harness-optimizer
description: Test harness optimizer for CI/CD pipelines. Analyzes test execution times, identifies slow tests, and optimizes test suite configuration for faster feedback cycles.
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: sonnet
---

Propósito: Analizar y optimizar el test harness de CI/CD para reducir el tiempo de feedback. Identifica tests lentos, analiza el paralelismo posible, sugiere y aplica optimizaciones en la configuración del pipeline.

Cuándo usarlo:

• Cuando los pipelines de CI tardan más de 10 minutos
• Cuando hay tests con timeouts frecuentes
• Al configurar un pipeline de CI por primera vez
• Cuando se agrega una nueva suite de tests y el pipeline se ralentiza significativamente

Lo que analiza:

• Tiempos de ejecución de cada test suite
• Tests que se ejecutan secuencialmente pero podrían paralelizarse
• Tests con setup/teardown costoso que podría compartirse
• Dependencias entre tests que impiden paralelismo
• Configuración de workers y concurrencia

Output típico: Reporte de bottlenecks identificados, cambios en la configuración del pipeline aplicados, estimación de mejora en tiempo de ejecución.

---

database-reviewer

---
name: database-reviewer
description: Database and query review specialist. Reviews SQL queries for performance, security (SQL injection), and correctness. Also reviews Supabase RLS policies and schema design.
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

Propósito: Revisar queries SQL, migraciones de base de datos y políticas de Row Level Security (RLS) en Supabase. Se enfoca en performance de queries, seguridad contra SQL injection, y correctitud del schema.

Lo que revisa:

• Performance: índices faltantes, N+1 queries, full table scans innecesarios
• Seguridad: SQL injection en queries dinámicas, RLS policies correctas en Supabase
• Schema: normalización apropiada, naming conventions, constraints correctos
• Migraciones: reversibilidad, impacto en producción (locking de tablas)

Cuándo usarlo:

• Después de escribir nuevas queries SQL complejas
• Al crear o modificar migraciones de base de datos
• Al configurar RLS en Supabase
• Cuando hay problemas de performance en queries existentes

---

4. Patrones de Delegación

Hay tres modos en los que un agente puede ser invocado en ECC.

4.1 Delegación Directa

El orquestador (ya sea el usuario en modo Agent o el chief-of-staff) invoca explícitamente un agente por nombre con un input específico.

Task: "Usa el agente planner para crear un plan de implementación para
el sistema de notificaciones. El codebase está en /src. Los requisitos son:
notificaciones push para mobile, email para desktop, preferencias por usuario."

En la delegación directa, el orquestador:

1. Selecciona el agente específico
2. Proporciona el input completo con contexto
3. Espera el output
4. Evalúa si el output es suficiente o requiere refinamiento

Cuándo usar delegación directa: Cuando sabes exactamente qué agente necesitas y tienes el contexto completo de la tarea.

4.2 Delegación por Comando

Los comandos slash (/plan, /tdd, /code-review, etc.) son atajos que activan agentes predefinidos. No requieren que el usuario conozca el nombre del agente.

/plan "Agregar sistema de pagos con Stripe"

Internamente esto se traduce en una invocación del agente planner con el argumento como descripción de la tarea. Los comandos slash están configurados en el archivo de configuración de ECC y mapean a agentes específicos.

Cuándo usar delegación por comando: Para las operaciones más frecuentes donde el mapeo comando→agente es claro y consistente.

4.3 Delegación Automática (Activación Proactiva)

Claude lee las descripciones de todos los agentes disponibles y activa automáticamente el más relevante basándose en el contexto de la conversación. No requiere ningún comando explícito del usuario.

Cuando el usuario dice:

“Quiero implementar un sistema de cache en Redis”

Claude analiza las descripciones de los agentes y encuentra coincidencias semánticas:

• planner: “feature implementation” ✓
• architect: “planning new features” ✓

Activa el planner (más específico para el caso de implementación concreta) automáticamente.

Por qué funciona: Las descripciones de los agentes en ECC incluyen intencionalmente frases que coinciden con el lenguaje natural del usuario. “Use PROACTIVELY when users request feature implementation” hace que Claude active el agente sin que el usuario lo pida.

Ventaja de la activación proactiva: El usuario puede trabajar de forma natural sin tener que recordar qué agente usar en cada situación. ECC opera en segundo plano seleccionando el especialista apropiado.

---

5. Workflows de Agentes Encadenados

Los agentes cobran su mayor valor cuando se encadenan en workflows donde el output de un agente se convierte en el input del siguiente.

Regla fundamental: Los outputs intermedios se almacenan en archivos. Cada agente produce un artifact específico que el siguiente agente consume.

5.1 Feature Development Workflow

El workflow más completo para implementar una nueva feature de forma robusta.

sequenceDiagram
    participant U as Usuario
    participant CS as chief-of-staff
    participant AR as architect
    participant PL as planner
    participant TDD as tdd-guide
    participant CR as code-reviewer
    participant SR as security-reviewer
    participant DU as doc-updater

    U->>CS: "Implementar sistema de autenticación OAuth"
    CS->>AR: Diseñar arquitectura del módulo auth
    AR-->>CS: architecture-decision.md
    CS->>PL: Crear plan basado en architecture-decision.md
    PL-->>CS: implementation-plan.md
    CS->>TDD: Implementar siguiendo implementation-plan.md
    TDD-->>CS: código + tests
    CS->>CR: Revisar código producido
    CR-->>CS: review-comments.md
    CS->>TDD: Aplicar correcciones de review-comments.md
    TDD-->>CS: código corregido
    CS->>SR: Auditar seguridad del módulo auth
    SR-->>CS: security-report.md
    CS->>DU: Actualizar docs con cambios implementados
    DU-->>CS: docs actualizadas
    CS-->>U: Reporte final consolidado

Inputs y outputs de cada fase:

Fase	Agente	Input	Output
1. Arquitectura	architect	Descripción del requisito, codebase actual	architecture-decision.md
2. Planning	planner	architecture-decision.md, codebase	implementation-plan.md
3. Implementación	tdd-guide	implementation-plan.md	código + tests
4. Review	code-reviewer	Código producido	review-comments.md
5. Fix	tdd-guide	review-comments.md	código corregido
6. Seguridad	security-reviewer	Módulo de auth completo	security-report.md
7. Docs	doc-updater	Cambios implementados	docs actualizadas

---

5.2 Bug Fix Workflow

Workflow optimizado para corregir bugs de forma robusta y documentada.

sequenceDiagram
    participant U as Usuario
    participant TDD as tdd-guide
    participant CR as code-reviewer
    participant BER as build-error-resolver

    U->>TDD: "El cálculo de descuento es incorrecto para órdenes > $1000"
    TDD->>TDD: Escribir test que reproduce el bug
    TDD->>TDD: Verificar que el test FALLA
    TDD->>TDD: Implementar el fix mínimo
    TDD->>TDD: Verificar que el test PASA
    TDD-->>U: fix + test
    U->>CR: Revisar el fix
    CR-->>U: review-comments.md
    alt Si hay errores de build
        U->>BER: Error: "cannot find module..."
        BER-->>U: fix aplicado, build pasa
    end

Lo que hace el TDD cycle antes del fix: Escribir un test que reproduce exactamente el bug garantiza que:

1. Entendemos correctamente el bug (el test lo documenta)
2. El fix realmente lo resuelve (el test lo verifica)
3. El bug no vuelve en el futuro (el test actúa como regression test)

---

5.3 Security Audit Workflow

Workflow para una auditoría de seguridad completa antes de un release.

sequenceDiagram
    participant U as Usuario
    participant SR as security-reviewer
    participant CR as code-reviewer
    participant DBR as database-reviewer
    participant E2E as e2e-runner

    U->>SR: "Auditar módulo de pagos antes del release"
    SR->>SR: Analizar todos los endpoints de pagos
    SR->>SR: Verificar manejo de datos de tarjeta
    SR->>SR: Revisar autenticación y autorización
    SR-->>U: security-report.md (vulnerabilidades encontradas)
    U->>CR: Revisar fixes de las vulnerabilidades
    CR-->>U: review aprobado
    U->>DBR: Revisar queries de transacciones
    DBR-->>U: SQL injection check, índices correctos
    U->>E2E: Correr tests de flujos críticos de pago
    E2E-->>U: reporte de tests E2E

Qué revisa la security-reviewer en el módulo de pagos:

• ¿Los datos de tarjeta nunca se logean?
• ¿La comunicación con el payment processor es HTTPS con certificate pinning?
• ¿Los webhooks de Stripe verifican la firma?
• ¿Los endpoints de pago requieren autenticación?
• ¿El amount se valida server-side (nunca confiar en el cliente)?

---

5.4 Refactoring Workflow

Workflow para refactorizar código con deuda técnica sin romper funcionalidad existente.

sequenceDiagram
    participant U as Usuario
    participant AR as architect
    participant RC as refactor-cleaner
    participant CR as code-reviewer
    participant TDD as tdd-guide

    U->>AR: "El módulo de users tiene 800 líneas, necesita refactoring"
    AR->>AR: Analizar estructura actual
    AR->>AR: Diseñar nueva estructura con responsabilidades claras
    AR-->>U: refactoring-plan.md
    U->>TDD: Asegurar cobertura de tests antes del refactoring
    TDD-->>U: tests escritos (coverage 80%+)
    U->>RC: Aplicar refactoring siguiendo refactoring-plan.md
    RC->>RC: Extraer funciones, separar responsabilidades
    RC->>RC: Verificar que tests siguen pasando
    RC-->>U: código refactorizado
    U->>CR: Revisar el refactoring
    CR-->>U: review aprobado / cambios sugeridos

Orden crítico: Los tests SIEMPRE van antes del refactoring. Sin tests que protejan el comportamiento existente, el refactoring puede introducir regresiones silenciosas.

---

5.5 Release Preparation Workflow

Workflow completo para preparar un release a producción.

sequenceDiagram
    participant U as Usuario
    participant SR as security-reviewer
    participant E2E as e2e-runner
    participant CR as code-reviewer
    participant HO as harness-optimizer
    participant DU as doc-updater

    U->>SR: Auditoría de seguridad completa
    SR-->>U: security-report.md
    U->>E2E: Correr suite completa de E2E tests
    E2E-->>U: reporte de E2E (todos los flujos críticos)
    U->>CR: Review final del diff del release
    CR-->>U: review aprobado
    U->>HO: Optimizar pipeline de CI para el release
    HO-->>U: pipeline optimizado
    U->>DU: Actualizar CHANGELOG y docs de release
    DU-->>U: CHANGELOG.md actualizado

---

6. El Problema del Contexto del Sub-Agente

El problema

Cuando el orquestador invoca un subagente, este solo recibe la instrucción literal que le envía el orquestador. No tiene acceso a la conversación completa, al contexto del usuario, ni a las decisiones previas del workflow.

Ejemplo del problema:

El usuario dice: “Revisa el módulo de autenticación con énfasis en que somos una aplicación médica y los datos deben cumplir HIPAA.”

El orquestador invoca al security-reviewer con: “Revisa el módulo de autenticación.”

El security-reviewer hace una revisión genérica, sin saber que el contexto HIPAA requiere audit logs específicos, encryption at rest obligatoria, y timeout de sesiones más agresivo.

El subagente solo conoce la query literal, no el propósito detrás de la query.

El Iterative Retrieval Pattern

La solución es que el orquestador pase contexto semántico suficiente en la instrucción al subagente, y evalúe si el output del subagente es suficiente antes de aceptarlo.

graph TD
    A[Orquestador envía tarea con contexto completo] --> B[Subagente ejecuta y devuelve resultado]
    B --> C{Orquestador evalúa calidad del resultado}
    C -->|Suficiente| D[Aceptar y continuar]
    C -->|Insuficiente| E[Formular pregunta de seguimiento]
    E --> F[Subagente vuelve a la fuente y responde]
    F --> C
    style C fill:#f9a,stroke:#333

Reglas del Iterative Retrieval Pattern:

1. El orquestador evalúa SIEMPRE cada output del subagente antes de aceptarlo
2. Máximo 3 ciclos de refinamiento por subagente
3. El contexto se pasa en la instrucción, no se asume que el subagente lo infiere
4. Las preguntas de seguimiento son específicas, no genéricas (“¿qué falta?”)

Ejemplo correcto de instrucción con contexto

Mal (sin contexto):

Revisa el módulo de autenticación para detectar vulnerabilidades.

Bien (con contexto semántico):

Revisa el módulo de autenticación en src/auth/ para detectar vulnerabilidades.
CONTEXTO IMPORTANTE:
- Esta es una aplicación médica que debe cumplir HIPAA
- Los requisitos HIPAA relevantes para auth son:
  1. Audit logs de todos los accesos con timestamp y user ID
  2. Timeout de sesión automático a los 15 minutos de inactividad
  3. Encryption at rest para todos los tokens almacenados
  4. MFA obligatorio para usuarios con rol "clinical"
- Revisar específicamente si estos 4 requisitos están implementados.

Con este contexto, el security-reviewer puede hacer una auditoría relevante para el dominio del sistema, no solo una auditoría genérica.

El ciclo de refinamiento en la práctica

Ciclo 1:
  Orquestador → "Revisa auth module con contexto HIPAA"
  Security-reviewer → "Encontré 3 vulnerabilidades XSS y 1 SQL injection"
  Orquestador evalúa → "El reporte no menciona HIPAA compliance. Insuficiente."

Ciclo 2:
  Orquestador → "El reporte no cubre HIPAA. ¿Los 4 requisitos HIPAA están implementados?
                 Específicamente: audit logs, session timeout, encryption, MFA para clinical"
  Security-reviewer → "Audit logs: presentes. Session timeout: falta.
                       Encryption at rest: falta. MFA para clinical: presente."
  Orquestador evalúa → "Ahora sí es suficiente. Aceptar."

Ciclo 3 (si fuera necesario):
  Orquestador → "Para session timeout y encryption at rest,
                 proporciona el código concreto de remediación"
  Security-reviewer → código de remediación específico
  Orquestador evalúa → "Completo. Aceptar."

---

7. Selección de Modelo por Tarea

La selección del modelo tiene impacto directo en costo y calidad. Esta tabla resume las reglas de ECC:

Tabla completa de selección

Tipo de tarea	Haiku	Sonnet	Opus
Búsqueda y recuperación de información	✓ preferido	OK	Excesivo
Formateo y transformación mecánica	✓ preferido	OK	Excesivo
Code review estándar	No adecuado	✓ preferido	OK
Implementación TDD	No adecuado	✓ preferido	OK
Resolución de build errors	No adecuado	✓ preferido	OK
Refactoring	No adecuado	✓ preferido	OK
Security review	No adecuado	✓ preferido	OK
E2E test writing	No adecuado	✓ preferido	OK
Language-specific review	No adecuado	✓ preferido	OK
Planificación de features	No adecuado	Puede funcionar	✓ preferido
Decisiones de arquitectura	No adecuado	Puede funcionar	✓ preferido
Orquestación compleja	No adecuado	No adecuado	✓ preferido
Análisis de sistemas legacy	No adecuado	No adecuado	✓ preferido

Cuándo la diferencia entre sonnet y opus importa más

Usa opus cuando:

• La tarea requiere razonamiento sobre trade-offs complejos con consecuencias de largo plazo
• Hay múltiples opciones igualmente válidas y la decisión correcta requiere contexto profundo
• El error en el análisis tendría un costo alto de corrección
• El sistema tiene muchas interdependencias que deben considerarse simultáneamente

Sonnet es suficiente cuando:

• Los patrones son conocidos y la tarea es aplicarlos
• El error es fácilmente detectable y corregible
• La tarea tiene un output bien definido (escribir tests, resolver un error de tipo)
• El contexto requerido es local (un archivo o un módulo)

---

8. Costo de los Agentes

Cómo calcular el costo de un workflow

El costo total de un workflow con agentes es la suma del costo de cada agente invocado:

costo_total = Σ (tokens_input_agente_i × precio_input_modelo_i) +
                (tokens_output_agente_i × precio_output_modelo_i)

Cada agente tiene su propio contexto, por lo que los tokens no se acumulan en una sola ventana. Esto es una ventaja clave sobre el modo de contexto monolítico.

Ejemplo: Feature Development Workflow completo

Asumiendo precios aproximados (verificar precios actuales en la documentación de Anthropic):

Agente	Modelo	Tokens input estimados	Tokens output estimados	Costo aprox.
architect	opus	8,000	2,000	Alto
planner	opus	10,000	3,000	Alto
tdd-guide	sonnet	12,000	4,000	Medio
code-reviewer	sonnet	8,000	2,000	Medio-bajo
security-reviewer	sonnet	6,000	1,500	Medio-bajo
doc-updater	sonnet	4,000	1,000	Bajo

La suma es significativa pero menor a tener todo el workflow en un solo contexto de opus donde los tokens se acumulan linealmente y la degradación de calidad requiere retrabajos adicionales.

Estrategia de optimización de costos

1. Reservar opus para planning y arquitectura: Las fases iniciales donde las decisiones son de mayor impacto justifican el costo de opus.

2. Usar sonnet para la ejecución: La implementación, reviews y resolución de errores son mecánicas suficientemente conocidas para sonnet.

3. Ser preciso en los inputs: Cuantos menos tokens innecesarios se pasen a cada agente, menor el costo. No pasar el codebase completo si el agente solo necesita un módulo específico.

4. Limitar el Iterative Retrieval: Máximo 3 ciclos. Si después de 3 ciclos el output no es satisfactorio, el problema es de diseño del workflow, no de tokens adicionales.

5. Paralelizar cuando es posible: El code-reviewer y el security-reviewer pueden correr en paralelo sobre el mismo código. El costo es el mismo pero el tiempo se reduce.

---

9. Crear un Agente Propio

Si los 28 agentes de ECC no cubren tu caso de uso, puedes crear agentes propios.

Template de agente

---
name: nombre-del-agente
description: [Qué hace el agente]. [Cuándo usarlo: trigger conditions].
             Use PROACTIVELY when [keywords de activación automática].
tools: ["Tool1", "Tool2"]
model: sonnet
---

Eres un especialista en [dominio del agente].

## Tu responsabilidad

[Descripción clara de qué hace este agente y qué NO hace]

## Proceso

1. [Primer paso del agente]
2. [Segundo paso]
3. [Tercer paso]

## Output esperado

[Formato exacto del output que debe producir el agente]

## Lo que NUNCA debes hacer

- [Restricción 1]
- [Restricción 2]

Guía paso a paso para crear un agente

Paso 1: Definir el dominio claramente

Antes de escribir el agente, responde:

• ¿Qué tarea específica hace este agente que ningún otro agente hace?
• ¿Cuáles son los inputs típicos?
• ¿Cuáles son los outputs esperados?
• ¿Qué herramientas necesita para completar su tarea?

Paso 2: Elegir el modelo correcto

Usa la tabla de selección de modelo de la sección 7. Para la mayoría de agentes nuevos, sonnet es el punto de partida correcto. Escala a opus solo si después de pruebas sonnet produce outputs insuficientes.

Paso 3: Escribir la descripción para activación proactiva

La descripción debe incluir:

• El rol primario (1 oración)
• Las condiciones de activación (cuándo usarlo)
• Palabras clave del lenguaje natural del usuario que deben dispararlo
• “Use PROACTIVELY when…” para activación automática

Paso 4: Definir tools con mínimo privilegio

• ¿El agente necesita leer archivos? → Read
• ¿Necesita buscar en el código? → Grep, Glob
• ¿Necesita escribir o modificar archivos? → Write, Edit
• ¿Necesita ejecutar comandos? → Bash
• ¿Es un orquestador? → Task

No agregues tools que “podrían ser útiles”. Solo las estrictamente necesarias.

Paso 5: Escribir el prompt del sistema

El prompt del sistema debe ser:

• Conciso: menos de 100 líneas
• Específico: describe exactamente qué hace el agente
• Restrictivo: dice explícitamente qué NO debe hacer
• Con formato de output: especifica exactamente cómo debe formatear la respuesta

Paso 6: Crear el archivo

# En el directorio de agentes de ECC
touch ~/.claude/agents/mi-agente.md

Paso 7: Probar el agente

# Invocar directamente para verificar comportamiento
Task: "Usa el agente mi-agente para [tarea de prueba]"

Verificar que:

• El agente hace lo que se esperaba
• No hace cosas que no debería
• El formato del output es el esperado
• Los tools requeridos son suficientes

Ejemplo: Agente para revisión de contratos GraphQL

---
name: graphql-reviewer
description: GraphQL schema and resolver review specialist. Reviews schema design, resolver efficiency, and N+1 problem detection. Use PROACTIVELY after writing GraphQL schemas or resolvers.
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

Eres un especialista en GraphQL con foco en schema design y performance.

## Tu responsabilidad

Revisar schemas de GraphQL y sus resolvers para detectar:
1. Problemas de N+1 queries (resolvers sin DataLoader)
2. Tipos no utilizados en el schema
3. Campos que exponen datos innecesariamente
4. Falta de pagination en listas potencialmente largas
5. Falta de depth limiting y complexity limits

## Proceso

1. Leer el archivo de schema (.graphql o schema definido en código)
2. Leer los resolvers asociados
3. Identificar cada problema con número de línea
4. Proporcionar el fix concreto para cada problema

## Output esperado

```markdown
## GraphQL Review: [archivo revisado]

### Problemas críticos
- [Línea X] N+1 query en resolver `User.posts`: usar DataLoader

### Problemas importantes
- [Línea Y] Campo `internalId` expuesto en tipo público `User`

### Sugerencias
- [Línea Z] Tipo `OldFeatureType` definido pero nunca consultado

Lo que NUNCA debes hacer

• No modificar el schema sin aprobación explícita
• No hacer recomendaciones de arquitectura general (eso es del architect)

---

## 10. Agentes por Lenguaje: Guía de Uso

### Cuándo usar el reviewer vs el build resolver

Para cada lenguaje hay dos tipos de agentes:
- **Reviewer** (`*-reviewer`): para code review DESPUÉS de escribir código
- **Build resolver** (`*-build-resolver`): para resolver errores de compilación

No son intercambiables. El reviewer analiza código que compila. El build resolver trabaja sobre código que no compila.

### Tabla de agentes por lenguaje

| Lenguaje | Reviewer | Build Resolver | Cuándo usar build resolver |
|----------|----------|---------------|--------------------------|
| Go | `go-reviewer` | `go-build-resolver` | `go build` o `go test` falla |
| Python | `python-reviewer` | (usa build-error-resolver genérico) | ImportError, SyntaxError |
| Rust | `rust-reviewer` | `rust-build-resolver` | `cargo build` falla |
| TypeScript | `typescript-reviewer` | (usa build-error-resolver genérico) | `tsc` o bundler falla |
| Java | `java-reviewer` | `java-build-resolver` | Maven/Gradle falla |
| Kotlin | `kotlin-reviewer` | `kotlin-build-resolver` | Gradle build falla |
| C++ | `cpp-reviewer` | `cpp-build-resolver` | CMake/g++/clang++ falla |
| Flutter | `flutter-reviewer` | `kotlin-build-resolver` (Android) | `flutter build` falla |
| PyTorch/ML | `python-reviewer` | `pytorch-build-resolver` | Errores CUDA, torch |

### Selector de agente por situación

```mermaid
graph TD
    A{¿El código compila?} --> |No| B[Usar build resolver del lenguaje]
    A --> |Sí| C{¿Acabas de escribir código?}
    C --> |Sí| D[Usar language reviewer + code-reviewer]
    C --> |No| E{¿Hay vulnerabilidades de seguridad?}
    E --> |Sí o no sé| F[Usar security-reviewer]
    E --> |No| G{¿Hay deuda técnica?}
    G --> |Sí| H[Usar refactor-cleaner]
    G --> |No| I[No se necesita agente ahora]

---

11. El Chief of Staff: Orquestación a Escala

El chief-of-staff es el único agente con acceso al Task tool, lo que le permite invocar otros agentes. Es el meta-agente que convierte ECC de una colección de especialistas en un sistema coordinado.

Cómo decide qué agente invocar

El chief-of-staff tiene conocimiento del catálogo completo de agentes y sus capacidades. Para cada fase de un workflow, selecciona el agente más apropiado según:

1. El tipo de tarea de la fase
2. Los outputs disponibles como inputs (de fases previas)
3. Las herramientas que el agente necesita
4. El modelo más costo-efectivo para la tarea

El chief-of-staff y el Iterative Retrieval Pattern

El chief-of-staff es el responsable de aplicar el iterative retrieval pattern. Después de recibir el output de cada subagente, evalúa:

• ¿El output cubre el input de la siguiente fase?
• ¿El output es específico o genérico?
• ¿Hay información crítica del contexto que el subagente ignoró?

Si la evaluación es negativa, envía una pregunta de seguimiento antes de avanzar a la siguiente fase.

Workflow de orquestación del chief-of-staff

graph TD
    A[Recibir tarea del usuario] --> B[Descomponer en fases]
    B --> C[Identificar agente para fase 1]
    C --> D[Invocar agente con contexto completo]
    D --> E[Evaluar output]
    E --> F{¿Suficiente?}
    F --> |No, ciclo < 3| G[Formular pregunta de seguimiento]
    G --> D
    F --> |No, ciclo = 3| H[Escalar al usuario]
    F --> |Sí| I{¿Hay más fases?}
    I --> |Sí| J[Preparar input para siguiente fase]
    J --> C
    I --> |No| K[Consolidar outputs y reportar]

Cuándo el chief-of-staff es el punto de entrada correcto

Usa el chief-of-staff como punto de entrada (en lugar de agentes individuales) cuando:

• La tarea implica 3 o más fases con agentes diferentes
• No estás seguro de qué agentes son necesarios ni en qué orden
• El workflow requiere decisiones condicionales (por ejemplo, si el plan inicial no es factible, rediseñar con el architect antes de continuar)
• Necesitas un reporte consolidado al final

---

12. El Loop Operator: Automatización de Tareas Repetitivas

El loop-operator es el agente para batch operations: cuando necesitas aplicar la misma operación a múltiples items de forma autónoma.

Casos de uso reales

Caso 1: Agregar types a funciones sin anotaciones

Task al loop-operator:
"Para cada archivo .ts en src/api/, si la función no tiene return type,
agrega el tipo apropiado basado en la implementación.
Lista de archivos: [user.ts, product.ts, order.ts, payment.ts, notification.ts]"

El loop-operator itera sobre cada archivo, analiza las funciones sin tipo, agrega los tipos, y reporta qué cambió en cada archivo.

Caso 2: Actualizar imports deprecated

Task al loop-operator:
"La API de React Router v5 está deprecada. En cada archivo que importe de
'react-router-dom', actualiza los imports a la API de v6:
- useHistory → useNavigate
- <Switch> → <Routes>
- <Route exact path="..."> → <Route path="...">
Lista de archivos: [todos los archivos que importen react-router-dom]"

Caso 3: Generar tests faltantes

Task al loop-operator:
"Para cada función pública en src/services/ que no tenga test en src/services/__tests__/,
crea un test básico con al menos un caso de éxito y uno de error."

Límites del loop-operator

El loop-operator trabaja bien cuando:

• La operación es la misma para todos los items (o tiene variaciones predecibles)
• Los items son independientes entre sí
• El criterio de éxito es claro y verificable por el agente

No funciona bien cuando:

• Cada item requiere una decisión arquitectural diferente
• Los items tienen dependencias entre sí
• La operación requiere contexto del dominio de negocio que no está en el código

---

13. El Harness Optimizer: CI/CD Eficiente

El harness-optimizer resuelve uno de los pain points más frecuentes en equipos de desarrollo: pipelines de CI lentos que bloquean el feedback.

Lo que analiza

1. Perfil de tiempos de ejecución

El harness-optimizer corre la suite de tests con timing detallado y produce un perfil:

Test suite profile:
  Unit tests:       2m 14s  (45% del tiempo total)
  Integration tests: 1m 48s  (36% del tiempo total)
  E2E tests:         0m 58s  (19% del tiempo total)
  Total:             5m 00s

Top 5 tests más lentos:
  1. UserService.integration.test.ts - 45s (setup de DB)
  2. PaymentFlow.e2e.test.ts - 32s (browser startup × 3)
  3. EmailService.test.ts - 28s (sleep(2000) innecesario)

2. Oportunidades de paralelismo

Identifica suites de tests que se ejecutan secuencialmente pero son independientes y podrían paralelizarse:

Paralelismo posible:
  [unit-tests] y [lint] son independientes → pueden correr en paralelo
  [integration-tests] depende de [unit-tests] → deben ser secuenciales
  [e2e-tests] puede partir antes, no depende de [integration-tests]

  Tiempo actual (secuencial):  8 minutos
  Tiempo optimizado (paralelo): 4 minutos

3. Optimizaciones de configuración

Propone y aplica cambios concretos en la configuración del CI (GitHub Actions, GitLab CI, etc.) para implementar el paralelismo identificado.

---

14. Mejores Prácticas: 15 Reglas de Oro

Regla 1: Un agente, un output claro

Cada invocación de un agente debe tener un output específico y verificable. “Revisa el código” es vago. “Produce review-comments.md con todos los problemas críticos y de calidad del módulo src/auth/” es específico.

Regla 2: Los intermedios se guardan en archivos

Los outputs de cada agente se almacenan como archivos en el proyecto. architecture-decision.md, implementation-plan.md, review-comments.md. Esto permite:

• Que el siguiente agente tenga acceso al contexto completo del output anterior
• Que el usuario revise y corrija outputs intermedios
• Trazabilidad del workflow completo

Regla 3: Nunca saltar fases

En el Feature Development Workflow, la tentación es saltarse el architect para “ir más rápido”. Esto casi siempre resulta en trabajo de refactoring posterior que cuesta más tiempo que el que se ahorró.

Regla 4: El contexto semántico siempre en el input

Todo contexto relevante del dominio, los requisitos de negocio y las restricciones debe estar en la instrucción al subagente. No asumir que el subagente infiere contexto que no está escrito.

Regla 5: Evaluar cada output antes de aceptarlo

El Iterative Retrieval Pattern es una disciplina. Antes de usar el output de un agente como input del siguiente, verificar que el output es suficientemente específico, correcto y completo.

Regla 6: Máximo 3 ciclos de refinamiento

Si después de 3 iteraciones el output del subagente no es satisfactorio, el problema es en el diseño de la tarea o en la descripción del agente. Escalar al usuario antes de continuar.

Regla 7: Usar el agente correcto para cada tarea

No usar el code-reviewer para tareas de arquitectura. No usar el architect para bugfixes simples. El especialista correcto produce resultados mejores con menor costo que el generalista.

Regla 8: TDD antes que código

Antes de cualquier nueva implementación, el tdd-guide escribe el test. Sin excepciones. Los tests son la documentación ejecutable del comportamiento esperado.

Regla 9: Seguridad no es opcional

El security-reviewer se ejecuta siempre en código que toca autenticación, inputs del usuario, o datos sensibles. No es un paso opcional en el workflow.

Regla 10: Tests antes de refactoring

Antes de invocar el refactor-cleaner, verificar que hay cobertura de tests suficiente (80%+). Sin tests, el refactoring puede romper comportamiento sin detectarse.

Regla 11: Documentación como parte del workflow

El doc-updater se ejecuta al final de cada feature completada. La documentación desactualizada es deuda técnica que crece con el tiempo.

Regla 12: Usar haiku para recuperación

Para tareas de búsqueda de información y recuperación de documentación, haiku es suficiente y más económico. No gastar tokens de opus en recuperación mecánica.

Regla 13: Paralelizar cuando es posible

El code-reviewer y el security-reviewer pueden ejecutarse en paralelo. Los language reviewers de múltiples módulos independientes pueden ejecutarse en paralelo. Identificar oportunidades de paralelismo reduce el tiempo total.

Regla 14: El planner antes del código

Ningún agente de implementación debería trabajar sin un plan. El planner es el punto de entrada del workflow de implementación. Ahorrar 10 minutos de planning puede costar 2 horas de reimplementación.

Regla 15: Revisar los outputs con sentido crítico

Los agentes pueden cometer errores. El usuario es el árbitro final de la calidad. Especialmente en el architect y el planner (donde las decisiones tienen mayor impacto), revisar y cuestionar los outputs antes de proceder.

---

15. Anti-patrones Comunes

Anti-patrón 1: El contexto monolítico infinito

Hacer todo en el contexto principal sin delegar. El contexto crece, la calidad degrada, los errores se acumulan y el costo por token sube. La señal de que estás en este anti-patrón: cuando el contexto tiene más de 50 mensajes y la calidad de las respuestas es notablemente peor que al principio.

Solución: Usar /clear y delegar la siguiente fase a un agente especializado.

Anti-patrón 2: El agente incorrecto

Usar el planner para architecture decisions, o el architect para planificación de implementación. El resultado es un output que mezcla responsabilidades y es menos útil que si hubiera usado el agente correcto.

Solución: Conocer la diferencia entre cada agente y ser deliberado en la selección.

Anti-patrón 3: El input vacío

Invocar un agente con “revisa el código” sin especificar qué código, qué criterios, qué contexto. El agente produce un output genérico y sin valor.

Solución: Siempre especificar: qué revisar, en qué contexto, con qué criterios, qué formato de output.

Anti-patrón 4: Aceptar el primer output sin evaluar

El primer output de un subagente puede ser correcto, pero también puede ser superficial, genérico o incompleto. Aceptarlo sin evaluación y usarlo como input de la siguiente fase propaga el problema.

Solución: Aplicar el Iterative Retrieval Pattern sistemáticamente.

Anti-patrón 5: Saltarse el agente de seguridad

“El código parece seguro, me salto el security-reviewer para ahorrar tiempo.” Las vulnerabilidades de seguridad raramente son obvias a simple vista. El security-reviewer hace un análisis sistemático que va más allá de la revisión casual.

Solución: security-reviewer es mandatorio para cualquier código de auth, input handling, o datos sensibles.

Anti-patrón 6: Refactorizar sin tests

Invocar el refactor-cleaner en código sin tests. El refactoring puede romper comportamiento sin que haya ningún test que lo detecte. El código resulta más “limpio” pero roto.

Solución: Siempre ejecutar tdd-guide para aumentar cobertura antes de refactor-cleaner.

Anti-patrón 7: Usar opus para todo

Asignar opus a todos los agentes por “asegurar calidad”. El costo es innecesariamente alto y la diferencia de calidad en tareas mecánicas es mínima.

Solución: Seguir la tabla de selección de modelo de la sección 7. Opus solo para planning y arquitectura.

Anti-patrón 8: El loop infinito de reviews

Iterar indefinidamente entre code-reviewer y tdd-guide sin avanzar. El code-reviewer encuentra problemas, el tdd-guide los corrige, el code-reviewer encuentra nuevos problemas, etc.

Solución: Máximo 2 ciclos de review-fix. Si después de 2 ciclos el código tiene problemas fundamentales, escalar al architect para un rediseño.

Anti-patrón 9: Ignorar los language reviewers

En proyectos Go o Rust, solo usar el code-reviewer genérico. El code-reviewer genérico no conoce los idioms específicos del lenguaje, el manejo de errores, ni los patrones de concurrencia propios de cada lenguaje.

Solución: Usar el language reviewer específico ADEMÁS del code-reviewer genérico.

Anti-patrón 10: El chief-of-staff para tareas simples

Invocar el chief-of-staff para una tarea que puede manejar un solo agente. Overhead de orquestación innecesario.

Solución: Para tareas simples (1-2 agentes), invocar directamente. El chief-of-staff es para workflows complejos con 3+ fases.

---

16. Ejercicios Prácticos

Ejercicio 1: Tu primer workflow de feature

Objetivo: Practicar el Feature Development Workflow completo.

Tarea: Implementar una función calculateShippingCost(weight: number, distance: number, priority: 'standard' | 'express'): number en un proyecto TypeScript existente.

Pasos:

• Invocar el planner con la descripción de la función y el contexto del proyecto
• Revisar el plan producido y aprobar o ajustar
• Invocar el tdd-guide para escribir los tests primero (peso negativo, distancia 0, priority inválida)
• Verificar que los tests fallan correctamente
• Implementar la función
• Verificar que los tests pasan
• Invocar el typescript-reviewer para revisar el código
• Invocar el code-reviewer para review general
• Aplicar correcciones si hay observaciones
• Invocar el doc-updater para agregar JSDoc a la función

Criterio de éxito: Tests pasan, review aprobado, función documentada.

---

Ejercicio 2: Diagnóstico de un build roto

Objetivo: Practicar el uso del build-error-resolver.

Setup: Introduce intencionalmente un error en un proyecto:

// En algún archivo existente
import { nonExistentFunction } from './utils';
const result: string = 42; // type error

Pasos:

• Ejecutar el build y capturar el error completo
• Invocar el build-error-resolver con el error completo
• Verificar que el agente identifica correctamente los dos problemas
• Aplicar los fixes sugeridos
• Verificar que el build pasa

---

Ejercicio 3: Auditoría de seguridad de un endpoint

Objetivo: Entender qué detecta el security-reviewer.

Setup: Crear un endpoint Express con vulnerabilidades intencionales:

// endpoint con SQL injection intencional
app.get('/user', async (req, res) => {
  const query = `SELECT * FROM users WHERE id = ${req.query.id}`;
  const result = await db.query(query);
  console.log(`User lookup: ${JSON.stringify(result)}`); // sensitive data en logs
  res.json(result);
});

Pasos:

• Invocar el security-reviewer con el endpoint como input
• Verificar que detecta SQL injection Y el log de datos sensibles
• Implementar los fixes sugeridos (prepared statement, remover log)
• Correr el security-reviewer de nuevo para verificar que los problemas están resueltos

---

Ejercicio 4: Crear un agente propio

Objetivo: Entender la anatomía de un agente creando uno desde cero.

Tarea: Crear un agente api-contract-reviewer que revise que los endpoints de una API REST siguen convenciones REST correctas (métodos HTTP apropiados, status codes correctos, naming de URLs).

Pasos:

• Definir el propósito exacto del agente
• Decidir qué tools necesita (solo Read, Grep, Glob — no necesita modificar)
• Decidir el modelo (sonnet es suficiente para este tipo de review)
• Escribir la descripción con keywords de activación proactiva
• Escribir el prompt del sistema con el proceso de revisión y el formato de output
• Crear el archivo en el directorio de agentes
• Probarlo sobre un endpoint existente
• Ajustar el prompt si el output no es el esperado

---

Ejercicio 5: Workflow de refactoring seguro

Objetivo: Practicar el Refactoring Workflow con protección de tests.

Setup: Tomar un archivo con más de 150 líneas y funciones de más de 30 líneas.

Pasos:

• Invocar el code-reviewer para identificar los problemas de mantenibilidad
• Invocar el tdd-guide para llevar la cobertura al 80%+ ANTES del refactoring
• Verificar que los tests pasan
• Invocar el architect para diseñar la nueva estructura del módulo
• Invocar el refactor-cleaner con el plan del architect como guía
• Verificar que los tests siguen pasando después del refactoring
• Invocar el code-reviewer de nuevo para confirmar que los problemas se resolvieron

---

17. Checklist y Resumen

Checklist de uso diario de agentes

Antes de implementar una feature:

• Invocar el planner para crear el plan de implementación
• Para features complejas, invocar el architect primero

Durante la implementación:

• Usar el tdd-guide para escribir tests primero
• Usar el language reviewer específico si trabajas en Go/Rust/TypeScript/etc.

Después de escribir código:

• Invocar el code-reviewer (es mandatorio según la descripción del agente)
• Para código de auth o input handling: invocar el security-reviewer

Para corregir errores de build:

• Usar el build-error-resolver genérico o el específico del lenguaje

Para mantenimiento:

• Antes de refactoring: verificar cobertura con tdd-guide
• Después de cada feature: invocar doc-updater
• Periódicamente: usar el harness-optimizer si el CI es lento

Los 28 agentes en una tabla de referencia

Agente	Categoría	Modelo	Cuándo invocar
planner	Planning	opus	Antes de implementar cualquier feature
architect	Planning	opus	Para decisiones de diseño de sistemas
tdd-guide	Desarrollo	sonnet	Para cualquier nuevo código
refactor-cleaner	Desarrollo	sonnet	Para limpiar código con deuda técnica
doc-updater	Desarrollo	sonnet	Después de cambios que afectan la API pública
code-reviewer	Review	sonnet	Después de escribir código (mandatorio)
security-reviewer	Review	sonnet	Para código de auth, input handling, datos sensibles
database-reviewer	Review	sonnet	Para queries SQL y RLS de Supabase
go-reviewer	Review	sonnet	Después de escribir código Go
python-reviewer	Review	sonnet	Después de escribir código Python
rust-reviewer	Review	sonnet	Después de escribir código Rust
typescript-reviewer	Review	sonnet	Después de escribir código TypeScript
java-reviewer	Review	sonnet	Después de escribir código Java
kotlin-reviewer	Review	sonnet	Después de escribir código Kotlin
cpp-reviewer	Review	sonnet	Después de escribir código C++
flutter-reviewer	Review	sonnet	Después de escribir código Flutter
build-error-resolver	Build	sonnet	Cuando el build falla (cualquier lenguaje)
go-build-resolver	Build	sonnet	Cuando go build falla
rust-build-resolver	Build	sonnet	Cuando cargo build falla
java-build-resolver	Build	sonnet	Cuando Maven/Gradle falla
kotlin-build-resolver	Build	sonnet	Cuando Gradle Kotlin build falla
cpp-build-resolver	Build	sonnet	Cuando CMake/g++/clang++ falla
pytorch-build-resolver	Build	sonnet	Cuando PyTorch/CUDA falla
e2e-runner	Testing	sonnet	Para tests de flujos de usuario críticos
docs-lookup	Docs	haiku	Para buscar información en la documentación
chief-of-staff	Orquestación	opus	Para workflows complejos con 3+ fases
loop-operator	Operaciones	sonnet	Para batch operations repetitivas
harness-optimizer	Operaciones	sonnet	Cuando el CI es lento

Resumen ejecutivo

Los agentes de ECC son la respuesta al principal problema de los flujos de trabajo con LLMs: la degradación de calidad a medida que el contexto crece. Al delegar a subagentes especializados con contextos aislados, cada tarea se ejecuta con el especialista correcto, el modelo apropiado, y las herramientas mínimas necesarias.

Los cinco principios fundamentales de los agentes en ECC:

1. Especialización: cada agente tiene un dominio claro y no hace más de lo que le corresponde
2. Aislamiento de contexto: el subagente no acumula ruido del contexto principal
3. Outputs como artifacts: los resultados intermedios se persisten en archivos para trazabilidad y reutilización
4. Mínimo privilegio: cada agente tiene solo las herramientas que necesita
5. Evaluación antes de avanzar: el Iterative Retrieval Pattern garantiza calidad en cada fase

La inversión en aprender estos 28 agentes y sus patrones de uso se recupera con creces en la primera feature compleja donde el workflow de agentes produce código más limpio, más seguro y mejor documentado que el workflow monolítico en el contexto principal.