# POLÍTICAS DE USO DE AGENTES Y SUBAGENTES

**Proyecto:** GAMILIT - Sistema de Gamificación Educativa
**Versión:** 1.1.0
**Fecha:** 2025-11-23 (actualizada)
**Estado:** OBLIGATORIO

---

## 🎯 OBJETIVO

Definir cuándo y cómo usar agentes y subagentes para maximizar eficiencia, calidad y trazabilidad del desarrollo.

---

## 🚨 PRINCIPIO FUNDAMENTAL: ESPECIALIZACIÓN Y DELEGACIÓN

**REGLA DE ORO:**
Cada agente tiene una responsabilidad específica. **NO implementes fuera de tu especialidad. ANALIZA, DOCUMENTA Y DELEGA.**

### Matriz de Responsabilidades y Delegación

| Agente | SÍ HACE (Implementa) | NO HACE (Delega a) |
|--------|---------------------|---------------------|
| **Database-Agent** | Crear DDL, seeds, RLS policies | Backend entities, Frontend → Backend-Agent/Frontend-Agent |
| **Backend-Agent** | Crear entities, services, controllers | DDL, Seeds → Database-Agent; UI → Frontend-Agent |
| **Frontend-Agent** | Crear components, pages, stores | Backend logic → Backend-Agent; DB → Database-Agent |
| **Requirements-Analyst** | Analizar, documentar requerimientos | **TODO código** → Delega a Database/Backend/Frontend |
| **Code-Reviewer** | Revisar, sugerir mejoras | **NO implementa correcciones** → Delega a agente responsable |
| **Architecture-Analyst** | Analizar, validar, documentar (docs/, ADRs, reportes), **ORQUESTAR agentes** (Tool: Task) | **TODO código en apps/** → Orquesta o Delega a Database/Backend/Frontend |
| **Workspace-Manager** | Organizar archivos, validar estructura | **NO modifica código** → Delega implementaciones |
| **Bug-Fixer** | Diagnosticar y corregir bugs | (Puede implementar en todas las capas según el bug) |
| **Feature-Developer** | Coordinar features completos | (Puede usar Database/Backend/Frontend como subagentes) |

### Principio de No Invasión de Responsabilidades

**❌ INCORRECTO:**
```markdown
Architecture-Analyst modifica:
- apps/database/ddl/00-prerequisites.sql
- apps/backend/src/modules/educational/entities/module.entity.ts
- apps/frontend/src/components/ModulesSection.tsx

Y ejecuta:
- psql para aplicar migraciones
- npm run dev
- npm run build
```

**✅ CORRECTO:**
```markdown
Architecture-Analyst:
1. Identifica gaps (GAP-003, GAP-004, GAP-005)
2. Analiza opciones (OPTION A, OPTION B)
3. Documenta solución detallada
4. Actualiza docs/, ADRs, trazas

Luego DELEGA a:
- Database-Agent: "Implementar GAP-004 según SPEC líneas 50-80"
- Frontend-Agent: "Implementar GAP-005 según SPEC líneas 120-180"
- QA-Agent: "Validar implementación según criterios de aceptación"
```

### Cómo Delegar Correctamente

**Paso 1: Identificar necesidad**
```markdown
Gap, bug, feature, etc.
```

**Paso 2: Documentar QUÉ (no CÓMO)**
```markdown
## GAP-XXX: [Descripción]

**Agente Responsable:** [Nombre-Agente]
**Prioridad:** P0/P1/P2/P3
**Ubicación archivos:** [rutas exactas]

**QUÉ debe hacerse:**
- [Especificación clara del resultado esperado]
- [Criterios de aceptación]

**ESPECIFICACIÓN DETALLADA:**
[Referencia a documento con detalles técnicos]

**ESTADO:** Documentado, pendiente de implementación
```

**Paso 3: Actualizar traza con delegación**
```markdown
### PRÓXIMAS ACCIONES

#### Delegadas a Database-Agent
- [ ] GAP-XXX: [Descripción breve] (Ver SPEC líneas X-Y)

#### Delegadas a Frontend-Agent
- [ ] GAP-XXX: [Descripción breve] (Ver SPEC líneas X-Y)
```

**Paso 4: NO ejecutar implementación**
```markdown
El agente que identificó la necesidad NO ejecuta:
- Comandos de compilación (npm, docker, psql)
- Modificaciones de código (excepto su especialidad)
- Deploys o cambios directos en BD sin DDL
```

---

## 📋 TIPOS DE AGENTES

### Agentes Principales (Por Stack Tecnológico)

#### 1. Database-Agent
**Responsabilidad:**
- Crear/modificar schemas, tablas, funciones, triggers
- Generar seeds (dev/prod)
- Validar DDL y ejecución de scripts
- Mantener inventario de objetos DB

**Cuándo usar:**
- Crear nuevo schema completo
- Modificar estructura de tablas existentes
- Crear funciones/triggers complejos
- Actualizar DDL y validar con carga limpia

**Subagentes disponibles:**
- Schema-Creator
- Table-Creator
- Function-Creator
- Seed-Generator
- RLS-Policy-Creator

**❌ PROHIBIDO:**
- Migration-Generator (usar DDL + recreación completa)
- Ejecutar ALTER/CREATE directamente sin DDL
- Crear archivos fix-*.sql o patch-*.sql

**Ver:** [DIRECTIVA-POLITICA-CARGA-LIMPIA.md](DIRECTIVA-POLITICA-CARGA-LIMPIA.md)

#### 2. Backend-Agent
**Responsabilidad:**
- Crear/modificar módulos NestJS
- Implementar entities, services, controllers, DTOs
- Configurar TypeORM, validaciones, guards
- Mantener inventario backend

**Cuándo usar:**
- Crear módulo completo
- Implementar CRUDs complejos
- Configurar autenticación/autorización
- Implementar lógica de negocio compleja

**Subagentes disponibles:**
- Entity-Creator
- Service-Creator
- Controller-Creator
- DTO-Creator
- CRUD-Generator

#### 3. Frontend-Agent
**Responsabilidad:**
- Crear/modificar páginas y componentes React
- Implementar stores Zustand
- Configurar servicios API
- Mantener inventario frontend

**Cuándo usar:**
- Crear página completa con múltiples componentes
- Implementar feature UI complejo
- Crear dashboards
- Configurar routing

**Subagentes disponibles:**
- Page-Creator
- Component-Creator
- Store-Creator
- Form-Generator
- Dashboard-Creator

---

### Agentes Especializados (Por Actividad)

#### 4. Requirements-Analyst
**Responsabilidad:**
- Analizar requerimientos del plan MVP
- Desglosar features en tareas ejecutables
- Mapear dependencias entre módulos
- Generar historias de usuario

**Cuándo usar:**
- Inicio de nuevo módulo/feature
- Análisis de viabilidad técnica
- Planificación de sprints
- Identificación de dependencias

**Genera:**
- TRAZA-REQUERIMIENTOS.md
- Planes de implementación desglosados
- Dependency graphs
- Estimaciones de esfuerzo

#### 5. Code-Reviewer
**Responsabilidad:**
- Revisar código según estándares
- Detectar code smells, anti-patterns
- Validar cumplimiento de directivas
- Sugerir refactorizaciones

**Cuándo usar:**
- Antes de merge a main
- Después de implementación de feature grande
- Revisión periódica semanal
- Pre-despliegue a producción

**Subagentes disponibles:**
- Security-Auditor
- Performance-Auditor
- Standards-Validator
- Documentation-Checker

**Genera:**
- TRAZA-VALIDACIONES.md
- Reportes de calidad
- Lista de issues encontrados
- Recomendaciones de mejora

#### 6. Bug-Fixer
**Responsabilidad:**
- Diagnosticar bugs reportados
- Implementar correcciones
- Crear tests para prevenir regresiones
- Validar fix end-to-end

**Cuándo usar:**
- Bug crítico (P0/P1)
- Bug que afecta múltiples módulos
- Bug complejo que requiere debugging profundo

**Subagentes disponibles:**
- Bug-Analyzer
- Test-Creator
- Fix-Validator

**Genera:**
- TRAZA-BUGS.md
- TRAZA-CORRECCIONES.md
- Tests de regresión
- Post-mortem (si bug crítico)

#### 7. Feature-Developer
**Responsabilidad:**
- Desarrollar features completos (DB + Backend + Frontend)
- Coordinar entre capas
- Validar integración end-to-end
- Documentar feature completo

**Cuándo usar:**
- Feature completo nuevo (ejemplo: módulo de estimaciones)
- Requiere cambios en las 3 capas
- Alta complejidad de integración

**Subagentes disponibles:**
- Database-Agent
- Backend-Agent
- Frontend-Agent
- Integration-Tester

**Genera:**
- TRAZA-FEATURES.md
- Documentación de feature
- Tests E2E
- Guía de uso

#### 8. Policy-Auditor
**Responsabilidad:**
- Auditar cumplimiento de políticas
- Validar inventarios vs realidad
- Detectar duplicaciones
- Verificar documentación obligatoria

**Cuándo usar:**
- Semanalmente (auditoría de rutina)
- Antes de release
- Cuando se detectan inconsistencias
- Post-implementación de feature grande

**Subagentes disponibles:**
- Documentation-Auditor
- Inventory-Auditor
- Standards-Auditor
- Anti-Duplication-Checker

**Genera:**
- TRAZA-VALIDACIONES.md
- Reportes de cumplimiento
- Lista de discrepancias
- Plan de corrección

#### 9. Architecture-Analyst
**Responsabilidad:**
- Analizar requerimientos arquitectónicos generales
- Analizar código de referencia de otros proyectos
- Equiparar implementaciones de referencia con documentación
- Identificar gaps entre documentación y referencias
- Proponer y documentar decisiones arquitectónicas (ADRs)
- Validar coherencia arquitectónica del proyecto
- **ORQUESTAR agentes especializados** para implementar gaps identificados

**Cuándo usar:**
- Análisis de nuevos proyectos de referencia
- Validación periódica de coherencia arquitectónica
- Antes de decisiones arquitectónicas importantes
- Cuando se detectan desviaciones del diseño
- Para actualizar documentación con mejores prácticas

**Capacidades especiales:**
- ✅ Puede ORQUESTAR Database-Agent, Backend-Agent, Frontend-Agent usando Tool: Task
- ✅ Puede DELEGAR tareas mediante documentación en trazas
- ✅ Puede usar Explore Agent para análisis de código
- ❌ NO implementa código directamente

**Subagentes disponibles:**
- Reference-Code-Analyzer
- Gap-Analyzer
- Architecture-Validator
- Documentation-Updater
- **Database-Agent** (mediante orquestación)
- **Backend-Agent** (mediante orquestación)
- **Frontend-Agent** (mediante orquestación)

**Genera:**
- TRAZA-ANALISIS-ARQUITECTURA.md
- ADRs (Architecture Decision Records)
- Reportes de análisis de referencias
- Gap analysis y planes de actualización
- Reportes de coherencia arquitectónica
- Especificaciones para agentes orquestados

#### 10. Workspace-Manager
**Responsabilidad:**
- Mantener workspace limpio y organizado
- Validar ubicación correcta de archivos generados
- Validar alineación código-documentación
- Gestionar y validar trazas e inventarios
- Detectar cambios en alcances y definiciones
- Asegurar cumplimiento de estructura organizacional
- Prevenir deuda técnica organizacional

**Cuándo usar:**
- Semanalmente (limpieza y validación de rutina)
- Cuando workspace está desorganizado
- Para validar alineación después de tareas grandes
- Cuando se detectan archivos en ubicaciones incorrectas
- Para consolidar trazas fragmentadas
- Después de cambios en documentación de requerimientos

**Subagentes disponibles:**
- Workspace-Cleaner
- Alignment-Validator
- Trace-Consolidator
- Scope-Change-Detector

**Genera:**
- TRAZA-WORKSPACE-MANAGEMENT.md
- Reportes de limpieza
- Reportes de alineación
- Reportes de cambios de alcance
- Planes de corrección organizacional

---

## 🔄 DECISIÓN: ¿Agente o Subagente?

### Usar Agente Principal

**Características de la tarea:**
- ✅ Complejidad: Alta (>5 pasos)
- ✅ Alcance: Múltiples módulos (>2)
- ✅ Archivos: Muchos (>10)
- ✅ Requiere análisis previo
- ✅ Coordinación entre capas (DB-Backend-Frontend)
- ✅ Genera documentación extensa

**Ejemplos:**
- Crear módulo completo de Proyectos y Obras
- Implementar sistema de autenticación
- Migrar base de datos de versión antigua
- Implementar reportes ejecutivos complejos

**Proceso:**
```
1. Análisis (01-ANALISIS.md)
2. Plan (02-PLAN.md)
3. Ejecución por ciclos (03-EJECUCION.md)
4. Validación (04-VALIDACION.md)
5. Documentación (05-DOCUMENTACION.md)
6. Actualizar inventarios y trazas
```

---

### Usar Subagente

**Características de la tarea:**
- ✅ Complejidad: Baja-Media (1-3 pasos)
- ✅ Alcance: Un módulo (1 archivo o grupo pequeño)
- ✅ Archivos: Pocos (1-3)
- ✅ Patrón repetitivo (CRUD, formularios)
- ✅ Sin dependencias complejas
- ✅ Bien especificado por agente principal

**Ejemplos:**
- Crear una tabla simple
- Crear entity + DTO básico
- Crear formulario estándar
- Agregar endpoint CRUD simple

**Proceso:**
```
1. Recibir contexto del agente principal
2. Validar anti-duplicación
3. Ejecutar tarea
4. Validar localmente
5. Actualizar inventario
6. Reportar al agente principal
```

---

## ⚙️ LÍMITES Y CONCURRENCIA

### Límites de Agentes Simultáneos

```yaml
concurrencia:
  agentes_principales_max: 3
    # Razón: Evitar conflictos, mantener contexto claro

  subagentes_por_agente_max: 5
    # Razón: Un agente puede coordinar hasta 5 subagentes

  subagentes_totales_max: 15
    # Razón: Límite de Claude Code

  agentes_especializados_max: 2
    # Razón: Requirements-Analyst y Code-Reviewer pueden correr juntos
```

### Reglas de Concurrencia

**✅ Permitido:**
- Database-Agent + Backend-Agent en paralelo (si no hay dependencias)
- Requirements-Analyst + Code-Reviewer en paralelo
- Múltiples subagentes del mismo agente en paralelo

**❌ No Permitido:**
- Database-Agent y Backend-Agent trabajando en mismo módulo
- Dos agentes modificando el mismo archivo
- Feature-Developer + Database-Agent en mismo schema

---

## 🚨 GESTIÓN DE ERRORES

### Error en Subagente

**Procedimiento:**
1. Subagente intenta autocorrección (máx 2 intentos)
2. Si persiste:
   - Marca tarea como fallida
   - Reporta error al agente principal
   - Agente principal decide: reintentar, escalar o cambiar approach
3. Documentar en TRAZA-BUGS.md si es bug del sistema

**Ejemplo:**
```markdown
## [BUG-001] Subagente Table-Creator falla al crear índice

**Agente:** Database-Agent
**Subagente:** Table-Creator (DB-005-SUB-002)
**Error:** Sintaxis SQL incorrecta en CREATE INDEX
**Intentos:** 2/2
**Acción tomada:** Agente principal corrigió manualmente
**Lección:** Validar sintaxis de índices parciales con WHERE
**Estado:** ✅ Resuelto
```

---

### Error en Agente Principal

**Procedimiento:**
1. Agente marca tarea como bloqueada (❌)
2. Crea entrada en TRAZA-BUGS.md
3. Notifica a supervisor (usuario)
4. Supervisor decide:
   - Proporcionar más contexto
   - Dividir tarea en subtareas más pequeñas
   - Asignar a agente especializado (Bug-Fixer)

**Ejemplo:**
```markdown
## [DB-042] Error al crear schema complex_reporting

**Estado:** ❌ Bloqueado
**Agente:** Database-Agent
**Error:** Dependencias circulares entre funciones
**Bloqueador:** Requiere reestructuración de dependencies
**Documentado en:** orchestration/agentes/database/DB-042/
**Notificado:** 2025-11-17 10:30
**Esperando:** Decisión de arquitectura
```

---

### Rollback

**Cuándo hacer rollback:**
- Error crítico que rompe compilación/ejecución
- Datos corruptos en base de datos
- Múltiples tests fallando después de cambio
- Vulnerabilidad de seguridad introducida

**Procedimiento:**
1. Identificar punto de rollback (último commit estable)
2. Guardar snapshot del estado actual (para análisis)
3. Ejecutar rollback:
   ```bash
   # Database
   psql $DATABASE_URL < backups/pre-{TAREA-ID}.sql

   # Backend/Frontend
   git revert {commit-hash}
   ```
4. Documentar rollback en TRAZA-CORRECCIONES.md
5. Analizar causa raíz
6. Replantear approach

**Ejemplo:**
```markdown
## [ROLLBACK-001] Revertir cambios de DB-045

**Fecha:** 2025-11-17 11:00
**Tarea original:** DB-045 - Agregar columnas a user_points
**Razón:** Cambio directo en BD sin actualizar DDL causó inconsistencias
**Problema detectado:**
  - Se ejecutó ALTER TABLE directamente en BD
  - DDL no fue actualizado
  - Recreación completa falló por missing columns
**Afectados:**
  - apps/database/ddl/schemas/gamification_system/tables/01-user_points.sql
**Rollback a:** Commit abc123def (pre DB-045)
**Plan de corrección:**
  1. Actualizar archivo DDL (NO crear migration)
  2. Agregar columnas en CREATE TABLE
  3. Validar con ./drop-and-recreate-database.sh
  4. Commitear DDL corregido
**Estado:** ✅ Rollback exitoso, corrección planificada
**Lección aprendida:** Siempre actualizar DDL primero (DDL-first approach)
```

---

## 📊 MÉTRICAS DE USO DE AGENTES

### KPIs a Monitorear

```yaml
metricas:
  agentes:
    tareas_completadas: 0
    tareas_en_progreso: 0
    tareas_bloqueadas: 0
    tasa_exito: 0%
    tiempo_promedio_tarea: "0h"

  subagentes:
    lanzados_total: 0
    exitosos: 0
    fallidos: 0
    tasa_exito: 0%

  errores:
    errores_autocorregidos: 0
    errores_escalados: 0
    rollbacks_realizados: 0

  eficiencia:
    velocity: 0.0  # tareas/día
    bloqueadores_promedio: 0
    tiempo_analisis_promedio: "0h"
    tiempo_ejecucion_promedio: "0h"
```

### Reportes Automáticos

**Diario:**
- Tareas completadas hoy
- Agentes activos
- Bloqueadores identificados

**Semanal:**
- Velocity de desarrollo
- Tasa de éxito de agentes/subagentes
- Calidad de código (Code-Reviewer)
- Cumplimiento de políticas (Policy-Auditor)

**Por Sprint:**
- Completitud de requerimientos
- Deuda técnica acumulada
- Cobertura de tests
- Documentación

---

## ✅ CHECKLIST DE USO DE AGENTES

### Antes de Lanzar Agente

- [ ] Verificar que no hay agente trabajando en mismo módulo
- [ ] Consultar límites de concurrencia
- [ ] Verificar que tarea requiere agente (no es muy simple)
- [ ] Preparar contexto completo para el agente
- [ ] Validar que inventarios están actualizados

### Durante Ejecución

- [ ] Monitorear progreso del agente
- [ ] Validar que sigue directivas
- [ ] Revisar documentación generada
- [ ] Validar que actualiza inventarios

### Después de Completar

- [ ] Revisar calidad del resultado
- [ ] Validar que inventarios están actualizados
- [ ] Verificar que trazas están completas
- [ ] Ejecutar validaciones (compilación, tests)
- [ ] Marcar tarea como completada

---

## 🎯 MEJORES PRÁCTICAS

### DO ✅

1. **Siempre consultar inventarios antes de crear**
   - Evita duplicaciones
   - Mantiene coherencia

2. **Usar agente correcto para la tarea**
   - Requirements-Analyst para planificación
   - Code-Reviewer antes de merge
   - Feature-Developer para features completos

3. **Documentar en traza correspondiente**
   - Requerimiento → TRAZA-REQUERIMIENTOS.md
   - Bug → TRAZA-BUGS.md
   - Feature → TRAZA-FEATURES.md

4. **Validar antes de marcar completo**
   - Compilación exitosa
   - Tests pasan
   - Documentación completa

5. **Actualizar métricas periódicamente**
   - Dashboard de estado
   - Velocity de desarrollo
   - Calidad de código

### DON'T ❌

1. **NO lanzar agente sin contexto completo**
   - Genera errores
   - Aumenta re-trabajo

2. **NO exceder límites de concurrencia**
   - Causa conflictos
   - Dificulta trazabilidad

3. **NO omitir validación de resultados**
   - Puede introducir bugs
   - Rompe integración

4. **NO olvidar actualizar inventarios**
   - Pierde trazabilidad
   - Causa duplicaciones

5. **NO trabajar sin backup**
   - Siempre tener punto de rollback
   - Especialmente en cambios DB

---

## 📚 REFERENCIAS

- [PROMPT-AGENTES-PRINCIPALES.md](../prompts/PROMPT-AGENTES-PRINCIPALES.md)
- [PROMPT-SUBAGENTES.md](../prompts/PROMPT-SUBAGENTES.md)
- [DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md](./DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md)

---

**Versión:** 1.0.0
**Revisión:** Mensual
**Próxima revisión:** 2025-12-17
