Context Matters: Evaluating Context Strategies for Automated ADR Generation Using LLMs

Resumen Técnico: Estrategias de Contexto para la Generación Automatizada de Registros de Decisiones de Arquitectura (ADR) con LLMs

1. El Problema

Los Registros de Decisiones de Arquitectura (ADR) son fundamentales para preservar la racionalidad detrás de las decisiones de diseño de software, facilitando la incorporación de nuevos miembros al equipo y evitando la "vaporización del conocimiento". Sin embargo, su adopción práctica es inconsistente debido a la alta carga de trabajo manual que implica su creación y mantenimiento (deuda de documentación).

Aunque los Modelos de Lenguaje Grande (LLMs) ofrecen la promesa de automatizar esta tarea, la investigación existente ha tratado la generación de ADRs como una tarea aislada, ignorando una propiedad fundamental de la arquitectura de software: la dependencia de la trayectoria (path dependency). Las decisiones arquitectónicas no se toman en el vacío; están restringidas por el historial de decisiones previas, la pila tecnológica establecida y los compromisos (trade-offs) aceptados anteriormente. La pregunta central es: ¿Cómo influyen las diferentes estrategias de presentación del contexto histórico en la calidad de los ADRs generados por LLMs?

2. Metodología

El estudio es una evaluación empírica a gran escala diseñada para controlar rigurosamente el contexto arquitectónico proporcionado a los modelos.

• Conjunto de Datos: Se curó y validó un corpus de más de 4,500 ADRs secuenciales extraídos de 750 repositorios de código abierto. Se realizó un filtrado manual exhaustivo para asegurar la integridad cronológica y eliminar ruido (plantillas vacías, documentación no arquitectónica).
• Modelos Evaluados: Se utilizaron cuatro familias de LLMs heterogéneas para evaluar la generalización:
  1. Gemini-2.5-Pro (Propietario, estado del arte).
  2. Qwen3-235B (Open Source, alto rendimiento).
  3. GLM-4.6 (Open Source, arquitectura aumentada por grafos).
  4. Gemma-3-4B (Open Source, ligero, ejecutable localmente).
• Estrategias de Contexto (Variables Independientes): Se compararon cinco estrategias de prompting:
  1. Baseline (Sin contexto): Solo el título del ADR a generar.
  2. All-History (All_N): Todo el historial de ADRs previos.
  3. First-K: Los primeros $K$ ADRs (contexto fundacional).
  4. Last-K: Los últimos $K$ ADRs (contexto reciente).
  5. RAFG (Retrieval-Augmented Few-shot Generation): Recuperación dinámica de los $K$ ADRs más semánticamente relevantes utilizando embeddings (SentenceTransformer) y similitud coseno, en lugar de un orden cronológico estricto.
• Métricas de Evaluación: Se utilizaron métricas automáticas (BERTScore, BLEU, ROUGE, METEOR) para medir la similitud semántica y léxica con la verdad fundamental (ADR escrito por humanos), complementadas con una revisión manual de una muestra de los resultados.

3. Contribuciones Clave

1. Corpus Validado: Creación de uno de los conjuntos de datos secuenciales de ADRs más grandes y curados hasta la fecha, garantizando el orden cronológico para experimentos de "siguiente paso".
2. Análisis de Ingeniería de Contexto: Demostración de que la estrategia de selección de contexto es un factor más determinante para la calidad de la generación que el tamaño del modelo en sí.
3. Estrategias de Contexto Cuantificadas: Evaluación sistemática de cómo el historial de decisiones (completo, fundacional, reciente o semántico) afecta la fidelidad de la generación.
4. Recomendaciones Prácticas: Definición de valores predeterminados para herramientas de automatización y estrategias de recuperación para escenarios complejos.

4. Resultados Principales

• Impacto del Contexto (RQ1): La inclusión de contexto histórico mejora drásticamente la calidad de generación en comparación con el baseline sin contexto. Los modelos sin contexto tienden a generar textos verbosos y genéricos que no capturan la racionalidad arquitectónica específica.
• Eficiencia del Contexto Selectivo (RQ2):
  • No es necesario el historial completo: La estrategia All-History no ofrece mejoras significativas en comparación con ventanas de contexto más pequeñas.
  • La ventana óptima: Una ventana de recencia pequeña (Last-K, típicamente 3 a 5 registros) ofrece el mejor equilibrio entre calidad y eficiencia.
  • Last-K vs. First-K: La estrategia Last-K supera consistentemente a First-K, indicando que el contexto arquitectónico inmediato es más predictivo de la racionalidad futura que las decisiones fundacionales antiguas.
  • Modelos Pequeños: Modelos más pequeños (como Gemma-3-4B) con un contexto adecuado pueden igualar el rendimiento de modelos masivos, reduciendo costos y barreras de privacidad.
• Recuperación Semántica vs. Cronológica (RQ3):
  • La estrategia RAFG (basada en recuperación semántica) rinde de manera comparable a Last-K en métricas agregadas.
  • Ventaja Específica: RAFG muestra superioridad en escenarios de preocupaciones transversales (cross-cutting concerns) o dependencias no secuenciales, donde una decisión antigua pero conceptualmente relevante es más importante que las decisiones recientes. Sin embargo, añade complejidad de implementación y latencia.

5. Significado e Implicaciones

• Cambio de Paradigma: El cuello de botella para la automatización de la Gestión del Conocimiento Arquitectónico (AKM) no es la capacidad de razonamiento del modelo (escala de parámetros), sino la ingeniería de contexto.
• Recomendaciones para Practicantes:
  • Utilizar Last-K (3-5 registros) como estrategia predeterminada por su simplicidad y alto rendimiento.
  • Priorizar la higiene de la documentación: Los ADRs deben ser autocontenidos. Las referencias a contenido externo (wikis, issues) degradan la calidad de la generación automática y la evaluación.
  • Considerar modelos locales ligeros para cumplir con requisitos de gobernanza de datos sin sacrificar calidad.
• Implicaciones para Investigadores:
  • Necesidad de desarrollar estrategias híbridas (recencia + recuperación semántica) para manejar la deriva arquitectónica.
  • Importancia de crear conjuntos de datos de investigación con ADRs autocontenidos y justificados completamente para evitar sesgos en la evaluación.
  • Exploración de representaciones basadas en grafos para modelar dependencias arquitectónicas más allá de la proximidad temporal o semántica simple.

En conclusión, el estudio demuestra que una ventana de contexto pequeña y reciente es suficiente para la mayoría de los flujos de trabajo de ADR, mientras que la recuperación semántica es una herramienta valiosa para casos de uso complejos, desplazando el foco de optimización desde el tamaño del modelo hacia la estrategia de ingeniería de prompts.