cdovaz/agent-loop-architect

Arquitecto de Loop de Agentes (Ingeniería de Bucles)

Descripción General

Arquitecto de Loop de Agentes es un estándar de ejecución y un patrón de diseño para orquestar flujos de trabajo multi-agente complejos y de múltiples etapas a través de iteraciones en bucle cerrado con memoria persistente y seguimiento de estado.

En lugar de tratar las ejecuciones de agentes como consultas únicas o pipelines lineales, el Agent Loop impone un ciclo de vida iterativo donde los subagentes se especializan, verifican su trabajo a través de puertas objetivas y aprenden sistemáticamente a lo largo de las ejecuciones.

Las Dos Reglas de Oro del Bucle

1. No hay ejecución sin aprendizaje previo: Antes de proponer o implementar cualquier solución, los agentes deben ejecutar la fase Aprender consultando los patrones positivos y negativos existentes en la memoria.
2. No hay finalización sin compresión: Un ciclo no termina cuando se escribe código o contenido; concluye solo después de que la fase Comprimir destila el resultado en la memoria y actualiza el estado.

flowchart TD
    Inicio([Tarea Iniciada]) --> Aprender[1. APRENDER: Ingerir .loop-memory/]
    Aprender --> Planificar[2. PLANIFICAR: Descomposición en Etapas y etapas.json]
    Planificar --> Ejecutar[3. EJECUTAR: Subagentes Especializados Despachados]
    Ejecutar --> Verificar{4. VERIFICAR: ¿Puertas Objetivas Superadas?}
    Verificar -- No: Regresar / Pivotar --> Aprender
    Verificar -- Sí --> Comprimir[5. COMPRIMIR: Destilar Memoria y Actualizar Estado]
    Comprimir --> Fin([Bucle Completado])

---

Las 5 Fases del Bucle

Cada ciclo del bucle avanza estrictamente a través de cinco fases:

Fase 1: Aprender (Ingesta Previa al Vuelo)

• Verificación obligatoria: Los subagentes deben leer:
  • .loop-memory/positive-cases/ (patrones ganadores, correcciones validadas, ángulos de copy de alta conversión, plantillas de prompt óptimas).
  • .loop-memory/negative-cases/ (anti-patrones, hipótesis fallidas, regresiones de casos extremos, enfoques prohibidos).
• Objetivo: Evitar que los agentes repitan errores previamente documentados y forzar la reutilización de patrones probados.

Fase 2: Planificar y Orquestar (Inicialización de Estado)

• Descomponer el objetivo en etapas discretas y ordenadas.
• Inicializar o actualizar etapas.json con el estado de la etapa, subagentes asignados, entradas, salidas y criterios de aceptación.
• Asignar roles de subagente dedicados que coincidan con los requisitos del dominio.

Fase 3: Ejecutar (Despacho de Subagentes Especializados)

• Ejecutar subagentes secuencialmente o en paralelo según las dependencias de las etapas.
• Los subagentes trabajan en contexto aislado, pasando artefactos concisos o diffs en lugar de bolsas conversacionales completas.

Fase 4: Verificar y Evaluar (Puertas de Aceptación Objetivas)

• Validar la salida de la ejecución contra criterios explícitos, automatizados o deterministas (p. ej., resultados de pruebas unitarias/de integración, linting, verificación de citas fácticas, cumplimiento de tono).
• Si la verificación falla:
  • Documentar el fallo como un patrón negativo intermedio.
  • Volver a Aprender/Planificar con la retroalimentación del fallo.
• Si la verificación es exitosa: proceder a Comprimir.

Fase 5: Comprimir (Destilación de Memoria Posterior al Vuelo)

• Destilación Positiva: Extraer el patrón exacto, plantilla, fragmento de prompt o corrección de código que tuvo éxito y escribirlo en .loop-memory/positive-cases/CASE-<ID>.md.
• Destilación Negativa: Documentar callejones sin salida, hipótesis rechazadas y regresiones en .loop-memory/negative-cases/CASE-<ID>.md.
• Finalización de Estado: Actualizar etapas.json con marcas de tiempo de finalización, artefactos finales y métricas de ejecución.

---

Estructura de Directorios y Arquitectura de Memoria

Cada proyecto que opera con el patrón Loop se adhiere a la siguiente estructura raíz o de espacio de trabajo:

<raíz-del-proyecto>/
├── .loop-memory/
│   ├── positive-cases/
│   │   ├── CASE-001-fix-auth-race-condition.md
│   │   └── CASE-002-high-conversion-cold-hook.md
│   └── negative-cases/
│       ├── CASE-001-failed-jwt-in-localstorage.md
│       └── CASE-002-clickbait-hook-bounce.md
├── etapas.json
├── references/
│   └── domain-examples.md
└── SKILL.md

Esquema de Caso de Memoria (.loop-memory/*/CASE-*.md)

Cada archivo de caso debe seguir esta plantilla estandarizada de markdown:

# Caso: [Título Descriptivo Corto]
- **Fecha:** YYYY-MM-DD
- **Dominio:** [Ingeniería | Redacción | Ventas | Investigación]
- **Tipo:** [Positivo | Negativo]
- **Desencadenante / Contexto:** [Situación exacta, mensaje de error u objetivo del prompt]

## Patrón / Técnica
[Descripción detallada de lo que funcionó o por qué falló]

## Artefacto Concreto / Fragmento de Código / Prompt
```[lenguaje]
[Pegue el fragmento concreto, plantilla o diff aquí]

Conclusión y Heurística

• Hacer: [Regla práctica para agentes futuros]
• No hacer: [Lo que debe evitarse]

### Esquema de `etapas.json`

El archivo `etapas.json` rastrea la progresión del ciclo de vida actual:

```json
{
  "project": "agent-loop-project",
  "loop_version": "2.0.0",
  "updated_at": "2026-11-06T21:00:00Z",
  "current_stage": "fix",
  "stages": [
    {
      "id": "reproduce",
      "role": "Subagente Reproductor de QA",
      "status": "completed",
      "input": "Reporte de error #402",
      "output": "tests/repro_spec.ts",
      "memory_consulted": ["CASE-001-fix-auth-race-condition.md"]
    },
    {
      "id": "fix",
      "role": "Subagente Ingeniero de Corrección Principal",
      "status": "in_progress",
      "input": "tests/repro_spec.ts",
      "output": null,
      "memory_consulted": []
    }
  ],
  "metrics": {
    "total_cycles": 1,
    "positive_patterns_harvested": 0,
    "negative_patterns_avoided": 1
  }
}

---

Arquetipos de Dominio Integrados

Agent Loop Architect incluye 4 pipelines de dominio probados en batalla. Para instrucciones paso a paso completas y prompts para cada arquetipo, consulte domain-examples.md.

1. Corrección de Errores e Ingeniería

• Pipeline: Reproducir -> Causa Raíz -> Corregir -> Probar -> Documentar
• Verificación de Aprendizaje: Ingerir correcciones previas para subsistemas relacionados; evitar regresiones pasadas.
• Puerta de Verificación: La prueba de reproducción cambia de ROJO a VERDE; sin roturas colaterales en las pruebas.
• Comprimir: Almacenar la explicación de la causa raíz y el diff de la corrección mínima en .loop-memory/positive-cases/.

2. Contenido y Redacción

• Pipeline: Investigación de Audiencia y Ángulo -> Borrador de Gancho y Narrativa -> Crítica y Pulido de Tono -> Revisión y Verificación de Hechos -> Empaquetado para Distribución
• Verificación de Aprendizaje: Leer los ganchos de mejor rendimiento y las palabras de moda/clichés prohibidos.
• Puerta de Verificación: Nivel de lectura objetivo, puntuación de rúbrica de voz de marca $≥ 8.5/10$, afirmaciones fácticas verificadas.
• Comprimir: Cosechar ángulos de alto rendimiento y fórmulas de gancho en la memoria.

3. Prospección de Ventas

• Pipeline: Inteligencia de Cliente Ideal -> Hipótesis de Valor -> Secuenciación Personalizada -> Refutación de Objeciones -> Preparación de Despacho
• Verificación de Aprendizaje: Consultar tasas de respuesta en propuestas de valor, patrones de objeción y suposiciones inválidas.
• Puerta de Verificación: Lista de verificación de especificidad (sin líneas genéricas de combinación de correo), cumplimiento con pautas de spam.
• Comprimir: Guardar ganchos de personalización exitosos y registrar ángulos de baja respuesta en casos negativos.

4. Investigación, Análisis Financiero y Legal

• Pipeline: Descubrimiento e Ingesta de Fuentes -> Verificación de Hechos y Matriz de Riesgos -> Síntesis Cuantitativa / Legal -> Pruebas de Estrés de Escenarios -> Informe Ejecutivo
• Verificación de Aprendizaje: Ingerir casos precedentes, descuidos de análisis pasados y estándares de validez de datos.
• Puerta de Verificación: 100% de trazabilidad de fuentes citadas; matrices de riesgo probadas contra escenarios de estrés.
• Comprimir: Guardar plantillas de síntesis, calificaciones de confiabilidad de fuentes y heurísticas de evaluación de riesgos.

---

Directrices de Despacho de Subagentes

Al despachar subagentes dentro de un bucle:

1. Especificidad de Rol: Nunca preguntar a un agente generalista. Prefijar los prompts con instrucciones de rol de dominio (p. ej., Eres el Subagente Reproductor de QA...).
2. Inyección de Memoria: Siempre proporcionar las rutas o el resumen de los casos relevantes de .loop-memory/ en el prompt inicial del subagente.
3. Entregas Discretas: Los subagentes deben comunicarse a través de archivos explícitos (p. ej., scripts de reproducción, archivos de borrador, rúbricas de evaluación) en lugar de historial conversacional.
4. Puerta de Paso Autónoma: Un subagente NO puede avanzar el estado de etapas.json a "completed" sin una prueba verificable (logs, salidas de pruebas, puntuaciones de validación).

---

Errores Comunes y Anti-Patrones

Anti-Patrón	Por Qué Rompe el Bucle	La Práctica Correcta
Saltarse la fase Aprender	Los agentes reinventan errores conocidos o usan ángulos de copy rechazados.	Exigir la lectura de .loop-memory/ como paso 0 en cada prompt.
Omitir la fase Comprimir	Las lecciones se pierden tan pronto como se restablece el contexto de la sesión.	Nunca concluir una tarea sin destilar casos ganadores/fallidos en archivos.
Ejecución de agente monolítica	Un solo agente se confunde al intentar planificar, codificar, verificar y documentar a la vez.	Despachar subagentes especializados para cada etapa discreta.
**Verificación blanda (