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

Titel

Context Matters: Evaluatie van Contextstrategieën voor Geautomatiseerde ADR-Generatie met LLM's

1. Probleemstelling

Architectuurbeslissingsrecords (ADRs) zijn cruciaal voor het vastleggen van de onderbouwing van systeemontwerp, maar hun creatie en onderhoud worden vaak verwaarloosd vanwege de hoge schrijfkosten ("documentation debt"). Hoewel Large Language Models (LLMs) potentie hebben om deze last te verlichten, is de huidige research beperkt. Bestaande studies behandelen ADR-generatie vaak als een geïsoleerde taak, waarbij modellen slechts op een smalle context of directe code-wijzigingen worden getraind.

De kernproblematiek die dit paper adresseert, is het gebrek aan inzicht in hoe context-engineering (de strategie om historische ADRs als input te presenteren) de kwaliteit van de gegenereerde ADRs beïnvloedt. Software-architectuur is "path-dependent": beslissingen worden niet in een vacuüm genomen, maar zijn beperkt door eerdere keuzes, technologie-stacks en afwegingen. De vraag is of LLMs deze historische context effectief kunnen benutten en welke strategie (bijv. volledige geschiedenis vs. recente records) het meest efficiënt en kwalitatief is.

2. Methodologie

De auteurs hebben een uitgebreide empirische studie uitgevoerd volgens het Goal-Question-Metric (GQM) paradigma.

• Dataset:

  • Er is een gecurateerde corpus van 4.500+ geverifieerde ADRs uit 750 open-source repositories samengesteld.
  • De data is handmatig gefilterd en geschoond om chronologische consistentie te garanderen (oplossing voor structurele heterogeniteit en tijdsdiscontinuïteit in de oorspronkelijke datasets).
  • De dataset simuleert een realistische evolutionaire lijn van architecturale beslissingen.

• Experimenteel Ontwerp:

  • Doel: Het genereren van de n-de ADR op basis van alleen de titel, met variatie in de context die aan het model wordt gegeven.
  • Contextstrategieën (Vergelijking):
    1. Baseline: Geen context (alleen de titel van de te genereren ADR).
    2. All_N: Alle voorgaande ADRs in de geschiedenis.
    3. First_K: De eerste K ADRs (fundamentele, vroege beslissingen).
    4. Last_K: De laatste K ADRs (recente beslissingen).
    5. RAFG (Retrieval-Augmented Few-shot Generation): Dynamisch ophalen van de K meest semantisch relevante ADRs uit de geschiedenis (gebaseerd op cosine similarity met embeddings), ongeacht de chronologische volgorde.
  • Modellen: Er zijn vier verschillende LLM-families getest om de invloed van modelgrootte en architectuur te evalueren:
    • Gemini-2.5-Pro (Propriëtaire SOTA).
    • Qwen3-235B (Beste open-source model).
    • GLM-4.6 (Alternatieve graf-gebaseerde architectuur).
    • Gemma-3-4B (Lichtgewicht, lokaal uitvoerbaar model).

• Evaluatiemetrics:

  • Automatisch: BERTScore (semantische gelijkenis), BLEU (lexicale overlap), ROUGE (recall/overzicht), METEOR (synoniemen/stemming).
  • Menselijk: Handmatige review van een subset om nuance, formatting en logische consistentie te beoordelen die automatische metrics missen.

3. Belangrijkste Bijdragen

1. Gecurateerde Chronologische Corpus: Een van de grootste datasets van sequentiële ADRs die specifiek is opgezet voor "next-step" generatie-experimenten, met gegarandeerde chronologische integriteit.
2. Empirische Validatie van Contextstrategieën: Een systematische vergelijking van vijf strategieën (geen context, volledige geschiedenis, eerste K, laatste K, en semantische retrieval) over meerdere modelgroottes.
3. Inzicht in "Context Engineering": Het aantonen dat de strategie voor het selecteren van context belangrijker is dan de schaal van het model zelf voor deze specifieke taak.

4. Resultaten

De resultaten tonen duidelijke trends op basis van de geautomatiseerde metrics en menselijke evaluatie:

• Impact van Geschiedenis (RQ1):

  • Het toevoegen van historische context verbetert de kwaliteit aanzienlijk ten opzichte van de "no-context" baseline.
  • Zonder context genereren LLMs vaak te lange, vage teksten (gemiddeld >1100 tokens voor Gemini vs. ~526 tokens voor menselijke grondwaarheid). Contextgebaseerde prompts leiden tot beknoptere, rationelere output die beter overeenkomt met menselijke ADRs.

• Efficiëntie van Selectieve Strategieën (RQ2):

  • Last_K (Recente context) presteert consistent het beste. Een venster van 3 tot 5 recente ADRs levert bijna dezelfde kwaliteit op als het gebruik van de volledige geschiedenis (All_N), maar met aanzienlijk minder token-kosten en complexiteit.
  • First_K (vroege beslissingen) presteert slechter dan Last_K, wat suggereert dat recente architecturale context relevanter is voor nieuwe beslissingen dan de oorspronkelijke fundamentele keuzes.
  • De volledige geschiedenis (All_N) biedt geen statistisch significant voordeel ten opzichte van een slim geselecteerd subset, maar is wel inefficiënt.

• Retrieval vs. Chronologisch (RQ3):

  • RAFG (semantische retrieval) presteert vergelijkbaar met Last_K in algemene metrics.
  • RAFG biedt echter een specialistisch voordeel in scenario's met "cross-cutting concerns" of niet-lineaire afhankelijkheden, waar een beslissing semantisch gerelateerd is aan een oude beslissing die niet in de directe recente geschiedenis zit.
  • Voor standaard, lineaire workflows is de extra complexiteit van RAFG echter niet gerechtvaardigd; Last_K is de meest kosteneffectieve standaard.

• Modelgrootte:

  • Kleinere modellen (zoals Gemma-3-4B) kunnen met de juiste context (Last_K) concurreren met veel grotere modellen (zoals Gemini-2.5-Pro). Dit bevestigt dat context-engineering de beperkende factor is, niet noodzakelijk het aantal parameters.

5. Betekenis en Implicaties

• Voor Practici:

  • Organisaties hoeven geen complexe RAG-systemen te bouwen voor elke ADR-taak. Een simpele strategie om de laatste 3-5 ADRs in de prompt te plaatsen, biedt de beste balans tussen kwaliteit en kosten.
  • Lokale, lightweight modellen zijn een haalbaar alternatief voor cloud-API's als ze goed worden geprompted, wat data-governance en kostenproblemen oplost.
  • Documentatiehygiëne is cruciaal: ADRs die verwijzen naar externe bronnen (wikis, tickets) zonder de onderbouwing zelf te bevatten, leiden tot slechtere generatiekwaliteit. ADRs moeten "zelfstandig" (self-contained) zijn.

• Voor Onderzoekers:

  • De focus moet verschuiven van het trainen van grotere modellen naar het optimaliseren van context-strategieën.
  • Er is behoefte aan datasets met volledig zelfstandige ADRs om de evaluatie van generatiemodellen te verbeteren.
  • Toekomstig werk zou hybride strategieën kunnen onderzoeken die recency (Last_K) combineren met semantische retrieval (RAFG) voor complexe architecturale scenario's.

Conclusie:
De studie concludeert dat context engineering de dominante factor is voor effectieve automatisering van ADRs. Een kleine recency-venster (3-5 records) is doorgaans voldoende voor optimale prestaties, waardoor complexe en dure retrieval-systemen vaak overbodig zijn voor standaard architecturale workflows.